@compaction/cli 0.1.4 → 0.2.0

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

@@ -0,0 +1,140 @@
+import { type ContextStoreItem, type RetrievalOptions, type RetrievalQuery } from "./context-store.js";
+/**
+ * V0.4 context-store eval harness — rung-1 Increment 2 (local, deterministic, fixture-based).
+ *
+ * PURPOSE: MEASURE whether deterministic retrieval + assembly surfaces the *sufficient*
+ * active context on fixtures, along four axes from the accepted design doc
+ * (`docs/design/v0.4-context-store-retrieval.md`):
+ *   - recall              — did the task-critical source-pointed items survive into the
+ *                           assembled context?
+ *   - source coverage     — are the required sources represented in the assembled context?
+ *   - latency             — observed retrieval + assembly wall time (a measurement, not a
+ *                           gate; it varies by machine).
+ *   - continuation success — can a fresh agent continue from the assembled context?
+ *                           **FIXTURE-BASED** (required markers present), NOT live model
+ *                           replay (true model replay is a future, gated axis — mirrors the
+ *                           engine harness's `task_check` honesty note).
+ * Plus a local recoverability signal (fraction of assembled items carrying a recoverable
+ * source pointer — the substrate invariant).
+ *
+ * WHAT THIS IS NOT (load-bearing):
+ * - This harness MAKES NO CLAIM. It reports per-fixture + aggregate metrics; it does NOT
+ *   decide "sufficient" and bakes in NO pass/fail thresholds. The thresholds that would gate
+ *   a rung-6 large-memory claim are an explicit OPEN founder decision (design doc open
+ *   question 4) — deliberately not encoded here.
+ * - NO model, NO embeddings, NO network. Continuation success is a deterministic substring
+ *   check against the assembled text, NOT model re-execution.
+ * - NO 300M / large-memory / retrieval-correctness claim is produced by running this.
+ */
+export declare const CONTEXT_STORE_EVAL_VERSION = "context-store-eval-v1";
+/** A monotonic clock returning milliseconds. Injected so latency is testable/deterministic. */
+export type Clock = () => number;
+/** The four quality axes a fixture is scored on (latency is a separate measurement). */
+export interface AxisScores {
+    recall: number;
+    source_coverage: number;
+    continuation_success: number;
+    recoverability: number;
+}
+/**
+ * Threshold role of a fixture:
+ * - `sufficiency` — the task-critical context SHOULD be surfaced; the fixture is GATED against
+ *   the sufficiency thresholds (see context-store-sufficiency.ts).
+ * - `adversarial` — a low/partial score is the CORRECT behavior; the fixture is NOT gated, it is
+ *   a regression ANCHOR (its measured scores must keep matching `expected`).
+ * Unlabeled fixtures default to `sufficiency`.
+ */
+export type ContextStoreFixtureRole = "sufficiency" | "adversarial";
+export interface ContextStoreEvalFixture {
+    /** Stable fixture name. */
+    name: string;
+    /** Optional human description of what the fixture exercises. */
+    description?: string;
+    /** Threshold role (default `sufficiency`). Metadata only — `evaluate` ignores it. */
+    role?: ContextStoreFixtureRole;
+    /** For `adversarial` fixtures: the expected (often low/partial) per-axis anchor outcome. */
+    expected?: Partial<AxisScores>;
+    /** The store under evaluation (the accumulated items). */
+    store: ContextStoreItem[];
+    /** The retrieval query (current step's context + optional source hints). */
+    query: RetrievalQuery;
+    /** Token budget for assembly (local estimate). */
+    tokenBudget: number;
+    /** Optional retrieval options (weights, limit). */
+    retrievalOptions?: RetrievalOptions;
+    /**
+     * Task-critical item CONTENT that MUST survive into the assembled context. Compared by
+     * normalized content hash (so authors write the text, not the hash).
+     */
+    goldItems: string[];
+    /** Source pointers that MUST be represented among the assembled items (optional). */
+    requiredSourcePointers?: string[];
+    /**
+     * FIXTURE-BASED continuation requirements: markers/substrings that MUST appear in the
+     * assembled context text for a fresh agent to continue. NOT live model replay.
+     */
+    continuationRequirements: string[];
+}
+export interface ContextStoreEvalResult {
+    version: string;
+    name: string;
+    /** [0,1] — fraction of gold (task-critical) items present in the assembled context. */
+    recall: number;
+    /** [0,1] — fraction of required sources represented (1 when none are required). */
+    source_coverage: number;
+    /** [0,1] — fraction of FIXTURE-BASED continuation markers present in the assembled text. */
+    continuation_success: number;
+    /**
+     * [0,1] — fraction of assembled items that are recoverable, i.e. carry BOTH a recoverable
+     * flag AND a source pointer to recover to (1 if nothing was assembled — vacuously true).
+     */
+    recoverability: number;
+    /** Observed retrieval + assembly time in ms (measurement, machine-dependent). */
+    latency_ms: number;
+    /** Local token estimate of the assembled context. */
+    assembled_token_estimate: number;
+    /** Whether all retrieved items fit under the budget. */
+    within_budget: boolean;
+    /** Raw counts behind the ratios (for transparency). */
+    detail: {
+        gold_total: number;
+        gold_present: number;
+        required_sources_total: number;
+        required_sources_covered: number;
+        continuation_total: number;
+        continuation_met: number;
+        assembled_item_count: number;
+    };
+}
+/**
+ * Evaluate a single fixture. Deterministic apart from `latency_ms` (wall time). Pure with
+ * respect to the inputs — no model, no network.
+ */
+export declare function evaluateContextStoreFixture(fixture: ContextStoreEvalFixture, options?: {
+    clock?: Clock;
+}): ContextStoreEvalResult;
+export interface ContextStoreEvalAggregate {
+    version: string;
+    fixture_count: number;
+    /** Mean across fixtures (each in [0,1]). */
+    mean_recall: number;
+    mean_source_coverage: number;
+    mean_continuation_success: number;
+    mean_recoverability: number;
+    /** Mean observed latency (ms) — measurement, not a gate. */
+    mean_latency_ms: number;
+    results: ContextStoreEvalResult[];
+}
+/**
+ * Evaluate a suite of fixtures and roll up the per-axis means. REPORTS metrics only — no
+ * pass/fail verdict, no thresholds (those are a gated founder decision, by design).
+ */
+export declare function evaluateContextStoreFixtures(fixtures: ContextStoreEvalFixture[], options?: {
+    clock?: Clock;
+}): ContextStoreEvalAggregate;
+/**
+ * Markdown report for a fixture suite. States the four axes, the honest non-claim, and the
+ * fixture-based-continuation caveat explicitly — so a reader cannot mistake these metrics for
+ * a large-memory / retrieval-correctness claim.
+ */
+export declare function formatContextStoreEvalMarkdown(aggregate: ContextStoreEvalAggregate): string;

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

@@ -0,0 +1,138 @@
+import { contentHash } from "./content-hash.js";
+import { assembleContext, retrieveContextItems } from "./context-store.js";
+/**
+ * V0.4 context-store eval harness — rung-1 Increment 2 (local, deterministic, fixture-based).
+ *
+ * PURPOSE: MEASURE whether deterministic retrieval + assembly surfaces the *sufficient*
+ * active context on fixtures, along four axes from the accepted design doc
+ * (`docs/design/v0.4-context-store-retrieval.md`):
+ *   - recall              — did the task-critical source-pointed items survive into the
+ *                           assembled context?
+ *   - source coverage     — are the required sources represented in the assembled context?
+ *   - latency             — observed retrieval + assembly wall time (a measurement, not a
+ *                           gate; it varies by machine).
+ *   - continuation success — can a fresh agent continue from the assembled context?
+ *                           **FIXTURE-BASED** (required markers present), NOT live model
+ *                           replay (true model replay is a future, gated axis — mirrors the
+ *                           engine harness's `task_check` honesty note).
+ * Plus a local recoverability signal (fraction of assembled items carrying a recoverable
+ * source pointer — the substrate invariant).
+ *
+ * WHAT THIS IS NOT (load-bearing):
+ * - This harness MAKES NO CLAIM. It reports per-fixture + aggregate metrics; it does NOT
+ *   decide "sufficient" and bakes in NO pass/fail thresholds. The thresholds that would gate
+ *   a rung-6 large-memory claim are an explicit OPEN founder decision (design doc open
+ *   question 4) — deliberately not encoded here.
+ * - NO model, NO embeddings, NO network. Continuation success is a deterministic substring
+ *   check against the assembled text, NOT model re-execution.
+ * - NO 300M / large-memory / retrieval-correctness claim is produced by running this.
+ */
+export const CONTEXT_STORE_EVAL_VERSION = "context-store-eval-v1";
+function defaultClock() {
+    return globalThis.performance.now();
+}
+function normalizeContent(content) {
+    return content.trim().replace(/\s+/g, " ");
+}
+function ratio(numerator, denominator, whenEmpty) {
+    return denominator === 0 ? whenEmpty : numerator / denominator;
+}
+/**
+ * Evaluate a single fixture. Deterministic apart from `latency_ms` (wall time). Pure with
+ * respect to the inputs — no model, no network.
+ */
+export function evaluateContextStoreFixture(fixture, options = {}) {
+    const clock = options.clock ?? defaultClock;
+    const start = clock();
+    const ranked = retrieveContextItems(fixture.store, fixture.query, fixture.retrievalOptions);
+    const assembled = assembleContext(ranked, { tokenBudget: fixture.tokenBudget });
+    const latency_ms = clock() - start;
+    const includedHashes = new Set(assembled.included.map((item) => item.content_sha256));
+    const includedPointers = new Set(assembled.included.map((item) => item.source_pointer).filter((p) => p !== undefined));
+    const goldHashes = fixture.goldItems.map((content) => contentHash(normalizeContent(content)));
+    const goldPresent = goldHashes.filter((hash) => includedHashes.has(hash)).length;
+    const requiredSources = fixture.requiredSourcePointers ?? [];
+    const sourcesCovered = requiredSources.filter((pointer) => includedPointers.has(pointer)).length;
+    const assembledLower = assembled.text.toLowerCase();
+    const continuationMet = fixture.continuationRequirements.filter((marker) => assembledLower.includes(marker.toLowerCase())).length;
+    // Recoverable requires BOTH a recoverable flag AND a source pointer to recover *to* — an
+    // item flagged recoverable but carrying no source pointer cannot actually be recovered.
+    const recoverableCount = assembled.included.filter((item) => item.recoverability === true && item.source_pointer !== undefined).length;
+    return {
+        version: CONTEXT_STORE_EVAL_VERSION,
+        name: fixture.name,
+        recall: ratio(goldPresent, goldHashes.length, 1),
+        source_coverage: ratio(sourcesCovered, requiredSources.length, 1),
+        continuation_success: ratio(continuationMet, fixture.continuationRequirements.length, 1),
+        recoverability: ratio(recoverableCount, assembled.included.length, 1),
+        latency_ms,
+        assembled_token_estimate: assembled.estimated_tokens,
+        within_budget: assembled.within_budget,
+        detail: {
+            gold_total: goldHashes.length,
+            gold_present: goldPresent,
+            required_sources_total: requiredSources.length,
+            required_sources_covered: sourcesCovered,
+            continuation_total: fixture.continuationRequirements.length,
+            continuation_met: continuationMet,
+            assembled_item_count: assembled.included.length
+        }
+    };
+}
+function mean(values) {
+    return values.length === 0 ? 0 : values.reduce((sum, v) => sum + v, 0) / values.length;
+}
+/**
+ * Evaluate a suite of fixtures and roll up the per-axis means. REPORTS metrics only — no
+ * pass/fail verdict, no thresholds (those are a gated founder decision, by design).
+ */
+export function evaluateContextStoreFixtures(fixtures, options = {}) {
+    const results = fixtures.map((fixture) => evaluateContextStoreFixture(fixture, options));
+    return {
+        version: CONTEXT_STORE_EVAL_VERSION,
+        fixture_count: results.length,
+        mean_recall: mean(results.map((r) => r.recall)),
+        mean_source_coverage: mean(results.map((r) => r.source_coverage)),
+        mean_continuation_success: mean(results.map((r) => r.continuation_success)),
+        mean_recoverability: mean(results.map((r) => r.recoverability)),
+        mean_latency_ms: mean(results.map((r) => r.latency_ms)),
+        results
+    };
+}
+function pct(value) {
+    return `${(value * 100).toFixed(1)}%`;
+}
+/**
+ * Markdown report for a fixture suite. States the four axes, the honest non-claim, and the
+ * fixture-based-continuation caveat explicitly — so a reader cannot mistake these metrics for
+ * a large-memory / retrieval-correctness claim.
+ */
+export function formatContextStoreEvalMarkdown(aggregate) {
+    const lines = [
+        "## Context-store eval (rung-1, local-deterministic, fixture-based)",
+        "",
+        `Fixtures: ${aggregate.fixture_count}`,
+        "",
+        "| Axis | Mean |",
+        "|---|---|",
+        `| Recall | ${pct(aggregate.mean_recall)} |`,
+        `| Source coverage | ${pct(aggregate.mean_source_coverage)} |`,
+        `| Continuation success (fixture-based) | ${pct(aggregate.mean_continuation_success)} |`,
+        `| Recoverability | ${pct(aggregate.mean_recoverability)} |`,
+        `| Latency (mean, ms) | ${aggregate.mean_latency_ms.toFixed(2)} |`,
+        "",
+        "### Per fixture",
+        "| Fixture | Recall | Source cov. | Continuation | Recoverability | Latency (ms) | Within budget |",
+        "|---|---|---|---|---|---|---|",
+        ...aggregate.results.map((r) => `| ${r.name} | ${pct(r.recall)} | ${pct(r.source_coverage)} | ${pct(r.continuation_success)} | ` +
+            `${pct(r.recoverability)} | ${r.latency_ms.toFixed(2)} | ${r.within_budget ? "yes" : "no"} |`),
+        "",
+        "**What these numbers are NOT:** this harness reports fixture metrics only. It bakes in NO",
+        "pass/fail thresholds and makes NO large-memory / 300M / retrieval-correctness claim — the",
+        "thresholds that would gate such a claim are an open, gated decision. Continuation success is",
+        "FIXTURE-BASED (required markers present in the assembled text), NOT live model re-execution.",
+        "Latency is an observed measurement and varies by machine."
+    ];
+    return lines.join("\n");
+}
+//# sourceMappingURL=context-store-eval.js.map

package/dist/core/context-store-fs.d.ts

@@ -0,0 +1,73 @@
+import { type ContextStoreItem } from "./context-store.js";
+/**
+ * Local-file persistence for the V0.4 context store (rung-1), with a simple local SIZE CAP.
+ *
+ * LOCAL-ONLY: the store is an append-only JSONL file under a `.compaction/`-rooted directory
+ * (gitignored). There is NO network, credential, upload, or DB here — plain local file I/O, by
+ * design. Store content is LOCAL-ONLY and must be EXCLUDED-BY-DEFAULT from any future share /
+ * `feedback` bundle (reuse the existing redaction discipline) — never uploaded.
+ *
+ * SIZE CAP (accepted decision, docs/design/v0.4-context-store-decisions.md): a simple,
+ * deterministic local cap bounds unbounded growth. See `applyContextStoreCap`:
+ * - Capped on BOTH item count AND total serialized bytes.
+ * - Eviction is DETERMINISTIC and oldest-first (by `created_at`, ties by `content_sha256`).
+ * - Eviction removes WHOLE items only; it NEVER mutates a retained item, so every retained
+ *   item keeps its `source_pointer` + recoverability intact (the provenance invariant holds).
+ * - The most recent item is always retained (a single oversized newest item is never silently
+ *   dropped to an empty store).
+ * Normal writes stay append-only; the file is rewritten (atomically) only when the cap evicts.
+ */
+/** Default store filename inside the store directory. */
+export declare const CONTEXT_STORE_FILE = "items.jsonl";
+/** Resolve the JSONL path for a given store directory. */
+export declare function contextStorePath(storeDir: string): string;
+/** A simple local size cap. Either bound may be omitted (treated as unbounded). */
+export interface ContextStoreCap {
+    /** Maximum number of items retained. */
+    maxItems?: number;
+    /** Maximum total serialized (JSONL) bytes retained. */
+    maxBytes?: number;
+}
+/** Conservative local defaults — enough headroom for real use, bounded against runaway growth. */
+export declare const DEFAULT_CONTEXT_STORE_CAP: Required<ContextStoreCap>;
+export interface CapResult {
+    /** Items retained, in deterministic chronological (oldest-kept → newest) order. */
+    kept: ContextStoreItem[];
+    /** Items evicted (the oldest), deterministic. */
+    evicted: ContextStoreItem[];
+}
+/**
+ * Apply the size cap. PURE — no I/O. Keeps the NEWEST items that fit within BOTH caps and
+ * evicts the OLDEST; the most recent item is always retained. Deterministic and testable.
+ * Input is assumed deduped by `content_sha256` (as produced by `loadContextStore`).
+ */
+export declare function applyContextStoreCap(items: ContextStoreItem[], cap?: ContextStoreCap): CapResult;
+/**
+ * Read every persisted item from the store directory, deduped by content hash.
+ * Returns `[]` if the store does not exist yet (starts empty — no migration).
+ * Malformed lines are skipped (a partially-written tail never throws).
+ */
+export declare function loadContextStore(storeDir: string): Promise<ContextStoreItem[]>;
+/** Atomically (write-temp-then-rename) replace the store file with `items`. */
+export declare function writeContextStore(storeDir: string, items: ContextStoreItem[]): Promise<void>;
+export interface AppendResult {
+    /** Items newly written this call (i.e. not already present by content hash). */
+    appended: ContextStoreItem[];
+    /** Items skipped because their content hash already existed in the store. */
+    skipped: ContextStoreItem[];
+    /** Items evicted by the size cap during this call (the oldest), deterministic. */
+    evicted: ContextStoreItem[];
+    /** Total distinct items retained in the store after this append (post-cap). */
+    total: number;
+}
+/**
+ * Append items to the store, skipping any whose `content_sha256` already exists (idempotent),
+ * then enforce the size cap. New writes are append-only; the file is rewritten (atomically)
+ * only when the cap evicts something. Returns what was appended / skipped / evicted.
+ */
+export declare function appendContextItems(storeDir: string, items: ContextStoreItem[], cap?: ContextStoreCap): Promise<AppendResult>;
+/**
+ * Enforce the size cap on an existing store WITHOUT appending (e.g. after lowering the cap).
+ * Rewrites the file only when something is evicted. Returns the kept/evicted split.
+ */
+export declare function enforceContextStoreCap(storeDir: string, cap?: ContextStoreCap): Promise<CapResult>;

package/dist/core/context-store-fs.js

@@ -0,0 +1,157 @@
+import { existsSync } from "node:fs";
+import { appendFile, mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { dedupeContextItems } from "./context-store.js";
+/**
+ * Local-file persistence for the V0.4 context store (rung-1), with a simple local SIZE CAP.
+ *
+ * LOCAL-ONLY: the store is an append-only JSONL file under a `.compaction/`-rooted directory
+ * (gitignored). There is NO network, credential, upload, or DB here — plain local file I/O, by
+ * design. Store content is LOCAL-ONLY and must be EXCLUDED-BY-DEFAULT from any future share /
+ * `feedback` bundle (reuse the existing redaction discipline) — never uploaded.
+ *
+ * SIZE CAP (accepted decision, docs/design/v0.4-context-store-decisions.md): a simple,
+ * deterministic local cap bounds unbounded growth. See `applyContextStoreCap`:
+ * - Capped on BOTH item count AND total serialized bytes.
+ * - Eviction is DETERMINISTIC and oldest-first (by `created_at`, ties by `content_sha256`).
+ * - Eviction removes WHOLE items only; it NEVER mutates a retained item, so every retained
+ *   item keeps its `source_pointer` + recoverability intact (the provenance invariant holds).
+ * - The most recent item is always retained (a single oversized newest item is never silently
+ *   dropped to an empty store).
+ * Normal writes stay append-only; the file is rewritten (atomically) only when the cap evicts.
+ */
+/** Default store filename inside the store directory. */
+export const CONTEXT_STORE_FILE = "items.jsonl";
+/** Resolve the JSONL path for a given store directory. */
+export function contextStorePath(storeDir) {
+    return join(storeDir, CONTEXT_STORE_FILE);
+}
+/** Conservative local defaults — enough headroom for real use, bounded against runaway growth. */
+export const DEFAULT_CONTEXT_STORE_CAP = {
+    maxItems: 10_000,
+    maxBytes: 5 * 1024 * 1024 // 5 MiB
+};
+/** Serialized on-disk footprint of one item (its JSONL line, including the newline). */
+function serializedBytes(item) {
+    return Buffer.byteLength(`${JSON.stringify(item)}\n`, "utf8");
+}
+/** Deterministic oldest-first order: `created_at` ascending, ties broken by `content_sha256`. */
+function oldestFirst(items) {
+    return [...items].sort((a, b) => {
+        if (a.created_at !== b.created_at)
+            return a.created_at < b.created_at ? -1 : 1;
+        return a.content_sha256 < b.content_sha256 ? -1 : 1;
+    });
+}
+/**
+ * Apply the size cap. PURE — no I/O. Keeps the NEWEST items that fit within BOTH caps and
+ * evicts the OLDEST; the most recent item is always retained. Deterministic and testable.
+ * Input is assumed deduped by `content_sha256` (as produced by `loadContextStore`).
+ */
+export function applyContextStoreCap(items, cap = DEFAULT_CONTEXT_STORE_CAP) {
+    const maxItems = cap.maxItems ?? Number.POSITIVE_INFINITY;
+    const maxBytes = cap.maxBytes ?? Number.POSITIVE_INFINITY;
+    const ordered = oldestFirst(items);
+    const keptReversed = [];
+    let count = 0;
+    let bytes = 0;
+    // Walk newest → oldest, keeping while within both caps. The newest item is always kept.
+    for (let i = ordered.length - 1; i >= 0; i -= 1) {
+        const item = ordered[i];
+        const itemBytes = serializedBytes(item);
+        const isNewestKept = keptReversed.length === 0;
+        if (!isNewestKept && (count + 1 > maxItems || bytes + itemBytes > maxBytes)) {
+            break; // every still-older item is evicted (keep the newest contiguous block)
+        }
+        keptReversed.push(item);
+        count += 1;
+        bytes += itemBytes;
+    }
+    const kept = keptReversed.reverse();
+    const keptHashes = new Set(kept.map((item) => item.content_sha256));
+    const evicted = ordered.filter((item) => !keptHashes.has(item.content_sha256));
+    return { kept, evicted };
+}
+/**
+ * Read every persisted item from the store directory, deduped by content hash.
+ * Returns `[]` if the store does not exist yet (starts empty — no migration).
+ * Malformed lines are skipped (a partially-written tail never throws).
+ */
+export async function loadContextStore(storeDir) {
+    const path = contextStorePath(storeDir);
+    if (!existsSync(path)) {
+        return [];
+    }
+    const raw = await readFile(path, "utf8");
+    const items = [];
+    for (const line of raw.split("\n")) {
+        const trimmed = line.trim();
+        if (trimmed.length === 0)
+            continue;
+        try {
+            const parsed = JSON.parse(trimmed);
+            if (parsed && typeof parsed.content_sha256 === "string" && typeof parsed.content === "string") {
+                items.push(parsed);
+            }
+        }
+        catch {
+            // Skip a malformed/partial line rather than failing the whole read.
+        }
+    }
+    return dedupeContextItems(items);
+}
+/** Atomically (write-temp-then-rename) replace the store file with `items`. */
+export async function writeContextStore(storeDir, items) {
+    const path = contextStorePath(storeDir);
+    await mkdir(dirname(path), { recursive: true });
+    const payload = items.length > 0 ? `${items.map((item) => JSON.stringify(item)).join("\n")}\n` : "";
+    const tmp = `${path}.tmp`;
+    await writeFile(tmp, payload, "utf8");
+    await rename(tmp, path);
+}
+/**
+ * Append items to the store, skipping any whose `content_sha256` already exists (idempotent),
+ * then enforce the size cap. New writes are append-only; the file is rewritten (atomically)
+ * only when the cap evicts something. Returns what was appended / skipped / evicted.
+ */
+export async function appendContextItems(storeDir, items, cap = DEFAULT_CONTEXT_STORE_CAP) {
+    const existing = await loadContextStore(storeDir);
+    const seen = new Set(existing.map((item) => item.content_sha256));
+    const appended = [];
+    const skipped = [];
+    const fresh = dedupeContextItems(items);
+    for (const item of fresh) {
+        if (seen.has(item.content_sha256)) {
+            skipped.push(item);
+        }
+        else {
+            seen.add(item.content_sha256);
+            appended.push(item);
+        }
+    }
+    if (appended.length > 0) {
+        const path = contextStorePath(storeDir);
+        await mkdir(dirname(path), { recursive: true });
+        const payload = `${appended.map((item) => JSON.stringify(item)).join("\n")}\n`;
+        await appendFile(path, payload, "utf8");
+    }
+    // Enforce the size cap (rewrites the file only when something is evicted).
+    const { kept, evicted } = applyContextStoreCap([...existing, ...appended], cap);
+    if (evicted.length > 0) {
+        await writeContextStore(storeDir, kept);
+    }
+    return { appended, skipped, evicted, total: kept.length };
+}
+/**
+ * Enforce the size cap on an existing store WITHOUT appending (e.g. after lowering the cap).
+ * Rewrites the file only when something is evicted. Returns the kept/evicted split.
+ */
+export async function enforceContextStoreCap(storeDir, cap = DEFAULT_CONTEXT_STORE_CAP) {
+    const existing = await loadContextStore(storeDir);
+    const result = applyContextStoreCap(existing, cap);
+    if (result.evicted.length > 0) {
+        await writeContextStore(storeDir, result.kept);
+    }
+    return result;
+}
+//# sourceMappingURL=context-store-fs.js.map

package/dist/core/context-store-sufficiency.d.ts

@@ -0,0 +1,98 @@
+import { type Clock, type ContextStoreEvalFixture } from "./context-store-eval.js";
+/**
+ * V0.4 context-store INTERNAL sufficiency report (rung-1).
+ *
+ * Applies the founder-accepted threshold defaults
+ * (`docs/design/v0.4-context-store-thresholds.md`) to the eval fixtures, purely as an
+ * INTERNAL regression/confidence gate. It is consumed only by the eval harness/tests — it is
+ * NOT wired to any CLI command and produces NO user-facing output.
+ *
+ * WHAT THIS IS NOT (load-bearing):
+ * - NOT a public claim. Passing means the deterministic retriever still behaves on SYNTHETIC
+ *   fixtures — it is NOT evidence of retrieval correctness for users, savings, semantic
+ *   preservation, or any large-memory / 300M readiness. Those remain gated.
+ * - NO model replay, NO embeddings, NO network.
+ *
+ * Model:
+ * - `sufficiency` fixtures are GATED against the thresholds below (hard axes fail; soft axes
+ *   warn; latency is recorded only).
+ * - `adversarial` fixtures are NOT gated — their low/partial scores are correct. They are
+ *   regression ANCHORS: the measured score must keep matching the fixture's `expected`.
+ */
+export declare const CONTEXT_STORE_SUFFICIENCY_VERSION = "context-store-sufficiency-v1";
+/** A per-axis gate. `hard` fails the report; `soft` only warns; `report` records (latency). */
+export type AxisGate = {
+    kind: "hard";
+    min: number;
+} | {
+    kind: "soft";
+    min: number;
+} | {
+    kind: "report";
+};
+export interface SufficiencyThresholds {
+    recall: AxisGate;
+    source_coverage: AxisGate;
+    recoverability: AxisGate;
+    continuation_success: AxisGate;
+    latency_ms: AxisGate;
+}
+/**
+ * Founder-accepted defaults (2026-06-24): hard recall / source coverage / recoverability
+ * (= 1.0 on sufficiency fixtures); soft continuation (advisory ≥ 0.9 — it is a marker proxy,
+ * not model replay); latency report-only. INTERNAL thresholds, not public claims.
+ */
+export declare const CONTEXT_STORE_SUFFICIENCY_THRESHOLDS: SufficiencyThresholds;
+/** The quality axes a fixture is gated/anchored on (latency is handled separately). */
+declare const QUALITY_AXES: readonly ["recall", "source_coverage", "recoverability", "continuation_success"];
+type QualityAxis = (typeof QUALITY_AXES)[number];
+export interface HardFailure {
+    fixture: string;
+    axis: QualityAxis;
+    measured: number;
+    min: number;
+}
+export interface SoftWarning {
+    fixture: string;
+    axis: QualityAxis;
+    measured: number;
+    min: number;
+}
+export interface AnchorFailure {
+    fixture: string;
+    axis: QualityAxis;
+    measured: number;
+    expected: number;
+}
+export interface LatencyRecord {
+    fixture: string;
+    latency_ms: number;
+}
+export interface SufficiencyReport {
+    version: string;
+    /** True iff there are no hard-axis failures and no anchor mismatches. */
+    passed: boolean;
+    sufficiency_fixtures: number;
+    adversarial_fixtures: number;
+    /** Hard-axis regressions on sufficiency fixtures — these FAIL the report. */
+    hard_failures: HardFailure[];
+    /** Soft-axis (continuation) dips on sufficiency fixtures — advisory only, do NOT fail. */
+    warnings: SoftWarning[];
+    /** Adversarial fixtures whose measured score drifted from their expected anchor — these FAIL. */
+    anchor_failures: AnchorFailure[];
+    /** Recorded latency per fixture — REPORT-ONLY, never gates. */
+    latency: LatencyRecord[];
+}
+/**
+ * Run every fixture and build the internal sufficiency report. Deterministic apart from the
+ * recorded latency (use an injected clock for reproducible reports).
+ */
+export declare function evaluateSufficiency(fixtures: ContextStoreEvalFixture[], thresholds?: SufficiencyThresholds, options?: {
+    clock?: Clock;
+}): SufficiencyReport;
+/**
+ * Internal markdown rendering of the sufficiency report. For local/CI inspection only —
+ * not a user-facing surface and not a claim.
+ */
+export declare function formatSufficiencyReportMarkdown(report: SufficiencyReport): string;
+export {};