@meterbility/collector 0.3.1

package/LICENSE

@@ -0,0 +1,33 @@
+MIT License
+
+Copyright (c) 2026 Meterbility authors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+----------------------------------------------------------------------
+
+Note: This MIT license covers everything in this repository EXCEPT the
+contents of the /ee directory (when present), which are licensed under the
+Elastic License 2.0 (ELv2) — see /ee/LICENSE.
+
+The /ee directory is reserved for Enterprise Edition modules: multi-tenant
+fleet orchestration, SSO/RBAC, audit logs, and long-retention features.
+
+Nothing under /ee today; the directory is created as a forward-compatible
+marker so the licensing boundary is visible before any /ee code lands.

package/README.md

@@ -0,0 +1,11 @@
+# @meterbility/collector
+
+Part of [Meterbility](https://github.com/HoneycombHairDevelopers/Meterbility) — the debugger for AI agents. Capture every run, inspect every decision, pause and inject live, fork from any step.
+
+The SQLite data plane: schema, queries, content-addressed blob store, baseline trees, and replay primitives.
+
+```bash
+npm install @meterbility/collector
+```
+
+See the [Meterbility documentation](https://github.com/HoneycombHairDevelopers/Meterbility#readme) for the full guide. MIT licensed.

package/dist/index.d.ts

@@ -0,0 +1,497 @@
+import Database from 'better-sqlite3';
+import { StepStatus, Step, TokenUsage, FileChange, BaselineTree, Run, AnnotationKind, AnnotationVerdict, Annotation, ForkEdit, ProbeState, Project, WorkingTree, ManifestEntry, IgnoreMatcher } from '@meterbility/shared';
+export { BaselineTree } from '@meterbility/shared';
+
+/**
+ * Two-stage heuristic for "is this buffer safe to send through the
+ * redaction pipeline?". Used to gate `redactBuffer` so PNG / .woff2 /
+ * lockfile / `.pyc` bytes don't get round-tripped through
+ * `String#replace` and shredded by U+FFFD substitution.
+ *
+ * Stage 1 — Full-buffer NUL scan. UTF-8 source code — even with CJK,
+ * emoji, every weird code point — never contains 0x00. A NUL byte
+ * anywhere is strong evidence of binary content. For files whose
+ * binary signature is at the start (PNG, ELF, .pyc, .woff2) this
+ * bails at byte 7-12 and is effectively O(1). Removing the previous
+ * 8KB cap closes the rare-but-real "binary file with all-non-NUL
+ * first 8KB" gap (gzip headers, some compressed formats can hit it).
+ *
+ * Stage 2 — Round-trip-length check. Even with no NUL, a buffer can
+ * still be invalid UTF-8 (stray continuation bytes, truncated multi-
+ * byte sequences). The redaction pipeline calls
+ * `Buffer.toString('utf-8')` which silently replaces invalid bytes
+ * with U+FFFD (3 encoded bytes per replacement). If the re-encoded
+ * length differs from the input, the round trip is lossy and would
+ * corrupt the caller's bytes. Classify as binary so the bytes survive.
+ *
+ * Both stages are O(n). Cost is dominated by the redaction pipeline
+ * itself (which also runs `toString` on the buffer), so this adds at
+ * most one extra full pass to the redact path. Callers who already
+ * know their bytes are binary can still pass `skipRedact: true` to
+ * skip both stages entirely.
+ */
+declare function isProbablyText(buf: Buffer): boolean;
+/**
+ * Content-addressed blob store.
+ *
+ * Layout: $METERBILITY_HOME/blobs/<aa>/<bb>/<sha256>
+ *
+ * Two-level sharding (256 × 256) keeps any single directory under a few
+ * thousand files even on heavy users. Writes are write-once: if the file
+ * exists, we trust it (SHA collision is the universe's problem, not ours).
+ *
+ * Every text write passes through the redaction pass and emits a
+ * `redaction_log` row when a rule fires so the user can audit what was
+ * scrubbed. **Binary writes skip redaction entirely** — `redactBuffer`
+ * goes via `String#replace`, which would shred any non-UTF-8 bytes. The
+ * `isProbablyText` heuristic gates this automatically; callers who
+ * already know the bytes are binary (e.g. v0.3 file capture) can also
+ * pass `skipRedact: true` to be explicit.
+ */
+declare class BlobStore {
+    private db;
+    constructor(db: Database.Database);
+    putString(content: string, opts?: {
+        skipRedact?: boolean;
+    }): Promise<string>;
+    putJson(value: unknown, opts?: {
+        skipRedact?: boolean;
+    }): Promise<string>;
+    /**
+     * Hash without persisting — useful when you want a snapshot id before
+     * deciding whether to write.
+     */
+    hashJson(value: unknown): string;
+    putBuffer(buf: Buffer, opts?: {
+        skipRedact?: boolean;
+    }): Promise<string>;
+    getString(hash: string): Promise<string>;
+    getJson<T = unknown>(hash: string): Promise<T>;
+    getBuffer(hash: string): Promise<Buffer>;
+    tryGetString(hash: string): Promise<string | undefined>;
+    /**
+     * Binary-safe variant of `tryGetString`. Used by /api/blob/:hash/render
+     * which has to look at raw bytes for MIME sniffing before deciding
+     * whether to render text or serve as image/octet-stream.
+     */
+    tryGetBuffer(hash: string): Promise<Buffer | undefined>;
+    /**
+     * Write pre-computed HTML (or other text) under a caller-chosen
+     * synthetic key, bypassing the content-addressed hash. Used by the
+     * blob_render cache to store rendered HTML under a key derived
+     * from `sha(blob_hash + lang + RENDER_VERSION)` rather than the
+     * content's own hash — this way two different renders of the same
+     * source code (e.g. lang=auto vs lang=typescript) cache separately
+     * but predictably.
+     *
+     * Skips redaction (renders are derived from already-stored blobs
+     * that went through redaction at put time).
+     */
+    putWithKey(content: string, key: string): Promise<void>;
+    rootDir(): string;
+}
+
+/**
+ * One-stop entry into the local data plane. `open()` creates the
+ * `$METERBILITY_HOME` tree if needed, applies the schema, and exposes both the
+ * raw SQLite handle (for queries.ts) and the blob store.
+ */
+declare class Store {
+    readonly db: Database.Database;
+    readonly blobs: BlobStore;
+    private constructor();
+    static open(opts?: {
+        path?: string;
+    }): Store;
+    static openAsync(opts?: {
+        path?: string;
+    }): Promise<Store>;
+    close(): void;
+}
+
+/**
+ * Schema — flat tables that map directly onto SPEC §6 entities. JSON
+ * columns hold the structured-but-not-indexed parts (action, outcome,
+ * tags). Foreign keys are enforced; large content lives in the blob store
+ * referenced by SHA256.
+ *
+ * Migration policy (locked in by SPEC v0.2 §17 and re-affirmed by v0.3
+ * §3.3): **additive only**. No renames, no drops, no CHECK-constraint
+ * tightening — SQLite can't ALTER a CHECK without a table rebuild, so we
+ * declare full enum coverage up front even for values future milestones
+ * write. v0.3 only writes `derived_from='tool_call'` and three of the
+ * five ops, but the constraint allows all of them so v0.4's file watcher
+ * and v0.5's normalizer don't need a migration.
+ *
+ * Version history:
+ *   v1 → v2 — split 5m vs 1h cache write tokens on `steps`
+ *   v2 → v3 — settings table for the web UI Settings page
+ *   v3 → v4 — file_change, baseline_tree, runs.baseline_tree_id,
+ *             runs.probe_state (Track A file capture + Track B Live Probe)
+ */
+declare const SCHEMA_VERSION = 5;
+declare function ensureSchema(db: Database.Database): void;
+
+declare function upsertProjectByCwd(store: Store, cwd: string, name?: string): Project;
+declare function upsertAgent(store: Store, projectId: string, name: string): {
+    agent_id: string;
+    project_id: string;
+    name: string;
+    created_at: string;
+};
+declare function insertRun(store: Store, run: Run): void;
+declare function updateRunTotals(store: Store, runId: string): void;
+declare function setRunStatus(store: Store, runId: string, status: StepStatus, endedAt?: string): void;
+declare function insertStep(store: Store, step: Step): void;
+declare function recordContextSnapshot(store: Store, snapshotId: string, blobRef: string, componentCount: number): void;
+/** Translate a logical snapshot_id (hash of components) into the blob_ref
+ *  under which the serialized snapshot is stored. Falls back to using the
+ *  snapshot_id itself if no mapping is recorded — handy for round-tripped
+ *  traces where the two hashes happen to coincide. */
+declare function resolveSnapshotBlobRef(store: Store, snapshotId: string): string;
+declare function getRun(store: Store, runId: string): Run | undefined;
+interface ListRunsOpts {
+    limit?: number;
+    projectId?: string;
+    agentId?: string;
+    status?: StepStatus;
+    containsTool?: string;
+}
+declare function listRuns(store: Store, opts?: ListRunsOpts): Run[];
+declare function listSteps(store: Store, runId: string): Step[];
+declare function getStep(store: Store, stepId: string): Step | undefined;
+declare function getStepBySequence(store: Store, runId: string, sequence: number): Step | undefined;
+declare function insertFork(store: Store, args: {
+    originRunId: string;
+    originStepId: string;
+    forkRunId: string;
+    edit: ForkEdit;
+}): string;
+declare function listForks(store: Store, originRunId: string): Array<{
+    fork_id: string;
+    origin_run_id: string;
+    origin_step_id: string;
+    fork_run_id: string;
+    edit_type: string;
+    created_at: string;
+}>;
+declare function insertAnnotation(store: Store, args: {
+    targetKind: "step" | "run";
+    targetId: string;
+    author: string;
+    /**
+     * Annotation discriminator (v0.3 schema v5). Defaults to 'comment'
+     * — human-authored notes via the Annotate CLI / web UI keep the
+     * back-compat shape. System-emitted events pass their own kind
+     * (`probe_pause`, `probe_edit`, `capture_skipped`).
+     */
+    kind?: AnnotationKind;
+    verdict?: AnnotationVerdict;
+    note?: string;
+}): Annotation;
+declare function listAnnotations(store: Store, targetKind: "step" | "run", targetId: string): Annotation[];
+declare function getIngestOffset(store: Store, source_runtime: string, source_path: string): number;
+declare function setIngestOffset(store: Store, source_runtime: string, source_path: string, offset: number): void;
+declare function getRunBySessionId(store: Store, sourceSessionId: string): Run | undefined;
+declare function aggregateTokens(steps: Step[]): TokenUsage;
+/**
+ * Thrown by `insertFileChange` when a candidate row violates the
+ * biconditional contract documented on `FileChange` in
+ * `packages/shared/src/types.ts:242-244`:
+ *
+ *   - `before_blob_ref` is null iff op === "create" OR partial_diff
+ *   - `after_blob_ref`  is null iff op === "delete" OR partial_diff
+ *   - op === "rename" requires `old_path`
+ *
+ * `chmod` is the documented exception — it's a mode-only operation
+ * and is exempt from both blob_ref biconditionals. The replay layer
+ * (`applyFileChange`) treats chmod blob refs as a no-op regardless,
+ * so accepting either shape is safe.
+ *
+ * Hard-fail by design: an adapter that produces an invariant-violating
+ * row would otherwise ship the malformation silently into the DB and
+ * surface as a downstream rendering or replay bug. Better to throw at
+ * the boundary.
+ */
+declare class FileChangeInvariantError extends Error {
+    constructor(message: string);
+}
+/**
+ * Verify a candidate FileChange satisfies the contract on `FileChange`
+ * in `packages/shared/src/types.ts`. Throws `FileChangeInvariantError`
+ * with a clear message on the first violation. Pure; no side effects.
+ *
+ * Exported for direct testing.
+ */
+declare function assertFileChangeInvariants(fc: {
+    op: FileChange["op"];
+    partial_diff: boolean;
+    before_blob_ref?: string;
+    after_blob_ref?: string;
+    old_path?: string;
+}): void;
+/**
+ * Insert a FileChange row. ID auto-generated if not provided.
+ *
+ * Idempotency: the schema's `UNIQUE(step_id, sequence)` constraint
+ * means writing the same logical FileChange twice will fail loudly.
+ * Adapters should compute deterministic `(step_id, sequence)` so a
+ * re-ingest of the same JSONL session doesn't duplicate rows.
+ *
+ * `created_at` defaults to "now" if omitted — adapters usually want
+ * this since they don't have a per-FileChange wall-clock from the
+ * source.
+ *
+ * Validation: every row passes through `assertFileChangeInvariants`
+ * before the INSERT. Adapter bugs that would otherwise ship malformed
+ * rows surface here as a thrown `FileChangeInvariantError` rather
+ * than as a silent downstream replay bug.
+ */
+declare function insertFileChange(store: Store, fc: Omit<FileChange, "file_change_id" | "created_at"> & {
+    file_change_id?: string;
+    created_at?: string;
+}): FileChange;
+interface ListFileChangesOpts {
+    runId?: string;
+    stepId?: string;
+    path?: string;
+    /**
+     * Used by the replay algorithm: include only FileChanges for steps
+     * with sequence < this value. Implemented via a join on `steps`. If
+     * `runId` is also given, the join is scoped to that run.
+     */
+    maxStepSeqExclusive?: number;
+}
+/**
+ * Sort order is `(step.sequence ASC, file_change.sequence ASC)` which
+ * matches the replay algorithm's contract (v0.3 §3.6): later steps win
+ * over earlier ones, and within a step, the intra-step `sequence` field
+ * preserves atomic-batch ordering (MultiEdit fans out N rows in order).
+ */
+declare function listFileChanges(store: Store, opts?: ListFileChangesOpts): FileChange[];
+declare function getFileChange(store: Store, fileChangeId: string): FileChange | undefined;
+declare function insertBaselineTree(store: Store, bt: Omit<BaselineTree, "baseline_tree_id" | "captured_at"> & {
+    baseline_tree_id?: string;
+    captured_at?: string;
+}): BaselineTree;
+declare function getBaselineTree(store: Store, baselineTreeId: string): BaselineTree | undefined;
+/**
+ * Find an existing baseline_tree row by its manifest blob ref — useful
+ * during baseline capture so two runs against the same git HEAD don't
+ * create two rows pointing at the same content. v0.3 §3.5 calls this
+ * out as the dominant dedup win.
+ */
+declare function findBaselineByManifest(store: Store, projectId: string, manifestBlobRef: string): BaselineTree | undefined;
+/**
+ * Attach a baseline tree to a run. Idempotent: passing the same id
+ * twice is a no-op. Passing a different id overwrites (the assumption
+ * being that the adapter re-walked the cwd and produced a new
+ * manifest — rare but legal).
+ */
+declare function setRunBaselineTree(store: Store, runId: string, baselineTreeId: string): void;
+/**
+ * Set the Live Probe state on a run. Pass `null` to clear. v0.3 §4 —
+ * only meaningful for source_runtime in (sdk-ts, sdk-py); callers are
+ * responsible for that guard.
+ */
+declare function setRunProbeState(store: Store, runId: string, state: ProbeState | null): void;
+
+/**
+ * Tiny key-value store on top of the `settings` SQLite table. Used by
+ * the web UI's Settings page so users can configure Slack webhooks,
+ * watched tools, default fork model, etc. without re-typing per
+ * session.
+ *
+ * Secrets warning: values are stored in plaintext in `~/.meterbility/meterbility.db`.
+ * The Settings UI surfaces this clearly. For Keychain-backed storage,
+ * see SPEC-DESKTOP.md (the desktop app's job, not the web UI's).
+ */
+type SettingKey = "slack.webhook" | "slack.default_events" | "live.watch_tools" | "live.stall_seconds" | "fork.default_model" | "fork.default_max_iterations" | "anthropic.api_key" | "postgres.url" | "export.include_file_blobs" | "web.bind_token" | "capture.files.enabled" | "capture.files.max_partial_bytes" | "capture.files.max_skip_bytes";
+declare function getSetting(store: Store, key: SettingKey): string | undefined;
+declare function setSetting(store: Store, key: SettingKey, value: string): void;
+declare function deleteSetting(store: Store, key: SettingKey): void;
+declare function listSettings(store: Store): Array<{
+    key: string;
+    value: string;
+    updated_at: string;
+}>;
+/**
+ * Resolve a setting that may also live in an environment variable.
+ * Env var wins when both are present — matches CLI semantics where
+ * env vars are the authoritative source.
+ */
+declare function resolveSetting(store: Store, key: SettingKey, envVar: string): string | undefined;
+declare function isSecret(key: string): boolean;
+/** Mask a secret value for display: `sk-ant-xxx…last4`. */
+declare function maskSecret(value: string): string;
+
+/**
+ * Serialize a list of manifest entries into the on-disk format. Entries
+ * are sorted by path (bytewise on the UTF-8 representation, matching
+ * git's convention — deterministic across locales).
+ *
+ * Throws on illegal paths: NUL (0x00) and newline (0x0A) bytes would
+ * break the record separators. POSIX disallows both in filenames; if
+ * the agent somehow produced one we refuse rather than silently
+ * corrupt the manifest.
+ */
+declare function serializeManifest(entries: ManifestEntry[]): Buffer;
+/**
+ * Inverse of `serializeManifest`. Tolerates an absent trailing newline
+ * (empty manifests serialize to an empty buffer; we return [] for both
+ * `Buffer.alloc(0)` and `Buffer.from([])`).
+ */
+declare function parseManifest(buf: Buffer): ManifestEntry[];
+/**
+ * Load a baseline tree's manifest from the blob store and parse it
+ * into a WorkingTree (the seed state the replay layers FileChanges on
+ * top of). Returns an empty tree if the manifest blob can't be read
+ * — better than throwing because a run with a missing baseline can
+ * still be partially reconstructed from FileChanges, and the UI can
+ * surface a warning instead of a hard failure.
+ */
+declare function loadBaselineTree(store: Store, baseline: BaselineTree): Promise<WorkingTree>;
+interface WorkingTreeAtOpts {
+    /**
+     * Apply only FileChanges from steps with `sequence < this value`.
+     * Default: undefined → include every step in the run (final state).
+     * Use 0 to get the baseline (pre-step-0) state.
+     */
+    stepSeq?: number;
+}
+/**
+ * Compute the working tree at a chosen point in a run.
+ *
+ * Implements the algorithm in v0.3 §3.6:
+ *   1. Load the run's baseline tree (the seed).
+ *   2. Apply every FileChange with `step.sequence < stepSeq` in order
+ *      (step.sequence ASC, file_change.sequence ASC).
+ *   3. Return the resulting (path → {blob_ref, mode}) map.
+ *
+ * Complexity: O(touched_paths). The `idx_fc_run_path` and the
+ * `listFileChanges` join keep this bounded by the number of files
+ * modified in the run, never by the total files in the repo.
+ *
+ * Returns an empty tree if:
+ *   - The run doesn't exist.
+ *   - The run has no `baseline_tree_id` AND no FileChanges (typical for
+ *     non-coding runs).
+ *
+ * Returns a baseline-only tree if the run has a baseline but no
+ * FileChanges before `stepSeq` — useful for "what did the agent see
+ * walking in?" queries.
+ */
+declare function workingTreeAt(store: Store, runId: string, opts?: WorkingTreeAtOpts): Promise<WorkingTree>;
+/**
+ * Apply a single FileChange to a WorkingTree in place. Pulled out so
+ * the v0.5 working-tree-scrubber UI can re-use it for incremental
+ * updates without re-running the whole replay each frame.
+ *
+ * `chmod` updates mode bits only — the spec's algorithm sketch passes
+ * for blob-ref purposes (content unchanged), but we DO update `mode`
+ * when present because mode is also part of the working-tree contract.
+ * If `mode_after` is unset, the operation is a true no-op.
+ *
+ * `partial_diff` FileChanges (typically Bash steps in v0.3) carry no
+ * blob refs. They're applied as a no-op for tree reconstruction — the
+ * Files UI surfaces the existence of the change separately so the user
+ * knows to enable the v0.4 watcher for full fidelity.
+ */
+declare function applyFileChange(tree: WorkingTree, fc: {
+    op: string;
+    path: string;
+    old_path?: string;
+    after_blob_ref?: string;
+    mode_after?: number;
+    partial_diff?: boolean;
+}): void;
+
+interface CaptureBaselineResult {
+    baseline_tree_id: string;
+    /** Manifest blob ref, exposed for diagnostics + tests. */
+    manifest_blob_ref: string;
+    /** Number of files that made it into the manifest. */
+    file_count: number;
+    /** Number of files skipped (oversize, unreadable, ignored). */
+    skipped: number;
+    /** True when this run dedup'd onto an existing baseline_tree row. */
+    reused_existing: boolean;
+    git_head?: string;
+    git_dirty: boolean;
+}
+interface CaptureBaselineOptions {
+    /**
+     * Pre-built ignore matcher. If omitted, the function loads
+     * `<cwd>/.meterbilityignore` + `<cwd>/.gitignore` on top of the
+     * shipped defaults.
+     */
+    matcher?: IgnoreMatcher;
+    /** Override the size cap (mostly for tests). */
+    maxFileBytes?: number;
+}
+/**
+ * Capture the baseline tree for a project's cwd. Returns `undefined` if
+ * the cwd doesn't exist or is empty — the adapter treats that as
+ * "non-coding run, no baseline needed" and continues without one.
+ */
+declare function captureBaseline(store: Store, projectId: string, cwd: string, opts?: CaptureBaselineOptions): Promise<CaptureBaselineResult | undefined>;
+
+/**
+ * File-size capture policy. Single source of truth for the 5MB / 50MB
+ * thresholds per SPEC-V0_3 §11.1. Every adapter that captures files
+ * MUST funnel through this helper before calling `insertFileChange`
+ * so the policy is uniform — a future adapter (Codex, Cursor,
+ * file-watcher) gets the gate for free.
+ *
+ * Policy (per SPEC-V0_3 §11.1):
+ *
+ *   ≤ max_partial_bytes (default 5 MB): full capture, both blobs kept,
+ *     partial_diff = false.
+ *   > max_partial_bytes AND ≤ max_skip_bytes: drop the LARGER side's
+ *     buffer (keep the smaller for delta context), partial_diff = true.
+ *   > max_skip_bytes: drop both buffers, redacted = true, emit a stub
+ *     FileChange row that records the path + op + original sizes so
+ *     the user knows something happened.
+ *
+ * Behaviour is pure (no I/O, no settings read inside the helper). The
+ * adapter resolves settings once via `getSetting()` and passes the
+ * resolved numbers in — per A7 "live-read per FileChange," settings
+ * are read at the call site so a mid-run toggle takes effect on the
+ * very next FileChange.
+ */
+declare const DEFAULT_MAX_PARTIAL_BYTES = 5000000;
+declare const DEFAULT_MAX_SKIP_BYTES = 50000000;
+interface FileSizePolicySettings {
+    /** Files at or under this size are captured in full. */
+    max_partial_bytes?: number;
+    /** Files at or under this size are partial-captured (larger blob dropped). */
+    max_skip_bytes?: number;
+}
+interface FileSizePolicyInput {
+    beforeBuf?: Buffer;
+    afterBuf?: Buffer;
+    settings?: FileSizePolicySettings;
+}
+interface FileSizePolicyResult {
+    /** The (possibly nulled) buffer to persist for the before-blob. */
+    beforeBuf?: Buffer;
+    /** The (possibly nulled) buffer to persist for the after-blob. */
+    afterBuf?: Buffer;
+    /** True when at least one buffer was dropped due to max_partial_bytes. */
+    partial_diff: boolean;
+    /** True when both buffers were dropped due to max_skip_bytes. */
+    redacted: boolean;
+    /** Original (pre-policy) size of before, regardless of whether kept. */
+    size_before?: number;
+    /** Original (pre-policy) size of after, regardless of whether kept. */
+    size_after?: number;
+}
+/**
+ * Apply the size-cap policy to the given buffers. Pure function — no
+ * I/O, no SQLite, no side effects. Throws on misconfiguration
+ * (max_skip ≤ max_partial) so a bad settings value surfaces loudly
+ * at ingest rather than silently producing skewed captures.
+ */
+declare function enforceFileSizePolicy(input: FileSizePolicyInput): FileSizePolicyResult;
+
+export { BlobStore, type CaptureBaselineOptions, type CaptureBaselineResult, DEFAULT_MAX_PARTIAL_BYTES, DEFAULT_MAX_SKIP_BYTES, FileChangeInvariantError, type FileSizePolicyInput, type FileSizePolicyResult, type FileSizePolicySettings, type ListFileChangesOpts, type ListRunsOpts, SCHEMA_VERSION, type SettingKey, Store, type WorkingTreeAtOpts, aggregateTokens, applyFileChange, assertFileChangeInvariants, captureBaseline, deleteSetting, enforceFileSizePolicy, ensureSchema, findBaselineByManifest, getBaselineTree, getFileChange, getIngestOffset, getRun, getRunBySessionId, getSetting, getStep, getStepBySequence, insertAnnotation, insertBaselineTree, insertFileChange, insertFork, insertRun, insertStep, isProbablyText, isSecret, listAnnotations, listFileChanges, listForks, listRuns, listSettings, listSteps, loadBaselineTree, maskSecret, parseManifest, recordContextSnapshot, resolveSetting, resolveSnapshotBlobRef, serializeManifest, setIngestOffset, setRunBaselineTree, setRunProbeState, setRunStatus, setSetting, updateRunTotals, upsertAgent, upsertProjectByCwd, workingTreeAt };