@compaction/cli 0.1.2 → 0.2.0

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 {};

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

@@ -0,0 +1,135 @@
+import { evaluateContextStoreFixture } 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 const CONTEXT_STORE_SUFFICIENCY_VERSION = "context-store-sufficiency-v1";
+/**
+ * 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 const CONTEXT_STORE_SUFFICIENCY_THRESHOLDS = {
+    recall: { kind: "hard", min: 1 },
+    source_coverage: { kind: "hard", min: 1 },
+    recoverability: { kind: "hard", min: 1 },
+    continuation_success: { kind: "soft", min: 0.9 },
+    latency_ms: { kind: "report" }
+};
+/** Float tolerance for threshold/anchor comparisons (e.g. recall = 2/3). */
+const TOLERANCE = 1e-9;
+/** The quality axes a fixture is gated/anchored on (latency is handled separately). */
+const QUALITY_AXES = ["recall", "source_coverage", "recoverability", "continuation_success"];
+/**
+ * Run every fixture and build the internal sufficiency report. Deterministic apart from the
+ * recorded latency (use an injected clock for reproducible reports).
+ */
+export function evaluateSufficiency(fixtures, thresholds = CONTEXT_STORE_SUFFICIENCY_THRESHOLDS, options = {}) {
+    const hard_failures = [];
+    const warnings = [];
+    const anchor_failures = [];
+    const latency = [];
+    let sufficiencyCount = 0;
+    let adversarialCount = 0;
+    for (const fixture of fixtures) {
+        const result = evaluateContextStoreFixture(fixture, { clock: options.clock });
+        latency.push({ fixture: fixture.name, latency_ms: result.latency_ms }); // report-only
+        const scores = {
+            recall: result.recall,
+            source_coverage: result.source_coverage,
+            recoverability: result.recoverability,
+            continuation_success: result.continuation_success
+        };
+        if ((fixture.role ?? "sufficiency") === "adversarial") {
+            adversarialCount += 1;
+            const expected = fixture.expected ?? {};
+            for (const axis of QUALITY_AXES) {
+                const exp = expected[axis];
+                if (exp !== undefined && Math.abs(scores[axis] - exp) > TOLERANCE) {
+                    anchor_failures.push({ fixture: fixture.name, axis, measured: scores[axis], expected: exp });
+                }
+            }
+        }
+        else {
+            sufficiencyCount += 1;
+            for (const axis of QUALITY_AXES) {
+                const gate = thresholds[axis];
+                if (gate.kind === "report")
+                    continue;
+                if (scores[axis] + TOLERANCE < gate.min) {
+                    if (gate.kind === "hard") {
+                        hard_failures.push({ fixture: fixture.name, axis, measured: scores[axis], min: gate.min });
+                    }
+                    else {
+                        warnings.push({ fixture: fixture.name, axis, measured: scores[axis], min: gate.min });
+                    }
+                }
+            }
+        }
+    }
+    return {
+        version: CONTEXT_STORE_SUFFICIENCY_VERSION,
+        passed: hard_failures.length === 0 && anchor_failures.length === 0,
+        sufficiency_fixtures: sufficiencyCount,
+        adversarial_fixtures: adversarialCount,
+        hard_failures,
+        warnings,
+        anchor_failures,
+        latency
+    };
+}
+function pct(value) {
+    return `${(value * 100).toFixed(1)}%`;
+}
+/**
+ * Internal markdown rendering of the sufficiency report. For local/CI inspection only —
+ * not a user-facing surface and not a claim.
+ */
+export function formatSufficiencyReportMarkdown(report) {
+    const lines = [
+        "## Context-store sufficiency report (INTERNAL — not a claim)",
+        "",
+        `Result: ${report.passed ? "PASS" : "FAIL"} · sufficiency fixtures: ${report.sufficiency_fixtures} · adversarial anchors: ${report.adversarial_fixtures}`,
+        ""
+    ];
+    if (report.hard_failures.length > 0) {
+        lines.push("### Hard-axis failures (FAIL)");
+        for (const f of report.hard_failures) {
+            lines.push(`- ${f.fixture} · ${f.axis}: ${pct(f.measured)} < required ${pct(f.min)}`);
+        }
+        lines.push("");
+    }
+    if (report.anchor_failures.length > 0) {
+        lines.push("### Adversarial anchor drift (FAIL)");
+        for (const f of report.anchor_failures) {
+            lines.push(`- ${f.fixture} · ${f.axis}: measured ${pct(f.measured)} ≠ expected ${pct(f.expected)}`);
+        }
+        lines.push("");
+    }
+    if (report.warnings.length > 0) {
+        lines.push("### Soft warnings (advisory — do not fail)");
+        for (const w of report.warnings) {
+            lines.push(`- ${w.fixture} · ${w.axis}: ${pct(w.measured)} < advisory ${pct(w.min)}`);
+        }
+        lines.push("");
+    }
+    lines.push("_Internal regression gate over synthetic fixtures. Hard axes: recall, source coverage,", "recoverability. Soft (advisory): continuation success (a marker proxy, NOT model replay).", "Latency: recorded only. Passing is NOT evidence of user-facing retrieval correctness,", "savings, semantic preservation, or any large-memory / 300M readiness._");
+    return lines.join("\n");
+}
+//# sourceMappingURL=context-store-sufficiency.js.map

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

@@ -0,0 +1,155 @@
+import type { AgentTrace, StateCapsule, StateCapsuleProvenanceEntry } from "./types.js";
+/**
+ * V0.4 context store — rung-1 (local, deterministic, source-grounded).
+ *
+ * SCOPE (accepted design doc `docs/design/v0.4-context-store-retrieval.md`,
+ * 2026-06-24): a durable, local, file-based store of source-pointed context items
+ * accumulated across runs, plus DETERMINISTIC local retrieval and assembly under a
+ * token budget. This module is the rung-1 core.
+ *
+ * HARD NON-GOALS (load-bearing — do not add here):
+ * - NO semantic / embedding retrieval. Retrieval ranks by deterministic signals only
+ *   (source-pointer match, lexical overlap, recency). Semantic retrieval needs a model
+ *   → not free-CLI local-first → deferred to the gated private engine/API.
+ * - NO network call, credential, upload, or model invocation. This module is pure +
+ *   local-file I/O only (see `loadContextStore` / `appendContextItems`).
+ * - NO hosted DB / vector store / auth.
+ * - NO large-memory / 300M-token / retrieval-correctness claim. Those are gated on the
+ *   four-axis eval harness (a follow-up increment) and rung-6 evidence.
+ *
+ * HONESTY: token figures here are `local_estimate` (chars/4), never provider-reported.
+ * Every stored item retains its `source_pointer` + recoverability so the assembled
+ * context stays recoverable to its sources (the substrate invariant).
+ */
+/** Algorithm + schema version, so a persisted store is self-describing. */
+export declare const CONTEXT_STORE_ITEM_VERSION = "context-store-item-v1";
+/**
+ * A single source-pointed context item accumulated in the store.
+ *
+ * `content` is local-only (like a captured trace) and is NEVER uploaded; the store
+ * lives under the gitignored `.compaction/` tree. `content_sha256` is the dedup key.
+ */
+export interface ContextStoreItem {
+    /** Schema version for forward-compatible reads. */
+    version: string;
+    /** SHA-256 of `content` — the dedup key (reuses the fingerprint discipline). */
+    content_sha256: string;
+    /** The retained context text (local-only; never uploaded). */
+    content: string;
+    /** Local token estimate (chars/4) for assembly budgeting. NOT provider-reported. */
+    estimated_tokens: number;
+    /** Recoverable pointer back to the source (kept so assembly stays recoverable). */
+    source_pointer?: string;
+    /** Source recoverability, carried straight from the substrate. */
+    recoverability: boolean | "unknown";
+    /** Per-run distinctness digest (from `computeTraceFingerprint`), if known. */
+    trace_fingerprint?: string;
+    /** The originating trace id, when known (a deterministic retrieval signal). */
+    source_trace_id?: string;
+    /** Provenance entry carried from the state-capsule, when available. */
+    provenance?: StateCapsuleProvenanceEntry;
+    /** Free-form deterministic labels (e.g. "retained_fact", "open_question"). */
+    labels: string[];
+    /** ISO-8601 creation timestamp (recency signal). Stamped at append time. */
+    created_at: string;
+}
+/** Input to `makeContextItem` — everything except the derived hash/token fields. */
+export interface ContextItemInput {
+    content: string;
+    source_pointer?: string;
+    recoverability?: boolean | "unknown";
+    trace_fingerprint?: string;
+    source_trace_id?: string;
+    provenance?: StateCapsuleProvenanceEntry;
+    labels?: string[];
+    created_at: string;
+}
+/**
+ * Build a single context item, deriving the dedup hash + local token estimate.
+ * Pure — no I/O, no clock (the caller supplies `created_at` so this stays
+ * deterministic and testable).
+ */
+export declare function makeContextItem(input: ContextItemInput): ContextStoreItem;
+/**
+ * Derive context items from a `StateCapsule`. Each retained fact / open question /
+ * safety note becomes a source-pointed item, inheriting the capsule's source pointer +
+ * recoverability + the originating trace id (and the supplied per-run fingerprint).
+ * Pure — `created_at` is supplied by the caller.
+ */
+export declare function contextItemsFromCapsule(capsule: StateCapsule, opts: {
+    created_at: string;
+    trace_fingerprint?: string;
+}): ContextStoreItem[];
+/**
+ * Derive context items from a normalized `AgentTrace` (the local artifact `compaction capture`
+ * / `import` produces). Each non-empty message becomes a source-pointed item recoverable to its
+ * `trace=<id> message=<id>` origin, tagged with the run's distinctness fingerprint. This is the
+ * free-CLI populate path (state-capsules require the gated engine; trace messages do not). Pure —
+ * `created_at` is supplied by the caller.
+ */
+export declare function contextItemsFromTrace(trace: AgentTrace, opts: {
+    created_at: string;
+}): ContextStoreItem[];
+/**
+ * Dedup by `content_sha256`, keeping the EARLIEST item deterministically (ties broken
+ * by `created_at`, then by the existing order). Reuses the fingerprint discipline:
+ * byte-identical content is one item, not many. Output order follows the
+ * first-occurrence order of each distinct hash in the input array.
+ */
+export declare function dedupeContextItems(items: ContextStoreItem[]): ContextStoreItem[];
+/** A retrieval query: the current step's context + optional source/trace hints. */
+export interface RetrievalQuery {
+    /** Free text describing the current step (task, recent messages, etc.). */
+    text: string;
+    /** Source pointers known to be relevant to the current step (exact-match boost). */
+    source_pointers?: string[];
+    /** Trace ids known to be relevant to the current step (exact-match boost). */
+    trace_ids?: string[];
+}
+export interface RetrievalOptions {
+    /** Max items to return (after ranking). Default: all candidates with score > 0. */
+    limit?: number;
+    /** Weight on exact source-pointer / trace-id match. Default 1. */
+    sourceMatchWeight?: number;
+    /** Weight on lexical overlap (overlap coefficient in [0,1]). Default 1. */
+    lexicalWeight?: number;
+}
+export interface RankedContextItem {
+    item: ContextStoreItem;
+    score: number;
+    source_match: boolean;
+    lexical_overlap: number;
+}
+/**
+ * Deterministic, local retrieval. Ranks items by:
+ *   score = sourceMatchWeight * (exact source/trace match ? 1 : 0)
+ *         + lexicalWeight     * lexical overlap coefficient in [0,1]
+ *
+ * Ties are broken deterministically by recency (newer first) then `content_sha256`
+ * ascending, so the same store + query always yields the same order. No model, no
+ * embeddings, no network — overlap is a pure word-set intersection.
+ */
+export declare function retrieveContextItems(items: ContextStoreItem[], query: RetrievalQuery, options?: RetrievalOptions): RankedContextItem[];
+export interface AssembleOptions {
+    /** Token budget for the assembled context (local estimate). */
+    tokenBudget: number;
+}
+export interface AssembledContext {
+    /** The assembled context text (included items joined, in ranked order). */
+    text: string;
+    /** Items that fit within the budget (provenance preserved on each). */
+    included: ContextStoreItem[];
+    /** Items dropped because the budget was exhausted (still recoverable from source). */
+    dropped: ContextStoreItem[];
+    /** Local token estimate of the assembled context. */
+    estimated_tokens: number;
+    /** Whether everything offered fit within the budget. */
+    within_budget: boolean;
+}
+/**
+ * Assemble ranked items into the sufficient active context under a token budget.
+ * Greedy in ranked order; dedups by `content_sha256`; PRESERVES the source pointer +
+ * provenance on every included item (so the assembled context stays recoverable).
+ * Token figures are local estimates.
+ */
+export declare function assembleContext(ranked: Array<RankedContextItem | ContextStoreItem>, options: AssembleOptions): AssembledContext;