@compaction/cli 0.1.4 → 0.2.0

package/README.md

@@ -24,6 +24,14 @@ Everything below runs on your machine and writes local files only:
   billing-confirmed**.
 - **Inspect spend and roll up runs.** `spend`, `summary`, and `aggregate` summarize where context
   spend came from and roll up local runs — local files only, no hosted dashboard.
+- **Build a local context store and retrieve from it.** `context add` accumulates source-pointed
+  items from a captured/imported trace into a local, size-capped store; `context get`
+  deterministically retrieves and assembles the active context for a query under a token budget,
+  printing it **with source pointers** plus local retrieval **diagnostics** (what was
+  considered / included / dropped, the recoverable fraction, latency). Local-only and
+  deterministic — **no model, no embeddings, no network**. It reports **diagnostics only** (no
+  quality or sufficiency verdict on your data) and makes **no savings claim** (see `spend` /
+  `summary` for cost).
 - **Write local reports.** `analyze` writes local JSON + Markdown reports under an
   operator-chosen output directory. Local files only.
 - **Create redacted, content-free share bundles.** `feedback --redact` writes a redacted,
@@ -66,7 +74,7 @@ npx @compaction/cli --help       # no install at all
 ```
 
 The installed binary is `compaction`. After a global install, sanity-check with
-`compaction --version` (→ `0.1.4`) and `compaction --help`.
+`compaction --version` (→ `0.2.0`) and `compaction --help`.
 
 ### curl one-liner
 
@@ -133,6 +141,8 @@ compaction capture provider-usage --endpoint <url> [--credential-env-var <NAME>]
 compaction import <trace-file> --source <source> --out <dir>
 compaction import --list-sources
 compaction analyze <trace-file>
+compaction context add <trace-file>             # build a local context store from a captured/imported trace
+compaction context get "<query>"                # retrieve + assemble the active context (with source pointers)
 compaction spend <trace-or-optimization-path>   # context-spend attribution
 compaction summary                               # roll up local run reports
 compaction aggregate                             # per-session / cross-session local rollups

package/dist/cli/commands/compact.js

@@ -2,7 +2,7 @@ import path from "node:path";
 import chalk from "chalk";
 import { Option } from "commander";
 import { writeJsonArtifact, writeTextArtifact } from "../../core/artifact-writer.js";
-import { withTraceFingerprint } from "../../core/report-generator.js";
+import { formatCompactionMarkdownReport, withSavingsEvidence, withTraceFingerprint } from "../../core/report-generator.js";
 import { describeTokenAccounting } from "../../core/token-accounting.js";
 import { parseTraceFile } from "../../core/trace-parser.js";
 import { buildRunLabelsFile, hasAnyLabel } from "../../core/run-labels.js";
@@ -124,11 +124,20 @@ export function registerCompactCommand(program) {
             // hand-assembled bundle — the eval consumes the identical PolicyMiddlewareResult.
             const policyResult = applyCompactionPolicy({ trace, compactSkillInjections: approveSkillInjectionPolicy });
             const artifacts = await writeCompactionArtifacts(trace, options.out, runId, policyResult, undefined, { reviewerType, reviewSummaryPresent, approveSkillInjectionPolicy });
-            // Attribution/integrity (V0.2 savings-evidence): re-persist report.json with the
-            // content-addressed trace fingerprint so `aggregate`/`summary` can attribute each saving to a
-            // verifiable run and de-duplicate the same captured run if it is rolled up twice. Additive,
-            // backward-compatible; does not change any existing report field/label.
-            await writeJsonArtifact(options.out, "report.json", withTraceFingerprint(artifacts.report, trace));
+            // Attribution/integrity + per-run evidence label (V0.2 savings-evidence): re-persist
+            // report.json with (1) the content-addressed trace fingerprint so `aggregate`/`summary` can
+            // attribute each saving to a verifiable run and de-duplicate a run rolled up twice, and
+            // (2) the composed `savings_evidence` record stating the per-run label explicitly. The
+            // compact path's figures are local estimates (chars/4) — `local_estimate` rung 1; never
+            // billing-confirmed, never semantic. Additive, backward-compatible; changes no existing field.
+            const evidenceReport = withSavingsEvidence(withTraceFingerprint(artifacts.report, trace), {
+                costSource: "local_estimate"
+            });
+            await writeJsonArtifact(options.out, "report.json", evidenceReport);
+            // Re-render report.md from the ENRICHED report so the per-run savings_evidence record
+            // appears in the human-readable artifact too (the engine rendered report.md from the base
+            // report before the CLI added the public-layer fingerprint/evidence enrichment).
+            await writeTextArtifact(options.out, "report.md", formatCompactionMarkdownReport(evidenceReport, artifacts.policy));
             console.log(chalk.cyan("compaction compact"));
             console.log(artifacts.consoleReport);
             // Operator-visible only when the approval gesture was given; default output is unchanged.

package/dist/cli/commands/context.d.ts

@@ -0,0 +1,2 @@
+import { Command } from "commander";
+export declare function registerContextCommand(program: Command): void;

package/dist/cli/commands/context.js

@@ -0,0 +1,130 @@
+import { existsSync, readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import chalk from "chalk";
+import { assembleContext, contextItemsFromTrace, retrieveContextItems } from "../../core/context-store.js";
+import { appendContextItems, loadContextStore } from "../../core/context-store-fs.js";
+/**
+ * V0.4 `compaction context` — a LOCAL memory + retrieval surface over the user's own captured
+ * traces (design: docs/design/v0.4-context-command.md, accepted 2026-06-24).
+ *
+ * HARD RAILS (load-bearing): local-only — no network, no model, no embeddings, no engine. It
+ * makes NO savings/cost claim (cost lives in `spend`/`summary`) and NO quality/recall/correctness
+ * verdict on user data (the four-axis sufficiency harness stays internal — there is no ground
+ * truth for an arbitrary user query). `get` prints local retrieval DIAGNOSTICS only.
+ */
+const DEFAULT_STORE_DIR = ".compaction/context-store";
+function readTrace(path) {
+    if (!existsSync(path)) {
+        throw new Error(`File not found: ${path}`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch {
+        throw new Error(`Not valid JSON: ${path}`);
+    }
+    const trace = parsed;
+    if (!trace || typeof trace.id !== "string" || !Array.isArray(trace.messages)) {
+        throw new Error("Not a normalized AgentTrace (expected { id, messages: [...] }). " +
+            "Produce one with `compaction capture` or `compaction import`.");
+    }
+    for (const message of trace.messages) {
+        const m = message;
+        if (!m || typeof m.id !== "string" || typeof m.content !== "string") {
+            throw new Error("Malformed trace: every message needs a string `id` and `content`. " +
+                "Produce a trace with `compaction capture` or `compaction import`.");
+        }
+    }
+    return parsed;
+}
+function collect(value, previous) {
+    return [...previous, value];
+}
+export function registerContextCommand(program) {
+    const context = program
+        .command("context")
+        .description("Local memory: build a durable context store from your own captured/imported traces and " +
+        "retrieve the active context for a next step (local-only; no model, no network, no savings claim).");
+    context
+        .command("add")
+        .argument("<artifact>", "Path to a local normalized AgentTrace JSON (from `compaction capture`/`import`)")
+        .option("--store-dir <dir>", "Context store directory (local, gitignored)", DEFAULT_STORE_DIR)
+        .description("Append context items derived from a local trace into the local context store (size-cap enforced).")
+        .action(async (artifact, options) => {
+        const storeDir = resolve(options.storeDir ?? DEFAULT_STORE_DIR);
+        const trace = readTrace(resolve(artifact));
+        const items = contextItemsFromTrace(trace, { created_at: new Date().toISOString() });
+        const result = await appendContextItems(storeDir, items);
+        console.log(chalk.cyan("compaction context add"));
+        console.log(`Source: ${artifact}`);
+        console.log(`Store: ${storeDir}`);
+        console.log(`Items added: ${result.appended.length}   skipped (duplicate): ${result.skipped.length}   ` +
+            `evicted (size cap): ${result.evicted.length}`);
+        console.log(`Store now holds: ${result.total} items.`);
+        console.log("Local-only: nothing was uploaded. This makes no savings claim (see `compaction spend`/`summary` for cost).");
+        console.log(chalk.bold('Next: compaction context get "<your query>"'));
+    });
+    context
+        .command("get")
+        .argument("<query>", "Free-text description of the current step")
+        .option("--store-dir <dir>", "Context store directory (local, gitignored)", DEFAULT_STORE_DIR)
+        .option("--budget <tokens>", "Token budget for the assembled context (local estimate)", "4000")
+        .option("--source <pointer>", "Required source pointer for coverage diagnostics (repeatable)", collect, [])
+        .option("--limit <n>", "Max candidate items to consider after ranking")
+        .description("Retrieve + assemble the active context for a query from the local store (deterministic, local). " +
+        "Prints the assembled context WITH source pointers + local retrieval diagnostics — not a quality score.")
+        .action(async (query, options) => {
+        const storeDir = resolve(options.storeDir ?? DEFAULT_STORE_DIR);
+        const budget = Number.parseInt(options.budget ?? "4000", 10);
+        if (Number.isNaN(budget) || budget < 0) {
+            console.error("--budget must be a non-negative integer number of tokens.");
+            process.exitCode = 1;
+            return;
+        }
+        let limit;
+        if (options.limit !== undefined) {
+            limit = Number.parseInt(options.limit, 10);
+            if (Number.isNaN(limit) || limit < 0) {
+                console.error("--limit must be a non-negative integer.");
+                process.exitCode = 1;
+                return;
+            }
+        }
+        const items = await loadContextStore(storeDir);
+        const retrievalOptions = limit !== undefined ? { limit } : {};
+        const start = performance.now();
+        const ranked = retrieveContextItems(items, { text: query, source_pointers: options.source && options.source.length > 0 ? options.source : undefined }, retrievalOptions);
+        const assembled = assembleContext(ranked, { tokenBudget: budget });
+        const latencyMs = performance.now() - start;
+        console.log(chalk.cyan("compaction context get"));
+        console.log(`Query: ${JSON.stringify(query)}`);
+        console.log(`Store: ${storeDir} (${items.length} items)`);
+        if (assembled.included.length === 0) {
+            console.log("Assembled context: (no matching context in the store for this query)");
+        }
+        else {
+            console.log(`Assembled context (~${assembled.estimated_tokens} tokens, local estimate; budget ${budget}):`);
+            for (const item of assembled.included) {
+                const pointer = item.source_pointer ?? "(no source pointer)";
+                const oneLine = item.content.replace(/\s+/g, " ");
+                console.log(`  [${pointer}] ${oneLine}`);
+            }
+        }
+        const recoverable = assembled.included.filter((i) => i.recoverability === true && i.source_pointer).length;
+        console.log("Diagnostics (local retrieval, not a quality score):");
+        console.log(`  considered: ${ranked.length}   included: ${assembled.included.length}   dropped: ${assembled.dropped.length}`);
+        console.log(`  recoverable (has source pointer): ${recoverable}/${assembled.included.length}`);
+        if (options.source && options.source.length > 0) {
+            const includedPointers = new Set(assembled.included.map((i) => i.source_pointer).filter((p) => Boolean(p)));
+            const covered = options.source.filter((s) => includedPointers.has(s)).length;
+            console.log(`  source coverage: ${covered}/${options.source.length}`);
+        }
+        else {
+            console.log("  source coverage: n/a (no --source given)");
+        }
+        console.log(`  latency: ${latencyMs.toFixed(1)} ms`);
+        console.log("No model, no network. Local memory/retrieval view — it makes no savings claim and no quality/correctness claim.");
+    });
+}
+//# sourceMappingURL=context.js.map

package/dist/cli/commands/import.js

@@ -5,8 +5,10 @@ function printSupportedSources() {
     console.log(chalk.cyan("compaction import sources"));
     for (const adapter of listTraceAdapters()) {
         console.log(`- ${adapter.id}: ${adapter.displayName}`);
+        console.log(`    readiness: ${adapter.readiness}`);
     }
-    console.log("Live provider/runtime integrations remain future work; codex-exec-jsonl reads only local export files.");
+    console.log("All sources are local file import (no live integration). Readiness above is an honest integration-readiness " +
+        "label (AGENTS.md Level 0–6) + validation status — not a stronger integration claim than the evidence supports.");
 }
 export function registerImportCommand(program) {
     program

package/dist/cli/commands/run.js

@@ -1,7 +1,7 @@
 import chalk from "chalk";
 import { parseRunCommand, executeLocalCommand, persistLocalCommandRun } from "../../core/command-runner.js";
-import { writeJsonArtifact } from "../../core/artifact-writer.js";
-import { withTraceFingerprint } from "../../core/report-generator.js";
+import { writeJsonArtifact, writeTextArtifact } from "../../core/artifact-writer.js";
+import { formatCompactionMarkdownReport, withSavingsEvidence, withTraceFingerprint } from "../../core/report-generator.js";
 import { localCommandRunToAgentTrace } from "../../core/run-trace-converter.js";
 import { runEngineCommand } from "../engine-degrade.js";
 export function registerRunCommand(program) {
@@ -24,10 +24,17 @@ export function registerRunCommand(program) {
             const trace = localCommandRunToAgentTrace(run);
             const tracePath = await writeJsonArtifact(persistedRun.outputDirectory, "trace.json", trace);
             const artifacts = await writeCompactionArtifacts(trace, persistedRun.outputDirectory, run.runId);
-            // Attribution/integrity (V0.2 savings-evidence): re-persist report.json with the content-addressed
-            // trace fingerprint so `aggregate`/`summary` attribute each saving to a verifiable run and
-            // de-duplicate a re-counted run. Additive; no existing report field/label changes.
-            await writeJsonArtifact(persistedRun.outputDirectory, "report.json", withTraceFingerprint(artifacts.report, trace));
+            // Attribution/integrity + per-run evidence label (V0.2 savings-evidence): re-persist
+            // report.json with the trace fingerprint (attribution/dedup) and the composed
+            // `savings_evidence` record (per-run label). `run` figures are local estimates (chars/4) —
+            // `local_estimate` rung 1. Additive; no existing report field/label changes.
+            const evidenceReport = withSavingsEvidence(withTraceFingerprint(artifacts.report, trace), {
+                costSource: "local_estimate"
+            });
+            await writeJsonArtifact(persistedRun.outputDirectory, "report.json", evidenceReport);
+            // Re-render report.md from the ENRICHED report so the per-run savings_evidence record
+            // appears in the human-readable artifact too (engine rendered it from the base report).
+            await writeTextArtifact(persistedRun.outputDirectory, "report.md", formatCompactionMarkdownReport(evidenceReport, artifacts.policy));
             console.log(`Exit code: ${run.exitCode ?? "none"}`);
             console.log(`Signal: ${run.signal ?? "none"}`);
             console.log(`Duration: ${run.durationMs} ms`);

package/dist/cli/index.js

@@ -11,6 +11,7 @@ import { registerBillingDeltaCommand } from "./commands/billing-delta.js";
 import { registerInitCommand } from "./commands/init.js";
 import { registerCaptureCommand } from "./commands/capture.js";
 import { registerCompactCommand } from "./commands/compact.js";
+import { registerContextCommand } from "./commands/context.js";
 import { registerEvalCommand } from "./commands/eval.js";
 import { registerExportSessionSeedCommand } from "./commands/export-session-seed.js";
 import { registerFeedbackCommand } from "./commands/feedback.js";
@@ -27,7 +28,7 @@ const program = new Command();
 program
     .name("compaction")
     .description("CLI-first trace compaction tools for AI agent workflows.")
-    .version("0.1.4");
+    .version("0.2.0");
 registerAnalyzeCommand(program);
 registerAdapterCommand(program);
 registerAggregateCommand(program);
@@ -39,6 +40,7 @@ registerBillingDeltaCommand(program);
 registerInitCommand(program);
 registerCaptureCommand(program);
 registerCompactCommand(program);
+registerContextCommand(program);
 registerEvalCommand(program);
 registerExportSessionSeedCommand(program);
 registerFeedbackCommand(program);
@@ -62,6 +64,7 @@ const PUBLIC_COMMANDS = new Set([
     "capture",
     "import",
     "analyze",
+    "context",
     "spend",
     "summary",
     "aggregate",

package/dist/core/context-store-eval-cases.d.ts

@@ -0,0 +1,6 @@
+import type { ContextStoreEvalFixture } from "./context-store-eval.js";
+export declare const CONTEXT_STORE_EVAL_FIXTURES: ContextStoreEvalFixture[];
+export declare const CONTEXT_STORE_EVAL_RICHER_FIXTURES: ContextStoreEvalFixture[];
+export declare const CONTEXT_STORE_EVAL_EDGE_FIXTURES: ContextStoreEvalFixture[];
+/** Every fixture (healthy + richer + edge), for the internal sufficiency report. */
+export declare const CONTEXT_STORE_ALL_EVAL_FIXTURES: ContextStoreEvalFixture[];

package/dist/core/context-store-eval-cases.js

@@ -0,0 +1,331 @@
+import { makeContextItem } from "./context-store.js";
+/** Label a fixture `sufficiency` — gated against the sufficiency thresholds. */
+function sufficiency(fixture) {
+    return { ...fixture, role: "sufficiency" };
+}
+/** Label a fixture `adversarial` — NOT gated; a regression anchor with an expected outcome. */
+function adversarial(fixture, expected) {
+    return { ...fixture, role: "adversarial", expected };
+}
+/**
+ * Canonical fixtures for the V0.4 context-store eval harness (rung-1).
+ *
+ * These are SYNTHETIC fixtures — hand-authored stores + queries with known task-critical
+ * items — used to MEASURE deterministic retrieval/assembly behavior. They are not captured
+ * sessions and carry no real-world claim. `created_at` values are fixed so the suite is
+ * fully deterministic (apart from observed latency).
+ */
+const T0 = "2026-06-20T09:00:00.000Z";
+const T1 = "2026-06-21T09:00:00.000Z";
+const T2 = "2026-06-22T09:00:00.000Z";
+function fact(content, source_pointer, created_at) {
+    return makeContextItem({
+        content,
+        source_pointer,
+        source_trace_id: source_pointer.split(" ")[0]?.replace("trace=", ""),
+        recoverability: true,
+        created_at
+    });
+}
+/** Fixture A: the task-critical item is lexically obvious and fits the budget. */
+const lexicalRecall = {
+    name: "lexical-recall",
+    description: "Task-critical item is lexically related to the query and fits the budget.",
+    store: [
+        fact("the auth token must be refreshed before every batch upload", "trace=A message=m1", T0),
+        fact("the user prefers a restrained blue palette in the TUI", "trace=A message=m2", T1),
+        fact("retry the upload with exponential backoff on 503", "trace=A message=m3", T2)
+    ],
+    query: { text: "how do we handle the auth token before an upload batch" },
+    tokenBudget: 1000,
+    goldItems: ["the auth token must be refreshed before every batch upload"],
+    requiredSourcePointers: ["trace=A message=m1"],
+    continuationRequirements: ["auth token", "batch upload"]
+};
+/**
+ * Fixture B: the source-pointer boost is the DECIDING factor. The task-critical item
+ * (trace B) has weak lexical overlap with the query, while a non-gold distractor (trace C)
+ * has high lexical overlap. The budget fits only one item — so without the trace-id boost
+ * the distractor would win the slot and the task-critical item would be lost. The boost is
+ * what makes the right item survive.
+ */
+const goldDecision = "decision: keep the public surface at eight commands for rung-1";
+const sourcePointerRecall = {
+    name: "source-pointer-recall",
+    description: "Under budget pressure, the exact trace-id hint is the deciding factor that keeps a lexically-weak task-critical item.",
+    store: [
+        fact(goldDecision, "trace=B message=m1", T0),
+        // Distractor: high lexical overlap with the query, but NOT task-critical (trace C, unboosted).
+        fact("what did we decide about the command surface here today", "trace=C message=m1", T1)
+    ],
+    query: { text: "what did we decide about the command surface", trace_ids: ["B"] },
+    // Budget fits exactly one item — forces the boost to decide which survives.
+    tokenBudget: makeContextItem({ content: goldDecision, created_at: T0 }).estimated_tokens,
+    goldItems: [goldDecision],
+    requiredSourcePointers: ["trace=B message=m1"],
+    continuationRequirements: ["eight commands"]
+};
+/** Fixture C: the budget forces a drop — the higher-ranked task-critical item must win. */
+const budgetPressure = {
+    name: "budget-pressure",
+    description: "Under a tight budget the task-critical (higher-ranked) item must survive.",
+    store: [
+        fact("critical: the migration must run before the API deploy", "trace=D message=m1", T0),
+        fact("aside: someone mentioned the office coffee machine is broken", "trace=D message=m2", T1)
+    ],
+    query: { text: "what must happen before the api deploy migration" },
+    // Budget large enough for one short item only.
+    tokenBudget: makeContextItem({ content: "critical: the migration must run before the API deploy", created_at: T0 })
+        .estimated_tokens,
+    goldItems: ["critical: the migration must run before the API deploy"],
+    requiredSourcePointers: ["trace=D message=m1"],
+    continuationRequirements: ["migration", "api deploy"]
+};
+export const CONTEXT_STORE_EVAL_FIXTURES = [
+    sufficiency(lexicalRecall),
+    sufficiency(sourcePointerRecall),
+    sufficiency(budgetPressure)
+];
+// ---------------------------------------------------------------------------
+// Richer / adversarial fixtures (V0.4 rung-1, 2026-06-24).
+//
+// PURPOSE: make the eval harness HARDER TO GAME before any threshold is set. Unlike the
+// healthy baseline above (every axis passes), several of these fixtures are designed so a
+// SPECIFIC axis legitimately FAILS — proving the harness reports honest sub-1.0 metrics and
+// cannot be satisfied by a degenerate retriever. Expected per-axis outcomes live next to the
+// assertions in `tests/core/context-store-eval-richer.test.ts`. No thresholds, no claim.
+// ---------------------------------------------------------------------------
+/** Flexible item builder — source pointer / recoverability are optional (for the negative cases). */
+function mk(content, opts = {}) {
+    return makeContextItem({
+        content,
+        source_pointer: opts.pointer,
+        source_trace_id: opts.trace ?? (opts.pointer ? opts.pointer.split(" ")[0]?.replace("trace=", "") : undefined),
+        recoverability: opts.recoverable ?? true,
+        created_at: opts.created_at ?? T0
+    });
+}
+function tokensOf(content) {
+    return makeContextItem({ content, created_at: T0 }).estimated_tokens;
+}
+/** R1 — task-critical item survives budget pressure against several genuinely-retrieved competitors. */
+const budgetPressureMulti = {
+    name: "budget-pressure-multi",
+    description: "Gold outranks several genuinely-retrieved competitors and wins the only budget slot.",
+    store: [
+        mk("critical: rotate the signing key before the release cutover", { pointer: "trace=E message=m1" }),
+        mk("rotate the release plan before cutover today", { pointer: "trace=E message=m2", created_at: T1 }),
+        mk("the signing key was discussed", { pointer: "trace=E message=m3", created_at: T2 })
+    ],
+    query: { text: "rotate the signing key before release cutover" },
+    tokenBudget: tokensOf("critical: rotate the signing key before the release cutover"),
+    goldItems: ["critical: rotate the signing key before the release cutover"],
+    requiredSourcePointers: ["trace=E message=m1"],
+    continuationRequirements: ["signing key", "release cutover"]
+};
+/** R2 — source coverage FAILS: a second required source is dropped under budget, gold still survives. */
+const sourceCoverageMiss = {
+    name: "source-coverage-miss",
+    description: "Two sources are required but the budget fits only the gold item; the other required source is missing.",
+    store: [
+        mk("the api key rotation runbook lives in the wiki", { pointer: "trace=A message=m1" }),
+        mk("the staging database snapshot policy", { pointer: "trace=B message=m1", created_at: T1 })
+    ],
+    query: { text: "where is the api key rotation runbook" },
+    tokenBudget: tokensOf("the api key rotation runbook lives in the wiki"),
+    goldItems: ["the api key rotation runbook lives in the wiki"],
+    requiredSourcePointers: ["trace=A message=m1", "trace=B message=m1"],
+    continuationRequirements: ["rotation runbook"]
+};
+/** R3 — continuation success FAILS: one required marker is absent from the assembled text. */
+const continuationMarkerAbsent = {
+    name: "continuation-marker-absent",
+    description: "The gold item is assembled but a required continuation marker is not present in it.",
+    store: [mk("deploy step: run the smoke test then promote the build", { pointer: "trace=F message=m1" })],
+    query: { text: "what is the deploy step for promote" },
+    tokenBudget: 1000,
+    goldItems: ["deploy step: run the smoke test then promote the build"],
+    requiredSourcePointers: ["trace=F message=m1"],
+    // "smoke test" is present; "rollback plan" is absent -> continuation_success = 0.5.
+    continuationRequirements: ["smoke test", "rollback plan"]
+};
+// R4/R5 share a store: a high-lexical-overlap distractor (trace C) vs a lexically-weak gold (trace B).
+const trapGold = "rollback procedure: restore the retained original artifact";
+const trapDistractor = "which note covers the deploy step we discussed";
+const lexicalTrapStore = [
+    mk(trapGold, { pointer: "trace=B message=m1" }),
+    mk(trapDistractor, { pointer: "trace=C message=m1", created_at: T1 })
+];
+/** R4 — lexical trap, source pointer SAVES it: the trace-id boost lifts the gold over the distractor. */
+const lexicalTrapPointerSaves = {
+    name: "lexical-trap-pointer-saves",
+    description: "An irrelevant high-overlap distractor would win, but the trace-id hint lifts the gold into the slot.",
+    store: lexicalTrapStore,
+    query: { text: "which note covers the deploy rollback step", trace_ids: ["B"] },
+    tokenBudget: tokensOf(trapGold),
+    goldItems: [trapGold],
+    requiredSourcePointers: ["trace=B message=m1"],
+    continuationRequirements: ["retained original"]
+};
+/** R5 — lexical trap, NO pointer: the irrelevant distractor wins the slot, gold is lost (recall 0). */
+const lexicalTrapNoPointer = {
+    name: "lexical-trap-no-pointer",
+    description: "Without a source-pointer hint the high-overlap distractor wins the slot and the gold is legitimately lost.",
+    store: lexicalTrapStore,
+    query: { text: "which note covers the deploy step" },
+    tokenBudget: tokensOf(trapDistractor),
+    goldItems: [trapGold],
+    requiredSourcePointers: ["trace=B message=m1"],
+    continuationRequirements: ["retained original"]
+};
+/** R6 — duplicate/redundant context must NOT inflate success: 3 byte-identical golds collapse to one. */
+const goldCanary = "the canary must pass before full rollout";
+const duplicateNoInflation = {
+    name: "duplicate-no-inflation",
+    description: "Three byte-identical copies of the gold plus one filler assemble to two distinct items, not four.",
+    store: [
+        mk(goldCanary, { pointer: "trace=G message=m1" }),
+        mk(goldCanary, { pointer: "trace=G message=m1", created_at: T1 }),
+        mk(goldCanary, { pointer: "trace=G message=m1", created_at: T2 }),
+        mk("full rollout schedule for the canary release", { pointer: "trace=H message=m1", created_at: T2 })
+    ],
+    query: { text: "when does the canary pass before rollout" },
+    tokenBudget: 1000,
+    goldItems: [goldCanary],
+    requiredSourcePointers: ["trace=G message=m1"],
+    continuationRequirements: ["canary"]
+};
+/** R7 — recoverability DROPS when an assembled item lacks a source pointer. */
+const recoverabilityMissingPointers = {
+    name: "recoverability-missing-pointers",
+    description: "Two task-critical items are assembled; one carries no source pointer, so recoverability is 0.5.",
+    store: [
+        mk("retain the original artifact for rollback", { pointer: "trace=A message=m1" }),
+        // No source pointer: flagged recoverable but cannot actually be recovered (no pointer to recover to).
+        mk("the diff summary should be reviewed before apply", { recoverable: true, created_at: T1 })
+    ],
+    query: { text: "what to retain and review before apply rollback" },
+    tokenBudget: 1000,
+    goldItems: ["retain the original artifact for rollback", "the diff summary should be reviewed before apply"],
+    requiredSourcePointers: ["trace=A message=m1"],
+    continuationRequirements: ["retain", "review"]
+};
+export const CONTEXT_STORE_EVAL_RICHER_FIXTURES = [
+    sufficiency(budgetPressureMulti),
+    adversarial(sourceCoverageMiss, { recall: 1, source_coverage: 0.5, continuation_success: 1, recoverability: 1 }),
+    adversarial(continuationMarkerAbsent, { recall: 1, source_coverage: 1, continuation_success: 0.5, recoverability: 1 }),
+    sufficiency(lexicalTrapPointerSaves),
+    adversarial(lexicalTrapNoPointer, { recall: 0, source_coverage: 0, continuation_success: 0, recoverability: 1 }),
+    sufficiency(duplicateNoInflation),
+    adversarial(recoverabilityMissingPointers, { recall: 1, source_coverage: 1, continuation_success: 1, recoverability: 0.5 })
+];
+// ---------------------------------------------------------------------------
+// Edge-class fixtures (V0.4 rung-1, 2026-06-24) — the missing classes the accepted
+// threshold note (docs/design/v0.4-context-store-thresholds.md) asked for BEFORE any
+// threshold is implemented:
+//   - multi-gold        -> makes recall/coverage FRACTIONAL (today they are binary), so a
+//                          future bar can be calibrated against real partials.
+//   - empty store       -> makes zero-context behavior explicit and honest.
+//   - budget / limit     -> recall + coverage degrade for the RIGHT, distinguishable reason
+//                          (token budget vs retrieval `limit`).
+//   - adversarial anchor -> a low score is the CORRECT behavior (the info is not in the store).
+// Fixtures/tests only. No thresholds, no claim, no command.
+// ---------------------------------------------------------------------------
+// Three equally-relevant task-critical items (each fully contains the query terms, so they
+// tie on lexical overlap and order deterministically by recency). Used by the multi-gold and
+// budget/limit fixtures so exactly which items survive is deterministic.
+const mgQuery = "rollout checklist: migration, signing, oncall";
+const mgA = "rollout checklist migration signing oncall — run the database migration first";
+const mgB = "rollout checklist migration signing oncall — rotate the signing key next";
+const mgC = "rollout checklist migration signing oncall — page the oncall engineer last";
+/** F1 — multi-gold, PARTIAL recall: budget fits two of three task-critical items. */
+const multiGoldPartialRecall = {
+    name: "multi-gold-partial-recall",
+    description: "Three equally-relevant gold items, budget fits two -> recall is a real fraction (not 0/1).",
+    store: [
+        mk(mgA, { pointer: "trace=MG message=a", created_at: T0 }),
+        mk(mgB, { pointer: "trace=MG message=b", created_at: T1 }),
+        mk(mgC, { pointer: "trace=MG message=c", created_at: T2 })
+    ],
+    query: { text: mgQuery },
+    // Room for the two newest (mgC, mgB by recency tie-break); mgA is dropped.
+    tokenBudget: tokensOf(mgC) + tokensOf(mgB),
+    goldItems: [mgA, mgB, mgC],
+    // No required sources / markers here: isolate PARTIAL RECALL as the signal.
+    requiredSourcePointers: [],
+    continuationRequirements: []
+};
+/** F2 — empty store: zero-context behavior is explicit and honest (no crash, no inflation). */
+const emptyStore = {
+    name: "empty-store",
+    description: "Nothing has been accumulated yet; retrieval/assembly must report honest zeros.",
+    store: [],
+    query: { text: "what did we decide about the migration", trace_ids: ["Z"] },
+    tokenBudget: 1000,
+    goldItems: ["a task-critical fact that is not in the store"],
+    requiredSourcePointers: ["trace=Z message=m1"],
+    continuationRequirements: ["migration decision"]
+};
+/** F3 — budget pressure: recall AND coverage degrade together, for the budget reason. */
+const budgetDegradesRecallAndCoverage = {
+    name: "budget-degrades-recall-and-coverage",
+    description: "All three sources are required but the budget fits two -> recall and coverage both drop.",
+    store: [
+        mk(mgA, { pointer: "trace=MG message=a", created_at: T0 }),
+        mk(mgB, { pointer: "trace=MG message=b", created_at: T1 }),
+        mk(mgC, { pointer: "trace=MG message=c", created_at: T2 })
+    ],
+    query: { text: mgQuery },
+    tokenBudget: tokensOf(mgC) + tokensOf(mgB),
+    goldItems: [mgA, mgB, mgC],
+    // All three required -> the dropped item's source is uncovered (coverage degrades WITH recall).
+    requiredSourcePointers: ["trace=MG message=a", "trace=MG message=b", "trace=MG message=c"],
+    continuationRequirements: []
+};
+/** F4 — retrieval `limit` omits one gold: recall degrades because of the LIMIT, not the budget. */
+const limitOmitsGold = {
+    name: "limit-omits-gold",
+    description: "Budget is generous but retrieval limit=2 caps the candidate set -> one gold never reaches assembly.",
+    store: [
+        mk(mgA, { pointer: "trace=MG message=a", created_at: T0 }),
+        mk(mgB, { pointer: "trace=MG message=b", created_at: T1 }),
+        mk(mgC, { pointer: "trace=MG message=c", created_at: T2 })
+    ],
+    query: { text: mgQuery },
+    tokenBudget: 1000, // generous: nothing is dropped BY BUDGET
+    retrievalOptions: { limit: 2 },
+    goldItems: [mgA, mgB, mgC],
+    requiredSourcePointers: [],
+    continuationRequirements: []
+};
+/** F5 — adversarial anchor: a low score is the CORRECT behavior because the info isn't stored. */
+const adversarialCorrectLowScore = {
+    name: "adversarial-correct-low-score",
+    description: "The store holds only unrelated items; the task-critical fact is absent, so recall 0 is correct (not a retriever failure).",
+    store: [
+        mk("the office wifi password was rotated on tuesday", { pointer: "trace=N message=m1", created_at: T0 }),
+        mk("lunch is catered on fridays this quarter", { pointer: "trace=N message=m2", created_at: T1 })
+    ],
+    query: { text: "what is the database migration rollback procedure" },
+    tokenBudget: 1000,
+    // The required fact was never captured into the store -> a faithful retriever cannot surface it.
+    goldItems: ["the database migration rollback procedure is to restore the retained original"],
+    requiredSourcePointers: ["trace=DB message=m1"],
+    continuationRequirements: ["rollback procedure"]
+};
+export const CONTEXT_STORE_EVAL_EDGE_FIXTURES = [
+    // All edge fixtures are adversarial anchors: their partial/zero scores are the CORRECT
+    // behavior (budget / limit / empty / absent-info), not a sufficiency failure.
+    adversarial(multiGoldPartialRecall, { recall: 2 / 3, source_coverage: 1, continuation_success: 1, recoverability: 1 }),
+    adversarial(emptyStore, { recall: 0, source_coverage: 0, continuation_success: 0, recoverability: 1 }),
+    adversarial(budgetDegradesRecallAndCoverage, { recall: 2 / 3, source_coverage: 2 / 3, continuation_success: 1, recoverability: 1 }),
+    adversarial(limitOmitsGold, { recall: 2 / 3, source_coverage: 1, continuation_success: 1, recoverability: 1 }),
+    adversarial(adversarialCorrectLowScore, { recall: 0, source_coverage: 0, continuation_success: 0, recoverability: 1 })
+];
+/** Every fixture (healthy + richer + edge), for the internal sufficiency report. */
+export const CONTEXT_STORE_ALL_EVAL_FIXTURES = [
+    ...CONTEXT_STORE_EVAL_FIXTURES,
+    ...CONTEXT_STORE_EVAL_RICHER_FIXTURES,
+    ...CONTEXT_STORE_EVAL_EDGE_FIXTURES
+];
+//# sourceMappingURL=context-store-eval-cases.js.map