@compaction/cli 0.2.0 → 0.3.1

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

package/dist/core/cross-surface-event.js

@@ -0,0 +1,330 @@
+/** Contract §2: which Compaction surface produced the event (exact values, verbatim). */
+export const CROSS_SURFACE_SURFACES = [
+    "cli",
+    "claude_code",
+    "codex",
+    "cursor",
+    "browser_extension",
+    "api_metered"
+];
+/** Contract §2: whose model/service was used — distinct from `surface`. */
+export const CROSS_SURFACE_PROVIDERS = ["anthropic", "openai", "cursor", "chatgpt", "other"];
+/** Contract §2: per-axis token source. Input and output are INDEPENDENT axes. */
+export const CROSS_SURFACE_TOKEN_SOURCES = ["provider-reported", "local-estimate", "unavailable"];
+/** Contract §2: how the cost figure (if any) is known. `operator-entered` is the billing-delta operator path. */
+export const CROSS_SURFACE_COST_SOURCES = [
+    "provider-reported",
+    "operator-entered",
+    "local-estimate",
+    "unavailable"
+];
+/**
+ * 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 const CROSS_SURFACE_CLAIM_SCOPES = [
+    "run-scoped",
+    "workflow-scoped",
+    "conditions-scoped",
+    "billing-confirmed-workflow-scoped"
+];
+/* ------------------------------------------------------------------------------------------------
+ * Surfaces ↔ existing wire ToolName mapping (additive helper; changes neither enum).
+ * ---------------------------------------------------------------------------------------------- */
+/**
+ * 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 function surfaceForToolName(tool) {
+    switch (tool) {
+        case "claude-code":
+            return "claude_code";
+        case "codex":
+            return "codex";
+        case "cursor":
+            return "cursor";
+        case "other":
+            return "cli";
+        case "openai-agents":
+            return undefined;
+    }
+}
+/* ------------------------------------------------------------------------------------------------
+ * REPORT-ONLY validator. Returns problems; never throws. It exists for the states TypeScript
+ * cannot police (parsed JSON, widened objects, wire data) and encodes the contract's honesty
+ * rules as label-correctness checks.
+ * ---------------------------------------------------------------------------------------------- */
+/**
+ * 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 const NEVER_PROVIDER_REPORTED_SURFACES = ["cursor", "browser_extension"];
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isOneOf(value, allowed) {
+    return typeof value === "string" && allowed.includes(value);
+}
+function isNonEmptyString(value) {
+    return typeof value === "string" && value.trim() !== "";
+}
+/** A count field may be absent, `null` (explicitly not counted), or a finite number ≥ 0. */
+function countProblem(field, value) {
+    if (value === undefined || value === null)
+        return undefined;
+    if (typeof value === "number" && Number.isFinite(value) && value >= 0)
+        return undefined;
+    return `${field}: must be a finite number >= 0, null, or absent`;
+}
+const INPUT_COUNT_FIELDS = ["input_before", "input_after"];
+const OUTPUT_COUNT_FIELDS = ["output_before", "output_after", "output_estimate"];
+function validateAxis(axisName, axis, event, problems) {
+    const countFields = axisName === "input" ? INPUT_COUNT_FIELDS : OUTPUT_COUNT_FIELDS;
+    if (!isPlainObject(axis)) {
+        problems.push(`token_source.${axisName}: must be an object with a per-axis source`);
+        return;
+    }
+    if (!isOneOf(axis.source, CROSS_SURFACE_TOKEN_SOURCES)) {
+        problems.push(`token_source.${axisName}.source: must be one of ${CROSS_SURFACE_TOKEN_SOURCES.join(" | ")} (exact)`);
+        return;
+    }
+    if (axis.source === "unavailable") {
+        // Contract §2: field-level unavailable WITH the exact reason — required per axis.
+        if (!isNonEmptyString(axis.unavailable_reason)) {
+            problems.push(`token_source.${axisName}.unavailable_reason: required when the ${axisName} axis is unavailable (the exact honest reason)`);
+        }
+        // Contract §2: never a silent zero — an unavailable axis never carries a numeric count
+        // (a 0 here would dress a missing count as a real one).
+        for (const field of countFields) {
+            if (typeof event[field] === "number") {
+                problems.push(`${field}: no silent zero — the ${axisName} axis is unavailable, so a numeric count (including 0) must not be present`);
+            }
+        }
+    }
+}
+/**
+ * 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 function validateCrossSurfaceEvent(value) {
+    const problems = [];
+    if (!isPlainObject(value)) {
+        return { problems: ["event: must be a JSON object"] };
+    }
+    const event = value;
+    // Rule 1 — exact enums.
+    if (!isOneOf(event.surface, CROSS_SURFACE_SURFACES)) {
+        problems.push(`surface: must be one of ${CROSS_SURFACE_SURFACES.join(" | ")} (exact)`);
+    }
+    if (event.provider !== undefined && !isOneOf(event.provider, CROSS_SURFACE_PROVIDERS)) {
+        problems.push(`provider: must be one of ${CROSS_SURFACE_PROVIDERS.join(" | ")} (exact)`);
+    }
+    if (event.cost_source !== undefined && !isOneOf(event.cost_source, CROSS_SURFACE_COST_SOURCES)) {
+        problems.push(`cost_source: must be one of ${CROSS_SURFACE_COST_SOURCES.join(" | ")} (exact)`);
+    }
+    if (event.claim_scope !== undefined && !isOneOf(event.claim_scope, CROSS_SURFACE_CLAIM_SCOPES)) {
+        problems.push(`claim_scope: must be one of ${CROSS_SURFACE_CLAIM_SCOPES.join(" | ")} (exact; generalized claims are not representable)`);
+    }
+    if (event.cost_source === "unavailable" && !isNonEmptyString(event.cost_unavailable_reason)) {
+        problems.push("cost_unavailable_reason: required when cost_source is unavailable (the exact honest reason)");
+    }
+    // Count fields are well-formed (absent | null | finite >= 0).
+    for (const field of [...INPUT_COUNT_FIELDS, ...OUTPUT_COUNT_FIELDS]) {
+        const problem = countProblem(field, event[field]);
+        if (problem !== undefined)
+            problems.push(problem);
+    }
+    // Rules 5–6 — per-axis honesty; rule 7 — counts require a labeled axis.
+    const tokenSource = event.token_source;
+    if (tokenSource !== undefined) {
+        if (!isPlainObject(tokenSource)) {
+            problems.push("token_source: must be an object with input and output axes");
+        }
+        else {
+            validateAxis("input", tokenSource.input, event, problems);
+            validateAxis("output", tokenSource.output, event, problems);
+        }
+    }
+    else {
+        for (const field of [...INPUT_COUNT_FIELDS, ...OUTPUT_COUNT_FIELDS]) {
+            if (typeof event[field] === "number") {
+                problems.push(`${field}: a numeric count requires token_source for its axis — an unlabeled count is not honest`);
+            }
+        }
+    }
+    // Rule 4 — tier ceilings (D3/D4): cursor + browser events never carry provider-reported tokens.
+    if (isOneOf(event.surface, NEVER_PROVIDER_REPORTED_SURFACES) &&
+        isPlainObject(tokenSource)) {
+        for (const axisName of ["input", "output"]) {
+            const axis = tokenSource[axisName];
+            if (isPlainObject(axis) && axis.source === "provider-reported") {
+                problems.push(`token_source.${axisName}.source: surface "${String(event.surface)}" can never be provider-reported (contract tier table — vendor exposes no usage)`);
+            }
+        }
+    }
+    // Rules 2–3 — the D5/D6 guardrail on unknown data.
+    const planEfficiency = event.plan_efficiency;
+    if (planEfficiency !== undefined) {
+        if (!isPlainObject(planEfficiency)) {
+            problems.push("plan_efficiency: must be an object");
+        }
+        else {
+            if (planEfficiency.evidence_type !== "plan-efficiency") {
+                problems.push('plan_efficiency.evidence_type: must be the literal "plan-efficiency"');
+            }
+            if (planEfficiency.billing_confirmed !== false) {
+                problems.push("plan_efficiency.billing_confirmed: must be the literal false — a fixed-plan figure can NEVER be billing-confirmed (contract §4, D5)");
+            }
+        }
+    }
+    const claimsBillingConfirmed = event.claim_scope === "billing-confirmed-workflow-scoped";
+    const isFixedPlanEvent = event.billing_model === "fixed-plan" ||
+        planEfficiency !== undefined ||
+        isOneOf(event.surface, NEVER_PROVIDER_REPORTED_SURFACES);
+    if (claimsBillingConfirmed) {
+        if (event.surface !== "api_metered") {
+            problems.push(`claim_scope: billing-confirmed is only possible on surface "api_metered" (contract §5, D6) — surface "${String(event.surface)}" can never be billing-confirmed`);
+        }
+        if (event.cost_source !== "provider-reported" && event.cost_source !== "operator-entered") {
+            problems.push("cost_source: a billing-confirmed claim requires provider-reported or operator-entered cost (contract §5, D6) — never a price-table/local estimate relabeled");
+        }
+        if (event.billing_model === "fixed-plan" || planEfficiency !== undefined) {
+            problems.push("claim_scope: a fixed-plan / plan-efficiency event can NEVER be billing-confirmed (contract §4, D5 — hard guardrail, no exceptions)");
+        }
+    }
+    // Defensive label rule: an evidence label that SAYS billing-confirmed on a fixed-plan event is
+    // the exact overclaim D5 forbids, whatever the claim_scope field says.
+    if (typeof event.evidence_level === "string" &&
+        event.evidence_level.toLowerCase().includes("billing-confirmed") &&
+        isFixedPlanEvent) {
+        problems.push("evidence_level: mentions billing-confirmed on a fixed-plan / plan-efficiency / never-provider-reported event — labels must make this impossible (contract §4, D5)");
+    }
+    return { problems };
+}
+/* ------------------------------------------------------------------------------------------------
+ * Run-record event builders — the writers of the additive `cross_surface_event` field on `run`
+ * local run records. Cursor shipped first (D3 alignment, charter 2026-07-03-run-5, #583); the
+ * codex + cli writers complete the `run` surfaces (#582 residual #5, same charter). Every writer
+ * populates the event from the SAME `RunFlowTokenReport` the record already embeds, so the two can
+ * never diverge — and per-axis sources are copied VERBATIM (the builder never launders labels).
+ * ---------------------------------------------------------------------------------------------- */
+/** Generic honest fallback when an unavailable axis arrives without its TRUE per-run reason. */
+const AXIS_UNAVAILABLE_FALLBACK = "not safely separable / not reported";
+/** One axis derived from the token report. NEVER relabels: if an upstream source ever wrongly said
+ *  provider-reported for a never-provider-reported surface (e.g. Cursor), this passes it through
+ *  and `validateCrossSurfaceEvent` flags it (rule 4) — the builder does not launder labels. */
+function axisFromReport(source, reason) {
+    if (source === "unavailable") {
+        return { source, unavailable_reason: reason ?? AXIS_UNAVAILABLE_FALLBACK };
+    }
+    return { source };
+}
+/**
+ * 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 const RUN_RECORD_EVENT_SURFACES = {
+    codex: {
+        surface: "codex",
+        provider: "openai",
+        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"
+    },
+    claude_code: {
+        surface: "claude_code",
+        provider: "anthropic",
+        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"
+    },
+    cursor: {
+        surface: "cursor",
+        provider: "cursor",
+        cost_unavailable_reason: "Cursor emits no usage or cost data; no cost figure exists for this run"
+    },
+    cli: {
+        surface: "cli",
+        provider: "other",
+        cost_unavailable_reason: "a bare wrapped command has no provider usage or billing surface; no cost figure exists for this run"
+    }
+};
+/**
+ * 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 function buildRunCrossSurfaceEvent(surfaceKey, params) {
+    const spec = RUN_RECORD_EVENT_SURFACES[surfaceKey];
+    const report = params.tokenReport;
+    const input = axisFromReport(report.input_token_source, params.reasons?.input);
+    const output = axisFromReport(report.output_token_source, params.reasons?.output);
+    return {
+        surface: spec.surface,
+        provider: spec.provider,
+        model_label: params.modelLabel ?? "unknown",
+        run_id: params.runId,
+        token_source: { input, output },
+        // Counts ride ONLY on an available axis (never a silent zero on an unavailable one).
+        ...(input.source !== "unavailable" && report.input_tokens !== undefined ? { input_before: report.input_tokens } : {}),
+        ...(output.source === "provider-reported" && report.output_tokens !== undefined
+            ? { output_before: report.output_tokens }
+            : {}),
+        ...(output.source === "local-estimate" && report.output_tokens !== undefined
+            ? { output_estimate: report.output_tokens }
+            : {}),
+        cost_source: "unavailable",
+        cost_unavailable_reason: spec.cost_unavailable_reason,
+        claim_scope: "run-scoped",
+        caveats: [...report.notes]
+    };
+}
+/**
+ * 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 function buildCursorRunCrossSurfaceEvent(params) {
+    return buildRunCrossSurfaceEvent("cursor", params);
+}
+//# sourceMappingURL=cross-surface-event.js.map