@abelxiaoxing/cadence 1.3.0 → 1.4.1

package/src/contracts.ts

@@ -52,6 +52,14 @@ export const LIMITS = {
   maxCompleteResultBytes: 64 * 1024,
 } as const;
 
+/** Shared collection bounds for runtime verification and author-facing schemas. */
+export const VERIFICATION_LIMITS = Object.freeze({
+  minSteps: 1,
+  maxSteps: 8,
+  minTestFiles: 1,
+  maxTestFiles: 64,
+});
+
 export const ARTIFACT_FAILURE_CODES = [
   "agents-impact-mismatch",
   "agents-target-mismatch",
@@ -117,7 +125,6 @@ export const ENVIRONMENT_FAILURE_CODES = [
   "checkout-failed",
   "clone-alternates",
   "clone-failed",
-  "child-session-create-failed",
   "dependency-path-unsafe",
   "git-apply-check-unavailable",
   "git-apply-failed",
@@ -125,11 +132,6 @@ export const ENVIRONMENT_FAILURE_CODES = [
   "git-ignore-check-failed",
   "git-index-unavailable",
   "invalid-subagent-endpoint",
-  "parent-bridge-capture-not-ready",
-  "parent-bridge-generation-invalidated",
-  "parent-bridge-model-key-mismatch",
-  "parent-bridge-provider-not-installed",
-  "parent-bridge-session-unavailable",
   "root-unavailable",
   "sandbox-runtime-unavailable",
 ] as const;
@@ -150,8 +152,14 @@ export const VERIFICATION_ADAPTER_CODES = [
   "script-command-mismatch",
   "script-missing",
   "script-unsafe",
+  "report-arguments-conflict",
+  "verification-config-mismatch",
+  "verification-config-unsafe",
 ] as const;
 export const CHILD_TRANSPORT_CODES = [
+  "first-progress-timeout",
+  "stream-idle-timeout",
+  "attempt-timeout",
   "child-no-final-assistant",
   "child-provider-stream-aborted",
   "child-provider-stream-error",
@@ -234,6 +242,10 @@ export type CandidateFailure =
   | { kind: "result-limit"; limitBytes: number };
 
 export type ChildFailure =
+  | {
+      kind: "execution-limit";
+      code: "child-turn-limit" | "child-context-limit";
+    }
   | CandidateFailure
   | {
       kind: "transport";
@@ -249,10 +261,35 @@ export type VerificationClassification =
   | "expected-green"
   | "expected-refactor";
 
+/** Runtime-owned evidence; unavailable checks never become product baselines. */
+export interface VerificationEvidence {
+  id: string;
+  exitCode: number;
+  classification: VerificationClassification;
+  tests?: number;
+  failureIdentities: string[];
+  policy: "report-file-v3";
+}
+export type VerificationObservation =
+  | { kind: "accepted"; evidence: VerificationEvidence }
+  | {
+      kind: "rejected";
+      code: "red-not-witnessed" | "verification-rejected";
+      evidence: VerificationEvidence;
+    }
+  | {
+      kind: "unavailable";
+      category: "environment" | "adapter" | "resource";
+      code: string;
+      verificationId: string;
+    }
+  | { kind: "cancelled" };
+
 interface VerificationBase {
   id: string;
   classification: VerificationClassification;
   expectedFailure?: string;
+  executionBindings?: Record<string, string | null>;
 }
 
 export type PackageManager = "bun" | "npm" | "pnpm" | "yarn";
@@ -338,6 +375,7 @@ export interface PhaseBoundary {
 }
 
 export interface TaskBoundary {
+  verificationMode?: "behavior" | "mechanical" | "refactor";
   changeId: string;
   taskId: string;
   dependsOn: string[];
@@ -408,6 +446,9 @@ type ImplementGraphDiagnosticDetails = Partial<{
   producerTaskId: string;
   producerPhase: ImplementationPhase;
   dependencyTaskId: string;
+  field: string;
+  expectedPaths: string[];
+  actualPaths: string[];
 }>;
 
 export type ImplementGraphReadinessDiagnostic =
@@ -449,6 +490,10 @@ export interface PacketEnvelope {
   output: "evidence" | "diff";
 }
 
+// JSON-schema counterpart for model-visible path arguments; keep its behavior
+// checked against isValidRelativePath rather than hiding constraints in prose.
+export const RELATIVE_PATH_PATTERN = String.raw`^(?:\.|(?!/)(?![a-zA-Z]:/)(?!\./)(?![\s\S]*\.\.)(?![\s\S]*[\\\u0000])(?![\s\S]*//)(?![\s\S]*/\.(?:/|$))(?![\s\S]*/$)[\s\S]+)$`;
+
 export function isValidRelativePath(p: unknown): p is string {
   return (
     typeof p === "string" &&
@@ -512,7 +557,7 @@ function validScriptCommand(value: unknown): value is string {
     value.length > 0 &&
     value.length <= 1024 &&
     value.trim() === value &&
-    !UNSAFE_VERIFICATION_TOKEN.test(value)
+    !value.includes("\0")
   );
 }
 
@@ -575,6 +620,7 @@ function validateExecutableRunner(value: unknown): value is ExecutableRunner {
 
 function validateVitestRunner(value: ExecutableRunner): boolean {
   if (value.kind === "package-script") {
+    if (UNSAFE_VERIFICATION_TOKEN.test(value.command)) return false;
     const tokens = value.command.split(/\s+/u);
     return (
       tokens[0] === "vitest" ||
@@ -591,8 +637,23 @@ function validateAtomicVerification(
 ): value is AtomicVerificationContract {
   if (!value || typeof value !== "object" || Array.isArray(value)) return false;
   const contract = value as Record<string, unknown>;
-  const expectedFailure =
-    contract.classification === "expected-red" ? ["expectedFailure"] : [];
+  if (
+    contract.executionBindings !== undefined &&
+    (!contract.executionBindings ||
+      typeof contract.executionBindings !== "object" ||
+      Array.isArray(contract.executionBindings) ||
+      Object.entries(contract.executionBindings).some(
+        ([key, hash]) =>
+          !VERIFICATION_CONFIGURATION_PATHS.includes(key) ||
+          (hash !== null &&
+            (typeof hash !== "string" || !/^[a-f0-9]{64}$/u.test(hash))),
+      ))
+  )
+    return false;
+  const expectedFailure = [
+    ...(contract.classification === "expected-red" ? ["expectedFailure"] : []),
+    ...(contract.executionBindings === undefined ? [] : ["executionBindings"]),
+  ];
   if (contract.kind === "vitest") {
     const executableRunner = contract.runner as ExecutableRunner;
     return (
@@ -610,8 +671,8 @@ function validateAtomicVerification(
       validateExecutableRunner(contract.runner) &&
       validateVitestRunner(executableRunner) &&
       Array.isArray(contract.testFiles) &&
-      contract.testFiles.length > 0 &&
-      contract.testFiles.length <= 64 &&
+      contract.testFiles.length >= VERIFICATION_LIMITS.minTestFiles &&
+      contract.testFiles.length <= VERIFICATION_LIMITS.maxTestFiles &&
       contract.testFiles.every(isValidRelativePath) &&
       new Set(contract.testFiles).size === contract.testFiles.length &&
       validVerificationArgs(contract.args) &&
@@ -679,8 +740,8 @@ function validateStructuredVerification(
       String(contract.classification),
     ) ||
     !Array.isArray(contract.steps) ||
-    contract.steps.length === 0 ||
-    contract.steps.length > 8 ||
+    contract.steps.length < VERIFICATION_LIMITS.minSteps ||
+    contract.steps.length > VERIFICATION_LIMITS.maxSteps ||
     !contract.steps.every((step) => validateAtomicVerification(step))
   ) {
     return false;
@@ -719,6 +780,38 @@ export function verificationSteps(
     : [structuredClone(normalized.value)];
 }
 
+export const VERIFICATION_CONFIGURATION_PATHS: readonly string[] = [
+  "package.json",
+  "package-lock.json",
+  "npm-shrinkwrap.json",
+  "bun.lock",
+  "bun.lockb",
+  "pnpm-lock.yaml",
+  "yarn.lock",
+  ".npmrc",
+  ".yarnrc",
+  ".yarnrc.yml",
+  "bunfig.toml",
+  "pnpm-workspace.yaml",
+];
+
+export function verificationBoundInputPaths(
+  verification: VerificationContract,
+): string[] {
+  return [
+    ...new Set([
+      ...verificationInputPaths(verification),
+      ...verificationSteps(verification).flatMap((step) =>
+        step.kind === "vitest" ||
+        step.kind === "package-script" ||
+        ("runner" in step && step.runner.kind === "package-script")
+          ? VERIFICATION_CONFIGURATION_PATHS
+          : [],
+      ),
+    ]),
+  ];
+}
+
 export function verificationInputPaths(
   verification: VerificationContract,
 ): string[] {
@@ -976,6 +1069,7 @@ function isWithinRoots(path: string, roots: string[]): boolean {
 function validatePhaseBoundary(
   value: unknown,
   phase: ImplementationPhase,
+  mode: unknown = "behavior",
 ): value is PhaseBoundary {
   if (
     !hasExactKeys(
@@ -1002,7 +1096,10 @@ function validatePhaseBoundary(
   const verification = validateVerificationContract(value.verification);
   if (!verification.ok) return false;
   const classification = {
-    red: "expected-red",
+    red:
+      mode !== undefined && mode !== "behavior"
+        ? "expected-green"
+        : "expected-red",
     green: "expected-green",
     refactor: "expected-refactor",
   } as const;
@@ -1014,19 +1111,27 @@ function validateTaskBoundary(
   snapshot: unknown,
 ): value is TaskBoundary {
   if (
-    !hasExactKeys(value, [
-      "changeId",
-      "taskId",
-      "dependsOn",
-      "objective",
-      "context",
-      "roots",
-      "phases",
-      "scheduling",
-      "agents",
-      "approvedDependencies",
-      "impactClosure",
-    ]) ||
+    !hasExactKeys(
+      value,
+      [
+        "changeId",
+        "taskId",
+        "dependsOn",
+        "objective",
+        "context",
+        "roots",
+        "phases",
+        "scheduling",
+        "agents",
+        "approvedDependencies",
+        "impactClosure",
+      ],
+      ["verificationMode"],
+    ) ||
+    (value.verificationMode !== undefined &&
+      !["behavior", "mechanical", "refactor"].includes(
+        String(value.verificationMode),
+      )) ||
     !validIdentifier(value.changeId) ||
     !validIdentifier(value.taskId) ||
     !validateIdentifierSet(value.dependsOn) ||
@@ -1038,7 +1143,7 @@ function validateTaskBoundary(
     typeof value.context.contract !== "string" ||
     !validateRoots(value.roots) ||
     !hasExactKeys(value.phases, ["red", "green"], ["refactor"]) ||
-    !validatePhaseBoundary(value.phases.red, "red") ||
+    !validatePhaseBoundary(value.phases.red, "red", value.verificationMode) ||
     !validatePhaseBoundary(value.phases.green, "green") ||
     (value.phases.refactor !== undefined &&
       !validatePhaseBoundary(value.phases.refactor, "refactor")) ||
@@ -1109,6 +1214,9 @@ export type ImplementGraphContractDiagnostic =
       field?: string;
       category?: string;
       outputId?: string;
+      path?: string;
+      expectedPaths?: string[];
+      actualPaths?: string[];
     }
   | {
       code: "invalid-output-path";
@@ -1120,6 +1228,7 @@ export type ImplementGraphContractDiagnostic =
 function phaseBoundaryContractDiagnostic(
   value: unknown,
   phase: ImplementationPhase,
+  mode: unknown = "behavior",
 ): Omit<
   Extract<
     ImplementGraphContractDiagnostic,
@@ -1176,7 +1285,10 @@ function phaseBoundaryContractDiagnostic(
     };
   }
   const classification = {
-    red: "expected-red",
+    red:
+      mode !== undefined && mode !== "behavior"
+        ? "expected-green"
+        : "expected-red",
     green: "expected-green",
     refactor: "expected-refactor",
   } as const;
@@ -1227,22 +1339,33 @@ function taskBoundaryContractDiagnostic(
     category,
   });
   if (
-    !hasExactKeys(value, [
-      "changeId",
-      "taskId",
-      "dependsOn",
-      "objective",
-      "context",
-      "roots",
-      "phases",
-      "scheduling",
-      "agents",
-      "approvedDependencies",
-      "impactClosure",
-    ])
+    !hasExactKeys(
+      value,
+      [
+        "changeId",
+        "taskId",
+        "dependsOn",
+        "objective",
+        "context",
+        "roots",
+        "phases",
+        "scheduling",
+        "agents",
+        "approvedDependencies",
+        "impactClosure",
+      ],
+      ["verificationMode"],
+    )
   ) {
     return diagnostic("task", "shape");
   }
+  if (
+    value.verificationMode !== undefined &&
+    !["behavior", "mechanical", "refactor"].includes(
+      String(value.verificationMode),
+    )
+  )
+    return diagnostic("verificationMode", "shape");
   if (!validIdentifier(value.changeId)) {
     return diagnostic("changeId", "identifier");
   }
@@ -1275,7 +1398,11 @@ function taskBoundaryContractDiagnostic(
   for (const phase of IMPLEMENTATION_PHASES) {
     const boundary = value.phases[phase];
     if (phase === "refactor" && boundary === undefined) continue;
-    const phaseDiagnostic = phaseBoundaryContractDiagnostic(boundary, phase);
+    const phaseDiagnostic = phaseBoundaryContractDiagnostic(
+      boundary,
+      phase,
+      value.verificationMode,
+    );
     if (phaseDiagnostic)
       return { ...diagnostic("phases", "contract"), ...phaseDiagnostic };
   }
@@ -1348,6 +1475,26 @@ function taskBoundaryContractDiagnostic(
     snapshot,
   );
   if (impactReason !== null) {
+    if (impactReason === "current-task related test is outside the write set") {
+      const related = (value.impactClosure as ImpactClosureContract)
+        .relatedTests;
+      const index = related.findIndex(
+        (test) =>
+          test.disposition === "current-task" &&
+          !declared.write.includes(test.path),
+      );
+      const test = related[index];
+      if (test)
+        return {
+          ...diagnostic(
+            `impactClosure.relatedTests.${index}.disposition`,
+            "current-task-outside-write-set",
+          ),
+          path: test.path,
+          expectedPaths: [...declared.write].sort(),
+          actualPaths: [test.path],
+        };
+    }
     return diagnostic("impactClosure", impactClosureCategory(impactReason));
   }
   return validateTaskBoundary(value, snapshot)
@@ -1361,6 +1508,7 @@ export function validateImplementGraphBoundary(value: unknown):
       ok: false;
       reason: string;
       diagnostic: ImplementGraphContractDiagnostic;
+      diagnostics?: ImplementGraphContractDiagnostic[];
     } {
   if (
     !hasExactKeys(value, ["changeId", "tasks", "outputs"]) ||
@@ -1370,29 +1518,33 @@ export function validateImplementGraphBoundary(value: unknown):
     value.tasks.length > 128 ||
     !Array.isArray(value.outputs) ||
     value.outputs.length > 512
-  ) {
+  )
     return {
       ok: false,
       reason: "invalid Implement graph boundary",
       diagnostic: { code: "invalid-implement-graph" },
     };
-  }
 
+  // Collect independent task/output failures without admitting a partial graph.
+  const failures: Array<{
+    reason: string;
+    diagnostic: ImplementGraphContractDiagnostic;
+  }> = [];
   for (const candidate of value.tasks) {
     if (
       !candidate ||
       typeof candidate !== "object" ||
       Array.isArray(candidate)
     ) {
-      return {
-        ok: false,
+      failures.push({
         reason: "invalid Implement task boundary",
         diagnostic: {
           code: "invalid-implement-graph",
           field: "tasks",
           category: "shape",
         },
-      };
+      });
+      continue;
     }
     const task = candidate as Record<string, unknown>;
     const diagnostic = Object.hasOwn(task, "changeId")
@@ -1405,31 +1557,27 @@ export function validateImplementGraphBoundary(value: unknown):
           { changeId: value.changeId, ...task },
           undefined,
         );
-    if (diagnostic) {
-      return {
-        ok: false,
+    if (diagnostic)
+      failures.push({
         reason: "invalid Implement task boundary",
         diagnostic: { code: "invalid-implement-graph", ...diagnostic },
-      };
-    }
+      });
   }
-
   for (const candidate of value.outputs) {
     if (
       !candidate ||
       typeof candidate !== "object" ||
       Array.isArray(candidate)
     ) {
-      return {
-        ok: false,
+      failures.push({
         reason: "invalid Implement graph output",
         diagnostic: { code: "invalid-implement-graph" },
-      };
+      });
+      continue;
     }
     const output = candidate as Record<string, unknown>;
     if (!isValidRelativePath(output.path)) {
-      return {
-        ok: false,
+      failures.push({
         reason: "invalid Implement graph output path",
         diagnostic: {
           code: "invalid-output-path",
@@ -1437,7 +1585,8 @@ export function validateImplementGraphBoundary(value: unknown):
           field: "outputs.path",
           category: "path",
         },
-      };
+      });
+      continue;
     }
     if (
       !hasExactKeys(output, ["id", "path", "producer", "postcondition"]) ||
@@ -1449,8 +1598,7 @@ export function validateImplementGraphBoundary(value: unknown):
       ) ||
       output.postcondition !== "regular-file"
     ) {
-      return {
-        ok: false,
+      failures.push({
         reason: "invalid Implement graph output",
         diagnostic: {
           code: "invalid-implement-graph",
@@ -1458,10 +1606,18 @@ export function validateImplementGraphBoundary(value: unknown):
           field: "outputs",
           category: "shape",
         },
-      };
+      });
     }
   }
-
+  const first = failures[0];
+  if (first)
+    return {
+      ok: false,
+      ...first,
+      ...(failures.length > 1
+        ? { diagnostics: failures.map((failure) => failure.diagnostic) }
+        : {}),
+    };
   return {
     ok: true,
     value: structuredClone(value) as unknown as ImplementGraphBoundary,
@@ -1868,6 +2024,24 @@ export interface DiffResult {
   contractCompliant: boolean;
 }
 
+// Diagnostics contain only code-owned field names, never unexpected keys or values.
+function evidenceFieldsFailure(
+  value: unknown,
+  fields: readonly string[],
+  location: string,
+): { ok: false; reason: string } {
+  if (!value || typeof value !== "object" || Array.isArray(value))
+    return { ok: false, reason: `${location}: expected an object` };
+  const missing = fields.filter((field) => !Object.hasOwn(value, field));
+  return {
+    ok: false,
+    reason:
+      missing.length > 0
+        ? `${location}: missing fields ${missing.join(", ")}`
+        : `${location}: unexpected fields; allowed fields ${fields.join(", ")}`,
+  };
+}
+
 export function validateEvidenceResult(value: unknown): {
   ok: boolean;
   reason?: string;
@@ -1891,7 +2065,7 @@ export function validateEvidenceResult(value: unknown): {
     "hints",
   ] as const;
   if (!hasExactKeys(r, fields)) {
-    return { ok: false, reason: "invalid evidence result fields" };
+    return evidenceFieldsFailure(r, fields, "result");
   }
   if (!validIdentifier(r.id) || typeof r.role !== "string")
     return { ok: false, reason: "invalid identity" };
@@ -1911,25 +2085,38 @@ export function validateEvidenceResult(value: unknown): {
       return { ok: false, reason: `invalid evidence field: ${field}` };
     }
   }
-  if (
-    !Array.isArray(r.citations) ||
-    r.citations.some(
-      (citation) =>
-        !hasExactKeys(citation, ["path", "lines"]) ||
-        !isValidRelativePath(citation.path) ||
-        typeof citation.lines !== "string",
-    )
-  ) {
-    return { ok: false, reason: "invalid evidence citations" };
-  }
-  if (
-    !hasExactKeys(r.hints, ["writeSet", "verification", "agentsImpact"]) ||
-    !validatePathSet(r.hints.writeSet) ||
-    typeof r.hints.verification !== "string" ||
-    !(AGENTS_IMPACTS as readonly unknown[]).includes(r.hints.agentsImpact)
-  ) {
-    return { ok: false, reason: "invalid evidence hints" };
-  }
+  if (!Array.isArray(r.citations))
+    return { ok: false, reason: "citations: expected an array" };
+  for (const [index, citation] of r.citations.entries()) {
+    const field = `citations[${index}]`;
+    if (!hasExactKeys(citation, ["path", "lines"]))
+      return evidenceFieldsFailure(citation, ["path", "lines"], field);
+    if (!isValidRelativePath(citation.path))
+      return {
+        ok: false,
+        reason: `${field}.path: expected a canonical relative path`,
+      };
+    if (typeof citation.lines !== "string")
+      return { ok: false, reason: `${field}.lines: expected a string` };
+  }
+  if (!hasExactKeys(r.hints, ["writeSet", "verification", "agentsImpact"]))
+    return evidenceFieldsFailure(
+      r.hints,
+      ["writeSet", "verification", "agentsImpact"],
+      "hints",
+    );
+  if (!validatePathSet(r.hints.writeSet))
+    return {
+      ok: false,
+      reason: "hints.writeSet: expected unique canonical relative paths",
+    };
+  if (typeof r.hints.verification !== "string")
+    return { ok: false, reason: "hints.verification: expected a string" };
+  if (!(AGENTS_IMPACTS as readonly unknown[]).includes(r.hints.agentsImpact))
+    return {
+      ok: false,
+      reason: `hints.agentsImpact: expected one of ${AGENTS_IMPACTS.join(", ")}`,
+    };
   const serialized = JSON.stringify(r);
   if (Buffer.byteLength(serialized, "utf8") > LIMITS.maxCompleteResultBytes) {
     return {
@@ -1970,36 +2157,65 @@ function validateDesignEvidenceResult(r: Record<string, unknown>): {
     "success_criteria_hints",
   ] as const;
   if (!hasExactKeys(r, fields)) {
-    return { ok: false, reason: "invalid Design evidence result fields" };
-  }
-  if (
-    !validIdentifier(r.id) ||
-    r.packet_id !== r.id ||
-    !isValidRelativePath(r.module_name)
-  ) {
-    return { ok: false, reason: "invalid Design evidence identity" };
+    return evidenceFieldsFailure(r, fields, "result");
   }
+  if (!validIdentifier(r.id))
+    return { ok: false, reason: "id: expected a valid identifier" };
+  if (r.packet_id !== r.id)
+    return { ok: false, reason: "packet_id: must equal id" };
+  if (!isValidRelativePath(r.module_name))
+    return {
+      ok: false,
+      reason: "module_name: expected a canonical relative path or module slug",
+    };
   if (!validatePathSet(r.scope) || r.scope.length === 0) {
-    return { ok: false, reason: "invalid Design evidence scope" };
+    return {
+      ok: false,
+      reason:
+        "scope: expected a nonempty set of unique canonical relative paths",
+    };
   }
-  if (!validatePathSet(r.files_read) || !validatePathSet(r.write_set_hints)) {
-    return { ok: false, reason: "invalid Design evidence path set" };
+  for (const field of ["files_read", "write_set_hints"] as const) {
+    if (!validatePathSet(r[field]))
+      return {
+        ok: false,
+        reason: `${field}: expected unique canonical relative paths`,
+      };
   }
-  if (
-    !Array.isArray(r.evidence) ||
-    r.evidence.some(
-      (entry) =>
-        !hasExactKeys(entry, ["claim", "path", "line_start", "line_end"]) ||
-        typeof entry.claim !== "string" ||
-        entry.claim.length === 0 ||
-        !isValidRelativePath(entry.path) ||
-        !Number.isSafeInteger(entry.line_start) ||
-        !Number.isSafeInteger(entry.line_end) ||
-        (entry.line_start as number) < 1 ||
-        (entry.line_end as number) < (entry.line_start as number),
+  if (!Array.isArray(r.evidence))
+    return { ok: false, reason: "evidence: expected an array" };
+  for (const [index, entry] of r.evidence.entries()) {
+    const field = `evidence[${index}]`;
+    if (!hasExactKeys(entry, ["claim", "path", "line_start", "line_end"])) {
+      return evidenceFieldsFailure(
+        entry,
+        ["claim", "path", "line_start", "line_end"],
+        field,
+      );
+    }
+    if (typeof entry.claim !== "string" || entry.claim.length === 0)
+      return { ok: false, reason: `${field}.claim: expected nonempty text` };
+    if (!isValidRelativePath(entry.path))
+      return {
+        ok: false,
+        reason: `${field}.path: expected a canonical relative path`,
+      };
+    if (
+      !Number.isSafeInteger(entry.line_start) ||
+      (entry.line_start as number) < 1
     )
-  ) {
-    return { ok: false, reason: "invalid Design evidence citations" };
+      return {
+        ok: false,
+        reason: `${field}.line_start: expected a positive safe integer`,
+      };
+    if (
+      !Number.isSafeInteger(entry.line_end) ||
+      (entry.line_end as number) < (entry.line_start as number)
+    )
+      return {
+        ok: false,
+        reason: `${field}.line_end: expected a safe integer >= line_start`,
+      };
   }
   for (const field of [
     "existing_structures",