@sensigo/realm 0.26.0 → 0.27.0

package/dist/store/trace-buffer-store.d.ts

@@ -1,24 +1,156 @@
 import type { AgentTraceEntry } from '../types/run-record.js';
+import { WorkflowError } from '../types/workflow-error.js';
+/**
+ * The store-layer capability ladder (issue #197 PR-1, design record `plans/issue-197-design.md`
+ * §3). Implication runs **upward-requires-downward ONLY**: `writer_nonce_carriage` requires
+ * `seal`; `seal` requires the fenced trio (issue #207). **The fenced trio ALONE stays fully
+ * legal** — a store declaring neither rung is still a fully conforming implementation (the
+ * shipped realm-cloud Postgres state; non-seal trio stores keep the #207 destructive-drain
+ * posture forever, not a transitional gap). `TraceBufferStore.traceCapabilities` below is the
+ * declaration; `storeDeclaresSeal`/`storeDeclaresNonceCarriage`/`validateTraceCapabilities`
+ * (this file) are the ONLY authoritative way to check a rung — no ad-hoc `typeof` checks for
+ * these two rungs anywhere else in the codebase (TCK, tools, or engine).
+ */
+export type TraceCapability = 'seal' | 'writer_nonce_carriage';
+/** Outcome of `sealFenced` (issue #197 PR-1, the `seal` rung — see `TraceBufferStore.sealFenced`
+ *  for the full contract). */
+export type SealResult = {
+    sealed: true;
+} | {
+    sealed: false;
+    /** `'absent'`: no live WAL existed for (runId, stepId) at all — #183 absence-is-success,
+     *  not a failure. `'capped'`: this key already holds `SEALED_ARTIFACTS_LIMIT_PER_STEP`
+     *  sealed artifacts — the caller must fall back to the existing destructive drain (bounded,
+     *  loud, never silent eviction of a sealed artifact to make room). */
+    reason: 'absent' | 'capped';
+};
+/**
+ * One line of a WAL, as read back — live or sealed (issue #197 PR-1). Defined in CORE, not
+ * mcp-server (where the fs store's own file-local `WalLine` type lives), because
+ * `listSealedForRun`'s return type must be usable without any core-adjacent caller importing an
+ * mcp-server-local type. The fs store's `WalLine` gains the identical optional `nonce` field and
+ * stays structurally assignable to this type (never a separate, divergent shape).
+ */
+export interface SealedWalLine {
+    ts: number;
+    entries: AgentTraceEntry[];
+    /** The writer nonce active when this line was appended, if any (issue #197 PR-1) — absent for
+     *  a bare/anonymous append. NEVER fabricated for a line that was genuinely bare. */
+    nonce?: string;
+}
+/** One sealed artifact for a single (runId, stepId) key — issue #197 PR-1, part of the `seal`
+ *  rung. A key may accumulate several sealed artifacts (repeated reclaim/settle-time seals),
+ *  distinguished by ascending `seq`. */
+export interface SealedArtifact {
+    step_id: string;
+    /** Ascending, per-key sequence number (0-based) — distinguishes repeated seals of the same
+     *  (runId, stepId) key from one another. */
+    seq: number;
+    lines: SealedWalLine[];
+}
+/**
+ * Structured `BUFFER_FULL` refusal detail shape (issue #197 PR-1, design §5) — every
+ * `TraceBufferStore.append`/`appendFenced` implementation populates this as the thrown
+ * `WorkflowError`'s `details`. `scope` names which budget bound the refusal: `'writer'` (this
+ * call's own writer — the nonce that made it, or ⊥ for a bare call — exceeded its per-writer
+ * `BUFFER_LIMIT_COUNT`/`BUFFER_LIMIT_BYTES` share) or `'file'` (the whole-file, all-writers-combined
+ * `BUFFER_BACKSTOP_COUNT`/`BUFFER_BACKSTOP_BYTES` ceiling). `binding_dimension` names which of the
+ * two triples actually caused the refusal — `count`/`bytes` are ALWAYS both populated (a caller
+ * can see the whole picture, not just the half that bound). `your_*`/`total_*` (file scope only)
+ * are the occupancy evidence: this writer's own share vs. the whole file's combined share —
+ * foreign share is stated as an observable FACT; crash causation for that foreign residue is
+ * NEVER asserted (design §5's corrected message framing — a foreign writer's residue might be a
+ * live concurrent step, not a crash).
+ */
+export interface BufferFullDetails {
+    scope: 'writer' | 'file';
+    binding_dimension: 'count' | 'bytes';
+    count: {
+        requested: number;
+        used: number;
+        limit: number;
+    };
+    bytes: {
+        requested: number;
+        used: number;
+        limit: number;
+    };
+    your_count?: number;
+    your_bytes?: number;
+    total_count?: number;
+    total_bytes?: number;
+}
 export interface AppendResult {
+    /**
+     * WRITER-scope numbers (issue #197 PR-1 re-documentation — values and meaning UNCHANGED for
+     * bare-only traffic, the compat law, design §5): this call's own writer (the nonce that made
+     * it, or ⊥ for a bare call) against the per-writer `BUFFER_LIMIT_COUNT`/`BUFFER_LIMIT_BYTES`
+     * ceiling. An all-bare WAL has exactly one writer (⊥), so writer-scope and file-scope coincide
+     * there and these fields are numerically IDENTICAL to before this capability existed.
+     */
     buffer_count: number;
     buffer_bytes: number;
     limit_count: number;
     limit_bytes: number;
     final_limit_entries: number;
     final_limit_bytes: number;
+    /**
+     * Whole-FILE scope numbers (issue #197 PR-1, additive) — populated ONLY by a store that
+     * declares `writer_nonce_carriage` (a non-declaring store never sets these; they stay
+     * `undefined`, never fabricated as `0`). Ride the new `BUFFER_BACKSTOP_COUNT`/
+     * `BUFFER_BACKSTOP_BYTES` ceiling — combined usage across every writer sharing this key.
+     */
+    file_count?: number;
+    file_limit_count?: number;
+    file_bytes?: number;
+    file_limit_bytes?: number;
+}
+/**
+ * Optional trailing options bag for `append`/`appendFenced` (issue #197 PR-1, the
+ * `writer_nonce_carriage` rung). Declaration-only: adding this parameter is NOT a separate
+ * method-presence check in `storeDeclaresNonceCarriage` (there is no way to detect "did this
+ * store implementation read the options bag" other than declared capability + behavior) — a
+ * non-declaring implementation is contractually required to IGNORE it, never throw or otherwise
+ * error on receiving one; the tool layer (PR-2) is responsible for never passing a nonce to a
+ * non-declaring store.
+ */
+export interface AppendOptions {
+    /** Client-minted, opaque per-step-attempt writer identity. Absent ⇒ the bare/anonymous writer
+     *  class (⊥) — today's behavior, byte-identical. NEVER validated/shaped by the store itself
+     *  (opaque string, store-agnostic) — protocol-level shape validation is a PR-2/tool-layer
+     *  concern (design §6). */
+    writerNonce?: string;
 }
 export interface TraceBufferStore {
+    /**
+     * Declares which of the two optional capability-ladder rungs (issue #197 PR-1) this store
+     * implements: `'seal'` and/or `'writer_nonce_carriage'`. See `TraceCapability`'s own doc for
+     * the ladder rule (carriage requires seal requires the fenced trio; trio alone stays legal).
+     *
+     * **Immutability**: this set MUST NOT change after construction — a reader may read it once and
+     * cache the result forever (the TCK's STRUCTURAL law asserts two reads are content-identical).
+     *
+     * **Authoritative only in conjunction with method presence**: a declared rung whose required
+     * methods are NOT actually present (or vice versa) is a construction-time defect, not a runtime
+     * condition — see `validateTraceCapabilities`. Absent entirely (`undefined`) is equivalent to
+     * declaring neither rung (the honest floor — trio-alone, or no fenced trio at all, both legal).
+     */
+    readonly traceCapabilities?: ReadonlySet<TraceCapability>;
     /**
      * Appends normalized entries to the buffer for (runId, stepId).
      * Each entry is per-entry normalized at append time (reserved prefix drop, field caps).
      * Batch timestamp (_internalTs) is assigned at write time.
-     * Throws BUFFER_FULL WorkflowError if the WAL limit would be exceeded.
+     * Throws BUFFER_FULL WorkflowError if the WAL limit would be exceeded (issue #197 PR-1: see
+     * `BufferFullDetails` for the refusal's structured `details` shape).
+     *
+     * @param options Optional trailing options bag (issue #197 PR-1) — see `AppendOptions`.
      */
-    append(runId: string, stepId: string, entries: AgentTraceEntry[]): Promise<AppendResult>;
+    append(runId: string, stepId: string, entries: AgentTraceEntry[], options?: AppendOptions): Promise<AppendResult>;
     /**
      * Reads all buffered entries for (runId, stepId) with their batch timestamps attached.
      * Returns empty array if no buffer exists.
-     * Entries carry _internalTs for ordering at finalization.
+     * Entries carry _internalTs for ordering at finalization, and (issue #197 PR-1) an optional
+     * `_nonce` re-attached from the line that carried them — see `BufferedEntry._nonce`.
      */
     read(runId: string, stepId: string): Promise<BufferedEntry[]>;
     /** Deletes the buffer for (runId, stepId). No-op if absent. */
@@ -39,34 +171,314 @@ export interface TraceBufferStore {
      * Never mutates; never throws on a missing run (an absent run/store location is just `{}`).
      */
     readAllForRun(runId: string): Promise<Record<string, unknown[]>>;
+    /**
+     * **The fenced trio (issue #207).** `appendFenced`, `deleteFenced`, and `deleteAllForRunFenced`
+     * are an ALL-OR-NOTHING optional capability: declaring ANY of the three requires declaring ALL
+     * THREE (the TCK's STRUCTURAL law enforces this deterministically). Declaring the trio is also
+     * a commitment that `read()`, `delete()`, and `deleteAllForRun()` serialize on the SAME
+     * per-(runId, stepId) critical sections the fenced methods use — a store that declares the trio
+     * but lets a legacy `read()`/`delete()`/`deleteAllForRun()` call bypass those critical sections
+     * has not actually implemented the capability.
+     *
+     * Guard contract, shared by all three methods:
+     * - `guard` is invoked at least once per call. Implementations MAY retry internally — every TCK
+     *   assertion about guard invocation is count-TOLERANT ("at least one"), never an exact count.
+     * - ALL guard invocations complete BEFORE the method's destructive/mutating effect (the write
+     *   for `appendFenced`; the delete for `deleteFenced`/`deleteAllForRunFenced`).
+     * - `guard` performs exactly one lock-free `runStore.get` read (the #132 atomic-rename-safe
+     *   read) — never more than one, and never a locked read.
+     * - `guard` never acquires a lock of its own. Global lock-ordering rule: a WAL critical-section
+     *   holder must never acquire the run-file lock, and a run-file-lock holder must never acquire a
+     *   WAL lock — callers that touch both (e.g. purge) always delete artifacts strictly BEFORE
+     *   their run-locked anchor delete, never the other way around.
+     * - A guard rejection propagates to the caller UNWRAPPED — the method performs no write/delete,
+     *   and the store's own error-wrapping (e.g. `toArtifactDeleteFailedError`) never touches it.
+     *
+     * Two-obligation form for a transaction-scoped store that enforces the race via a native SQL
+     * predicate instead of an in-process critical section (`fenceForm: 'native-predicate'` in the
+     * TCK): (1) `guard` is still invoked at least once per call, but MAY run outside the store's
+     * atomic section — it must never `await` foreign code while holding a transaction/row lock, and
+     * must never open a second pooled connection while the first is held. (2) The actual racing
+     * predicate must be enforced by a CONFLICT-INDUCING read in the SAME transaction as the
+     * buffer write (e.g. `SELECT ... FOR SHARE` at minimum — a plain same-transaction `WHERE` under
+     * READ COMMITTED is insufficient; it is vulnerable to statement-snapshot staleness). **A
+     * native-predicate store's race closure is NOT verified by a green TCK run** — the latch-based
+     * laws (`CS_OCCUPANCY`, `PER_KEY_INDEPENDENCE`, `NO_SILENT_LOSS`) produce an explicit, visible
+     * documented skip for such a store, never a silent pass; that store's OWN in-transaction fencing
+     * suite is what must verify race closure (the same posture `RunStore.claimStep`'s cross-host
+     * obligation already states for `CLAIM_SINGLE_OWNER`, issue #188).
+     *
+     * Legacy `append`/`delete`/`deleteAllForRun` remain on the interface, byte-frozen, for any store
+     * that does not declare the fenced trio.
+     */
+    appendFenced?(runId: string, stepId: string, entries: AgentTraceEntry[], guard: () => Promise<void>, options?: AppendOptions): Promise<AppendResult>;
+    /**
+     * See `appendFenced`'s doc (above) for the shared guard contract and the all-or-nothing
+     * declaration rule. Runs `guard` inside the SAME per-(runId, stepId) critical section
+     * `appendFenced` uses, immediately before deleting the buffer. Returns the number of entries
+     * actually deleted — `0` means the buffer was already absent (absence is success; the guard
+     * still runs first, and still gates the no-op). This same-critical-section count is what lets a
+     * caller (e.g. reclaim) report how many entries a destructive drain actually destroyed without a
+     * separate, lock-re-entrant `read()` call — a store's own critical section must never be
+     * re-entered from within itself.
+     */
+    deleteFenced?(runId: string, stepId: string, guard: () => Promise<void>): Promise<number>;
+    /**
+     * See `appendFenced`'s doc (above) for the shared guard contract and the all-or-nothing
+     * declaration rule. Deletes every buffer for `runId` across all steps. `guard` is RE-INVOKED
+     * inside EACH per-file (per-(runId, stepId)) critical section, immediately before that file's
+     * delete — a refusal on any one file aborts the whole sweep with that file's error
+     * (stop-on-first-error, matching the legacy `deleteAllForRun`'s own semantics). When zero files
+     * match `runId` at all, `guard` is still consulted at least once — the scan (resolving which
+     * files match) necessarily runs first, then the guard is invoked at least once even for that
+     * empty result. If it throws, the sweep rejects with that error exactly as it would for a
+     * non-empty sweep — propagation is UNIFORM across the zero-match and non-empty cases (the TCK
+     * asserts rejection here, not merely invocation count: a refusing guard makes even a zero-match
+     * sweep reject). A guard rejection (e.g. a
+     * typed `STATE_RUN_BUSY`) propagates to the caller UNWRAPPED, past the store's own
+     * `toArtifactDeleteFailedError` wrapping — which still wraps genuine unlink/I-O failures,
+     * preserving the #183 absence/unreachable/corrupt trichotomy: a guard refusal is neither
+     * "absent" nor a genuine I/O failure, it is a third, distinct outcome that must reach the caller
+     * exactly as the guard threw it.
+     *
+     * @param dirEntries Optional pre-scanned directory listing (see the legacy method's own doc) —
+     *   ignored by non-fs implementations.
+     */
+    deleteAllForRunFenced?(runId: string, guard: () => Promise<void>, dirEntries?: readonly string[]): Promise<void>;
+    /**
+     * **`sealFenced` (issue #197 PR-1, the `seal` rung — design §4).** Atomically retires the
+     * ENTIRE live WAL for (runId, stepId) to a sealed artifact, under the SAME per-key critical
+     * section the fenced trio uses. `guard` runs IN-CS, immediately BEFORE the move (same guard
+     * contract as the trio: at-least-once invocation, completes before the mutating effect, exactly
+     * one lock-free `runStore.get`, never acquires its own lock, a rejection propagates UNWRAPPED —
+     * nothing is moved).
+     *
+     * Semantics:
+     * - Absent live WAL ⇒ `{sealed: false, reason: 'absent'}` — #183 absence-is-success, not an
+     *   error.
+     * - This key already at the per-key seal-budget cap (`SEALED_ARTIFACTS_LIMIT_PER_STEP`) ⇒
+     *   `{sealed: false, reason: 'capped'}` — the caller falls back to the existing destructive
+     *   drain (`deleteFenced`); bounded, loud, never a silent eviction of an existing sealed
+     *   artifact to make room.
+     * - Otherwise ⇒ raw bytes move VERBATIM to the sealed artifact — no parse, no copy, no
+     *   truncation, no dedup. A torn/corrupt trailing line moves as bytes too (readers of the
+     *   sealed artifact skip + warn on it, mirroring the live WAL reader's own #183 corruption
+     *   posture) ⇒ `{sealed: true}`.
+     * - Any OTHER I/O errno (not absence) ⇒ a typed throw (#183) — the caller warns; this is
+     *   residue-not-loss (the live WAL is left exactly as it was; nothing moved).
+     *
+     * A store implements this ONLY as part of declaring the `seal` rung (`storeDeclaresSeal`) —
+     * requires the full fenced trio to already be declared (the ladder).
+     */
+    sealFenced?(runId: string, stepId: string, guard: () => Promise<void>): Promise<SealResult>;
+    /**
+     * **`listSealedForRun` (issue #197 PR-1, part of the `seal` rung — design §4).** Returns every
+     * sealed artifact for `runId`, across all steps — descriptors plus their parsed lines
+     * (torn-tolerant: a corrupt line inside a sealed artifact is skipped + a loud warning emitted,
+     * mirroring the live WAL reader's own discipline; the corrupt bytes stay on disk untouched).
+     * Absence of any sealed artifacts for this run ⇒ `[]`, never a throw. Lock-free, point-in-time
+     * (mirrors `readAllForRun`'s own posture, issue #159) — never mutates.
+     */
+    listSealedForRun?(runId: string): Promise<SealedArtifact[]>;
 }
-/** An AgentTraceEntry extended with engine-assigned ordering timestamp (milliseconds). */
+/** An AgentTraceEntry extended with engine-assigned ordering timestamp (milliseconds), and
+ *  (issue #197 PR-1) the writer nonce that carried it, if any — re-attached from the line the
+ *  entry was originally appended in. NEVER fabricated for a genuinely bare line. */
 export interface BufferedEntry extends AgentTraceEntry {
     _internalTs: number;
+    _nonce?: string;
 }
+/** PER-WRITER budget (issue #197 PR-1 re-documentation — value unchanged): the ceiling for ONE
+ *  writer's own share of a (runId, stepId) buffer — the nonce that made the call, or ⊥ (the
+ *  bare/anonymous writer class) for a call with no nonce. An all-bare WAL has exactly one writer
+ *  (⊥), so this is the ONLY ceiling that can ever bind there — byte-identity with pre-#197
+ *  behavior is emergent from that fact, not a special case. */
 export declare const BUFFER_LIMIT_COUNT = 200;
+/** See `BUFFER_LIMIT_COUNT` — the per-writer BYTE ceiling. */
 export declare const BUFFER_LIMIT_BYTES: number;
 export declare const FINAL_LIMIT_ENTRIES = 100;
 export declare const FINAL_LIMIT_BYTES: number;
+/** Whole-FILE backstop (issue #197 PR-1, additive, design §5): the ceiling across EVERY writer
+ *  sharing a (runId, stepId) key combined, regardless of nonce — 2× the per-writer ceiling.
+ *  Unconditional: enforced even on a store that hasn't seen a single nonced append, though it is
+ *  UNREACHABLE in the all-bare case (the lone writer ⊥ already refuses at the per-writer ceiling,
+ *  which is half the backstop — the backstop only ever binds when at least one OTHER writer's
+ *  residue is sharing the file). */
+export declare const BUFFER_BACKSTOP_COUNT: number;
+/** See `BUFFER_BACKSTOP_COUNT` — the whole-file BYTE backstop. */
+export declare const BUFFER_BACKSTOP_BYTES: number;
+/** Per-(runId, stepId) seal budget (issue #197 PR-1, the `seal` rung, design §4): the maximum
+ *  number of sealed artifacts one key may accumulate. On reaching the cap, `sealFenced` returns
+ *  `{sealed: false, reason: 'capped'}` — the caller falls back to the existing destructive drain
+ *  (`deleteFenced`), bounded and loud, rather than silently evicting an existing sealed artifact
+ *  to make room. */
+export declare const SEALED_ARTIFACTS_LIMIT_PER_STEP = 8;
 /**
  * Per-entry normalization run at append time (not at finalization).
  * Mirrors the normalization in normalizeTrace for the parts that don't need seq or byte-budget context.
  * Returns null if the entry should be dropped (reserved prefix).
  */
 export declare function normalizeEntryForBuffer(entry: AgentTraceEntry): AgentTraceEntry | null;
+/**
+ * True iff `store` both DECLARES the `seal` rung (in `traceCapabilities`) AND actually implements
+ * every method that rung requires: the full fenced trio (`appendFenced`/`deleteFenced`/
+ * `deleteAllForRunFenced`, issue #207) PLUS `sealFenced` PLUS `listSealedForRun` (the ladder: seal
+ * requires the trio). This is the ONLY authoritative `seal` predicate.
+ */
+export declare function storeDeclaresSeal(store: TraceBufferStore): boolean;
+/**
+ * True iff `store` both DECLARES `writer_nonce_carriage` (in `traceCapabilities`) AND satisfies
+ * `storeDeclaresSeal` (the ladder: carriage requires seal requires the trio). Carriage itself
+ * adds no NEW required method — the `options` bag on `append`/`appendFenced` is declaration-only
+ * (there is no way to detect "does this implementation actually read the options bag" other than
+ * declared capability + behavior), so this predicate is exactly "declared AND seal holds". This
+ * is the ONLY authoritative `writer_nonce_carriage` predicate.
+ */
+export declare function storeDeclaresNonceCarriage(store: TraceBufferStore): boolean;
+/**
+ * Wiring-time validation MECHANISM (issue #197 PR-1, design §3/§12 — INVOKING this at the
+ * injection seams, e.g. `server.ts`/CLI executors, is deliberately PR-2's job, not this one's).
+ * Typed fail-loud (a `TRACE_CAPABILITY_INCONSISTENT` `WorkflowError`) when a rung is DECLARED but
+ * its predicate does not hold (declared-but-inconsistent — a construction-time wiring defect,
+ * never a runtime condition worth retrying). Silent success when a rung is simply undeclared —
+ * the honest floor: trio-alone, or no capabilities at all, are both fully legal and never an
+ * error.
+ */
+export declare function validateTraceCapabilities(store: TraceBufferStore): void;
+/**
+ * Pure per-writer + whole-file budget decision (issue #197 PR-1, design §5) — shared by every
+ * `TraceBufferStore` implementation enforcing this pair, so the decision logic and the
+ * `BufferFullDetails` shape live in exactly ONE place rather than being independently
+ * (and riskily divergently) reimplemented per store. Deliberately takes BEFORE-and-AFTER pairs
+ * (rather than a "delta" this call would add) because the two shipped stores compute "after"
+ * differently and both must stay exact: the fs store's JSONL format is genuinely additive (byte
+ * delta = the one new line's own serialized size), but the in-memory store's byte-identity
+ * constraint requires re-serializing the WHOLE flattened array exactly as its pre-#197 formula
+ * always did — forcing a shared "delta" abstraction on top of that would risk being byte-inexact
+ * for one of the two stores. Returns `undefined` when neither ceiling would be exceeded.
+ *
+ * Writer scope is checked FIRST: if the appender's own share alone would exceed the per-writer
+ * ceiling, that is what gets reported — a caller whose own share already exceeds the (smaller)
+ * per-writer ceiling should be told that specifically, not the (less actionable, and in that
+ * case also necessarily true) whole-file ceiling. This ordering is also what makes the compat
+ * law hold: an all-bare file's lone writer (⊥) hits `scope:'writer'` at exactly today's legacy
+ * limits — the file backstop (2×) is arithmetically unreachable for a single writer alone.
+ */
+export declare function checkBufferBudget(params: {
+    writerCountBefore: number;
+    writerBytesBefore: number;
+    writerCountAfter: number;
+    writerBytesAfter: number;
+    fileCountBefore: number;
+    fileBytesBefore: number;
+    fileCountAfter: number;
+    fileBytesAfter: number;
+}): BufferFullDetails | undefined;
+/**
+ * Builds the `BUFFER_FULL` `WorkflowError` from a `BufferFullDetails` (issue #197 PR-1, design
+ * §5) — the SAME message wording, error code, category, and `agentAction` every store uses, so
+ * the only thing that ever varies between stores is which concrete numbers went into `details`.
+ * Guidance wording is deliberate: foreign share (file scope's `your_*`/`total_*`) is stated as an
+ * observable FACT; crash causation for that foreign residue is NEVER asserted (design §5's
+ * corrected framing — foreign residue might be a live concurrent writer, not a crash). Code stays
+ * `BUFFER_FULL`, category `ENGINE`, `agentAction: 'provide_input'` — unchanged from before this
+ * capability existed.
+ */
+export declare function bufferFullError(details: BufferFullDetails): WorkflowError;
+/**
+ * Flattens WAL batches (`{ts, entries, nonce?}`, issue #197 PR-1's internal batch shape — see
+ * `SealedWalLine`) into the read-back `BufferedEntry[]` shape, in batch order: `_internalTs` from
+ * the batch's `ts`; `_nonce` re-attached ONLY when the batch actually carried one (never
+ * fabricated for a bare batch — the key byte-identity property: a flattened all-bare batch list
+ * produces EXACTLY the same shape/bytes as the pre-#197 flat representation always did).
+ */
+export declare function flattenWalBatches(batches: readonly SealedWalLine[]): BufferedEntry[];
 /**
  * In-memory TraceBufferStore for use in tests and non-persistent environments.
  * Entries are lost on process restart (no file I/O).
+ *
+ * Declares the fenced trio (issue #207): `append`, `read`, `delete`, and `deleteAllForRun` all
+ * serialize on the SAME per-(runId, stepId) critical section `appendFenced`/`deleteFenced` use,
+ * via a per-key async mutex (a promise-chain map) — every one of the operations for a given key
+ * runs strictly after the previous operation on THAT SAME key has settled (success or failure).
+ * Liveness posture: a hung guard hangs only that key's chain — a different key's chain is
+ * untouched and proceeds normally (this per-key granularity is load-bearing; see the TCK's
+ * PER_KEY_INDEPENDENCE law). The chain map's entry for a key is deleted once its own tail
+ * settles and no newer call has chained after it, so an idle key holds no Map entry (no leak).
+ *
+ * Issue #197 PR-1 additionally declares BOTH capability-ladder rungs (`seal` and
+ * `writer_nonce_carriage`, `traceCapabilities`). The live-WAL internal representation is
+ * BATCH-preserving (`Map<string, SealedWalLine[]>`, one entry per `append`/`appendFenced` call) —
+ * NOT flattened — because `sealFenced` must be able to retire a key's exact batch history as one
+ * unit, and each batch's own (possibly absent) writer nonce must survive independently for
+ * carriage/budget partitioning. Every flattening surface (`read`, `readAllForRun`, `deleteFenced`'s
+ * count, the byte-budget arithmetic) derives its answer from this representation via
+ * `flattenWalBatches` (or direct batch arithmetic over it), reproducing the exact pre-#197
+ * observable shape and byte formula for all-bare traffic — see `appendUnlocked`.
  */
 export declare class InMemoryTraceBufferStore implements TraceBufferStore {
+    readonly traceCapabilities: ReadonlySet<TraceCapability>;
     private buffers;
+    private sealed;
+    private chains;
     private key;
-    append(runId: string, stepId: string, entries: AgentTraceEntry[]): Promise<AppendResult>;
+    /**
+     * Runs `fn` strictly after the current tail of the per-key chain for `k` has settled (whether
+     * that prior link resolved or rejected), and installs `fn`'s own settlement as the new tail.
+     * Returns/throws `fn`'s real result — chain-tracking never swallows or reshapes it. Removes the
+     * map entry for `k` once this call's tail settles, but only if no NEWER call has since replaced
+     * it (an identity check against the exact promise reference this call stored).
+     */
+    private withKeyLock;
+    /**
+     * Count + bytes for exactly the batches belonging to `writerNonce` (`undefined` = ⊥, the bare
+     * writer class) — computed by flattening JUST that writer's own batches and re-stringifying,
+     * so the byte number for a single-writer (all-bare) file is bit-for-bit the old whole-array
+     * formula. Equality is plain `===` over `batch.nonce ?? undefined`, which implements the
+     * design's `adopted(line) ⇔ line.nonce ≡ claimant.nonce, with absent ≡ absent` rule with no
+     * special-casing (`undefined === undefined` is `true`).
+     */
+    private partitionStats;
+    /** Whole-file count + bytes across every writer combined — the pre-#197 formula, applied to
+     *  the full batch list regardless of how many distinct writers contributed to it. */
+    private fileStats;
+    private appendUnlocked;
+    append(runId: string, stepId: string, entries: AgentTraceEntry[], options?: AppendOptions): Promise<AppendResult>;
+    /** guard runs INSIDE the per-key critical section, immediately before the write — see the
+     *  interface doc for the full guard contract. */
+    appendFenced(runId: string, stepId: string, entries: AgentTraceEntry[], guard: () => Promise<void>, options?: AppendOptions): Promise<AppendResult>;
     read(runId: string, stepId: string): Promise<BufferedEntry[]>;
     delete(runId: string, stepId: string): Promise<void>;
+    /** guard runs INSIDE the same per-key critical section `appendFenced` uses, immediately before
+     *  the delete — see the interface doc for the full guard contract. Returns the number of
+     *  entries actually deleted, summed across every live batch (0 = buffer already absent; the
+     *  guard still ran first). Sealed artifacts for this key are NOT touched — sealing exists
+     *  precisely to move content out of this destructive drain's reach; only `deleteAllForRun*`
+     *  (run-level bulk delete) also retires sealed artifacts. */
+    deleteFenced(runId: string, stepId: string, guard: () => Promise<void>): Promise<number>;
     deleteAllForRun(runId: string, _dirEntries?: readonly string[]): Promise<void>;
-    /** Returns each in-memory buffer for the run, keyed by stepId, as its stored `BufferedEntry[]`
-     *  (already-flattened individual entries — this store's own natural shape; see `append`). */
+    /** guard is RE-INVOKED inside EACH per-(runId, stepId) critical section, immediately before
+     *  that key's delete — see the interface doc for the full guard contract, including the
+     *  zero-match-sweep invocation requirement (handled below: the guard still runs at least once
+     *  even when this run has no buffers at all). Sealed artifacts join this run-level bulk delete
+     *  (design §4 — a sealed artifact is retained ONLY until its owning run itself is purged). */
+    deleteAllForRunFenced(runId: string, guard: () => Promise<void>, _dirEntries?: readonly string[]): Promise<void>;
+    /** guard runs INSIDE the per-key critical section, immediately before the seal-move — see the
+     *  interface doc for the full contract. Atomically retires the ENTIRE live batch history for
+     *  (runId, stepId) into a new sealed artifact (ascending `seq`), clearing the live buffer in
+     *  the same step — the in-memory analogue of the fs store's no-clobber rename-based seal
+     *  (there is no filesystem race to guard against here; the per-key mutex already serializes
+     *  every operation on this key, so `seq` can simply be the next array index). */
+    sealFenced(runId: string, stepId: string, guard: () => Promise<void>): Promise<SealResult>;
+    /** Lock-free point-in-time snapshot of every sealed artifact for a run, across all its steps —
+     *  matches `readAllForRun`'s deliberately-unlocked posture (see D3 residual 9). */
+    listSealedForRun(runId: string): Promise<SealedArtifact[]>;
+    /** Returns each in-memory LIVE buffer for the run, keyed by stepId, flattened to
+     *  `BufferedEntry[]` (this store's own natural read shape; see `read`). Lock-free
+     *  point-in-time diagnostic, matching #159's shipped `export`/`readAllForRun` posture —
+     *  deliberately NOT serialized through the per-key mutex (see D3 residual 9). Sealed artifacts
+     *  are NOT included (see `listSealedForRun`) — unchanged scope from before this capability
+     *  existed; PR-2 decides how/whether call sites merge the two. */
     readAllForRun(runId: string): Promise<Record<string, unknown[]>>;
 }
 //# sourceMappingURL=trace-buffer-store.d.ts.map

package/dist/store/trace-buffer-store.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"trace-buffer-store.d.ts","sourceRoot":"","sources":["../../src/store/trace-buffer-store.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAG9D,MAAM,WAAW,YAAY;IAC3B,YAAY,EAAE,MAAM,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,mBAAmB,EAAE,MAAM,CAAC;IAC5B,iBAAiB,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,gBAAgB;IAC/B;;;;;OAKG;IACH,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,eAAe,EAAE,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC;IAEzF;;;;OAIG;IACH,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,EAAE,CAAC,CAAC;IAE9D,+DAA+D;IAC/D,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAErD;;;;;;OAMG;IACH,eAAe,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE9E;;;;;;OAMG;IACH,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC;CAClE;AAED,0FAA0F;AAC1F,MAAM,WAAW,aAAc,SAAQ,eAAe;IACpD,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,eAAO,MAAM,kBAAkB,MAAM,CAAC;AACtC,eAAO,MAAM,kBAAkB,QAAa,CAAC;AAC7C,eAAO,MAAM,mBAAmB,MAAM,CAAC;AACvC,eAAO,MAAM,iBAAiB,QAAY,CAAC;AAO3C;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,eAAe,GAAG,eAAe,GAAG,IAAI,CA+BtF;AAED;;;GAGG;AACH,qBAAa,wBAAyB,YAAW,gBAAgB;IAC/D,OAAO,CAAC,OAAO,CAAsC;IAErD,OAAO,CAAC,GAAG;IAIL,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,eAAe,EAAE,GAAG,OAAO,CAAC,YAAY,CAAC;IA+CxF,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,EAAE,CAAC;IAI7D,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIpD,eAAe,CAAC,KAAK,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAQpF;iGAC6F;IACvF,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,EAAE,CAAC,CAAC;CAUvE"}
+{"version":3,"file":"trace-buffer-store.d.ts","sourceRoot":"","sources":["../../src/store/trace-buffer-store.ts"],"names":[],"mappings":"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"}