本页目录

自定义 verb

14 个 verb 在 v1 是固定的。加一个 verb 走的流程跟自定义 kind 一样，多一步：L3 检查器要知道怎么处理它。

什么时候该加 verb

多数领域里特定的关系都能塞进 14 个里（尤其 related 和 see-also 是逃生通道）。新加 verb，只在两种情况下值得：

这条关系带操作语义，运行时要对它做出反应（比如某个 verb 触发 contract 解析）。
这条关系带校验语义，L3 要查（比如"在这个 verb 下，kind X 必须指向 kind Y"）。

要改的 5 个文件

1. Verb 字面量 —— `packages/types/src/ast.ts`

export type EdgeVerb =
  | 'related' | 'requires' | 'enhances' | 'validates-with'
  | 'contradicts' | 'specializes' | 'conflicts' | 'extends'
  | 'derived-from' | 'compatible' | 'supplies-to'
  | 'see-also' | 'includes' | 'relationships'
  | 'measures';   // ← your new verb

2. Lexer 里的字段名 —— `packages/parser/src/lexer.ts`

// Verb names are recognised as field names in atom bodies.
const EDGE_VERBS = new Set<EdgeVerb>([
  // ...
  'measures',
]);

3. L1 verb 形状校验 —— `packages/compiler/src/checker-l1.ts`

这条 verb 允许的源 / 目标 kind：

const VERB_KIND_RULES: Record<EdgeVerb, KindRule> = {
  // ...
  'measures': {
    sourceKinds: ['metric'],
    targetKinds: ['fact', 'rule', 'pattern'],
    description: 'A metric measures the property described by an atom.',
  },
};

4. L3 图推理 —— `packages/compiler/src/checker-l3-cross.ts`

// Add a check for your verb's specific invariants.
function checkMeasuresInvariants(graph: EdgeGraph): Diagnostic[] {
  const ds: Diagnostic[] = [];
  for (const e of graph.edgesByVerb('measures')) {
    const target = graph.atomById(e.target);
    if (!target) continue;
    if (!target.fields.has('measurable-property')) {
      ds.push({
        level: 'warning',
        message: `measures ${e.target} but target has no measurable-property field`,
      });
    }
  }
  return ds;
}

5. Fixture 加测试

// packages/compiler/test/fixtures/measures.prime
metric Latency {
  id: "@perf/metric-latency"
  ...
  measures: [@perf/rule-fast-response]
}

L3 检查器做什么

新 verb 要让 L3 抓什么，由你决定。几个例子：

基数："每个 metric 至少要有一条 measures 边。"
可达性："通过 measures 引用的原子，目标必须有反向边。"
领域匹配："measures 的源和目标必须落在同一个 domain。"

RFC 流程

跟自定义 kind 同一套 Tier-2 RFC 流程。详见自定义 kind。