comisai 1.0.42 → 1.0.44

package/node_modules/@comis/agent/dist/memory/benchmark/beam-scorer.js

@@ -0,0 +1,77 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Pure per-ability BEAM recall@k scorer.
+ *
+ * THE METRIC: given the planted per-ability needles (each a `{ability, query,
+ * goldDocId}`) and the LIVE ranked recall result per needle (keyed by the needle's
+ * `query`), group the needles by ability and macro-average recall@1/3/5 + MRR PER
+ * ABILITY (and once overall) — the long-context per-ability aggregation axis BEAM
+ * exposes. A high per-ability recall@k is good; a low one shows where recall degrades
+ * at scale for that ability class.
+ *
+ * REUSE, DON'T REIMPLEMENT (the cut-clean seam): recall@k / MRR are computed by
+ * {@link scoreRanking} from `../recall-eval.js` — the SAME deterministic IR scorer
+ * the retrieval harness uses. This module only GROUPS needles into per-ability
+ * {@link EvalQuery} lists (each carrying `relevantIds = [goldDocId]`) and supplies a
+ * sync `rankFn` closure reading the `rankedByNeedle` memo, exactly as
+ * retrieval-harness.bench.test.ts scores recall.
+ *
+ * PURE: no clock, no I/O, no @comis/memory import — mirrors recall-eval.ts. The gated
+ * harness (beam-harness.bench.test.ts) feeds it the per-needle ranked results from the
+ * live recall pipeline; the unit test pins the math.
+ *
+ * SECURITY — prototype-pollution discipline (sibling of qa-accuracy.ts): although the
+ * ability keys are a fixed string-literal union, the `perAbility` map is materialized
+ * on an `Object.create(null)` map with literal-keyed writes, so even an unexpected key
+ * can never mutate `Object.prototype`.
+ *
+ * @module
+ */
+import { scoreRanking } from "../recall-eval.js";
+/**
+ * Build the {@link EvalQuery} list for a set of needles, with a `rankFn`-readable
+ * memo: each needle becomes one EvalQuery whose `relevantIds = [goldDocId]` and whose
+ * `query` is the memo key the rankFn reads. `group` is a fixed valid tag —
+ * `scoreRanking` ignores it (it reads only `relevantIds` + the rankFn result).
+ */
+function toEvalQueries(needles) {
+    return needles.map((n) => ({
+        group: "reranking",
+        query: n.query,
+        candidates: [], // unused by scoreRanking — the rankFn supplies the ranked list
+        relevantIds: [n.goldDocId],
+    }));
+}
+/**
+ * Score per-ability + overall recall@k over the planted needles.
+ *
+ * Groups `needles` by ability (on a null-prototype map), then for each ability calls
+ * {@link scoreRanking} over that ability's {@link EvalQuery} list with a sync `rankFn`
+ * that reads `rankedByNeedle.get(query)` (the live ranked result for that needle); the
+ * overall metrics fold ALL needles. An empty `needles` yields an empty `perAbility`
+ * and a zeroed (never-NaN) `overall` — `scoreRanking([])` returns all-zero metrics.
+ *
+ * PURE: no I/O, no @comis/memory. Reuses `scoreRanking` — does NOT reimplement recall@k.
+ */
+export function scoreBeam(needles, rankedByNeedle) {
+    // The sync rankFn reads the live ranked result by the needle's query (the memo key).
+    const rankFn = (q) => rankedByNeedle.get(q.query) ?? [];
+    // Group needles by ability on a null-prototype accumulator (prototype-pollution-safe
+    // even though the ability keys are a fixed union).
+    const byAbility = Object.create(null);
+    for (const n of needles) {
+        // Literal-keyed write on the null-proto map — never a prototype mutation.
+        (byAbility[n.ability] ??= []).push(n);
+    }
+    // Materialize per-ability metrics onto a fresh null-prototype map.
+    const perAbility = Object.create(null);
+    for (const ability of Object.keys(byAbility)) {
+        // `Object.keys` yields only present keys; the project does not set
+        // noUncheckedIndexedAccess, so the indexed access is a defined BeamNeedle[].
+        perAbility[ability] = scoreRanking(toEvalQueries(byAbility[ability]), rankFn);
+    }
+    return {
+        perAbility,
+        overall: scoreRanking(toEvalQueries(needles), rankFn),
+    };
+}

package/node_modules/@comis/agent/dist/memory/benchmark/competitor-adapter.d.ts

@@ -0,0 +1,165 @@
+/**
+ * The uniform competitor-adapter layer — the single contract the one
+ * head-to-head runner drives across every memory system it compares.
+ *
+ * WHAT THIS IS: a `CompetitorAdapter` interface (`run(tier, config) ->
+ * AdapterResult`), a `skipWithDisclosure` helper, and skip-with-disclosure
+ * SKELETON adapters for mem0 / zep / hindsight / mnemosyne. The `letta-fs-baseline`
+ * adapter (the one that actually runs keyless at $0) lives in its sibling
+ * `letta-fs-baseline-adapter.ts`.
+ *
+ * THE LOAD-BEARING INTEGRITY INVARIANT (the reason this layer exists at all): an
+ * absent competitor system (no key / not installed / no sibling clone) degrades
+ * GRACEFULLY to a skip — `{ ran:false, skipped:true, system, reason, disclosure }`
+ * — a shape that carries NO score field. {@link AdapterResult} is a DISCRIMINATED
+ * UNION whose `ran:false` arm has no `accuracy`/`overall`/`score`/`manifestRef`,
+ * so it is structurally IMPOSSIBLE for an absent system to fabricate a number
+ * (CONTEXT.md decision 4; the anti-fabrication threat). The keyless CI
+ * always hits the skip branch (no env, no install) — that IS the wiring proof; the
+ * operator-costed run (keys + competitor installs + LLM spend) fills the real
+ * numbers in a costed re-run, honestly deferred.
+ *
+ * SUPPLY-CHAIN HARD CONSTRAINT (CLAUDE.md "Supply-chain invariants" + AGENTS.md):
+ * mem0 / zep / hindsight / mnemosyne (and any future competitor) are NEVER added to
+ * any `packages/*\/package.json`. All deps are exact-pinned; `@comis/*` are
+ * private:true + bundled. These skeletons import NOTHING from a competitor package
+ * — they PROBE presence (an injectable predicate) and SKIP. Competitors are
+ * operator/external installs (mem0/zep external; hindsight/mnemosyne are sibling
+ * clones `../hindsight`, `../mnemosyne`). competitor-adapter.test.ts Test 5
+ * statically reads every manifest and asserts no competitor specifier is present.
+ *
+ * GLOBALS DISCIPLINE (globals.test.ts forbids `process.env` in packages/*\/src):
+ * the presence probe is an INJECTED predicate. Its default is `() => false` — the
+ * keyless default always skips and this module reads ZERO environment variables.
+ * The operator wires a real env/path probe at call time (in their own non-src
+ * script or test, where `process.env` is permitted). This keeps the module pure
+ * and lets a test drive both branches deterministically.
+ *
+ * ARCHITECTURE: imports NOTHING — no @comis/memory (the agent↛memory cut), no
+ * competitor package. The live store + recall wiring lives ONLY in the gated
+ * `.bench.test.ts` (the single cut escape).
+ *
+ * @module
+ */
+/**
+ * The per-cell config the runner passes to an adapter for one (tier, system)
+ * cell. Kept minimal + OPEN (an index signature) so a future cell can carry
+ * extra tier-scoped knobs WITHOUT changing this contract — the runner and each
+ * adapter agree on the keys they use; unknown keys are ignored by an adapter that
+ * does not need them.
+ */
+export interface AdapterConfig {
+    /** The benchmark tier this cell runs (e.g. "j1", "suite-04"). */
+    readonly tier: string;
+    /**
+     * Optional per-cell haystack the letta-fs control dumps as its full-context
+     * baseline. Declared so a caller passing the one structured key the
+     * shipped control consumes gets compiler-checked, while the open extension point
+     * below still admits future tier-scoped knobs. The adapter STILL re-validates
+     * this at runtime via a total `coerceDocs` (the config can arrive from a
+     * non-typed JS caller), so a wrong shape degrades to an empty haystack, never a
+     * crash.
+     */
+    readonly docs?: ReadonlyArray<{
+        content: string;
+        createdAt: number;
+    }>;
+    /** Open extension point — extra per-cell, tier-scoped knobs (never a secret). */
+    readonly [key: string]: unknown;
+}
+/**
+ * The result of running ONE (tier, system) cell — a DISCRIMINATED UNION.
+ *
+ * The `ran:true` arm links the cell to its committed manifest (the number lives
+ * in the manifest, read back from disk and asserted before it is ever quoted —
+ * the honesty protocol). The `ran:false` arm is the skip-with-disclosure shape
+ * and carries NO score field of any name — an absent system can never fabricate a
+ * number. Code that consumes a result MUST narrow on `ran` before reading either
+ * arm's fields (the compiler enforces it).
+ */
+export type AdapterResult = {
+    /** The cell ran a real, valid==0 measurement. */
+    readonly ran: true;
+    /** Which system produced this cell. */
+    readonly system: string;
+    /** True for the letta-fs-baseline control row — NEVER Comis's headline. */
+    readonly isControl: boolean;
+    /** The cell -> committed-manifest link (the number lives in the manifest). */
+    readonly manifestRef: string;
+    /**
+     * The observed character length of the context the cell actually rendered.
+     * This makes the cell's keyless work LOAD-BEARING: the letta-fs
+     * control records the length of its full-dump formatted context here, so the
+     * format call cannot be deleted as dead code without a behavioural change.
+     * NOT a score — a digest of the work done. Absent on cells that render no
+     * in-harness context (the real number lives in the committed manifest).
+     */
+    readonly contextChars?: number;
+} | {
+    /** The cell was NOT run (system/keys absent) — this arm has NO score. */
+    readonly ran: false;
+    /** Always true on this arm (the explicit skip discriminant). */
+    readonly skipped: true;
+    /** Which system was absent. */
+    readonly system: string;
+    /** A short machine-ish reason (e.g. "mem0 not detected"). */
+    readonly reason: string;
+    /** An ACTIONABLE disclosure: the env var / install / clone path to enable this cell. */
+    readonly disclosure: string;
+};
+/**
+ * The uniform adapter the single head-to-head runner drives across every system
+ * it compares. One method, `run`, returns an {@link AdapterResult} — either a
+ * ran-manifest link or a skip-with-disclosure. The runner never special-cases a
+ * system; it iterates adapters and records each cell's result.
+ */
+export interface CompetitorAdapter {
+    /** The system this adapter represents (e.g. "mem0", "letta-fs-baseline"). */
+    readonly system: string;
+    /** True only for a control adapter (letta-fs-baseline) — never Comis's headline. */
+    readonly isControl?: boolean;
+    /** Run ONE cell for `tier` under `config`; degrade to skip-with-disclosure if absent. */
+    run(tier: string, config: AdapterConfig): Promise<AdapterResult>;
+}
+/**
+ * Build the skip-with-disclosure result for an absent system. ALWAYS returns the
+ * `ran:false` arm — NEVER a number. This is the single constructor for the
+ * anti-fabrication shape; every skeleton adapter routes its absent path through
+ * here so the invariant cannot be bypassed by a hand-built object.
+ */
+export declare function skipWithDisclosure(system: string, reason: string, disclosure: string): AdapterResult;
+/**
+ * Options shared by every skeleton adapter. The ONLY behavioural knob is the
+ * presence probe — an injectable predicate that reports whether the operator's
+ * environment has this competitor system wired (keys + install/clone). Its
+ * default is `() => false`, so the keyless default ALWAYS skips and this module
+ * reads no environment. The operator passes a real probe (which may read
+ * `process.env` / check a clone path) at call time from a non-src caller.
+ */
+export interface SkeletonAdapterOptions {
+    /** Reports whether this competitor system is wired. Default: `() => false` (keyless skip). */
+    readonly isPresent?: () => boolean;
+}
+/**
+ * mem0 skeleton. Absent by default → skip-with-disclosure naming the
+ * env var AND the install. mem0 is an EXTERNAL package + a hosted key — NEVER a
+ * Comis dependency (supply-chain invariant).
+ */
+export declare function createMem0Adapter(options?: SkeletonAdapterOptions): CompetitorAdapter;
+/**
+ * zep skeleton. Absent by default → skip-with-disclosure naming the
+ * env var / account. zep is an EXTERNAL service + SDK — NEVER a Comis dependency.
+ */
+export declare function createZepAdapter(options?: SkeletonAdapterOptions): CompetitorAdapter;
+/**
+ * hindsight skeleton. Absent by default → skip-with-disclosure naming
+ * the SIBLING-CLONE path. hindsight is a sibling clone (`../hindsight`) the
+ * operator builds — NEVER a Comis dependency.
+ */
+export declare function createHindsightAdapter(options?: SkeletonAdapterOptions): CompetitorAdapter;
+/**
+ * mnemosyne skeleton. Absent by default → skip-with-disclosure naming
+ * the SIBLING-CLONE path. mnemosyne is a sibling clone (`../mnemosyne`) the
+ * operator builds — NEVER a Comis dependency.
+ */
+export declare function createMnemosyneAdapter(options?: SkeletonAdapterOptions): CompetitorAdapter;

package/node_modules/@comis/agent/dist/memory/benchmark/competitor-adapter.js

@@ -0,0 +1,108 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * The uniform competitor-adapter layer — the single contract the one
+ * head-to-head runner drives across every memory system it compares.
+ *
+ * WHAT THIS IS: a `CompetitorAdapter` interface (`run(tier, config) ->
+ * AdapterResult`), a `skipWithDisclosure` helper, and skip-with-disclosure
+ * SKELETON adapters for mem0 / zep / hindsight / mnemosyne. The `letta-fs-baseline`
+ * adapter (the one that actually runs keyless at $0) lives in its sibling
+ * `letta-fs-baseline-adapter.ts`.
+ *
+ * THE LOAD-BEARING INTEGRITY INVARIANT (the reason this layer exists at all): an
+ * absent competitor system (no key / not installed / no sibling clone) degrades
+ * GRACEFULLY to a skip — `{ ran:false, skipped:true, system, reason, disclosure }`
+ * — a shape that carries NO score field. {@link AdapterResult} is a DISCRIMINATED
+ * UNION whose `ran:false` arm has no `accuracy`/`overall`/`score`/`manifestRef`,
+ * so it is structurally IMPOSSIBLE for an absent system to fabricate a number
+ * (CONTEXT.md decision 4; the anti-fabrication threat). The keyless CI
+ * always hits the skip branch (no env, no install) — that IS the wiring proof; the
+ * operator-costed run (keys + competitor installs + LLM spend) fills the real
+ * numbers in a costed re-run, honestly deferred.
+ *
+ * SUPPLY-CHAIN HARD CONSTRAINT (CLAUDE.md "Supply-chain invariants" + AGENTS.md):
+ * mem0 / zep / hindsight / mnemosyne (and any future competitor) are NEVER added to
+ * any `packages/*\/package.json`. All deps are exact-pinned; `@comis/*` are
+ * private:true + bundled. These skeletons import NOTHING from a competitor package
+ * — they PROBE presence (an injectable predicate) and SKIP. Competitors are
+ * operator/external installs (mem0/zep external; hindsight/mnemosyne are sibling
+ * clones `../hindsight`, `../mnemosyne`). competitor-adapter.test.ts Test 5
+ * statically reads every manifest and asserts no competitor specifier is present.
+ *
+ * GLOBALS DISCIPLINE (globals.test.ts forbids `process.env` in packages/*\/src):
+ * the presence probe is an INJECTED predicate. Its default is `() => false` — the
+ * keyless default always skips and this module reads ZERO environment variables.
+ * The operator wires a real env/path probe at call time (in their own non-src
+ * script or test, where `process.env` is permitted). This keeps the module pure
+ * and lets a test drive both branches deterministically.
+ *
+ * ARCHITECTURE: imports NOTHING — no @comis/memory (the agent↛memory cut), no
+ * competitor package. The live store + recall wiring lives ONLY in the gated
+ * `.bench.test.ts` (the single cut escape).
+ *
+ * @module
+ */
+/**
+ * Build the skip-with-disclosure result for an absent system. ALWAYS returns the
+ * `ran:false` arm — NEVER a number. This is the single constructor for the
+ * anti-fabrication shape; every skeleton adapter routes its absent path through
+ * here so the invariant cannot be bypassed by a hand-built object.
+ */
+export function skipWithDisclosure(system, reason, disclosure) {
+    return { ran: false, skipped: true, system, reason, disclosure };
+}
+/**
+ * Shared skeleton body: a competitor adapter whose `run` PROBES presence and
+ * either skips-with-disclosure (absent — the keyless default) or, when the
+ * operator's probe reports the system present, STILL skips with a
+ * "no runner wired here" disclosure (this layer has no costed runner — the real
+ * run is the operator-costed pass). It NEVER fabricates a `ran:true` with a
+ * number; the discriminated union makes that structurally impossible.
+ */
+function makeSkeletonAdapter(system, absentReason, absentDisclosure, presentDisclosure, options) {
+    const isPresent = options.isPresent ?? (() => false);
+    return {
+        system,
+        async run(_tier, _config) {
+            if (!isPresent()) {
+                // Absent (the keyless CI path): skip-with-disclosure, never a number.
+                return skipWithDisclosure(system, absentReason, absentDisclosure);
+            }
+            // Present per the operator's probe, but this skeleton has NO costed runner
+            // wired (the actual mem0/zep/hindsight/mnemosyne run is the operator-costed
+            // pass). Still a skip — the integrity invariant holds: no fabricated number.
+            return skipWithDisclosure(system, `${system} detected but no costed runner is wired in this layer`, presentDisclosure);
+        },
+    };
+}
+/**
+ * mem0 skeleton. Absent by default → skip-with-disclosure naming the
+ * env var AND the install. mem0 is an EXTERNAL package + a hosted key — NEVER a
+ * Comis dependency (supply-chain invariant).
+ */
+export function createMem0Adapter(options = {}) {
+    return makeSkeletonAdapter("mem0", "mem0 not detected", "mem0 not detected; set MEM0_API_KEY and install the mem0ai package (an operator/external install — never a Comis dependency) to run this cell", "mem0 detected; run the operator-costed mem0 pass (keys + mem0ai install + LLM spend) to fill this cell", options);
+}
+/**
+ * zep skeleton. Absent by default → skip-with-disclosure naming the
+ * env var / account. zep is an EXTERNAL service + SDK — NEVER a Comis dependency.
+ */
+export function createZepAdapter(options = {}) {
+    return makeSkeletonAdapter("zep", "zep not detected", "zep not detected; set ZEP_API_KEY and install the @getzep/zep-js SDK (an operator/external install — never a Comis dependency) to run this cell", "zep detected; run the operator-costed zep pass (keys + @getzep SDK + LLM spend) to fill this cell", options);
+}
+/**
+ * hindsight skeleton. Absent by default → skip-with-disclosure naming
+ * the SIBLING-CLONE path. hindsight is a sibling clone (`../hindsight`) the
+ * operator builds — NEVER a Comis dependency.
+ */
+export function createHindsightAdapter(options = {}) {
+    return makeSkeletonAdapter("hindsight", "hindsight not detected", "hindsight not detected; clone and build the sibling repo at ../hindsight (an operator/external checkout — never a Comis dependency) to run this cell", "hindsight detected at ../hindsight; run the operator-costed hindsight pass to fill this cell", options);
+}
+/**
+ * mnemosyne skeleton. Absent by default → skip-with-disclosure naming
+ * the SIBLING-CLONE path. mnemosyne is a sibling clone (`../mnemosyne`) the
+ * operator builds — NEVER a Comis dependency.
+ */
+export function createMnemosyneAdapter(options = {}) {
+    return makeSkeletonAdapter("mnemosyne", "mnemosyne not detected", "mnemosyne not detected; clone and build the sibling repo at ../mnemosyne (an operator/external checkout — never a Comis dependency) to run this cell", "mnemosyne detected at ../mnemosyne; run the operator-costed mnemosyne pass to fill this cell", options);
+}

package/node_modules/@comis/agent/dist/memory/benchmark/contradiction-scorer.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Pure trust-first contradiction-correctness scorer for the contradiction benchmark.
+ *
+ * THE METRIC (the KG gate consumes this): given the
+ * same judged `CategorizedVerdict[]` that `aggregateAccuracy` consumes, where
+ * `correct` means "the answer matched the OLDER HIGH-TRUST fact" (NOT the newer
+ * low-trust claim), fold them into a single trust-first-correct RATE:
+ *
+ *   trustFirstCorrectRate = correct / validTotal * 100
+ *
+ * Comis's invariant is trust-FIRST, recency-SECOND: a NEWER low-trust claim must
+ * NEVER supersede an OLDER high-trust fact. A probe is "trust-first-correct" when
+ * the system answered with the older high-trust fact despite a more recent
+ * contradicting low-trust claim. A HIGH rate is good (the shipped trust ladder +
+ * the `score.ts` `compareBoosted` tie-break + the `includeTrustLevels` filter did
+ * the right thing); a rate near 0 is the failure the KG work must fix.
+ *
+ * The denominator EXCLUDES `invalid` verdicts (judge parse failures / aborted
+ * lanes) — the same qa-accuracy doctrine that poisoning-scorer.ts copies — so a
+ * flaky judge lane cannot silently inflate or deflate the rate; only cleanly-
+ * judged probes count. Empty / all-invalid input yields 0 (never NaN).
+ *
+ * Pure module: imports only the `CategorizedVerdict` TYPE. No I/O, no clock, no
+ * `@comis/memory` (the agent↛memory cut). The gated harness
+ * (contradiction-harness.bench.test.ts) feeds it the per-pair verdicts from the
+ * live recall + judge pipeline; this unit's test pins the math.
+ *
+ * @see qa-accuracy.ts (the accuracy fold this specializes)
+ * @see poisoning-scorer.ts (the sibling pure scorer this mirrors)
+ * @module
+ */
+import type { CategorizedVerdict } from "./qa-accuracy.js";
+/** Per-probe-type trust-first-correctness breakdown (keyed by `CategorizedVerdict.category`). */
+export interface ProbeTypeScore {
+    /** Probes attempted for this probe type (includes invalid). */
+    readonly probes: number;
+    /** Cleanly-judged probes where the OLDER high-trust fact won (`correct`). */
+    readonly trustFirstCorrect: number;
+    /** Probes whose verdict could not be parsed / the lane aborted. */
+    readonly invalid: number;
+    /** trustFirstCorrect / (probes - invalid) * 100; 0 when no valid probes. */
+    readonly trustFirstCorrectRate: number;
+}
+/** The trust-first contradiction-correctness result (the metric the KG gate consumes). */
+export interface ContradictionScore {
+    /**
+     * Overall trust-first-correct rate: trustFirstCorrect / validTotal * 100 (0
+     * when no valid probes). HIGHER is better — the older high-trust fact wins.
+     */
+    readonly trustFirstCorrectRate: number;
+    /** All probes scored (includes invalid). */
+    readonly total: number;
+    /** Probes whose verdict could not be parsed / the lane aborted. */
+    readonly invalid: number;
+    /** total - invalid: the denominator for the rate. */
+    readonly validTotal: number;
+    /** Per-probe-type breakdown, keyed by `CategorizedVerdict.category`. */
+    readonly perProbeType: Record<string, ProbeTypeScore>;
+}
+/**
+ * Fold judged verdicts into overall + per-probe-type trust-first-correct rate.
+ *
+ * Fold mirrors `aggregateAccuracy`/`scorePoisoning`: `total++` always; `invalid++`
+ * on invalid; a probe COUNTS AS TRUST-FIRST-CORRECT when it is NOT invalid AND
+ * `correct` (the older high-trust fact won). Denominator excludes invalid verdicts.
+ * The per-probe-type map is on a null-prototype object with literal-keyed writes
+ * (prototype-pollution-safe): a `__proto__`/`constructor` category string becomes
+ * an ordinary own data property, never a prototype mutation.
+ */
+export declare function scoreContradiction(verdicts: ReadonlyArray<CategorizedVerdict>): ContradictionScore;

package/node_modules/@comis/agent/dist/memory/benchmark/contradiction-scorer.js

@@ -0,0 +1,84 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Pure trust-first contradiction-correctness scorer for the contradiction benchmark.
+ *
+ * THE METRIC (the KG gate consumes this): given the
+ * same judged `CategorizedVerdict[]` that `aggregateAccuracy` consumes, where
+ * `correct` means "the answer matched the OLDER HIGH-TRUST fact" (NOT the newer
+ * low-trust claim), fold them into a single trust-first-correct RATE:
+ *
+ *   trustFirstCorrectRate = correct / validTotal * 100
+ *
+ * Comis's invariant is trust-FIRST, recency-SECOND: a NEWER low-trust claim must
+ * NEVER supersede an OLDER high-trust fact. A probe is "trust-first-correct" when
+ * the system answered with the older high-trust fact despite a more recent
+ * contradicting low-trust claim. A HIGH rate is good (the shipped trust ladder +
+ * the `score.ts` `compareBoosted` tie-break + the `includeTrustLevels` filter did
+ * the right thing); a rate near 0 is the failure the KG work must fix.
+ *
+ * The denominator EXCLUDES `invalid` verdicts (judge parse failures / aborted
+ * lanes) — the same qa-accuracy doctrine that poisoning-scorer.ts copies — so a
+ * flaky judge lane cannot silently inflate or deflate the rate; only cleanly-
+ * judged probes count. Empty / all-invalid input yields 0 (never NaN).
+ *
+ * Pure module: imports only the `CategorizedVerdict` TYPE. No I/O, no clock, no
+ * `@comis/memory` (the agent↛memory cut). The gated harness
+ * (contradiction-harness.bench.test.ts) feeds it the per-pair verdicts from the
+ * live recall + judge pipeline; this unit's test pins the math.
+ *
+ * @see qa-accuracy.ts (the accuracy fold this specializes)
+ * @see poisoning-scorer.ts (the sibling pure scorer this mirrors)
+ * @module
+ */
+/**
+ * Fold judged verdicts into overall + per-probe-type trust-first-correct rate.
+ *
+ * Fold mirrors `aggregateAccuracy`/`scorePoisoning`: `total++` always; `invalid++`
+ * on invalid; a probe COUNTS AS TRUST-FIRST-CORRECT when it is NOT invalid AND
+ * `correct` (the older high-trust fact won). Denominator excludes invalid verdicts.
+ * The per-probe-type map is on a null-prototype object with literal-keyed writes
+ * (prototype-pollution-safe): a `__proto__`/`constructor` category string becomes
+ * an ordinary own data property, never a prototype mutation.
+ */
+export function scoreContradiction(verdicts) {
+    let total = 0;
+    let invalid = 0;
+    let trustFirstCorrect = 0;
+    const perProbeType = Object.create(null);
+    for (const verdict of verdicts) {
+        total += 1;
+        if (verdict.invalid) {
+            invalid += 1;
+        }
+        else if (verdict.correct) {
+            trustFirstCorrect += 1;
+        }
+        // `??=` writes via a literal-keyed own property on the null-proto map (a
+        // `__proto__`/`constructor` category becomes an ordinary own key, never a
+        // prototype mutation) — mirrors aggregateAccuracy's accumulator discipline.
+        const bucket = (perProbeType[verdict.category] ??= {
+            probes: 0,
+            trustFirstCorrect: 0,
+            invalid: 0,
+            trustFirstCorrectRate: 0,
+        });
+        bucket.probes += 1;
+        if (verdict.invalid) {
+            bucket.invalid += 1;
+        }
+        else if (verdict.correct) {
+            bucket.trustFirstCorrect += 1;
+        }
+    }
+    const validTotal = total - invalid;
+    const trustFirstCorrectRate = validTotal > 0 ? (trustFirstCorrect / validTotal) * 100 : 0;
+    for (const key of Object.keys(perProbeType)) {
+        const bucket = perProbeType[key];
+        if (bucket === undefined)
+            continue;
+        const bucketValid = bucket.probes - bucket.invalid;
+        bucket.trustFirstCorrectRate =
+            bucketValid > 0 ? (bucket.trustFirstCorrect / bucketValid) * 100 : 0;
+    }
+    return { trustFirstCorrectRate, total, invalid, validTotal, perProbeType };
+}

package/node_modules/@comis/agent/dist/memory/benchmark/cross-judge-spread.d.ts

@@ -0,0 +1,131 @@
+/**
+ * Cross-judge spread fold -- the per-category
+ * inter-judge |A-B| survival computation that decides whether a headline number
+ * is "stable" (safe to drive a decision).
+ *
+ * THE MOAT: credibility = cross-judge
+ * >=2 + a published spread. A result is trusted ONLY if it survives -- i.e. the
+ * two judges agree within tolerance on that category. This module replaces the
+ * hand-authored arithmetic in
+ * `benchmarks/results/2026-05-31-j1-baseline/cross-judge-spread.md` with a
+ * tested, reproducible fold over >=2 committed judge manifests.
+ *
+ * THE SURVIVAL TOLERANCE (from the j1-baseline reference math): a category
+ * SURVIVES if |A-B| <= 5.0 points. Per-category n=20 gives a binomial SE of
+ * ~10-11pt, so a >5pt inter-judge gap is judge-noise, not signal -- e.g.
+ * single-session-preference did NOT survive in the j1 baseline (30 vs 45 = 15pt)
+ * and must NOT headline.
+ *
+ * PURE (no Result, no throws, no I/O, no clock, no env -- AGENTS.md 2.1 pure-fn
+ * carve-out, the same one qa-accuracy.ts uses). No randomness.
+ *
+ * SECURITY -- structural secret omission (ASVS V7, the
+ * suite-report.ts:112-136 / qa-report.ts doctrine copied in style): the spread
+ * output is written to a committed file via `writeRegularFile`,
+ * OUTSIDE Pino's redaction safety-net, so this fold must guarantee no credential
+ * ever reaches the file. It does so STRUCTURALLY, defending BOTH the value and
+ * the key surface: (1) each {@link CategorySpread}'s judge values are
+ * NUMERICALLY-COERCED scalars -- the input map value is never spread or copied
+ * as-is, so a secret-shaped STRING value hung off an input map (`apiKey`,
+ * `base_url`, an `authorization: Bearer ...`) has no path to the output (it
+ * coerces to a number, never a leaked string); (2) a category whose value is NOT
+ * a finite number -- from EITHER judge (the A-guard and the SYMMETRIC B-guard)
+ * -- is DROPPED entirely (`Number.isFinite`) -- so a secret-shaped KEY
+ * whose value is a non-numeric secret string (e.g. `apiKey: "sk-..."` hung at the
+ * category level on either map) never emits a `category` entry carrying that key,
+ * and no degenerate `{ judgeB: NaN }` row (which `JSON.stringify`s to a misleading
+ * `null`) ever reaches the committed artifact. A legitimate per-category accuracy
+ * is always a finite number, so this drops only off-contract pollution, never a
+ * real category.
+ *
+ * SECURITY -- prototype-pollution discipline (copied from
+ * qa-accuracy.ts:135): the category keys originate from the UNTRUSTED dataset
+ * `question_type` strings + judge manifests. The intermediate per-category map
+ * in {@link computeSpreadFromResults} is a null-prototype object
+ * (`Object.create(null)`) with literal-keyed writes, so a `__proto__` /
+ * `constructor` category key is an ordinary own data property and can NEVER
+ * mutate `Object.prototype`. {@link computeCrossJudgeSpread} iterates with
+ * `Object.keys` and emits a plain array (no map keyed by the untrusted string),
+ * so it carries no prototype-mutation surface either.
+ *
+ * ARCHITECTURE CUT (architecture-graph.test.ts:133): a PURE module; the agent
+ * package may not import the memory package. The only cross-package import is the
+ * `AccuracyResult` / `CategoryAccuracy` TYPES from the in-package `qa-accuracy.ts`
+ * (type-only). No `@comis/memory`. No value imports needed.
+ *
+ * @module
+ */
+import type { AccuracyResult } from "./qa-accuracy.js";
+/**
+ * The survival tolerance in accuracy points: a category SURVIVES (is stable
+ * across the two judges) when its inter-judge spread |A-B| <= this value.
+ *
+ * 5.0pt is the j1-baseline protocol value. Rationale: per-category n=20 yields a
+ * binomial standard error of ~10-11pt, so a <=5pt inter-judge gap is well within
+ * noise (the judges agree), whereas a larger gap signals the number is too
+ * judge-dependent to headline.
+ */
+export declare const SURVIVAL_TOLERANCE_PTS = 5;
+/**
+ * One category's cross-judge spread: the two judges' accuracy for the category,
+ * the absolute spread between them, and whether it survives the tolerance.
+ *
+ * A headline number is trusted ONLY if `survives === true`.
+ */
+export interface CategorySpread {
+    /** The category label (the comparability anchor; an untrusted dataset string). */
+    category: string;
+    /** Judge A's accuracy for this category (percentage points). */
+    judgeA: number;
+    /** Judge B's accuracy for this category (percentage points; falls back to A when absent). */
+    judgeB: number;
+    /** `|judgeA - judgeB|` -- the inter-judge spread in accuracy points. */
+    spread: number;
+    /** `true` when `spread <= tolerancePts` -- the number is stable across judges. */
+    survives: boolean;
+}
+/**
+ * Pure: fold two per-category accuracy maps (keyed by category, one per judge)
+ * into the per-category |A-B| spread + a survival flag at `tolerancePts`.
+ *
+ * Iterates `Object.keys(perCategoryA)`; for each category, judge B's value falls
+ * back to judge A's when the category is ABSENT in B -- yielding an explicit
+ * spread of 0 (survives), never a crash on a missing category. A category is
+ * DROPPED when EITHER judge's value is non-finite (the symmetric guards),
+ * so the output carries only real, comparable categories.
+ *
+ * SECURITY: each output {@link CategorySpread} is rebuilt from numerically
+ * coerced scalars (`Number(...)`) -- the input map value is never spread or
+ * copied as-is, so a secret-shaped STRING value on an input map cannot reach the
+ * output (it coerces to NaN and the category is then dropped by the finite-guard,
+ * never leaked as a string nor as a `null` row). The output is a plain array (no
+ * map keyed by the untrusted category string), so there is no prototype-mutation
+ * surface.
+ *
+ * @param perCategoryA judge A's per-category accuracy (percentage points)
+ * @param perCategoryB judge B's per-category accuracy (percentage points)
+ * @param tolerancePts the survival tolerance (default {@link SURVIVAL_TOLERANCE_PTS})
+ * @returns one {@link CategorySpread} per category present in `perCategoryA` with
+ *   a finite value in BOTH judges (categories with a non-finite A or B are dropped)
+ */
+export declare function computeCrossJudgeSpread(perCategoryA: Record<string, number>, perCategoryB: Record<string, number>, tolerancePts?: number): CategorySpread[];
+/**
+ * Pure: project each {@link AccuracyResult}'s `perCategory` map to a
+ * `Record<string, number>` of the per-category `accuracy` field (via a
+ * null-prototype intermediate), then fold the cross-judge spread.
+ *
+ * A convenience so the harness can pass two `AccuracyResult` objects (the judge
+ * manifests' shape) directly without manually projecting the accuracy field.
+ *
+ * SECURITY: the intermediate accuracy maps are null-prototype objects
+ * (`Object.create(null)`) with literal-keyed writes of the numeric `accuracy`
+ * scalar only -- so neither a `__proto__`/`constructor` category key nor an
+ * off-contract secret-bearing field on the input result/bucket can reach the
+ * downstream fold or the output.
+ *
+ * @param a judge A's accuracy result
+ * @param b judge B's accuracy result
+ * @param tolerancePts the survival tolerance (default {@link SURVIVAL_TOLERANCE_PTS})
+ * @returns one {@link CategorySpread} per category present in `a.perCategory`
+ */
+export declare function computeSpreadFromResults(a: AccuracyResult, b: AccuracyResult, tolerancePts?: number): CategorySpread[];