@compaction/cli 0.1.4 → 0.3.0

package/dist/core/context-store.js

@@ -0,0 +1,228 @@
+import { contentHash } from "./content-hash.js";
+import { estimateTextTokens } from "./token-estimator.js";
+import { computeTraceFingerprint } from "./trace-fingerprint.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 const CONTEXT_STORE_ITEM_VERSION = "context-store-item-v1";
+function normalizeContent(content) {
+    return content.trim().replace(/\s+/g, " ");
+}
+/**
+ * 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 function makeContextItem(input) {
+    const content = normalizeContent(input.content);
+    return {
+        version: CONTEXT_STORE_ITEM_VERSION,
+        content_sha256: contentHash(content),
+        content,
+        estimated_tokens: estimateTextTokens(content),
+        source_pointer: input.source_pointer,
+        recoverability: input.recoverability ?? "unknown",
+        trace_fingerprint: input.trace_fingerprint,
+        source_trace_id: input.source_trace_id,
+        provenance: input.provenance,
+        labels: input.labels ? [...input.labels] : [],
+        created_at: input.created_at
+    };
+}
+/**
+ * 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 function contextItemsFromCapsule(capsule, opts) {
+    const primaryProvenance = capsule.provenance_entries?.[0];
+    const base = {
+        source_pointer: capsule.source_pointer ?? primaryProvenance?.source_pointer,
+        recoverability: capsule.source_recoverable ?? primaryProvenance?.source_recoverable ?? "unknown",
+        source_trace_id: capsule.source_trace_id ?? capsule.traceId,
+        provenance: primaryProvenance,
+        trace_fingerprint: opts.trace_fingerprint,
+        created_at: opts.created_at
+    };
+    const items = [];
+    for (const fact of capsule.retainedFacts) {
+        if (fact.trim().length === 0)
+            continue;
+        items.push(makeContextItem({ ...base, content: fact, labels: ["retained_fact"] }));
+    }
+    for (const question of capsule.openQuestions) {
+        if (question.trim().length === 0)
+            continue;
+        items.push(makeContextItem({ ...base, content: question, labels: ["open_question"] }));
+    }
+    for (const note of capsule.safetyNotes) {
+        if (note.trim().length === 0)
+            continue;
+        items.push(makeContextItem({ ...base, content: note, labels: ["safety_note"] }));
+    }
+    return dedupeContextItems(items);
+}
+/**
+ * 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 function contextItemsFromTrace(trace, opts) {
+    const trace_fingerprint = computeTraceFingerprint(trace).content_sha256;
+    const items = [];
+    for (const message of trace.messages) {
+        if (message.content.trim().length === 0)
+            continue;
+        const labels = [message.role];
+        if (message.toolName)
+            labels.push(message.toolName);
+        items.push(makeContextItem({
+            content: message.content,
+            source_pointer: `trace=${trace.id} message=${message.id}`,
+            source_trace_id: trace.id,
+            recoverability: true,
+            trace_fingerprint,
+            labels,
+            created_at: opts.created_at
+        }));
+    }
+    return dedupeContextItems(items);
+}
+/**
+ * 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 function dedupeContextItems(items) {
+    const byHash = new Map();
+    for (const item of items) {
+        const existing = byHash.get(item.content_sha256);
+        if (!existing || item.created_at < existing.created_at) {
+            // Merge labels so a later duplicate's labels are not lost.
+            if (existing) {
+                const labels = Array.from(new Set([...item.labels, ...existing.labels])).sort();
+                byHash.set(item.content_sha256, { ...item, labels });
+            }
+            else {
+                byHash.set(item.content_sha256, item);
+            }
+        }
+        else {
+            const labels = Array.from(new Set([...existing.labels, ...item.labels])).sort();
+            byHash.set(item.content_sha256, { ...existing, labels });
+        }
+    }
+    return Array.from(byHash.values());
+}
+const WORD_RE = /[a-z0-9]+/g;
+function tokenSet(text) {
+    const set = new Set();
+    const matches = text.toLowerCase().match(WORD_RE);
+    if (matches) {
+        for (const word of matches)
+            set.add(word);
+    }
+    return set;
+}
+/**
+ * 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 function retrieveContextItems(items, query, options = {}) {
+    const sourceWeight = options.sourceMatchWeight ?? 1;
+    const lexicalWeight = options.lexicalWeight ?? 1;
+    const queryWords = tokenSet(query.text);
+    const wantedPointers = new Set(query.source_pointers ?? []);
+    const wantedTraces = new Set(query.trace_ids ?? []);
+    const ranked = items.map((item) => {
+        const sourceMatch = (item.source_pointer !== undefined && wantedPointers.has(item.source_pointer)) ||
+            (item.source_trace_id !== undefined && wantedTraces.has(item.source_trace_id));
+        let overlap = 0;
+        if (queryWords.size > 0) {
+            const itemWords = tokenSet(item.content);
+            if (itemWords.size > 0) {
+                let intersection = 0;
+                const [small, large] = queryWords.size <= itemWords.size ? [queryWords, itemWords] : [itemWords, queryWords];
+                for (const word of small) {
+                    if (large.has(word))
+                        intersection += 1;
+                }
+                // Overlap coefficient: intersection / min(|q|, |item|) — in [0, 1].
+                overlap = intersection / Math.min(queryWords.size, itemWords.size);
+            }
+        }
+        const score = sourceWeight * (sourceMatch ? 1 : 0) + lexicalWeight * overlap;
+        return { item, score, source_match: sourceMatch, lexical_overlap: overlap };
+    });
+    ranked.sort((a, b) => {
+        if (b.score !== a.score)
+            return b.score - a.score;
+        if (a.item.created_at !== b.item.created_at)
+            return a.item.created_at < b.item.created_at ? 1 : -1;
+        return a.item.content_sha256 < b.item.content_sha256 ? -1 : 1;
+    });
+    const withSignal = ranked.filter((entry) => entry.score > 0);
+    return options.limit !== undefined ? withSignal.slice(0, options.limit) : withSignal;
+}
+/**
+ * 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 function assembleContext(ranked, options) {
+    const items = ranked.map((entry) => ("item" in entry ? entry.item : entry));
+    const included = [];
+    const dropped = [];
+    const seen = new Set();
+    let total = 0;
+    for (const item of items) {
+        if (seen.has(item.content_sha256))
+            continue;
+        seen.add(item.content_sha256);
+        if (total + item.estimated_tokens <= options.tokenBudget) {
+            included.push(item);
+            total += item.estimated_tokens;
+        }
+        else {
+            dropped.push(item);
+        }
+    }
+    return {
+        text: included.map((item) => item.content).join("\n"),
+        included,
+        dropped,
+        estimated_tokens: total,
+        within_budget: dropped.length === 0
+    };
+}
+//# sourceMappingURL=context-store.js.map

package/dist/core/cross-surface-event.d.ts

@@ -0,0 +1,306 @@
+/**
+ * ADDITIVE typed representation of the cross-surface evidence & reporting contract —
+ * `docs/ops/cross-surface-evidence-contract.md` (authority doc; founder decisions D1–D6, 2026-07-03).
+ *
+ * One event model, many surfaces: every Compaction surface reports the SAME kind of event with
+ * different honest evidence tiers. This module is the *contract/type level* of that model:
+ *
+ * - It is ADDITIVE. It does NOT change the existing `usage_event` wire shape
+ *   (`src/core/capture-record.ts`), the local run record (`src/core/local-run-record.ts`), or any
+ *   current writer/reader. No writer is REQUIRED to populate these fields (named follow-ups in
+ *   the contract §7 stay follow-ups); the Cursor `run cursor` local run record is the first
+ *   writer that does (D3 alignment, charter 2026-07-03-run-5), via
+ *   `buildCursorRunCrossSurfaceEvent` below.
+ * - It makes the D5 HARD GUARDRAIL structural where TypeScript allows: a fixed-plan /
+ *   plan-efficiency event can NEVER be billing-confirmed. `claim_scope:
+ *   "billing-confirmed-workflow-scoped"` is only constructible on `surface: "api_metered"` with
+ *   `cost_source: "provider-reported" | "operator-entered"` (contract §5 / D6), and a
+ *   plan-efficiency payload structurally excludes it (`plan_efficiency?: never` on that arm;
+ *   `billing_confirmed: false` is a literal type on the payload itself).
+ * - Where the type system cannot enforce a rule on parsed/unknown data, the REPORT-ONLY validator
+ *   `validateCrossSurfaceEvent` catches it: it returns problems and never throws.
+ * - Honesty rails (contract §2): per-axis `token_source` with `unavailable_reason` required when
+ *   unavailable; never a silent zero (an unavailable axis never carries a numeric count); input
+ *   and output are independent axes; "generalized" is not a representable claim scope.
+ *
+ * NOTE on naming: contract `surface` values use underscores (`claude_code`, `browser_extension`)
+ * per the founder-verbatim field contract; the existing wire `ToolName` enum uses dashes
+ * (`claude-code`). `surfaceForToolName` maps between them without changing either.
+ */
+import type { ToolName } from "./api-client/index.js";
+import type { RunFlowTokenReport } from "./run-flow-report.js";
+/** Contract §2: which Compaction surface produced the event (exact values, verbatim). */
+export declare const CROSS_SURFACE_SURFACES: readonly ["cli", "claude_code", "codex", "cursor", "browser_extension", "api_metered"];
+export type CrossSurfaceSurface = (typeof CROSS_SURFACE_SURFACES)[number];
+/** Contract §2: whose model/service was used — distinct from `surface`. */
+export declare const CROSS_SURFACE_PROVIDERS: readonly ["anthropic", "openai", "cursor", "chatgpt", "other"];
+export type CrossSurfaceProvider = (typeof CROSS_SURFACE_PROVIDERS)[number];
+/** Contract §2: per-axis token source. Input and output are INDEPENDENT axes. */
+export declare const CROSS_SURFACE_TOKEN_SOURCES: readonly ["provider-reported", "local-estimate", "unavailable"];
+export type CrossSurfaceTokenSource = (typeof CROSS_SURFACE_TOKEN_SOURCES)[number];
+/** Contract §2: how the cost figure (if any) is known. `operator-entered` is the billing-delta operator path. */
+export declare const CROSS_SURFACE_COST_SOURCES: readonly ["provider-reported", "operator-entered", "local-estimate", "unavailable"];
+export type CrossSurfaceCostSource = (typeof CROSS_SURFACE_COST_SOURCES)[number];
+/** Contract §5 (D6): the ONLY cost sources that can underwrite a billing-confirmed figure. */
+export type BillingConfirmedCostSource = "provider-reported" | "operator-entered";
+/**
+ * Contract §2 honesty rule: what a figure may be scoped to — this run / this workflow / these
+ * conditions. A GENERALIZED claim is intentionally NOT representable (D6: "Generalized
+ * billing-confirmed = future only. Public generalized 'saves X%' is forbidden.").
+ * `billing-confirmed-workflow-scoped` exists only on the `BillingConfirmedCrossSurfaceEvent` arm.
+ */
+export declare const CROSS_SURFACE_CLAIM_SCOPES: readonly ["run-scoped", "workflow-scoped", "conditions-scoped", "billing-confirmed-workflow-scoped"];
+export type CrossSurfaceClaimScope = (typeof CROSS_SURFACE_CLAIM_SCOPES)[number];
+/** Every claim scope EXCEPT billing-confirmed — the only scopes a standard event may carry. */
+export type NonBillingClaimScope = Exclude<CrossSurfaceClaimScope, "billing-confirmed-workflow-scoped">;
+/** Contract §2: accepted/reverted — reverts are honest signal, never hidden. */
+export type CrossSurfaceAcceptance = "accepted" | "reverted";
+/** Contract §2: result of the applicable eval gate, or `not_evaluated` (never auto-certified). */
+export type CrossSurfaceEvalStatus = "passed" | "failed" | "not_computed" | "not_evaluated";
+/** How the underlying product is billed. `fixed-plan` marks quota/subscription billing (D5). */
+export type CrossSurfaceBillingModel = "fixed-plan" | "metered" | "unknown";
+/**
+ * One token axis: its honest source, plus the EXACT reason (and optional rerun guidance) when the
+ * axis is `unavailable`. Contract §2: "field-level unavailable WITH the exact reason".
+ */
+export interface CrossSurfaceTokenAxis {
+    source: CrossSurfaceTokenSource;
+    /** REQUIRED (validator-enforced) when `source` is "unavailable" — the exact honest reason. */
+    unavailable_reason?: string;
+}
+/** Per-axis token sources. Neither axis ever inherits the other's tier (contract §2). */
+export interface CrossSurfaceTokenSources {
+    input: CrossSurfaceTokenAxis;
+    output: CrossSurfaceTokenAxis;
+}
+/**
+ * Contract §4 (D5): plan-efficiency — a NEW evidence type for fixed-plan products
+ * (quota-extension). DEFINED only; ZERO evidence exists today and no claim may be made.
+ * `billing_confirmed` is the LITERAL `false`: a plan-efficiency figure is structurally incapable
+ * of being billing-confirmed, however strong the measurement.
+ */
+export interface PlanEfficiencySignals {
+    evidence_type: "plan-efficiency";
+    /** HARD GUARDRAIL (D5): literal `false` — a fixed-plan figure can NEVER be billing-confirmed. */
+    billing_confirmed: false;
+    /** Identity of the quota window the signals were observed in (content-free). */
+    quota_window_id?: string;
+    /** More useful work per quota window (contract §4). */
+    tasks_completed_in_window?: number | null;
+    /** Fewer / later cap events (contract §4). */
+    cap_events_in_window?: number | null;
+    /** Fewer visible tokens per task — LOCAL-ESTIMATE per the tier table (contract §4). */
+    visible_tokens_per_task_estimate?: number | null;
+    /** More successful tasks before reset (contract §4). */
+    successful_tasks_before_reset?: number | null;
+}
+/**
+ * Fields shared by every event arm. ALL fields are optional/additive (contract §2: "a surface
+ * omits what it genuinely cannot observe, with a reason") — the discriminating fields live on the
+ * arms below. Counts may be `null` to mean "explicitly not counted" (never rendered as 0).
+ */
+export interface CrossSurfaceEventCommon {
+    /** Existing user/team model (paid reporting aggregates by these). Free/local may omit (no sync). */
+    user_id?: string;
+    team_id?: string;
+    /** Whose model/service was used — e.g. surface `browser_extension` + provider `chatgpt`. */
+    provider?: CrossSurfaceProvider;
+    /** The model as honestly known — `unknown` stays `unknown`, never inferred. */
+    model_label?: string;
+    /** Identity for rollup and A/B comparability (billing-delta requires pinned workflow identity). */
+    workflow_id?: string;
+    session_id?: string;
+    run_id?: string;
+    /** Input tokens before/after Compaction acted, counted per `token_source.input`. */
+    input_before?: number | null;
+    input_after?: number | null;
+    /** Output tokens before/after (or estimate), counted per `token_source.output`. */
+    output_before?: number | null;
+    output_after?: number | null;
+    /** An estimate is an estimate and says so — it never upgrades the axis tier. */
+    output_estimate?: number | null;
+    /** Per-axis honest sources. A numeric count without a labeled axis is a validator problem. */
+    token_source?: CrossSurfaceTokenSources;
+    /** Which deterministic policy acted (content-free identifier). */
+    policy_used?: string;
+    /** Whether the user kept or reverted the optimization. */
+    acceptance?: CrossSurfaceAcceptance;
+    /** Result of the applicable recoverability eval gate, or `not_evaluated`. */
+    recoverability?: CrossSurfaceEvalStatus;
+    /** Result of the applicable output eval gate (short-but-sufficient), or `not_evaluated`. */
+    eval_status?: CrossSurfaceEvalStatus;
+    /** The exact honest label for this event's figures — never stronger than the sources support. */
+    evidence_level?: string;
+    /** Per-surface honesty caveats carried WITH the event, never stripped in rollup. */
+    caveats?: string[];
+    /** Exact reason when `cost_source` is "unavailable". */
+    cost_unavailable_reason?: string;
+}
+/**
+ * The standard event arm: any surface, any honest cost source, any NON-billing-confirmed claim
+ * scope. Fixed-plan surfaces and plan-efficiency events live here — and ONLY here.
+ */
+export interface StandardCrossSurfaceEvent extends CrossSurfaceEventCommon {
+    surface: CrossSurfaceSurface;
+    billing_model?: CrossSurfaceBillingModel;
+    cost_source?: CrossSurfaceCostSource;
+    /** Structurally excludes "billing-confirmed-workflow-scoped" (D5/D6). */
+    claim_scope?: NonBillingClaimScope;
+    /** Plan-efficiency signals (fixed-plan quota-extension) — never on the billing-confirmed arm. */
+    plan_efficiency?: PlanEfficiencySignals;
+}
+/**
+ * The ONLY arm that can carry a billing-confirmed claim (contract §5 / D6): `api_metered`
+ * surface, provider-billed or operator-entered cost, workflow-scoped only. A plan-efficiency
+ * payload is structurally unrepresentable here (`never`), and `billing_model` can never be
+ * "fixed-plan".
+ */
+export interface BillingConfirmedCrossSurfaceEvent extends CrossSurfaceEventCommon {
+    surface: "api_metered";
+    claim_scope: "billing-confirmed-workflow-scoped";
+    cost_source: BillingConfirmedCostSource;
+    billing_model?: "metered";
+    plan_efficiency?: never;
+}
+/**
+ * The cross-surface event. A discriminated union: constructing a fixed-plan / non-metered /
+ * plan-efficiency event with a billing-confirmed claim scope is a TYPE ERROR, not just a
+ * validator problem.
+ */
+export type CrossSurfaceEvent = StandardCrossSurfaceEvent | BillingConfirmedCrossSurfaceEvent;
+type Assert<T extends true> = T;
+type BillingConfirmedArm = Extract<CrossSurfaceEvent, {
+    claim_scope: "billing-confirmed-workflow-scoped";
+}>;
+/** The billing-confirmed arm exists (so the guards below can never pass vacuously via `never`). */
+export type StructuralGuard_BillingConfirmedArmExists = Assert<[BillingConfirmedArm] extends [never] ? false : true>;
+/** A billing-confirmed claim can ONLY exist on the api_metered surface. */
+export type StructuralGuard_BillingConfirmedRequiresMeteredSurface = Assert<BillingConfirmedArm["surface"] extends "api_metered" ? true : false>;
+/** A billing-confirmed claim can ONLY carry provider-reported | operator-entered cost. */
+export type StructuralGuard_BillingConfirmedCostSource = Assert<BillingConfirmedArm["cost_source"] extends BillingConfirmedCostSource ? true : false>;
+/** A billing-confirmed event can NEVER carry a plan-efficiency payload. */
+export type StructuralGuard_BillingConfirmedExcludesPlanEfficiency = Assert<Required<BillingConfirmedArm>["plan_efficiency"] extends never ? true : false>;
+/** A plan-efficiency payload is structurally incapable of claiming billing_confirmed. */
+export type StructuralGuard_PlanEfficiencyNeverBillingConfirmed = Assert<PlanEfficiencySignals["billing_confirmed"] extends false ? true : false>;
+/** A billing-confirmed event can never be marked fixed-plan. */
+export type StructuralGuard_BillingConfirmedNeverFixedPlan = Assert<Required<BillingConfirmedArm>["billing_model"] extends "metered" ? true : false>;
+/**
+ * Map the EXISTING wire `ToolName` to the contract `surface` value, honestly:
+ * - `claude-code` → `claude_code`, `codex` → `codex`, `cursor` → `cursor`;
+ * - `other` (the bare `compaction run -- <cmd>` wrapper) → `cli` per the tier table ("bare
+ *   run/trace analysis without provider usage");
+ * - `openai-agents` → `undefined`: the contract names no surface for it, and unknown stays
+ *   unknown — this helper never guesses (named residual, like the control-plane enum alignment).
+ */
+export declare function surfaceForToolName(tool: ToolName): CrossSurfaceSurface | undefined;
+/**
+ * Contract tier table (§3, D3/D4): surfaces whose token tier can NEVER be provider-reported —
+ * Cursor emits no usage (vendor gap; "never provider-reported"), and the browser's visible
+ * surface exposes no provider usage ("may NOT claim provider-reported web tokens").
+ */
+export declare const NEVER_PROVIDER_REPORTED_SURFACES: readonly CrossSurfaceSurface[];
+export interface CrossSurfaceEventValidation {
+    /** Empty when the event honors the contract. Report-only: nothing throws, nothing exits. */
+    problems: string[];
+}
+/**
+ * Validate one parsed/unknown cross-surface event against the contract. REPORT-ONLY: returns the
+ * list of problems (empty = contract-honest) and NEVER throws — mirroring the repo's
+ * skipped-with-reason validator style. Rules enforced here are exactly the ones the type system
+ * cannot enforce on unknown data:
+ *
+ * 1. exact enums for surface / provider / token sources / cost source / claim scope;
+ * 2. D5 hard guardrail: a fixed-plan or plan-efficiency event is NEVER billing-confirmed;
+ * 3. D6: billing-confirmed requires surface api_metered + provider-reported|operator-entered cost;
+ * 4. tier table (D3/D4): cursor and browser_extension events never carry provider-reported tokens;
+ * 5. no silent zero: an unavailable axis never carries a numeric count;
+ * 6. per-axis unavailable_reason required when an axis is unavailable;
+ * 7. a numeric count requires its axis to be labeled (a count without a token_source is unlabeled).
+ */
+export declare function validateCrossSurfaceEvent(value: unknown): CrossSurfaceEventValidation;
+/**
+ * Per-surface constraints for the `run` local-run-record writers (contract tier table §3):
+ * - `codex` — `run codex`: provider `openai`; token axes are provider-reported where a
+ *   `turn.completed.usage` block existed (the report says which). Codex reports token usage but
+ *   never a cost/billing figure, so cost is UNAVAILABLE with that exact reason.
+ * - `cursor` — `run cursor`: provider `cursor`; LOCAL-ESTIMATE/unavailable only (D3 ceiling —
+ *   Cursor emits no usage), and no cost data exists at all.
+ * - `cli` — bare `run -- <cmd>`: an arbitrary wrapped command, provider `other` (no provider is
+ *   involved that Compaction can observe); input is a local chars/4 estimate, output is
+ *   unavailable with the command-surface reason, and no billing surface exists.
+ * - `claude_code` — the `capture claude-code --from-hook` always-on path (charter 2026-07-04-run-8):
+ *   provider `anthropic`; token axes are PROVIDER-REPORTED where the Claude Code session usage
+ *   fields carried them (the report says which — a missing axis stays unavailable-with-reason,
+ *   never a silent zero). Claude Code reports tokens but no cost/billing figure, so cost is
+ *   UNAVAILABLE with that exact reason. This is NOT invented evidence: the Stop-hook capture reads
+ *   the session's OWN provider usage metadata — the same provider-reported tokens `capture
+ *   claude-code` already surfaces — it simply also records a metrics-only activity event so a
+ *   subsequent session appears in `compaction activity` with no manual import.
+ */
+export declare const RUN_RECORD_EVENT_SURFACES: {
+    readonly codex: {
+        readonly surface: "codex";
+        readonly provider: "openai";
+        readonly cost_unavailable_reason: "codex exec --json reports token usage (turn.completed.usage) but no cost or billing figure; no cost data exists on this path";
+    };
+    readonly claude_code: {
+        readonly surface: "claude_code";
+        readonly provider: "anthropic";
+        readonly cost_unavailable_reason: "Claude Code session usage reports provider tokens (input/output) but no cost or billing figure; no cost data exists on this path";
+    };
+    readonly cursor: {
+        readonly surface: "cursor";
+        readonly provider: "cursor";
+        readonly cost_unavailable_reason: "Cursor emits no usage or cost data; no cost figure exists for this run";
+    };
+    readonly cli: {
+        readonly surface: "cli";
+        readonly provider: "other";
+        readonly cost_unavailable_reason: "a bare wrapped command has no provider usage or billing surface; no cost figure exists for this run";
+    };
+};
+export type RunRecordEventSurface = keyof typeof RUN_RECORD_EVENT_SURFACES;
+export interface RunCrossSurfaceEventParams {
+    runId: string;
+    tokenReport: RunFlowTokenReport;
+    /** TRUE per-axis unavailability reasons from the capture (required content for unavailable axes). */
+    reasons?: {
+        input?: string;
+        output?: string;
+    };
+    /** The model as the capture HONESTLY knows it. Omitted → "unknown" (unknown stays unknown, never inferred). */
+    modelLabel?: string;
+}
+/**
+ * Build the honest cross-surface event for one `run` local run record (any of the three `run`
+ * surfaces above):
+ * - `surface`/`provider` fixed per surface; `model_label` only as honestly known, else `"unknown"`;
+ * - per-axis `token_source` copied VERBATIM from the token report (input and output INDEPENDENT),
+ *   with the capture's TRUE per-run reason on any unavailable axis (never a bare "unavailable");
+ * - counts only on available axes, under the count field that matches the axis tier:
+ *   `input_before` for the counted/estimated input; a provider-reported output is a COUNT
+ *   (`output_before`), a local-estimate output is an ESTIMATE and says so (`output_estimate`) —
+ *   an unavailable axis carries NO count (never a silent zero);
+ * - `cost_source: "unavailable"` with the exact per-surface reason (no `run` path has billing data);
+ * - `claim_scope: "run-scoped"` (never generalized); caveats = the report's honest notes.
+ *
+ * The tier ceilings stay intact: this builder never SETS provider-reported (it only copies the
+ * report's label), and if a never-provider-reported surface (Cursor) is handed one it passes it
+ * through unchanged so the report-only validator rejects it (rule 4) instead of hiding it.
+ */
+export declare function buildRunCrossSurfaceEvent(surfaceKey: RunRecordEventSurface, params: RunCrossSurfaceEventParams): StandardCrossSurfaceEvent;
+/**
+ * The Cursor writer (D3 alignment, #583) — kept as the named entry point its call/test sites use;
+ * now a thin delegate to the generalized builder with the `cursor` constraints (`surface:
+ * "cursor"`, `provider: "cursor"`, `model_label: "unknown"` — never inferred, D3 ceiling intact).
+ */
+export declare function buildCursorRunCrossSurfaceEvent(params: {
+    runId: string;
+    tokenReport: RunFlowTokenReport;
+    /** TRUE per-axis unavailability reasons from the capture (required content for unavailable axes). */
+    reasons?: {
+        input?: string;
+        output?: string;
+    };
+}): StandardCrossSurfaceEvent;
+export {};