@sensigo/realm-mcp 0.26.0 → 0.27.0

package/dist/index.d.ts

@@ -3,5 +3,5 @@ export type { RealmMcpServerOptions } from './server.js';
 export { generateProtocol } from './protocol/generator.js';
 export type { WorkflowProtocol, ProtocolStep } from './protocol/generator.js';
 export { JsonTraceBufferStore } from './json-trace-buffer-store.js';
-export declare const VERSION = "0.26.0";
+export declare const VERSION = "0.27.0";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -4,5 +4,5 @@ export { generateProtocol } from './protocol/generator.js';
 // issue #107: exported so the operator run-purge CLI command (packages/cli) can construct one
 // and register it as a PerRunArtifactStore alongside JsonFileStore/FailedAttemptStore.
 export { JsonTraceBufferStore } from './json-trace-buffer-store.js';
-export const VERSION = '0.26.0';
+export const VERSION = '0.27.0';
 //# sourceMappingURL=index.js.map

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

@@ -1,19 +1,162 @@
-import { type TraceBufferStore, type BufferedEntry, type AppendResult, type PerRunArtifactStore, type OrphanSweepableStore, type OrphanArtifact } from '@sensigo/realm';
+import { type TraceBufferStore, type BufferedEntry, type AppendResult, type AppendOptions, type TraceCapability, type SealResult, type SealedArtifact, type PerRunArtifactStore, type OrphanSweepableStore, type OrphanArtifact } from '@sensigo/realm';
 import type { AgentTraceEntry } from '@sensigo/realm';
+/** A `proper-lockfile` retry policy: either a bare retry count (its own simple default backoff)
+ *  or an explicit `retry`-module-compatible options object. */
+type LockRetries = number | {
+    retries: number;
+    minTimeout?: number;
+    maxTimeout?: number;
+};
+/** Lock-acquisition profile shared by every `lockWal` call in this file (issue #207).
+ *  Constructor-injectable so a conformance suite can inflate the retry budget (e.g. to make a
+ *  deliberately slow/latched guard's lock contention observable instead of exhausting the retry
+ *  budget too quickly and masking the scenario under test). */
+export interface TraceBufferLockProfile {
+    retries: LockRetries;
+    stale: number;
+    realpath: boolean;
+}
 /**
  * File-based TraceBufferStore that persists WAL entries to JSONL files on disk.
  * WAL file path: <runsDir>/trace-buffer-<runId>-<base64url(stepId)>.jsonl
+ *
+ * Crash model: like `JsonFileStore`, this store never calls `fsync` — process-crash consistency
+ * comes from `appendFile`'s per-line granularity plus `readWal`'s per-line, torn-line-tolerant
+ * parsing (a crash mid-write can leave one unparseable trailing line, which is skipped; every
+ * earlier, already-written line survives intact). Durability across a true power loss (not just a
+ * process crash) is outside this store's contract, unchanged from its pre-#207 posture.
+ *
+ * Declares the fenced trio (issue #207): `read`, `delete`, and `deleteAllForRun` now serialize on
+ * the SAME per-(runId, stepId) critical section (a `proper-lockfile` lock on the WAL path)
+ * `appendFenced`/`deleteFenced`/`deleteAllForRunFenced` use — see `lockWal` and the interface's
+ * own doc for the full contract.
+ *
+ * Issue #197 PR-1 additionally declares BOTH capability-ladder rungs (`seal` and
+ * `writer_nonce_carriage`, `traceCapabilities`). `sealFenced` retires a live WAL file to a sealed
+ * artifact (`sealed-trace-<runId>-<base64url(stepId)>.<seq>.jsonl`) via the SAME `lockWal`
+ * chokepoint every other operation uses — see `sealFenced`'s own doc for the no-clobber move
+ * mechanics.
  */
 export declare class JsonTraceBufferStore implements TraceBufferStore, PerRunArtifactStore, OrphanSweepableStore {
+    readonly traceCapabilities: ReadonlySet<TraceCapability>;
     private readonly runsDir;
-    constructor(runsDir: string);
+    private readonly lockProfile;
+    constructor(runsDir: string, lockProfile?: Partial<TraceBufferLockProfile>);
     private walPath;
+    /** Builds the on-disk path for one sealed artifact — see `SEALED_PREFIX`'s doc for the shape
+     *  and why it never collides with a live WAL path. */
+    private sealedWalPath;
+    /**
+     * The SOLE `lockfile.lock(` call site in this file (issue #207) — every critical-section
+     * acquisition (`append`, `appendFenced`, `read`, `delete`, `deleteFenced`, `deleteAllForRun`,
+     * `deleteAllForRunFenced`) goes through this one chokepoint. Pins the shared base options
+     * (`stale`/`realpath`) and always installs an explicit `onCompromised` handler — a loud
+     * `console.warn` naming the WAL path — never `proper-lockfile`'s own default handler, which
+     * THROWS from inside a timer callback and crashes the process. `retriesOverride` lets
+     * `append`/`appendFenced` keep their own, more patient retry count; every other caller uses
+     * this store's configured `lockProfile.retries` (constructor-injectable — e.g. a conformance
+     * suite inflating it to make contention observable rather than exhausted-too-fast).
+     *
+     * Verified (issue #207): `lockfile.lock(path, { realpath: false })` acquires cleanly against a
+     * path that does not yet exist — no pre-lock placeholder file is needed for that. `append()`'s
+     * own placeholder-creation below predates this and stays byte-identical for that method, but no
+     * fenced method replicates it.
+     */
+    private lockWal;
     private readWal;
-    append(runId: string, stepId: string, entries: AgentTraceEntry[]): Promise<AppendResult>;
+    /**
+     * Count + bytes for exactly the batches belonging to `writerNonce` (issue #197 PR-1, design §5's
+     * byte-attribution rule) — `undefined` = ⊥, the bare/anonymous writer class.
+     *
+     * A NONCED writer's stats are computed DIRECTLY: sum the `entries.length` and re-serialized
+     * byte size of exactly its own successfully-parsed lines. `JSON.stringify` of a parsed
+     * `WalLine` reproduces its ORIGINAL on-disk bytes exactly — this file only ever writes lines via
+     * `JSON.stringify({ts, entries[, nonce]})`, and V8 preserves string-key insertion order through
+     * parse→re-stringify, so re-serializing a parsed line is bit-for-bit identical to how it was
+     * actually written.
+     *
+     * ⊥'s stats are a RESIDUAL, not a direct sum: `bytes = fileBytes - Σ(every DISTINCT nonced
+     * partition's own bytes)`. This is what makes ⊥ "inherit all unattributable bytes" — a
+     * torn/unparseable line's raw bytes are captured in `fileBytes` (computed from the whole raw
+     * file content, not from re-stringifying parsed lines) but can never be subtracted out as part
+     * of any nonced partition (it never parsed into one), so they remain in ⊥'s residual exactly as
+     * they always silently were before this capability existed. For an all-bare file (no nonced
+     * lines at all), the residual is arithmetically the WHOLE file — byte-identical to the pre-#197
+     * formula, emergent rather than special-cased.
+     */
+    private partitionStats;
+    /**
+     * The actual write logic, shared by `append` and `appendFenced` (issue #207) so BUFFER_FULL /
+     * normalization / `AppendResult` shape live in exactly one place. Assumes the caller already
+     * holds the per-path critical section. `writerNonce` (issue #197 PR-1) is `undefined` for a bare
+     * call — the byte-identical legacy path (this file's own `newLine` shape omits the `nonce` key
+     * entirely when so, exactly matching the pre-#197 JSONL bytes for all-bare traffic).
+     */
+    private appendWithinCS;
+    append(runId: string, stepId: string, entries: AgentTraceEntry[], options?: AppendOptions): Promise<AppendResult>;
+    /**
+     * `guard` runs INSIDE the critical section, immediately before the physical write (issue #207)
+     * — see the interface doc for the full guard contract. NO pre-lock placeholder file: verified
+     * `lockfile.lock(path, { realpath: false })` acquires cleanly against a target that does not yet
+     * exist; the legacy `append()`'s placeholder above predates this and stays byte-identical there,
+     * but is not needed and is not replicated here — `appendFile`'s own `O_CREAT`, inside the
+     * critical section, is the sole creator of the WAL file on this path.
+     */
+    appendFenced(runId: string, stepId: string, entries: AgentTraceEntry[], guard: () => Promise<void>, options?: AppendOptions): Promise<AppendResult>;
+    /** `_nonce` is re-attached per-line ONLY when that line actually carried one — via the SAME
+     *  `flattenWalBatches` core helper the in-memory store uses, so "never fabricate `_nonce` for a
+     *  bare line" is enforced from exactly one shared code path rather than reimplemented twice. */
     read(runId: string, stepId: string): Promise<BufferedEntry[]>;
     delete(runId: string, stepId: string): Promise<void>;
     /**
-     * Deletes every orphaned WAL file for `runId` (issue #107).
+     * `guard` runs INSIDE the same per-path critical section `append`/`appendFenced` use,
+     * immediately before the delete (issue #207) — see the interface doc for the full guard
+     * contract. Returns the number of entries actually deleted (`0` = buffer already absent; the
+     * guard still ran first). Counts via the already-open `readWal` internals — NEVER the public
+     * `read()`, which would re-acquire this same lock (a critical section must never be re-entered
+     * from within itself — `proper-lockfile` is not reentrant).
+     */
+    deleteFenced(runId: string, stepId: string, guard: () => Promise<void>): Promise<number>;
+    /**
+     * `guard` runs INSIDE the SAME per-path critical section every other operation on this key
+     * uses (issue #197 PR-1, the `seal` rung — design §4: "no second locking path"), immediately
+     * before the seal-move. Atomically retires the live WAL file to a new sealed artifact via the
+     * no-clobber `link`-then-`unlink` primitive (`linkNoClobberThenUnlink`) — plain `rename()` is
+     * FORBIDDEN here, since it would silently overwrite an existing sealed artifact at the same
+     * `seq`.
+     *
+     * `seq` is probed by the link attempt ITSELF (no pre-listing, no separate TOCTOU-prone scan):
+     * starting at 0, an `EEXIST` on the link means that `seq` is already taken by an earlier seal —
+     * bump and retry, bounded by `SEALED_ARTIFACTS_LIMIT_PER_STEP`. Exhausting the bound without
+     * success returns `{sealed: false, reason: 'capped'}` — the caller falls back to the existing
+     * destructive drain (`deleteFenced`), never a silent eviction of an already-sealed artifact.
+     *
+     * `{sealed: false, reason: 'absent'}` when no live WAL file exists for this key AT ALL (checked
+     * via `statIfExists` — #183's ENOENT-is-absence discipline) — nothing to seal is success, not a
+     * failure. A present-but-empty file (e.g. `append()`'s legacy placeholder) is NOT "absent" — it
+     * gets sealed like any other live WAL (a harmless, if pointless, empty sealed artifact).
+     */
+    sealFenced(runId: string, stepId: string, guard: () => Promise<void>): Promise<SealResult>;
+    /**
+     * Lock-free point-in-time read of every sealed artifact for `runId`, across all its steps
+     * (issue #197 PR-1, the `seal` rung) — matches `readAllForRun`'s deliberately-unlocked posture.
+     * Parses each sealed file torn-tolerant, per-line, exactly like `readWal`/`readAllForRun` (a
+     * sealed artifact's raw bytes moved verbatim from the live WAL, including any trailing torn
+     * line it already had at seal time — this is a READ concern, not something sealing fixes).
+     */
+    listSealedForRun(runId: string): Promise<SealedArtifact[]>;
+    /** Resolves the candidate WAL files for `runId`, sorted deterministically — shared by
+     *  `deleteAllForRun` and `deleteAllForRunFenced` (issue #207). */
+    private matchingWalFiles;
+    /** Resolves the candidate SEALED artifact files for `runId`, sorted deterministically — the
+     *  same shared-`dirEntries`-or-own-`readdir` shape as `matchingWalFiles` (issue #197 PR-1: a
+     *  sealed artifact is retained only until its owning run itself is purged — design §4). */
+    private matchingSealedFiles;
+    /**
+     * Deletes every orphaned WAL file for `runId` (issue #107). Now serialized per-file on the same
+     * critical section `appendFenced`/`deleteFenced` use (issue #207) — declaring the fenced trio
+     * commits this legacy method too. Issue #197 PR-1: sealed artifacts for this run join the same
+     * sweep (`matchingSealedFiles`) — a sealed artifact outlives its step but not its run.
      *
      * @param dirEntries Optional pre-scanned `readdir(runsDir)` listing supplied by a batch purge —
      *   when present, this method filters it in-memory instead of re-scanning the directory itself
@@ -21,6 +164,28 @@ export declare class JsonTraceBufferStore implements TraceBufferStore, PerRunArt
      *   omitted, exactly as before.
      */
     deleteAllForRun(runId: string, dirEntries?: readonly string[]): Promise<void>;
+    /**
+     * `guard` is RE-INVOKED inside EACH per-file critical section, immediately before that file's
+     * delete (issue #207) — a refusal on any one file aborts the whole sweep with that file's error
+     * (stop-on-first-error, matching the legacy method's own semantics). When zero files match
+     * `runId` at all, `guard` is still consulted at least once (issue #207 correction: the scan
+     * — resolving which files match — necessarily runs FIRST, since there is nothing to invoke a
+     * per-file guard against otherwise; the guard is then invoked once for the empty case). 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, and a per-file lock-contention failure (classified `STATE_RUN_BUSY`,
+     * mirroring `deleteAllForRun`'s own classification above), both propagate UNWRAPPED — never
+     * touched by `toArtifactDeleteFailedError`, which still wraps genuine unlink/I-O failures (the
+     * #183 absence/unreachable/corrupt trichotomy, extended with this third, distinct guard-refusal
+     * outcome). The guard call itself sits OUTSIDE the try/catch scope that performs this wrapping
+     * (see the loop body below) — so a guard that happens to throw an `FsIoError` (e.g. its own
+     * lock-free `runStore.get` hitting EACCES) is never mistaken for `deleteIfExists`'s own failure.
+     *
+     * Issue #197 PR-1: sealed artifacts for this run join the same fenced sweep, same as the
+     * unfenced `deleteAllForRun` above.
+     */
+    deleteAllForRunFenced(runId: string, guard: () => Promise<void>, dirEntries?: readonly string[]): Promise<void>;
     /**
      * Reads every WAL file for `runId` across all steps — the read-only counterpart to
      * `deleteAllForRun`, for `realm run export`'s evidence assembly (issue #159). Mirrors
@@ -55,4 +220,5 @@ export declare class JsonTraceBufferStore implements TraceBufferStore, PerRunArt
      */
     listOrphans(liveRunIds: ReadonlySet<string>): Promise<OrphanArtifact[]>;
 }
+export {};
 //# sourceMappingURL=json-trace-buffer-store.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"json-trace-buffer-store.d.ts","sourceRoot":"","sources":["../src/json-trace-buffer-store.ts"],"names":[],"mappings":"AAKA,OAAO,EACL,KAAK,gBAAgB,EACrB,KAAK,aAAa,EAClB,KAAK,YAAY,EACjB,KAAK,mBAAmB,EACxB,KAAK,oBAAoB,EACzB,KAAK,cAAc,EAUpB,MAAM,gBAAgB,CAAC;AACxB,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAkBtD;;;GAGG;AACH,qBAAa,oBACX,YAAW,gBAAgB,EAAE,mBAAmB,EAAE,oBAAoB;IAEtE,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;gBAErB,OAAO,EAAE,MAAM;IAI3B,OAAO,CAAC,OAAO;YAKD,OAAO;IA6Bf,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,eAAe,EAAE,GAAG,OAAO,CAAC,YAAY,CAAC;IA6ExF,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,EAAE,CAAC;IAQ7D,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAY1D;;;;;;;OAOG;IACG,eAAe,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAmCnF;;;;;;;;;;;;;;;OAeG;IACG,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,EAAE,CAAC,CAAC;IAiDtE;;;;;;;;;;;;;;OAcG;IACG,WAAW,CAAC,UAAU,EAAE,WAAW,CAAC,MAAM,CAAC,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC;CAiC9E"}
+{"version":3,"file":"json-trace-buffer-store.d.ts","sourceRoot":"","sources":["../src/json-trace-buffer-store.ts"],"names":[],"mappings":"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"}