@compaction/cli 0.2.0 → 0.3.0

package/dist/core/activity-event.js

@@ -0,0 +1,182 @@
+/**
+ * ADDITIVE activity extension of the cross-surface event (charter 2026-07-04-run-7, lane
+ * "shared activity/event model"; founder measurement-fields decision: "approval status, auto-apply
+ * status, recovery location, activity event id, sync status").
+ *
+ * WHY A SIBLING MODULE (not edits to `cross-surface-event.ts`): that file is the typed rendering
+ * of the run-5 authority doc `docs/ops/cross-surface-evidence-contract.md` (D1–D6) and is kept
+ * byte-stable here so "additive, existing writers/tests unmodified" is trivially provable. This
+ * module IMPORTS the same event union and extends it by intersection — one event model, the same
+ * arms and guardrails, plus the activity fields. Nothing here changes any existing wire shape,
+ * writer, or validator behavior.
+ *
+ * The activity fields, ALL optional/additive on the event:
+ * - `approval_status` — whether/how the user approved what Compaction did on this run.
+ * - `auto_apply` — the auto-apply STATE MODEL only (no auto-apply logic exists anywhere).
+ *   Structurally OFF BY DEFAULT: `applied_automatically: true` is only *representable* when the
+ *   user preference is the explicit opt-in `"auto-when-gates-pass"`, `eligible` is `true`, AND
+ *   `gates_passed` is non-empty (a non-empty tuple type). An "auto-applied" event under the
+ *   default `"ask-each-time"` preference is a TYPE ERROR and a validator problem — matching the
+ *   founder decision: "If full gates are not implementable safely in one pass: fail-closed
+ *   scaffold + tests proving auto-apply OFF by default."
+ * - `recovery` — whether the original was retained and WHERE (a content-free path/pointer, never
+ *   content).
+ * - `sync_status` — `local-only | metrics-synced | hosted-private`; the default is `local-only`
+ *   (no event syncs anywhere unless a hosted path is explicitly configured — none is here).
+ * - `activity_event_id` — a DETERMINISTIC content-free id (sha-256 over the canonicalized
+ *   metrics-only fields), the dedupe key of the local activity store.
+ */
+import { createHash } from "node:crypto";
+import { validateCrossSurfaceEvent } from "./cross-surface-event.js";
+/** Founder D-list: whether/how the user approved what Compaction did on this run (exact values). */
+export const ACTIVITY_APPROVAL_STATUSES = [
+    "not-required",
+    "asked-approved",
+    "asked-declined",
+    "auto-applied-by-policy",
+    "not-asked"
+];
+/**
+ * The binary auto-apply preference (founder product model: after a first approval, ONE binary
+ * question — default no). `"ask-each-time"` IS the default; `"auto-when-gates-pass"` is only ever
+ * an explicit prior user opt-in. Preference STORAGE is a named residual (no storage exists here).
+ */
+export const AUTO_APPLY_PREFERENCES = ["ask-each-time", "auto-when-gates-pass"];
+/** Founder D-list sync status. `local-only` is the default: nothing syncs without explicit config. */
+export const ACTIVITY_SYNC_STATUSES = ["local-only", "metrics-synced", "hosted-private"];
+export const DEFAULT_ACTIVITY_SYNC_STATUS = "local-only";
+/* ------------------------------------------------------------------------------------------------
+ * Deterministic content-free id.
+ * ---------------------------------------------------------------------------------------------- */
+export const ACTIVITY_EVENT_ID_PATTERN = /^act-[0-9a-f]{24}$/;
+/** Canonicalize: drop undefined, sort object keys recursively — same event, same bytes, same id. */
+function canonicalize(value) {
+    if (Array.isArray(value))
+        return value.map(canonicalize);
+    if (typeof value === "object" && value !== null) {
+        return Object.fromEntries(Object.entries(value)
+            .filter(([, entry]) => entry !== undefined)
+            .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+            .map(([key, entry]) => [key, canonicalize(entry)]));
+    }
+    return value;
+}
+/**
+ * Compute the deterministic content-free id: sha-256 over the canonicalized event EXCLUDING any
+ * existing `activity_event_id` (so recomputing on a stored event reproduces the same id). The id
+ * is derived only from the metrics-only fields the event already carries — no randomness, no
+ * clock, no content.
+ */
+export function computeActivityEventId(event) {
+    const { activity_event_id: _existing, ...rest } = event;
+    const digest = createHash("sha256").update(JSON.stringify(canonicalize(rest))).digest("hex");
+    return `act-${digest.slice(0, 24)}`;
+}
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isOneOf(value, allowed) {
+    return typeof value === "string" && allowed.includes(value);
+}
+function isStringArray(value) {
+    return Array.isArray(value) && value.every((entry) => typeof entry === "string" && entry.trim() !== "");
+}
+function validateAutoApply(value, problems) {
+    if (value === undefined)
+        return;
+    if (!isPlainObject(value)) {
+        problems.push("auto_apply: must be an object ({ eligible, preference, applied_automatically, gates_* })");
+        return;
+    }
+    if (typeof value.eligible !== "boolean")
+        problems.push("auto_apply.eligible: must be a boolean");
+    if (!isOneOf(value.preference, AUTO_APPLY_PREFERENCES)) {
+        problems.push(`auto_apply.preference: must be one of ${AUTO_APPLY_PREFERENCES.join(" | ")} (exact)`);
+    }
+    if (typeof value.applied_automatically !== "boolean") {
+        problems.push("auto_apply.applied_automatically: must be a boolean");
+    }
+    for (const field of ["gates_passed", "gates_failed"]) {
+        if (value[field] !== undefined && !isStringArray(value[field])) {
+            problems.push(`auto_apply.${field}: must be an array of non-empty content-free gate identifiers`);
+        }
+    }
+    // OFF-BY-DEFAULT rules (mirror of the type-level arm) — auto-apply is opt-in + gated, always.
+    if (value.applied_automatically === true) {
+        if (value.preference !== "auto-when-gates-pass") {
+            problems.push('auto_apply: applied_automatically=true under preference "ask-each-time" is invalid — auto-apply is OFF by default and only ever an explicit prior opt-in ("auto-when-gates-pass")');
+        }
+        if (value.eligible !== true) {
+            problems.push("auto_apply: applied_automatically=true requires eligible=true (an ineligible change can never be auto-applied)");
+        }
+        if (!isStringArray(value.gates_passed) || value.gates_passed.length === 0) {
+            problems.push("auto_apply: applied_automatically=true requires a NON-EMPTY gates_passed — an auto-apply with zero passed safety gates is invalid (fail-closed)");
+        }
+    }
+}
+function validateRecovery(value, problems) {
+    if (value === undefined)
+        return;
+    if (!isPlainObject(value)) {
+        problems.push("recovery: must be an object ({ original_retained, location? })");
+        return;
+    }
+    if (typeof value.original_retained !== "boolean") {
+        problems.push("recovery.original_retained: must be a boolean (honest — never assumed)");
+    }
+    if (value.location !== undefined) {
+        if (typeof value.location !== "string" || value.location.trim() === "") {
+            problems.push("recovery.location: must be a non-empty content-free path/pointer string when present");
+        }
+        else if (value.location.includes("\n")) {
+            problems.push("recovery.location: must be a single-line path/pointer — multi-line values look like content, not a location");
+        }
+    }
+}
+/**
+ * Validate one parsed/unknown activity event. Runs the EXISTING cross-surface validator first
+ * (all D5/D6/tier/silent-zero rules stay binding), then the activity rules:
+ * 1. exact enums for approval_status / sync_status / auto_apply.preference;
+ * 2. auto-apply OFF-by-default: applied_automatically=true requires the explicit opt-in
+ *    preference AND eligible=true AND non-empty gates_passed;
+ * 3. recovery.location is a single-line content-free pointer;
+ * 4. activity_event_id matches the deterministic `act-<24 hex>` shape.
+ */
+export function validateActivityEvent(value) {
+    const problems = [...validateCrossSurfaceEvent(value).problems];
+    if (!isPlainObject(value))
+        return { problems };
+    const event = value;
+    if (event.approval_status !== undefined && !isOneOf(event.approval_status, ACTIVITY_APPROVAL_STATUSES)) {
+        problems.push(`approval_status: must be one of ${ACTIVITY_APPROVAL_STATUSES.join(" | ")} (exact)`);
+    }
+    if (event.sync_status !== undefined && !isOneOf(event.sync_status, ACTIVITY_SYNC_STATUSES)) {
+        problems.push(`sync_status: must be one of ${ACTIVITY_SYNC_STATUSES.join(" | ")} (exact)`);
+    }
+    if (event.activity_event_id !== undefined &&
+        (typeof event.activity_event_id !== "string" || !ACTIVITY_EVENT_ID_PATTERN.test(event.activity_event_id))) {
+        problems.push("activity_event_id: must match act-<24 hex chars> (the deterministic content-free id)");
+    }
+    validateAutoApply(event.auto_apply, problems);
+    validateRecovery(event.recovery, problems);
+    return { problems };
+}
+/* ------------------------------------------------------------------------------------------------
+ * Measure-only builder — the ONLY activity-event writer this cycle. `run` / `run codex` /
+ * `run cursor` measure and report; they never modify the user's session or apply anything, so:
+ * approval "not-required" (there was nothing to approve), auto_apply not eligible + the default
+ * "ask-each-time" preference + applied_automatically false (no auto-apply logic exists),
+ * sync "local-only" (no hosted path is configured on the `run` flow), recovery = what the record
+ * HONESTLY knows (the captured-trace artifact the front-end just wrote, by path).
+ * ---------------------------------------------------------------------------------------------- */
+export function buildMeasureOnlyActivityEvent(event, recovery) {
+    const activity = {
+        ...event,
+        approval_status: "not-required",
+        auto_apply: { eligible: false, preference: "ask-each-time", applied_automatically: false },
+        recovery,
+        sync_status: DEFAULT_ACTIVITY_SYNC_STATUS
+    };
+    return { ...activity, activity_event_id: computeActivityEventId(activity) };
+}
+//# sourceMappingURL=activity-event.js.map

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

@@ -0,0 +1,63 @@
+import { type ActivityEvent } from "./activity-event.js";
+/** Default local activity directory (sibling of `.compaction/run-records`; gitignored via `.compaction/`). */
+export declare const DEFAULT_ACTIVITY_DIRECTORY = ".compaction/activity";
+/** The single append-only JSONL log inside it. */
+export declare const ACTIVITY_LOG_FILENAME = "activity.jsonl";
+/** Top-level keys an activity event may carry: the cross-surface contract fields + the activity fields. */
+export declare const ACTIVITY_EVENT_ALLOWED_KEYS: readonly string[];
+/**
+ * Longest string a metrics-only event may carry per field. The longest honest values today are
+ * unavailability reasons / caveats (~120 chars); 600 leaves headroom while making prompt/response
+ * smuggling in a "label" field impossible.
+ */
+export declare const ACTIVITY_MAX_STRING_LENGTH = 600;
+/**
+ * The write-time invariant: the FULL contract validator + the metrics-only allowlist + string
+ * bounds + store requirements (`activity_event_id` and `sync_status` present — the store's dedupe
+ * key and sync default are always materialized before this runs). Report-only: returns problems.
+ */
+export declare function validateActivityEventForStore(value: unknown): {
+    problems: string[];
+};
+export type AppendActivityEventResult = {
+    appended: true;
+    path: string;
+    activity_event_id: string;
+} | {
+    appended: false;
+    reason: string;
+    problems?: string[];
+};
+/**
+ * Append ONE metrics-only event to the local JSONL log. Fail-closed: a rejected event writes
+ * NOTHING (and the rejection carries the exact problems). Dedupe: an id already in the log is a
+ * reported no-op. Local file I/O only — never a network call.
+ */
+export declare function appendActivityEvent(event: ActivityEvent, directory?: string): Promise<AppendActivityEventResult>;
+export interface SkippedActivityLine {
+    /** 1-based line number in the JSONL log. */
+    line: number;
+    reason: string;
+}
+/**
+ * Read all events from the local log. A missing directory/file means "no activity yet" (empty,
+ * not an error). Invalid lines are SKIPPED with a reason — never guessed at; a duplicate id keeps
+ * the FIRST occurrence (defensive read-side dedupe; the write side already prevents this).
+ */
+export declare function readActivityEvents(directory?: string): Promise<{
+    events: ActivityEvent[];
+    skipped: SkippedActivityLine[];
+}>;
+/** A content-free one-line summary per event — ids, surface, statuses; never counts recomputed. */
+export interface ActivityEventSummary {
+    activity_event_id: string;
+    surface: string;
+    run_id?: string;
+    approval_status?: string;
+    sync_status?: string;
+}
+/** List the stored events as content-free summaries (the future `compaction activity` command's data). */
+export declare function listActivityEvents(directory?: string): Promise<{
+    summaries: ActivityEventSummary[];
+    skipped: SkippedActivityLine[];
+}>;

package/dist/core/activity-store.js

@@ -0,0 +1,254 @@
+/**
+ * Minimal LOCAL metrics-only activity store (charter 2026-07-04-run-7, lane "shared activity/event
+ * model … minimal local metrics-only activity store"). Founder product model: "all runs captured
+ * as metrics-only activity".
+ *
+ * What it is: an append-only JSONL file under `.compaction/activity/` (already gitignored via the
+ * `.compaction/` rule) holding ONE metrics-only `ActivityEvent` per line. Local file I/O only —
+ * no network, no new dependencies, no CLI surface (the `compaction activity` command is a NAMED
+ * RESIDUAL, not built here).
+ *
+ * Invariants ENFORCED AT WRITE TIME (fail-closed — a rejected event writes NOTHING):
+ * 1. CONTENT-FREE / metrics-only: every key must be on the known metrics-only allowlist (unknown
+ *    keys are rejected — an unknown field could carry content; classically content-shaped names
+ *    like `prompt`/`response`/`messages` get the explicit content message), and every string
+ *    value is length-bounded (a multi-hundred-char "label" is content wearing a label's clothes).
+ * 2. The FULL event contract: `validateActivityEvent` (which itself runs the existing
+ *    cross-surface validator — D5/D6, tier ceilings, no silent zero) must return zero problems,
+ *    including the auto-apply OFF-by-default rules.
+ * 3. DEDUPE by `activity_event_id`: the deterministic id is the primary key; appending an event
+ *    whose id is already in the log is a no-op (reported, not silent).
+ *
+ * `sync_status` defaults to `"local-only"` and `activity_event_id` is computed when absent —
+ * the store never invents any other field.
+ */
+import { appendFile, mkdir, readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { DEFAULT_ACTIVITY_SYNC_STATUS, computeActivityEventId, validateActivityEvent } from "./activity-event.js";
+/** Default local activity directory (sibling of `.compaction/run-records`; gitignored via `.compaction/`). */
+export const DEFAULT_ACTIVITY_DIRECTORY = ".compaction/activity";
+/** The single append-only JSONL log inside it. */
+export const ACTIVITY_LOG_FILENAME = "activity.jsonl";
+/* ------------------------------------------------------------------------------------------------
+ * Metrics-only (content-free) key allowlist — the write-time invariant of rule 1.
+ * ---------------------------------------------------------------------------------------------- */
+/** Top-level keys an activity event may carry: the cross-surface contract fields + the activity fields. */
+export const ACTIVITY_EVENT_ALLOWED_KEYS = [
+    // cross-surface event (src/core/cross-surface-event.ts — contract §2)
+    "user_id",
+    "team_id",
+    "surface",
+    "provider",
+    "model_label",
+    "workflow_id",
+    "session_id",
+    "run_id",
+    "input_before",
+    "input_after",
+    "output_before",
+    "output_after",
+    "output_estimate",
+    "token_source",
+    "cost_source",
+    "cost_unavailable_reason",
+    "billing_model",
+    "policy_used",
+    "acceptance",
+    "recoverability",
+    "eval_status",
+    "evidence_level",
+    "claim_scope",
+    "caveats",
+    "plan_efficiency",
+    // activity extension (src/core/activity-event.ts — founder D-list)
+    "activity_event_id",
+    "approval_status",
+    "auto_apply",
+    "recovery",
+    "sync_status"
+];
+/** Nested-object key allowlists (content can hide one level down just as easily). */
+const NESTED_ALLOWED_KEYS = {
+    token_source: ["input", "output"],
+    "token_source.input": ["source", "unavailable_reason"],
+    "token_source.output": ["source", "unavailable_reason"],
+    auto_apply: ["eligible", "preference", "applied_automatically", "gates_passed", "gates_failed"],
+    recovery: ["original_retained", "location"],
+    plan_efficiency: [
+        "evidence_type",
+        "billing_confirmed",
+        "quota_window_id",
+        "tasks_completed_in_window",
+        "cap_events_in_window",
+        "visible_tokens_per_task_estimate",
+        "successful_tasks_before_reset"
+    ]
+};
+/** Classic content-shaped key names — rejected with the explicit content message (case-insensitive). */
+const CONTENT_SHAPED_KEY_NAMES = [
+    "prompt",
+    "response",
+    "content",
+    "text",
+    "message",
+    "messages",
+    "transcript",
+    "stdout",
+    "stderr",
+    "body",
+    "completion",
+    "diff",
+    "code"
+];
+/**
+ * Longest string a metrics-only event may carry per field. The longest honest values today are
+ * unavailability reasons / caveats (~120 chars); 600 leaves headroom while making prompt/response
+ * smuggling in a "label" field impossible.
+ */
+export const ACTIVITY_MAX_STRING_LENGTH = 600;
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function looksContentShaped(key) {
+    return CONTENT_SHAPED_KEY_NAMES.includes(key.toLowerCase());
+}
+function checkStrings(path, value, problems) {
+    if (typeof value === "string") {
+        if (value.length > ACTIVITY_MAX_STRING_LENGTH) {
+            problems.push(`${path}: string exceeds the metrics-only bound (${value.length} > ${ACTIVITY_MAX_STRING_LENGTH} chars) — that is content-sized, not a count/source/id/label`);
+        }
+        return;
+    }
+    if (Array.isArray(value)) {
+        value.forEach((entry, index) => checkStrings(`${path}[${index}]`, entry, problems));
+        return;
+    }
+    if (isPlainObject(value)) {
+        for (const [key, entry] of Object.entries(value))
+            checkStrings(`${path}.${key}`, entry, problems);
+    }
+}
+function checkAllowedKeys(path, value, allowed, problems) {
+    for (const key of Object.keys(value)) {
+        if (allowed.includes(key))
+            continue;
+        problems.push(looksContentShaped(key)
+            ? `${path === "" ? key : `${path}.${key}`}: content-shaped field — activity events are metrics-only (counts, sources, ids, labels); prompt/response/output content is never stored`
+            : `${path === "" ? key : `${path}.${key}`}: not on the metrics-only activity-event allowlist — unknown fields are rejected at write time (fail-closed content-free invariant)`);
+    }
+}
+/**
+ * The write-time invariant: the FULL contract validator + the metrics-only allowlist + string
+ * bounds + store requirements (`activity_event_id` and `sync_status` present — the store's dedupe
+ * key and sync default are always materialized before this runs). Report-only: returns problems.
+ */
+export function validateActivityEventForStore(value) {
+    const problems = [...validateActivityEvent(value).problems];
+    if (!isPlainObject(value))
+        return { problems };
+    checkAllowedKeys("", value, ACTIVITY_EVENT_ALLOWED_KEYS, problems);
+    for (const [path, allowed] of Object.entries(NESTED_ALLOWED_KEYS)) {
+        const segments = path.split(".");
+        let cursor = value;
+        for (const segment of segments) {
+            cursor = isPlainObject(cursor) ? cursor[segment] : undefined;
+        }
+        if (isPlainObject(cursor))
+            checkAllowedKeys(path, cursor, allowed, problems);
+    }
+    checkStrings("event", value, problems);
+    if (typeof value.activity_event_id !== "string" || value.activity_event_id === "") {
+        problems.push("activity_event_id: required by the activity store (the dedupe key)");
+    }
+    if (value.sync_status === undefined) {
+        problems.push('sync_status: required by the activity store (default "local-only" is applied before validation)');
+    }
+    return { problems };
+}
+/**
+ * Append ONE metrics-only event to the local JSONL log. Fail-closed: a rejected event writes
+ * NOTHING (and the rejection carries the exact problems). Dedupe: an id already in the log is a
+ * reported no-op. Local file I/O only — never a network call.
+ */
+export async function appendActivityEvent(event, directory = DEFAULT_ACTIVITY_DIRECTORY) {
+    const withDefaults = {
+        ...event,
+        sync_status: event.sync_status ?? DEFAULT_ACTIVITY_SYNC_STATUS
+    };
+    const materialized = {
+        ...withDefaults,
+        activity_event_id: withDefaults.activity_event_id ?? computeActivityEventId(withDefaults)
+    };
+    const { problems } = validateActivityEventForStore(materialized);
+    if (problems.length > 0) {
+        return { appended: false, reason: "metrics-only invariant rejected the event — nothing was written", problems };
+    }
+    const id = materialized.activity_event_id;
+    const { events } = await readActivityEvents(directory);
+    if (events.some((existing) => existing.activity_event_id === id)) {
+        return { appended: false, reason: `duplicate activity_event_id ${id} — already recorded (dedupe; nothing written)` };
+    }
+    await mkdir(directory, { recursive: true });
+    const path = join(directory, ACTIVITY_LOG_FILENAME);
+    await appendFile(path, `${JSON.stringify(materialized)}\n`, "utf8");
+    return { appended: true, path, activity_event_id: id };
+}
+/**
+ * Read all events from the local log. A missing directory/file means "no activity yet" (empty,
+ * not an error). Invalid lines are SKIPPED with a reason — never guessed at; a duplicate id keeps
+ * the FIRST occurrence (defensive read-side dedupe; the write side already prevents this).
+ */
+export async function readActivityEvents(directory = DEFAULT_ACTIVITY_DIRECTORY) {
+    let raw;
+    try {
+        raw = await readFile(join(directory, ACTIVITY_LOG_FILENAME), "utf8");
+    }
+    catch (error) {
+        const code = typeof error === "object" && error !== null && "code" in error ? String(error.code) : "unknown";
+        if (code === "ENOENT")
+            return { events: [], skipped: [] };
+        throw error;
+    }
+    const events = [];
+    const skipped = [];
+    const seen = new Set();
+    raw.split("\n").forEach((line, index) => {
+        if (line.trim() === "")
+            return;
+        let parsed;
+        try {
+            parsed = JSON.parse(line);
+        }
+        catch {
+            skipped.push({ line: index + 1, reason: "invalid JSON" });
+            return;
+        }
+        const { problems } = validateActivityEventForStore(parsed);
+        if (problems.length > 0) {
+            skipped.push({ line: index + 1, reason: `invalid activity event: ${problems[0]}` });
+            return;
+        }
+        const event = parsed;
+        const id = event.activity_event_id;
+        if (seen.has(id)) {
+            skipped.push({ line: index + 1, reason: `duplicate activity_event_id ${id} — first occurrence kept` });
+            return;
+        }
+        seen.add(id);
+        events.push(event);
+    });
+    return { events, skipped };
+}
+/** List the stored events as content-free summaries (the future `compaction activity` command's data). */
+export async function listActivityEvents(directory = DEFAULT_ACTIVITY_DIRECTORY) {
+    const { events, skipped } = await readActivityEvents(directory);
+    const summaries = events.map((event) => ({
+        activity_event_id: event.activity_event_id,
+        surface: event.surface,
+        ...(event.run_id !== undefined ? { run_id: event.run_id } : {}),
+        ...(event.approval_status !== undefined ? { approval_status: event.approval_status } : {}),
+        ...(event.sync_status !== undefined ? { sync_status: event.sync_status } : {})
+    }));
+    return { summaries, skipped };
+}
+//# sourceMappingURL=activity-store.js.map

package/dist/core/activity-view.d.ts

@@ -0,0 +1,76 @@
+/**
+ * READ-ONLY, metrics-only rendering of the local activity store (charter 2026-07-04-run-7, lane 4:
+ * "compaction activity"). Turns stored `ActivityEvent`s into a content-free table / JSON view of
+ * recent runs. Pure functions — no I/O here (the command reads the store and calls these).
+ *
+ * HONESTY RAILS (product-critic gate for this surface):
+ * - NO wall-clock: activity events carry no timestamp (deterministic content-free ids, no clock).
+ *   So there is NO fabricated "time" column — runs are ordered by append recency and numbered
+ *   (`#1` = most recent), with a one-line note that the order is append order, not clock time.
+ * - Token counts render at the EVENT'S OWN axis tier: `input`/`output` say `local-estimate` vs
+ *   `provider-reported` vs `unavailable` verbatim; a tier is never upgraded in rendering.
+ * - OUTPUT is "output tokens measured" (a count), NEVER "output savings". No cost, no billing, no
+ *   savings, no projection is rendered on this surface.
+ * - An input before→after delta is shown ONLY when BOTH input_before and input_after are present
+ *   (a real reshaping happened). A measure-only run (input_before only) shows the measured count,
+ *   never an implied reduction.
+ */
+import type { ActivityEvent } from "./activity-event.js";
+/** One rendered, content-free row. All labels are honest; nothing is inferred. */
+export interface ActivityRow {
+    /** 1 = most recent (append recency; events carry no wall-clock). */
+    position: number;
+    activity_event_id: string;
+    surface: string;
+    provider: string;
+    model_label: string;
+    /** Present only when a real before→after reshaping happened (both counts present). */
+    input_before: number | null;
+    input_after: number | null;
+    input_source: string;
+    input_unavailable_reason?: string;
+    /** The measured output token COUNT (never a savings), or null when the axis is unavailable. */
+    output_tokens: number | null;
+    output_source: string;
+    output_unavailable_reason?: string;
+    policy_used: string;
+    approval_status: string;
+    auto_apply_status: string;
+    sync_status: string;
+}
+export interface BuildActivityRowsOptions {
+    /** Max rows to render (most recent first). Default 20. */
+    limit?: number;
+    /** Filter to one surface (exact match) before limiting. */
+    surface?: string;
+}
+export declare const DEFAULT_ACTIVITY_LIMIT = 20;
+export declare const NO_ACTIVITY_MESSAGE = "No activity recorded yet \u2014 run a supported workflow (e.g. `compaction run <tool> -- \u2026`) and it will appear here.";
+/** Build the rendered rows: newest first, optional surface filter, then limit. */
+export declare function buildActivityRows(events: ActivityEvent[], options?: BuildActivityRowsOptions): ActivityRow[];
+/** Machine output for `--json`: rows plus honest meta. Pure data (the command JSON-stringifies it). */
+export interface ActivityJson {
+    activity: ActivityRow[];
+    meta: {
+        total_events: number;
+        shown: number;
+        limit: number;
+        surface_filter: string | null;
+        ordering: "append-recency (events carry no wall-clock time); position 1 = most recent";
+        labels: "token counts are shown at each event's own axis tier (local-estimate | provider-reported | unavailable); output is a measured token count, never a savings figure; no cost or billing figure is shown";
+    };
+    skipped_note?: string;
+}
+export declare function buildActivityJson(rows: ActivityRow[], meta: {
+    totalEvents: number;
+    limit: number;
+    surface?: string;
+    skippedCount?: number;
+}): ActivityJson;
+/** Human table. Content-free; honest labels; a header note that ordering is append-recency. */
+export declare function formatActivityTable(rows: ActivityRow[], meta: {
+    totalEvents: number;
+    limit: number;
+    surface?: string;
+    skippedCount?: number;
+}): string;