kibi-cli 2.1.0 → 2.2.0

package/src/public/operations/specs/reporting.ts

@@ -209,12 +209,26 @@ export async function perContractTestBindings(
   const { removeFrontmatterBlock } = await import(
     "../../../operations/proof/receipt-document.js"
   );
+  const { loadCoveredBySymbolsByTest, receiptCodeScopeSymbolIds } =
+    await import("../../../operations/proof/code-scope.js");
+  // Only the contract, scoped code, and authored source feed the binding
+  // hash. The paged projection never materializes receipt histories, which
+  // grow without bound and previously overflowed the bounded Prolog output
+  // on real stores. Engine failures must surface: silently dropping to strict
+  // snapshot semantics would hide an unhealthy engine behind stale receipts.
   let tests: Record<string, unknown>[];
   try {
-    tests = await loadEntities(context.prolog as never, { type: "test" });
-  } catch {
-    return null;
+    tests = await loadEntities(requireProlog(context), {
+      type: "test",
+      projection: "proof_contract",
+    });
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new Error(`Per-contract receipt binding query failed: ${message}`);
   }
+  const coveredBy = tests.length
+    ? await loadCoveredBySymbolsByTest(requireProlog(context))
+    : new Map<string, readonly string[]>();
   const entries: string[] = [];
   const manifestPath = join(context.workspaceRoot, ".kb", "symbols.yaml");
   for (const test of tests) {
@@ -233,17 +247,14 @@ export async function perContractTestBindings(
       const absolute = join(context.workspaceRoot, source);
       const authored = await context.fs.readFile(absolute);
       const stripped = removeFrontmatterBlock(authored, "proof_receipts");
-      const rawBindings: ReadonlyArray<{ symbol_id?: unknown }> = Array.isArray(
-        test.proof_bindings,
-      )
-        ? (test.proof_bindings as ReadonlyArray<{ symbol_id?: unknown }>)
-        : [];
-      const boundIds = rawBindings
-        .map((binding) =>
-          typeof binding.symbol_id === "string" ? binding.symbol_id : "",
-        )
-        .filter((id) => id !== "");
-      const codeScope = resolveBoundSymbolScope(manifestPath, boundIds);
+      const codeScope = resolveBoundSymbolScope(
+        manifestPath,
+        receiptCodeScopeSymbolIds(
+          contract,
+          test.proof_bindings,
+          coveredBy.get(testId) ?? [],
+        ),
+      );
       const binding = receiptBindingHash(
         contract as never,
         stripped ?? authored,
@@ -258,6 +269,42 @@ export async function perContractTestBindings(
   return `_{${entries.join(", ")}}`;
 }
 
+/**
+ * Coverage rows can be large (full proof stages per requirement), so a
+ * whole-KB report in one answer approaches the engine's bounded output cap.
+ * Fetch it in small row pages instead; the engine memoizes the computed
+ * report per store generation, so later pages only paginate and encode.
+ */
+export const COVERAGE_ROW_PAGE_SIZE = 10;
+
+// implements REQ-kibi-verification-evidence-contract
+export async function readCoveragePages(
+  prolog: NonNullable<OperationContext["prolog"]>,
+  goalFor: (limit: number, offset: number) => string,
+  limit: number,
+  offset: number,
+): Promise<CoveragePayload> {
+  const read = (pageLimit: number, pageOffset: number) =>
+    runOperationJsonQuery<CoveragePayload>(
+      prolog,
+      "discovery.pl",
+      goalFor(pageLimit, pageOffset),
+      "Coverage execution",
+    );
+  if (limit <= COVERAGE_ROW_PAGE_SIZE) return read(limit, offset);
+  const first = await read(COVERAGE_ROW_PAGE_SIZE, offset);
+  const rows = [...first.rows];
+  let lastPageSize = first.rows.length;
+  let lastPageLimit = COVERAGE_ROW_PAGE_SIZE;
+  while (lastPageSize === lastPageLimit && rows.length < limit) {
+    lastPageLimit = Math.min(COVERAGE_ROW_PAGE_SIZE, limit - rows.length);
+    const page = await read(lastPageLimit, offset + rows.length);
+    rows.push(...page.rows);
+    lastPageSize = page.rows.length;
+  }
+  return { ...first, rows };
+}
+
 export async function executeCoverage(
   input: CoverageInput,
   context: OperationContext,
@@ -275,17 +322,17 @@ export async function executeCoverage(
       statuses.length === 0 && (input.by ?? "req") === "req"
         ? await perContractTestBindings(context)
         : null;
-    const goal =
+    const goalFor = (limit: number, offset: number): string =>
       bindingsDict !== null
-        ? `discovery:coverage_report_json('${input.by ?? "req"}', ${toPrologList(input.tags)}, ${input.includePassing ?? false}, per_contract, ${bindingsDict}, ${input.includeTransitive ?? true}, ${input.limit ?? 100}, ${input.offset ?? 0}, ${toPrologAtom(codeSnapshot)}, ${toPrologAtom(checkedAt)}, ${PROOF_RECEIPT_MAX_AGE_SECONDS}, JsonString)`
+        ? `discovery:coverage_report_json('${input.by ?? "req"}', ${toPrologList(input.tags)}, ${input.includePassing ?? false}, per_contract, ${bindingsDict}, ${input.includeTransitive ?? true}, ${limit}, ${offset}, ${toPrologAtom(codeSnapshot)}, ${toPrologAtom(checkedAt)}, ${PROOF_RECEIPT_MAX_AGE_SECONDS}, JsonString)`
         : statuses.length > 0
-          ? `discovery:coverage_report_json('${input.by ?? "req"}', ${toPrologList(input.tags)}, ${input.includePassing ?? false}, ${toPrologList(statuses)}, ${input.includeTransitive ?? true}, ${input.limit ?? 100}, ${input.offset ?? 0}, ${toPrologAtom(codeSnapshot)}, ${toPrologAtom(checkedAt)}, ${PROOF_RECEIPT_MAX_AGE_SECONDS}, JsonString)`
-          : `discovery:coverage_report_json('${input.by ?? "req"}', ${toPrologList(input.tags)}, ${input.includePassing ?? false}, ${input.includeTransitive ?? true}, ${input.limit ?? 100}, ${input.offset ?? 0}, ${toPrologAtom(codeSnapshot)}, ${toPrologAtom(checkedAt)}, ${PROOF_RECEIPT_MAX_AGE_SECONDS}, JsonString)`;
-    const payload = await runOperationJsonQuery<CoveragePayload>(
+          ? `discovery:coverage_report_json('${input.by ?? "req"}', ${toPrologList(input.tags)}, ${input.includePassing ?? false}, ${toPrologList(statuses)}, ${input.includeTransitive ?? true}, ${limit}, ${offset}, ${toPrologAtom(codeSnapshot)}, ${toPrologAtom(checkedAt)}, ${PROOF_RECEIPT_MAX_AGE_SECONDS}, JsonString)`
+          : `discovery:coverage_report_json('${input.by ?? "req"}', ${toPrologList(input.tags)}, ${input.includePassing ?? false}, ${input.includeTransitive ?? true}, ${limit}, ${offset}, ${toPrologAtom(codeSnapshot)}, ${toPrologAtom(checkedAt)}, ${PROOF_RECEIPT_MAX_AGE_SECONDS}, JsonString)`;
+    const payload = await readCoveragePages(
       requireProlog(context),
-      "discovery.pl",
-      goal,
-      "Coverage execution",
+      goalFor,
+      input.limit ?? 100,
+      input.offset ?? 0,
     );
     const rows =
       (input.by ?? "req") === "req"

package/src/public/operations/specs/upsert.ts

@@ -28,7 +28,7 @@ export const upsertSpec = {
       id: {
         type: "string",
         description:
-          "Unique entity ID (string). Example: 'REQ-123'. Existing ID updates the entity; new ID creates it.",
+          "Unique entity ID (string). Example: 'REQ-cli-gc'. Name entities by the behavior they govern (<TYPE>-<area>-<behavior>), never by the next free number. Existing ID updates the entity; new ID creates it.",
       },
       properties: ENTITY_PROPERTIES_SCHEMA,
       relationships: RELATIONSHIPS_SCHEMA,

package/src/public/operations/symbol-repair-plan.ts

@@ -7,7 +7,13 @@ import {
   enrichSymbolCoordinates,
 } from "../../extractors/symbols-coordinator.js";
 import { isCoarseGranularityReason } from "../symbol-granularity.js";
-import { loadEntities } from "./discovery-entities.js";
+import { loadEntitiesPaged } from "./discovery-entities.js";
+
+/**
+ * Symbol pages for repair planning. The full symbol inventory is already half
+ * of the bounded engine output on large workspaces, so it is read in pages.
+ */
+const SYMBOL_PAGE_SIZE = 250;
 import type { OperationContext } from "./runtime-types.js";
 
 export const SYMBOL_REPAIR_PLAN_VERSION = "kibi.symbol-repair-plan.v1" as const;
@@ -131,7 +137,7 @@ export async function addCoordinateRepairEvidence(
   const ids = new Set(missingByRow.flat());
   if (ids.size === 0 || !context.prolog) return rows;
   const symbols = (
-    await loadEntities(context.prolog, { type: "symbol" })
+    await loadEntitiesPaged(context.prolog, "symbol", SYMBOL_PAGE_SIZE)
   ).filter((symbol) => ids.has(String(symbol.id)));
   const evidence = await inspectCoordinateRepairs(
     symbols,
@@ -227,7 +233,11 @@ export async function buildSymbolRepairPlan(
   context: OperationContext,
 ): Promise<SymbolRepairPlan | undefined> {
   if (!context.prolog || rows.length === 0) return undefined;
-  const symbols = await loadEntities(context.prolog, { type: "symbol" });
+  const symbols = await loadEntitiesPaged(
+    context.prolog,
+    "symbol",
+    SYMBOL_PAGE_SIZE,
+  );
   const extractedByPath = new Map<
     string,
     readonly { name: string; kind: string }[]

package/src/public/schemas/entity.ts

@@ -531,6 +531,26 @@ const entitySchema: Record<string, unknown> = {
     aliases: { type: "array", items: { type: "string" } },
     examples: { type: "array", items: { type: "string" } },
     predicate_args: { type: "array", items: { type: "string" } },
+    // predicate_schema only: allowed constants per argument name. Arguments
+    // without an entry stay open; predicate facts must use a listed constant.
+    argument_constants: {
+      type: "object",
+      additionalProperties: {
+        type: "array",
+        minItems: 1,
+        uniqueItems: true,
+        items: { type: "string", minLength: 1 },
+      },
+    },
+    // predicate_schema only: legacy spellings per argument name, each mapped
+    // to one declared constant. kibi migrate rewrites facts that use them.
+    argument_aliases: {
+      type: "object",
+      additionalProperties: {
+        type: "object",
+        additionalProperties: { type: "string", minLength: 1 },
+      },
+    },
     rule_ir: { $ref: "#/$defs/logicRule" },
     rule_hash: { type: "string", pattern: "^[a-f0-9]{64}$" },
     rule_schema_id: { type: "string", minLength: 1 },
@@ -594,6 +614,8 @@ const entitySchema: Record<string, unknown> = {
             { required: ["aliases"] },
             { required: ["examples"] },
             { required: ["predicate_args"] },
+            { required: ["argument_constants"] },
+            { required: ["argument_aliases"] },
             { required: ["rule_ir"] },
             { required: ["rule_hash"] },
             { required: ["rule_schema_id"] },

package/src/public/schemas/relationship.ts

@@ -40,6 +40,7 @@ const relationshipSchema = {
         "publishes",
         "consumes",
         "supersedes",
+        "restates",
         "relates_to",
       ],
     },

package/src/public/skills/kibi-usage/SKILL.md

@@ -2,7 +2,7 @@
 id: kibi-usage
 name: Kibi Usage
 description: Use Kibi's source-first, exact-Git, migration-aware, proof-aware operations safely across MCP or the trusted local CLI, including partial completion repair.
-version: 2.1.3
+version: 2.2.0
 kibiCompatibility: ">=1.0.0"
 tags:
   - kibi
@@ -59,7 +59,11 @@ mutability, and Prolog requirements of each operation.
 ## Safe workflow
 
 1. Always discover before you mutate: start with `kb_search`, then exact-filter with `kb_query`. Use
-   `kb_status` when branch or freshness confidence matters.
+   `kb_status` when branch or freshness confidence matters. `kb_search` ranks
+   lexically unless you pass `rankingMode: "intent-v1"`, `semanticFacets`, or
+   `sourceLocations`; use intent mode with grounded facets for conceptual
+   questions and before changing a source file, and keep lexical search for
+   literal identifiers. See `resources/workflows.md` for the mode recipe.
 2. Resolve genuine ambiguity with the human; use semantic advisor/modeling
    operations for deterministic interpretation and typed facts.
 3. Create endpoints before relationships and upsert small batches sequentially.
@@ -160,7 +164,7 @@ Represent implementation ownership with a `symbol` entity that has
 `sourceFile`, `implements` to the requirement, and `covered_by` to the test.
 Prolog `symbol-coverage` also requires the test to `validates` the requirement
 (or the requirement `verified_by` the test). `covered_by` alone is not
-enough. Do not rely on legacy `// implements REQ-xxx` comments as the
+enough. Do not rely on legacy `// implements REQ-<area>-<behavior>` comments as the
 traceability record.
 
 ## Complete Logical Coverage

package/src/public/skills/kibi-usage/resources/fact-lanes.md

@@ -55,6 +55,10 @@ relationship: { type: requires_predicate, from: REQ-EDITOR-DRAFT-AUTOSAVE, to: F
 
 The project-local schema endpoint must exist before this fact is linked. When ontology extension is explicitly authorized, define it first with `fact_kind: predicate_schema`, `predicate_name`, `predicate_arity`, and equally sized `argument_names` and `argument_types`. Without an authorized stable signature, record `review:ontology-gap` instead of inventing a schema.
 
+### Closed argument vocabularies
+
+A schema can close an argument with `argument_constants` (allowed values keyed by argument name) and map older spellings with `argument_aliases`. Reuse a declared constant; `kb_upsert` rejects any other value and names the constant to use for an alias. When a genuinely new value is needed, extend `argument_constants` on the schema first. To converge existing facts, declare aliases for their spellings and let `kibi migrate` rewrite them (`predicate_schema_alignment` actions). Close only arguments with a natural shared vocabulary, such as the governed component or a severity; forcing distinct obligations into a few constants makes different requirements share one ground term.
+
 ### Deny predicate
 
 Claim: “Suspended users must not publish articles.” When `permission_rule` fits, preserve its positive schema name and encode prohibition as polarity:

package/src/public/skills/kibi-usage/resources/relationship-directions.md

@@ -12,6 +12,7 @@
 | `constrains` | req -> fact(subject) | Requirement constrains a strict-lane domain fact |
 | `requires_property` | req -> fact(property_value) | Requirement requires a specific property value fact |
 | `supersedes` | new-req -> old-req | New requirement formally replaces an old requirement |
+| `restates` | req -> req | Requirement intentionally restates another current requirement (for example a product requirement echoed in a platform requirement); suppresses `domain-redundancy` for that pair without retiring either side |
 | `covered_by` | symbol -> test | Production symbol has test coverage evidence |
 
 ## Valid Payload Examples
@@ -20,32 +21,32 @@
 ```yaml
 relationships:
   - type: implements
-    from: SYM-001
-    to: REQ-001
+    from: SYM-operation-execute-check
+    to: REQ-cli-check
 ```
 
 ### specified_by
 ```yaml
 relationships:
   - type: specified_by
-    from: REQ-001
-    to: SCEN-001
+    from: REQ-mcp-search-discovery
+    to: SCEN-mcp-search-discovery
 ```
 
 ### verified_by
 ```yaml
 relationships:
   - type: verified_by
-    from: REQ-001
-    to: TEST-001
+    from: REQ-mcp-search-discovery
+    to: TEST-mcp-search-discovery
 ```
 
 ### validates
 ```yaml
 relationships:
   - type: validates
-    from: TEST-001
-    to: SCEN-001
+    from: TEST-mcp-search-discovery
+    to: SCEN-mcp-search-discovery
 ```
 
 ### executable_for
@@ -53,39 +54,56 @@ relationships:
 relationships:
   - type: executable_for
     from: SYM-test-login
-    to: TEST-001
+    to: TEST-mcp-search-discovery
 ```
 
 ### constrains
 ```yaml
 relationships:
   - type: constrains
-    from: REQ-019
-    to: FACT-USER-ROLE
+    from: REQ-cli-check
+    to: FACT-SUBJECT-KIBI-CHECK
 ```
 
 ### requires_property
 ```yaml
 relationships:
   - type: requires_property
-    from: REQ-019
-    to: FACT-LIMIT-3
+    from: REQ-cli-check
+    to: FACT-PROP-CHECK-FAILURE-EXIT-CODE
 ```
 
 ### supersedes
 ```yaml
 relationships:
   - type: supersedes
-    from: REQ-001-v2
-    to: REQ-001
+    from: REQ-opencode-kibi-briefing-v2
+    to: REQ-opencode-kibi-briefing-v1
 ```
 
+A `-v2` suffix is acceptable only for a direct superseding replacement like
+this one; otherwise name the new requirement by the behavior it governs.
+
+### restates
+```yaml
+# Illustrative: a product requirement echoes a platform requirement verbatim.
+relationships:
+  - type: restates
+    from: REQ-billing-invoice-retention
+    to: REQ-platform-record-retention
+```
+
+Use `restates` only when two current requirements deliberately ground the same
+logical term (same predicate, property tuple, or rule semantic key). It keeps
+both requirements current and tells `domain-redundancy` the duplication is
+intentional. If one requirement replaces the other, use `supersedes` instead.
+
 ### covered_by
 ```yaml
 relationships:
   - type: covered_by
-    from: SYM-handler
-    to: TEST-005
+    from: SYM-operation-execute-check
+    to: TEST-mcp-search-discovery
 ```
 
 ## Invalid Test-Fact Shortcuts

package/src/public/skills/kibi-usage/resources/source-authoring.md

@@ -29,3 +29,39 @@ Cancellation follows the same rule: wait for the terminal journal state. A
 pre-commit rollback is retryable, a committed source with a failed derivative
 is repairable, and an indeterminate outcome is non-retryable until its recovery
 action resolves the journal.
+
+## Naming entities
+
+Name every entity by what it governs, the way you would name a source file.
+Never choose "the next number": parallel branches pick the same next number and
+collide even when they touch unrelated behavior.
+
+- Use `<TYPE>-<area>-<behavior>` in kebab-case, with the type prefix kept
+  uppercase: `REQ-cli-gc`, `SCEN-mcp-search-discovery`,
+  `TEST-mcp-search-discovery`, `ADR-capability-plugins-v1`,
+  `EVT-exact-branch-store-ensure`, and a flag named after its gate such as
+  `FLAG-scip-symbol-extraction`.
+- The filename stem equals the frontmatter `id`
+  (`.kb/requirements/REQ-cli-gc.md` has `id: REQ-cli-gc`). Always set `id`
+  explicitly; a missing `id` falls back to a path-and-title hash that changes
+  when the file is renamed.
+- Before creating an entity, `kb_search` the area. If an existing entity already
+  covers the behavior, update it, or create a replacement and link it with
+  `supersedes`. A `-v2` suffix is acceptable only for that direct superseding
+  replacement.
+- A name collision with another branch usually means the same work was done
+  twice. Reconcile the two entities; do not rename one of them to dodge the
+  collision.
+- The area prefix is for humans. Whether two requirements are about the same
+  thing is decided by their facts: a shared `subject_key` and identical
+  predicate or property signatures, which `domain-redundancy` and
+  `domain-contradictions` compare deterministically. Reuse existing subject keys
+  (dotted `component.aspect[.sub]`, lowercase snake segments such as
+  `kibi.cli.check.staged`) instead of deriving a subject from the requirement
+  ID.
+
+`entity-id-style` reports new purely numeric IDs (`REQ-123`) and IDs whose
+filename stem differs from `id` as non-blocking quality diagnostics. Legacy
+numbered entities created before the naming standard are grandfathered and are
+not renamed, because code comments such as `// implements REQ-003` still
+reference them.

package/src/public/skills/kibi-usage/resources/workflows.md

@@ -33,11 +33,62 @@ surfaces are a release defect: require a new package version and label any
 project override temporary. This skill never selects a package manager or
 edits dependency configuration.
 
+## Choosing a discovery mode
+
+`kb_search` is not one behavior. It selects deterministic intent ranking when
+you pass `rankingMode: "intent-v1"`, `semanticFacets`, or `sourceLocations`,
+and legacy lexical ranking otherwise. Naming the tool is not enough; the inputs
+decide the path.
+
+- **Exact identity** — you already know the ID. Use `kb_query`, not search.
+- **Literal token** — a symbol, file, or error string that appears verbatim.
+  Use lexical `kb_search` and keep the query close to the literal text.
+- **Conceptual or behavioral** — "how does checkout handle a declined card".
+  Use intent mode and ground it in what you actually know:
+
+```json
+{
+  "query": "declined card during checkout",
+  "rankingMode": "intent-v1",
+  "semanticFacets": {
+    "actors": ["shopper"],
+    "actions": ["pay"],
+    "objects": ["card"],
+    "constraints": ["declined"]
+  }
+}
+```
+
+- **Before changing code** — pass the file you are about to edit as a source
+  location, so results are matched against source-linked symbols and return
+  source evidence:
+
+```json
+{
+  "query": "checkout total rounding",
+  "rankingMode": "intent-v1",
+  "sourceLocations": [{ "path": "src/checkout.ts", "symbol": "computeTotal" }]
+}
+```
+
+Supply facets only from the request, the code, or prior results. Inventing
+facets fabricates evidence and biases ranking. Intent mode abstains below
+`minScore` instead of returning weak matches; an abstention is an explicit
+no-answer, so widen the query or drop to lexical search rather than treating it
+as "nothing exists". There is no target percentage of intent-mode calls — a
+literal identifier lookup is still best served lexically.
+
+Results are summaries by default: identifying metadata, score, reasons, and a
+snippet. Read them to pick candidates, then `kb_query` those IDs for full
+bodies, or pass `fields: "full"` when you genuinely need every body. Extract
+the relevant existing constraints and decisions from the response before
+planning a behavior change; a search receipt is not comprehension.
+
 ## Discovery to Validation Sequence
 
 The canonical workflow for any KB operation follows this pattern:
 
-1. **Discover**: `kb_search` with focused probes
+1. **Discover**: `kb_search` with focused probes; pick the mode above
 2. **Confirm**: `kb_query` for exact IDs and state
 3. **Inspect**: `kb_status` when freshness matters
 4. **Decompose**: `kb_semantic_advisor` on the complete normative prose; verify or supply every atomic clause

package/src/public/telemetry-acceptance.ts

@@ -363,11 +363,30 @@ function advisorBeforeRequirementWriteMetric(
   };
 }
 
+function sourceLookupMessage(
+  zeroResults: number,
+  lookups: number,
+  unobservable: number,
+): string {
+  const unreadable =
+    unobservable > 0
+      ? `${unobservable} source-linked lookups recorded no readable result count.`
+      : "";
+  if (lookups === 0) {
+    return (
+      unreadable ||
+      "No source-linked query or search calls occurred in the evaluated window."
+    );
+  }
+  const observed = `${zeroResults}/${lookups} source-linked lookups returned zero results.`;
+  return unreadable ? `${observed} ${unreadable}` : observed;
+}
+
 function sourceLookupMetric(
   recent: readonly TimedEvent[],
   policy: TelemetryAcceptancePolicy,
 ): MutableMetric {
-  const lookups = recent.filter(({ event }) => {
+  const sourceLinked = recent.filter(({ event }) => {
     if (
       (event.tool !== "kb_query" && event.tool !== "kb_search") ||
       !eventSucceeded(event)
@@ -376,6 +395,14 @@ function sourceLookupMetric(
     }
     return typeof eventArgs(event).sourceFile === "string";
   });
+  // A row whose count could not be read is unobservable, not a hit.  Counting
+  // it as a non-zero result would let a broken logger report a healthy rate.
+  const lookups = sourceLinked.filter(
+    ({ event }) =>
+      typeof event.result_count === "number" ||
+      typeof event.zero_results === "boolean",
+  );
+  const unobservable = sourceLinked.length - lookups.length;
   const zeroResults = lookups.filter(
     ({ event }) => event.zero_results === true || event.result_count === 0,
   );
@@ -387,7 +414,10 @@ function sourceLookupMetric(
   }
   return {
     id: "source_lookup_zero_result_rate",
-    status: thresholdStatus(actual, "<=", policy.sourceLookupZeroResultMaximum),
+    status:
+      lookups.length === 0 && unobservable > 0
+        ? "insufficient_evidence"
+        : thresholdStatus(actual, "<=", policy.sourceLookupZeroResultMaximum),
     numerator: zeroResults.length,
     denominator: lookups.length,
     ...(actual !== undefined ? { rate: actual } : {}),
@@ -395,10 +425,11 @@ function sourceLookupMetric(
       operator: "<=",
       value: policy.sourceLookupZeroResultMaximum,
     },
-    message:
-      lookups.length === 0
-        ? "No source-linked query or search calls occurred in the evaluated window."
-        : `${zeroResults.length}/${lookups.length} source-linked lookups returned zero results.`,
+    message: sourceLookupMessage(
+      zeroResults.length,
+      lookups.length,
+      unobservable,
+    ),
     evidence: {
       zeroResultSourceFiles: [...sourceCounts.entries()]
         .sort(

package/src/schemas/entity.schema.json

@@ -1173,6 +1173,28 @@
         "type": "string"
       }
     },
+    "argument_constants": {
+      "type": "object",
+      "additionalProperties": {
+        "type": "array",
+        "minItems": 1,
+        "uniqueItems": true,
+        "items": {
+          "type": "string",
+          "minLength": 1
+        }
+      }
+    },
+    "argument_aliases": {
+      "type": "object",
+      "additionalProperties": {
+        "type": "object",
+        "additionalProperties": {
+          "type": "string",
+          "minLength": 1
+        }
+      }
+    },
     "rule_ir": {
       "$ref": "#/$defs/logicRule"
     },
@@ -1373,6 +1395,16 @@
                 "predicate_args"
               ]
             },
+            {
+              "required": [
+                "argument_constants"
+              ]
+            },
+            {
+              "required": [
+                "argument_aliases"
+              ]
+            },
             {
               "required": [
                 "rule_ir"

package/src/schemas/relationship.schema.json

@@ -22,6 +22,7 @@
         "publishes",
         "consumes",
         "supersedes",
+        "restates",
         "relates_to"
       ]
     },