@dzhechkov/harness-core 0.5.0 → 0.5.2

package/src/parity.ts

@@ -99,6 +99,18 @@ export interface CapabilityEvidence {
   readonly kind: 'transcript' | 'reproducer';
   /** ISO date the evidence was produced. Stale evidence is still evidence — silence is not. */
   readonly at: string;
+  /**
+   * The RUNTIME VERSION the evidence was measured on, verbatim from the runtime's own `--version`
+   * (e.g. `codex-cli 0.147.0`).
+   *
+   * ADR-006 pins capability grants to a runtime version, and the gate enforced only that a record
+   * existed and its file was on disk — so evidence recorded on codex 0.147 kept a grant alive on
+   * the installed 0.148 (independent review, finding 3). A hook registry is exactly the kind of
+   * surface a minor version moves. When this is set and the caller supplies a PROBED version that
+   * differs, the grant is reported `stale-runtime-version` — INCONCLUSIVE, not revoked: the fix is
+   * a fresh probe, and an absent probe flips nothing.
+   */
+  readonly runtimeVersion?: string;
 }
 
 export const CAPABILITY_EVIDENCE: Record<TargetName, Partial<Record<RuntimeCapability, CapabilityEvidence>>> = {
@@ -119,15 +131,28 @@ export const CAPABILITY_EVIDENCE: Record<TargetName, Partial<Record<RuntimeCapab
     mcp: { evidence: 'codex mcp list', kind: 'reproducer', at: '2026-07-19' },
     // The two-sided live block: our marker in the transcript AND the sentinel side effect absent,
     // in a NON-bypassed run, with the entry reported `trusted` by codex's own `hooks/list`.
+    // RE-PROBED on the installed runtime at the independent-QE fix round (review finding 3): the
+    // 0.147.0 evidence was stale on a machine running 0.148.0, and re-running it was NOT a
+    // formality — the arming path had silently stopped working, because `hooks/list` spells its
+    // `eventName` field `preToolUse` on 0.148 while the trust KEY still says `pre_tool_use`.
+    // All four legs pass on 0.148.0 with the trust axis PARSED from `hooks/list` rather than
+    // hard-coded (the pre-fix grader asserted `trustStatus: 'trusted'` as a constant).
     'hooks-shell': {
-      evidence: 'features/crossrt-2-codex-hooks/07_code_changes/probe-results/veto-armed.txt',
+      evidence: 'features/crossrt-2-codex-hooks/07_code_changes/probe-results/fixround/veto-armed.txt',
       kind: 'transcript',
       at: '2026-08-19',
+      runtimeVersion: 'codex-cli 0.148.0',
     },
+    // NOT re-probed on 0.148: the recall canary is a separate live run (forced hit + removed twin)
+    // and this round did not execute it. The version it was measured on is recorded HONESTLY, so
+    // `findUnbackedCapabilities` reports it `stale-runtime-version` — INCONCLUSIVE — the moment a
+    // caller supplies the probed 0.148.0. That is the correct state: the grant is not withdrawn,
+    // it is awaiting its re-probe.
     'hooks-prompt': {
       evidence: 'features/crossrt-2-codex-hooks/07_code_changes/probe-results/recall-canary.md',
       kind: 'transcript',
       at: '2026-08-19',
+      runtimeVersion: 'codex-cli 0.147.0',
     },
   },
   opencode: { shell: { evidence: 'adapter emit', kind: 'reproducer', at: '2026-07-19' }, skills: { evidence: 'dz compose --target opencode', kind: 'reproducer', at: '2026-07-19' } },
@@ -143,10 +168,23 @@ export const CAPABILITY_EVIDENCE: Record<TargetName, Partial<Record<RuntimeCapab
 export interface UnbackedCapability {
   readonly target: TargetName;
   readonly capability: RuntimeCapability;
-  readonly reason: 'no-evidence-record' | 'dangling-transcript';
+  /**
+   * `stale-runtime-version` is INCONCLUSIVE, not a refutation: the grant was proven, on a runtime
+   * that is no longer the installed one. It clears when a current-version probe is recorded.
+   */
+  readonly reason: 'no-evidence-record' | 'dangling-transcript' | 'stale-runtime-version';
   readonly evidence?: string;
+  /** `recorded → probed`, for the stale case. */
+  readonly recordedVersion?: string;
+  readonly probedVersion?: string;
 }
 
+/**
+ * Runtime versions observed NOW, keyed by target — injected, never probed here (this module is
+ * pure). An absent entry means "not probed", which flips nothing.
+ */
+export type ProbedRuntimeVersions = Partial<Record<TargetName, string>>;
+
 /**
  * Every capability grant that is NOT backed by usable evidence.
  *
@@ -159,6 +197,7 @@ export function findUnbackedCapabilities(
   transcriptExists: (path: string) => boolean,
   capabilities: Record<TargetName, readonly RuntimeCapability[]> = TARGET_CAPABILITIES,
   evidence: Record<TargetName, Partial<Record<RuntimeCapability, CapabilityEvidence>>> = CAPABILITY_EVIDENCE,
+  probedVersions: ProbedRuntimeVersions = {},
 ): UnbackedCapability[] {
   const out: UnbackedCapability[] = [];
   for (const target of Object.keys(capabilities) as TargetName[]) {
@@ -170,12 +209,112 @@ export function findUnbackedCapabilities(
       }
       if (record.kind === 'transcript' && !transcriptExists(record.evidence)) {
         out.push({ target, capability, reason: 'dangling-transcript', evidence: record.evidence });
+        continue;
+      }
+      // Version pin (ADR-006, finding 3). Only fires when BOTH sides are known: an unprobed target
+      // stays silent rather than reporting every grant stale on a machine without the runtime.
+      const probed = probedVersions[target];
+      if (record.runtimeVersion !== undefined && probed !== undefined && probed !== record.runtimeVersion) {
+        out.push({
+          target,
+          capability,
+          reason: 'stale-runtime-version',
+          evidence: record.evidence,
+          recordedVersion: record.runtimeVersion,
+          probedVersion: probed,
+        });
       }
     }
   }
   return out;
 }
 
+/**
+ * Compare two recorded runtime versions the way a version string means it.
+ *
+ * `null` when the two are not comparable (different product, unparseable) — which the caller reads
+ * as "not the newest", the conservative direction.
+ */
+function compareRuntimeVersions(a: string, b: string): number | null {
+  const parse = (v: string): { product: string; parts: number[] } | null => {
+    const m = /^(.*?)\s*(\d+(?:\.\d+)*)\s*$/.exec(v.trim());
+    if (m === null) return null;
+    return { product: (m[1] ?? '').trim(), parts: (m[2] ?? '').split('.').map((n) => Number(n)) };
+  };
+  const pa = parse(a);
+  const pb = parse(b);
+  if (pa === null || pb === null || pa.product !== pb.product) return null;
+  const len = Math.max(pa.parts.length, pb.parts.length);
+  for (let i = 0; i < len; i += 1) {
+    const x = pa.parts[i] ?? 0;
+    const y = pb.parts[i] ?? 0;
+    if (x !== y) return x < y ? -1 : 1;
+  }
+  return 0;
+}
+
+/**
+ * The newest runtime version recorded among a target's TRANSCRIPT evidence, or `null`.
+ *
+ * This is what makes staleness detectable WITHOUT running anything: the records date themselves
+ * against each other. `dz parity` computes a matrix and must keep doing so deterministically — a
+ * `codex --version` subprocess inside it would make a pure report depend on the machine it prints
+ * on. Re-probing one capability is what dates the others (fix round 2, R2-3).
+ */
+export function newestRecordedRuntimeVersion(
+  target: TargetName,
+  evidence: Record<TargetName, Partial<Record<RuntimeCapability, CapabilityEvidence>>> = CAPABILITY_EVIDENCE,
+): string | null {
+  let newest: string | null = null;
+  for (const record of Object.values(evidence[target] ?? {})) {
+    if (record === undefined || record.kind !== 'transcript' || record.runtimeVersion === undefined) continue;
+    if (newest === null) {
+      newest = record.runtimeVersion;
+      continue;
+    }
+    const cmp = compareRuntimeVersions(newest, record.runtimeVersion);
+    if (cmp !== null && cmp < 0) newest = record.runtimeVersion;
+  }
+  return newest;
+}
+
+/**
+ * Transcript evidence that is out of date with the newest record for its own target.
+ *
+ * SCOPE, stated because it is a judgement and not a derivation: the version rule applies to
+ * `kind: 'transcript'` records only. A transcript FREEZES one runtime moment, so it can go stale; a
+ * `reproducer` is a command anyone can re-run, and calling it stale would report `dz --version` as
+ * expired. A transcript with NO `runtimeVersion` is stale too — an undated observation cannot be
+ * shown to be current.
+ *
+ * INCONCLUSIVE, never a refutation: the grant is not withdrawn, it is awaiting its re-probe.
+ */
+export function findStaleTranscriptEvidence(
+  capabilities: Record<TargetName, readonly RuntimeCapability[]> = TARGET_CAPABILITIES,
+  evidence: Record<TargetName, Partial<Record<RuntimeCapability, CapabilityEvidence>>> = CAPABILITY_EVIDENCE,
+): UnbackedCapability[] {
+  const out: UnbackedCapability[] = [];
+  for (const target of Object.keys(capabilities) as TargetName[]) {
+    const newest = newestRecordedRuntimeVersion(target, evidence);
+    if (newest === null) continue; // nothing version-pinned on this target ⇒ nothing to be stale against
+    for (const capability of capabilities[target]) {
+      const record = evidence[target]?.[capability];
+      if (record === undefined || record.kind !== 'transcript') continue;
+      const recorded = record.runtimeVersion;
+      if (recorded !== undefined && compareRuntimeVersions(recorded, newest) === 0) continue;
+      out.push({
+        target,
+        capability,
+        reason: 'stale-runtime-version',
+        evidence: record.evidence,
+        ...(recorded !== undefined ? { recordedVersion: recorded } : {}),
+        probedVersion: newest,
+      });
+    }
+  }
+  return out;
+}
+
 /** How a feature manifests on a platform: a concrete FORM with its runtime requirements. */
 export interface FeatureForm {
   /** Human-readable name of the form, shown as the `via` of a parity cell (AM-2). */
@@ -329,6 +468,42 @@ export function computeParity(feature: ParityFeature, capabilities: readonly Run
   return { level: 'none' };
 }
 
+/**
+ * A parity cell AS REPORTED — the computed level, plus the one thing the computation cannot know:
+ * whether the evidence behind the deciding capability is still current.
+ *
+ * `inconclusive` is a REPORTING level, not a model level: `computeParity` keeps answering the
+ * capability question, and this layer answers the evidence question. Keeping them apart is what
+ * lets the matrix stay a pure function of the capability model.
+ */
+export interface ParityReportCell {
+  readonly level: 'full' | 'manual' | 'none' | 'inconclusive';
+  readonly via?: string | undefined;
+  /** The stale capabilities the deciding form depends on (present only when `inconclusive`). */
+  readonly staleEvidence?: readonly RuntimeCapability[];
+}
+
+/**
+ * Downgrade a cell whose DECIDING form rests on stale evidence to `inconclusive`.
+ *
+ * The round-1 gate could tell that `hooks-prompt` evidence was stale and nothing a user runs ever
+ * asked it (fix round 2, R2-3): `dz parity` printed `full` for the auto-recall leg on codex off a
+ * transcript recorded on a runtime that is no longer installed. A cell that says `full` on evidence
+ * nobody has re-confirmed is the same class of claim this whole feature exists to refuse.
+ */
+export function downgradeForStaleEvidence(
+  feature: ParityFeature,
+  cell: ParityCell,
+  staleCapabilities: readonly RuntimeCapability[],
+): ParityReportCell {
+  if (cell.level === 'none' || cell.via === undefined || staleCapabilities.length === 0) return cell;
+  const form = feature.forms.find((f) => f.form === cell.via);
+  if (form === undefined) return cell;
+  const hit = form.requires.filter((r) => staleCapabilities.includes(r));
+  if (hit.length === 0) return cell;
+  return { level: 'inconclusive', via: cell.via, staleEvidence: hit };
+}
+
 export interface ParityMatrixRow {
   readonly feature: ParityFeature;
   readonly cells: Readonly<Record<TargetName, ParityCell>>;