@sema-agent/server 7.43.0 → 7.44.0

package/dist/orchestration/workflow-notify-journal.js

@@ -1,52 +1,7 @@
-/**
- * SVC-1 (core contract) — the AT-LEAST-ONCE workflow completion-notify TRUST GATE.
- *
- * ## Why this exists
- * core's `run_workflow` tool already does the BACKGROUND-RUN half of SVC-1: `startWorkflow` returns a `runId`
- * synchronously (the caller never blocks), the workflow runs to terminal in the background, and on terminal the
- * tool fires a single in-process completion notify through the {@link import("@sema-agent/core").WorkflowCompletionNotifier}
- * seam (see core `run-workflow-tool.js`). That notify is **at-MOST-once**: it lives only in the process that
- * started the run. If the replica CRASHES between the workflow reaching terminal and the receiver acking the
- * notification — or if it crashes before the run even finishes — the notification is LOST. Nothing re-derives it.
- *
- * SVC-1 makes the completion notify **at-LEAST-once**, the half that is service's (design boundary
- * [[core-service-boundary]] — the durable wiring + the deployment notify route is TOB, not core):
- *  1. **terminal → notify** (steady state): every started run is journaled as `pending`; when its in-process
- *     notify fires, we record the terminal status durably, DELIVER to the wrapped notifier, and mark the journal
- *     entry `acked`. Delivery before ack ⇒ a crash mid-delivery re-delivers on recovery (never a silent drop).
- *  2. **crash-recovery → re-derive + notify** (startup): on boot we read the journal for every NOT-`acked` entry
- *     and RE-FETCH the run from the durable {@link import("@sema-agent/core").WorkflowRunStore}. A run that is now
- *     TERMINAL (its in-process notify was lost to the crash, or it finished while we were down) is RE-DELIVERED
- *     and acked. A run still `running` is left pending — the live process owns its terminal notify, and the next
- *     recovery sweep (or that process's own delivery) will catch it. A run MISSING from the store (reaped /
- *     never persisted) is acked-as-abandoned so the journal does not grow unbounded chasing a ghost.
- *  3. **idempotent**: the journal de-dups by `runId` (a delivered+acked run is never re-delivered), so the
- *     wrapped notifier — and the downstream receiver — may safely be invoked twice for the same run across a
- *     crash boundary (the SVC-1 contract: the receiver is idempotent on `runId`). We dedup on OUR side too, so a
- *     double recovery sweep, or a recovery racing the live notify, delivers at most one extra time, not N.
- *
- * ## Durability model
- * The journal is itself a {@link WorkflowNotifyJournalStore} — a tiny append-only `(runId → entry)` durable map,
- * deliberately SEPARATE from the `WorkflowRunStore`: the run store is core-owned (its schema/CAS is core's), and
- * critically it has **no cross-scope enumeration** (`listByScope` needs a scope; there is no "list all runs" /
- * "list all scopes"), so it cannot by itself answer "which runs might still owe a notify?" after a restart. The
- * journal records `(runId, scope)` for exactly that: a bounded, service-owned to-do list of notifications, scoped
- * to the deployment, that the recovery sweep walks. It is the SINGLE source of truth for "has this run's
- * completion been delivered?".
- *
- * The default {@link FileWorkflowNotifyJournalStore} is zero-dependency + crash-safe (atomic-append ledger, same
- * posture as core's `FileWorkflowRunStore`) so the no-DB / TOC-local path is durable out of the box. A durable
- * cross-replica backend (TiDB/PG) is a thin port of the same interface (a follow-on; the recovery sweep + the
- * gate logic here are backend-agnostic).
- */
 import { mkdirSync, readFileSync, existsSync, openSync, writeSync, fsyncSync, closeSync } from "node:fs";
 import { join } from "node:path";
 import { buildFleetWorkflowRow } from "../fleet/fleet-bus.js";
 import { isTerminalWorkflowRowStatus, seedTerminalWorkflowRow } from "../fleet/fleet-terminal-window.js";
-/** Build a bounded + redacted completion summary from a durable run's terminal state (the recovery path — the
- *  live path uses core's own `boundedSummary`). We never have the raw result here (the run store keeps the run,
- *  not the originator's payload), so we synthesize a conservative one: status + the run's already-bounded error.
- *  Mirrors core `failureSummary`/`redactSummary` posture — strip URLs/tokens/paths defensively. */
 const SUMMARY_MAX = 500;
 export function recoverySummary(status, error) {
     if (status === "completed")
@@ -57,24 +12,9 @@ export function recoverySummary(status, error) {
         .replace(/\b(?:Bearer|Basic)\s+[A-Za-z0-9._~+/=-]+/gi, "[redacted-token]")
         .replace(/\b(?:api[_-]?key|secret|token|password|authorization)\b\s*[:=]\s*"?[^\s"',}]+/gi, "[redacted-secret]")
         .replace(/(?:\/[A-Za-z0-9_.-]+){2,}/g, "[redacted-path]")
-        // Windows/UNC paths too (SVC-1 review): `C:\dir\file` + `\\host\share\…` would otherwise surface VERBATIM — a
-        // host-path/identity leak the forward-slash rule above misses. `\\{1,2}` covers the UNC double-leading-backslash.
         .replace(/(?:[A-Za-z]:)?(?:\\{1,2}[A-Za-z0-9_.$-]+){2,}/g, "[redacted-path]");
     return redacted.length > SUMMARY_MAX ? `${redacted.slice(0, SUMMARY_MAX)}…[+${redacted.length - SUMMARY_MAX} chars]` : redacted;
 }
-/**
- * The AT-LEAST-ONCE completion-notify gate. Wrap the deployment's real delivery once at boot, then:
- *  - {@link buildNotifier} hands core a {@link import("@sema-agent/core").WorkflowCompletionNotifier} whose `notify`
- *    runs the LIVE deliver-then-ack path (the in-process at-most-once notify, now journaled into at-least-once).
- *  - {@link onWorkflowStart} journals a run the moment it starts (so a crash BEFORE its terminal notify still
- *    leaves a pending entry the recovery sweep finds). Call it from wherever the runId becomes known.
- *  - {@link recover} runs ONCE at boot: re-derives every pending run's terminal state from the
- *    {@link WorkflowRunStore} and re-delivers + acks the ones that are terminal.
- *
- * The gate is the SINGLE writer of `acked`, and dedups every delivery against the journal, so the wrapped
- * delivery sink is invoked at most once per run in steady state (and at most one extra time across a crash —
- * the at-least-once / idempotent contract).
- */
 export class WorkflowNotifyGate {
     journal;
     runStore;
@@ -86,35 +26,18 @@ export class WorkflowNotifyGate {
         this.deliver = deliver;
         this.opts = opts;
     }
-    /**
-     * The runIds whose journal entry THIS process recorded — the boot-orphan judgment's authoritative anchor
-     * (round-1 review, MEDIUM). A wall-clock cutoff alone is not sound: after a BACKWARD clock step the entries
-     * this process records land BELOW the boot cutoff, and the sweep would finalize runs whose in-process
-     * executor is alive and running (a false `failed` notify for a workflow that then keeps going — worse than
-     * the absent row it was fixing). Membership here is a fact about THIS incarnation, unforgeable by any clock.
-     * Retired on ack AND the moment a sweep observes the run terminal (the anchor only ever gates the `running`
-     * arm), so a delivery/ack outage cannot pile up entries for runs that are no longer executing.
-     */
     recordedThisIncarnation = new Set();
     now() {
         return this.opts.now ? this.opts.now() : Date.now();
     }
-    /** Record a journal entry AND remember that this incarnation is the one that recorded it (see the field). */
     async recordPending(entry) {
         await this.journal.record(entry);
         this.recordedThisIncarnation.add(entry.runId);
     }
-    /** Ack an entry + drop its incarnation mark (acked ⇒ never scanned again, so the mark has no further use). */
     async ackDelivered(runId) {
         await this.journal.ack(runId, this.now());
         this.recordedThisIncarnation.delete(runId);
     }
-    /**
-     * Journal a STARTED run as pending-notify. Call this with the synchronous `runId` from `startWorkflow` /
-     * `run_workflow` — BEFORE the workflow can reach terminal — so a crash mid-run still leaves a recoverable
-     * to-do. Best-effort + idempotent: a journal throw is reported, never propagated (it must not break the
-     * workflow start; worst case the recovery sweep won't know about this run — degraded, not corrupting).
-     */
     async onWorkflowStart(input) {
         try {
             await this.recordPending({
@@ -126,15 +49,9 @@ export class WorkflowNotifyGate {
             });
         }
         catch (err) {
-            this.opts.onError?.("record", input.runId, err); // start-time JOURNAL write failed (not a delivery)
+            this.opts.onError?.("record", input.runId, err);
         }
     }
-    /**
-     * The core-facing notifier. core calls this exactly once per run on terminal (its own at-most-once, runId-dedup
-     * `fire`). We turn it into at-least-once: ensure the run is journaled (the start hook may have been skipped),
-     * then deliver-then-ack. Idempotent: if the run is ALREADY acked (a recovery sweep beat us, or a duplicate
-     * core fire), skip — at most one delivery.
-     */
     buildNotifier() {
         return {
             notify: async (input) => {
@@ -144,24 +61,16 @@ export class WorkflowNotifyGate {
                     summary: input.summary,
                     ...(input.sourceTaskId ? { sourceTaskId: input.sourceTaskId } : {}),
                     ...(input.principal ? { principal: input.principal } : {}),
-                    ...(input.originatingSessionId ? { originatingSessionId: input.originatingSessionId } : {}), // core 1.208: lookup-free session routing
+                    ...(input.originatingSessionId ? { originatingSessionId: input.originatingSessionId } : {}),
                 }, input.scope ?? input.principal ?? "default");
             },
         };
     }
-    /**
-     * Deliver a run's completion exactly once (idempotent on the journal). Ensures the entry exists (record is a
-     * no-op if it already does), SKIPS if already acked, otherwise delivers THEN acks (a crash between deliver and
-     * ack re-delivers on recovery — at-least-once). A delivery throw is reported and re-thrown to the LIVE caller
-     * only as a swallowed report (core's `fire` already `.catch`es), leaving the entry pending for the next sweep.
-     */
     async deliverOnce(p, scope) {
         const existing = await this.journal.get(p.runId);
         if (existing?.acked)
-            return; // already delivered — idempotent skip
+            return;
         if (!existing) {
-            // The start hook didn't journal it (e.g. a run started before this gate existed, or the hook was skipped).
-            // Record it now so the deliver-then-ack ordering still holds and a crash mid-delivery is recoverable.
             await this.recordPending({
                 runId: p.runId,
                 scope,
@@ -174,59 +83,17 @@ export class WorkflowNotifyGate {
             await this.deliver(p);
         }
         catch (err) {
-            // Stays PENDING (not acked) → the next recovery sweep re-delivers. Report, never throw back into core.
             this.opts.onError?.("deliver", p.runId, err);
             return;
         }
         await this.ackDelivered(p.runId);
     }
-    /**
-     * RECOVERY sweep — run at boot AND PERIODICALLY (wired into the service reaper), BEFORE/while serving traffic.
-     * For every pending (not-acked) journal entry, re-fetch the run from the durable {@link WorkflowRunStore}:
-     *  - TERMINAL (completed/failed): its in-process notify was lost to a crash (or it finished while we were
-     *    down) → re-deliver + ack (idempotent on the receiver).
-     *  - `running` but STALE (run.startedAt older than `orphanGraceMs`): a crash-orphaned run — core never resumes
-     *    a prior `running` row (resume mints a NEW runId) and never reaps a `running` row, so NOTHING will ever
-     *    flip it terminal. Finalize-as-ABANDONED: deliver a `failed` completion (so the originator learns the
-     *    workflow died) + ack, instead of leaking the entry forever. This closes the exact crash topology SVC-1
-     *    exists for (a replica SIGKILLed mid-run).
-     *  - `running` and FRESH (within the grace window): genuinely in flight → leave pending (the owning process
-     *    delivers its terminal notify, or the next sweep catches it once it goes terminal or stale). The sweep
-     *    publishes NOTHING here — see the single-writer invariant below.
-     *  - MISSING (reaped / never persisted): ack-as-abandoned so the journal doesn't chase a ghost forever.
-     * `orphanGraceMs` MUST exceed the max expected workflow runtime (the run store has no cross-replica liveness
-     * signal, so age is the only orphan proxy). Returns a tally. A per-entry throw is isolated so one bad entry
-     * can't abort the sweep.
-     *
-     * BOTH abandoned arms (boot-orphan + stale-past-grace) flip the DURABLE row to `failed` FIRST (CAS on rev),
-     * so the run store, the fleet panel and the delivered notify give ONE answer — previously the notify said
-     * `failed` while `/workflows` kept saying `running` forever ([2999]: republishing without finalizing would
-     * have turned "panel empty" into "panel shows a row that never moves"). A lost CAS means the run moved under
-     * the sweep (e.g. its real terminal landed concurrently) — skip this pass; the entry stays pending and the
-     * next sweep handles the NEW state.
-     *
-     * 🔴 SINGLE-WRITER INVARIANT for the fleet row (round-1 review, two HIGH findings): the sweep only ever
-     * publishes a **TERMINAL** fleet frame (the flip above, via `publishTerminalFleetRow` → final frame + remove).
-     * It NEVER publishes a `running` row. Two reasons, both "a row we mint here can become one nobody can retire":
-     *  1. cross-replica (SQL journal): a pending `running` entry may belong to ANOTHER replica. Its terminal
-     *     update lands on that replica's own (replica-local) fleet bus, and its ack removes the entry from the
-     *     shared journal — so this replica would never see the run again and its minted row would sit `running`
-     *     forever. (The terminal-redelivery arm deliberately doesn't publish either — it is a notify path.)
-     *  2. same-replica: `runStore.get` is a READ-TIME SNAPSHOT. If the live run commits its terminal (and the
-     *     wrapper removes the row) between that read and the publish, a `running` republish resurrects a row
-     *     that will never be removed again.
-     * A live row's ONE writer is this replica's `put`/`update` observation point ({@link JournalingWorkflowRunStore}),
-     * which by construction sees every transition including the terminal one.
-     */
     async recover(opts = {}) {
-        const orphanGraceMs = opts.orphanGraceMs ?? 24 * 60 * 60 * 1000; // 24h default — well beyond any normal workflow
+        const orphanGraceMs = opts.orphanGraceMs ?? 24 * 60 * 60 * 1000;
         const pending = await this.journal.listPending();
         let redelivered = 0;
         let stillRunning = 0;
         let abandoned = 0;
-        /** Was this entry recorded by a PREVIOUS incarnation of this process? Only meaningful when the caller granted
-         *  the replica-local finalize authority (a shared/SQL journal carries other replicas' entries). Both halves
-         *  are required — see `finalizeStartedBeforeMs` + {@link recordedThisIncarnation}. */
         const isPreBootEntry = (entry) => opts.finalizeStartedBeforeMs !== undefined &&
             !this.recordedThisIncarnation.has(entry.runId) &&
             entry.createdAt < opts.finalizeStartedBeforeMs;
@@ -234,69 +101,33 @@ export class WorkflowNotifyGate {
             try {
                 const run = await this.runStore.get(entry.runId);
                 if (!run) {
-                    // No durable run — USUALLY a ghost (the row was reaped, or its `put` threw). But it is ALSO the
-                    // transient shape of a run being started RIGHT NOW: JournalingWorkflowRunStore journals BEFORE it
-                    // persists (deliberately — a persist that throws must still leave a recoverable entry), so there is a
-                    // window where the entry exists and the row does not. Acking that window is unrecoverable: the owner's
-                    // own terminal `deliverOnce` then sees `acked` and drops the completion for good — the exact loss SVC-1
-                    // exists to prevent (round-2 review, HIGH). So only ack a ghost that PROVABLY isn't that window: one
-                    // that predates this incarnation, or one older than the grace the whole sweep already trusts.
                     if (!isPreBootEntry(entry) && this.now() - entry.createdAt <= orphanGraceMs) {
-                        stillRunning++; // "left pending this pass" — a start-in-progress is exactly that
+                        stillRunning++;
                         continue;
                     }
                     await this.ackDelivered(entry.runId);
                     abandoned++;
                     continue;
                 }
-                // principal fallback: the start-hook (JournalingWorkflowRunStore.put) records only runId+scope — scope IS
-                // the creating principal, so it's the sound owner attribution when entry.principal is absent (M6: a
-                // recovered notify must still carry an owner).
                 const principal = entry.principal ?? entry.scope;
-                // #3 G (core 1.187): sourceTaskId used to be "genuinely unrecoverable" here (the durable WorkflowRun didn't
-                // carry it). core now threads it onto WorkflowRun.sourceTaskId (startWorkflow stores it / RunWorkflow passes the
-                // host taskId), so fall back to run's copy when the journal entry lost it — the recovered notify can finally
-                // attribute the originating host task.
                 const sourceTaskId = entry.sourceTaskId ?? run.sourceTaskId;
-                // core 1.210: the durable WorkflowRun now records `originatingSessionId` (same story as
-                // sourceTaskId's 1.187) — thread it onto the RECOVERED payload so crash-recovery routes lookup-free,
-                // symmetric with the live notify (resolveCompletionRoute reads it first).
                 const originatingSessionId = run.originatingSessionId;
                 if (run.status === "running") {
                     const startedAt = run.startedAt || entry.createdAt;
-                    // [2995] boot-orphan judgment (replica-local journal only): the entry predates this process, so the
-                    // in-process executor that owned it died with the previous incarnation — nothing will ever flip it.
-                    // (Conditions in `isPreBootEntry`: replica-local authority + not recorded by US + predates boot.)
                     const bootOrphan = isPreBootEntry(entry);
                     if (!bootOrphan && this.now() - startedAt <= orphanGraceMs) {
                         stillRunning++;
-                        // fresh → genuinely in flight; the owner (or a later sweep) delivers terminal. Publish NOTHING here:
-                        // a `running` row minted from a read-time snapshot can outlive every chance to retire it (the
-                        // single-writer invariant on the doc-comment above).
                         continue;
                     }
-                    // Orphaned `running` — boot-orphan (executor died with the previous process) or stale past grace
-                    // (nothing will ever flip it terminal). Finalize as abandoned/failed: flip the DURABLE row first
-                    // ([2999] honesty half — store/fleet/notify must give one answer), then deliver + ack.
                     const abandonSummary = bootOrphan
                         ? "workflow abandoned — the engine restarted while it was running (its in-process executor did not survive the restart)"
                         : "workflow abandoned — still `running` past the orphan grace window (replica likely crashed mid-run)";
                     const flipped = { ...run, status: "failed", error: abandonSummary, endedAt: this.now() };
                     const flippedOk = await this.runStore.update(entry.runId, run.scope, flipped, run.rev !== undefined ? { rev: run.rev } : undefined);
                     if (!flippedOk)
-                        continue; // the run moved under the sweep — leave pending; next sweep sees the NEW state
-                    this.recordedThisIncarnation.delete(entry.runId); // terminal now — the anchor only ever gates `running`
-                    // ORDER: retire the fleet row FIRST — immediately after the durable flip, before anything is awaited.
-                    // Same order as the live leg (the wrapper publishes the terminal frame, then core fires its notify), and
-                    // it is the only order where "a finalized run leaves the active fleet" survives every delivery outcome
-                    // (rounds 4+5): the delivery may throw at its ack, or never settle at all, and a `finally` cannot help
-                    // with the latter — while the NEXT sweep takes the terminal-redelivery arm, which deliberately publishes
-                    // nothing, so a row skipped here would be stranded `running` with nobody left to retire it.
-                    // The converse risk is bounded and self-healing: if the projection throws, this pass delivers nothing
-                    // and the entry stays pending — the next sweep's terminal arm delivers it. Deferred by one sweep, never
-                    // lost. (Subscriber throws are already isolated inside the fleet bus — per-callback try/catch with a
-                    // registered fail-open tag — so a projection throw here means the publish machinery itself broke.)
-                    opts.publishTerminalFleetRow?.(entry.runId, flipped); // final frame then remove
+                        continue;
+                    this.recordedThisIncarnation.delete(entry.runId);
+                    opts.publishTerminalFleetRow?.(entry.runId, flipped);
                     await this.deliverOnce({
                         runId: entry.runId,
                         status: "failed",
@@ -309,10 +140,6 @@ export class WorkflowNotifyGate {
                         abandoned++;
                     continue;
                 }
-                // Terminal but not acked ⇒ the crash dropped its notify. Re-derive the bounded summary + re-deliver.
-                // Drop the incarnation mark FIRST (round-2 review, MEDIUM): the anchor only ever gates the `running` arm,
-                // so a terminal run has no use for it — retiring here (not only on a successful ack) keeps the registry
-                // tracking runs that are actually in flight even through a prolonged delivery outage.
                 this.recordedThisIncarnation.delete(entry.runId);
                 await this.deliverOnce({
                     runId: entry.runId,
@@ -322,7 +149,6 @@ export class WorkflowNotifyGate {
                     ...(principal ? { principal } : {}),
                     ...(originatingSessionId ? { originatingSessionId } : {}),
                 }, entry.scope);
-                // deliverOnce only acks on a clean delivery; count a redelivery whether or not it stuck (it logs on fail).
                 const after = await this.journal.get(entry.runId);
                 if (after?.acked)
                     redelivered++;
@@ -334,16 +160,6 @@ export class WorkflowNotifyGate {
         return { scanned: pending.length, redelivered, stillRunning, abandoned };
     }
 }
-/**
- * Default zero-dependency, crash-safe {@link WorkflowNotifyJournalStore}. An append-only JSONL ledger replayed
- * at boot (last-writer-wins per `runId`), the same durable posture as core's `FileWorkflowRunStore` — fsync'd
- * appends, atomic single-line records. Single-instance / TOC-local: a cross-replica TiDB/PG port is a follow-on
- * (the recovery sweep + gate are backend-agnostic).
- *
- * The ledger only ever grows by one line per `record`/`ack`; an acked entry's line is not deleted (the replay
- * folds it), so retention is a future compaction concern — the backlog `listPending` walks is bounded by
- * IN-FLIGHT + un-swept runs, not history.
- */
 export class FileWorkflowNotifyJournalStore {
     fsyncEnabled;
     ledgerPath;
@@ -352,15 +168,10 @@ export class FileWorkflowNotifyJournalStore {
     constructor(root, fsyncEnabled = true) {
         this.fsyncEnabled = fsyncEnabled;
         const dir = join(root, "workflow-notify");
-        // 0o700 dir + 0o600 ledger: the journal persists tenant identity (scope/principal/sourceTaskId) — it must not
-        // be group/world-readable (parity with the durable-secret posture; a default-umask file would leak identity).
         mkdirSync(dir, { recursive: true, mode: 0o700 });
         this.ledgerPath = join(dir, "journal.jsonl");
         this.replay();
     }
-    /** Replay the ledger into the authoritative map (last-writer-wins by line order). Tolerates a torn final line
-     *  (a crash mid-append) by dropping an unparsable trailing record — the same crash-safety FileWorkflowRunStore
-     *  relies on (a partial append is simply not yet committed state). */
     replay() {
         if (!existsSync(this.ledgerPath))
             return;
@@ -373,17 +184,15 @@ export class FileWorkflowNotifyJournalStore {
                 ev = JSON.parse(line);
             }
             catch {
-                continue; // torn/partial line — skip (uncommitted)
+                continue;
             }
             if (ev && typeof ev.runId === "string")
                 this.entries.set(ev.runId, ev);
         }
     }
-    /** Commit one entry: append the JSON line (fsync) THEN flip the in-memory map (crash-safe ordering — the
-     *  durable record lands before the in-memory state the caller observes). */
     commit(entry) {
         if (this.fd === undefined)
-            this.fd = openSync(this.ledgerPath, "a", 0o600); // owner-only (identity data)
+            this.fd = openSync(this.ledgerPath, "a", 0o600);
         writeSync(this.fd, `${JSON.stringify(entry)}\n`);
         if (this.fsyncEnabled)
             fsyncSync(this.fd);
@@ -391,7 +200,6 @@ export class FileWorkflowNotifyJournalStore {
     }
     async record(input) {
         const existing = this.entries.get(input.runId);
-        // Idempotent: never reset an existing entry (esp. an acked one → it would re-deliver forever).
         if (existing)
             return;
         this.commit({
@@ -406,7 +214,7 @@ export class FileWorkflowNotifyJournalStore {
     async ack(runId, ackedAt) {
         const existing = this.entries.get(runId);
         if (!existing || existing.acked)
-            return; // idempotent
+            return;
         this.commit({ ...existing, acked: true, ackedAt });
     }
     async listPending() {
@@ -415,32 +223,25 @@ export class FileWorkflowNotifyJournalStore {
     async get(runId) {
         return this.entries.get(runId) ?? null;
     }
-    /** Release the append handle (best-effort) — called on shutdown. */
     close() {
         if (this.fd !== undefined) {
             try {
                 closeSync(this.fd);
             }
             catch {
-                /* best-effort */
             }
             this.fd = undefined;
         }
     }
-    /** Test/inspection: total entries (acked + pending). */
     get size() {
         return this.entries.size;
     }
 }
-/** In-process {@link WorkflowNotifyJournalStore} — tests / single-instance ephemeral. Does NOT survive a
- *  restart (so it provides NO crash-recovery on its own); use {@link FileWorkflowNotifyJournalStore} or a
- *  durable backend for the real at-least-once guarantee. Useful to unit-test the gate's live + idempotency
- *  paths without touching disk, and to simulate a crash by handing a FRESH store to a new gate. */
 export class InMemoryWorkflowNotifyJournalStore {
     entries = new Map();
     async record(input) {
         if (this.entries.has(input.runId))
-            return; // idempotent
+            return;
         this.entries.set(input.runId, {
             runId: input.runId,
             scope: input.scope,
@@ -466,53 +267,19 @@ export class InMemoryWorkflowNotifyJournalStore {
         return this.entries.size;
     }
 }
-/**
- * A {@link WorkflowRunStore} DECORATOR that journals a run the instant core persists it at START. core's
- * `startWorkflow` `put`s the run row (`status: "running"`) synchronously before the body runs, carrying both the
- * `runId` and the `scope` — the one synchronous start-time hook the service gets WITHOUT a new core seam (core
- * exposes no `onWorkflowStart`). Wrapping the run store here observes that `put`, journals the started run as
- * pending-notify, then delegates to the wrapped store. Every other method is a pure pass-through (the run store
- * stays core's source of truth for `/workflows`). This is the [[core-service-boundary]]-clean wiring: reuse the
- * core store seam, observe writes through it, never fork a parallel run model.
- *
- * Journaling on `put` (not on notify) is what makes recovery cover a crash BEFORE terminal: the entry exists the
- * moment the run starts, so the boot sweep finds it even if the process died mid-run.
- */
 export class JournalingWorkflowRunStore {
     inner;
     gate;
     fleetBus;
-    constructor(inner, 
-    /** [1262] optional since the fleet decoupling: undefined ⇒ no start-time journal (ephemeral memory
-     *  backend has nothing to recover), the FLEET half still publishes — the panel is replica-local UI
-     *  state and must not be gated on the durable-notify machinery (the regression that emptied clay's
-     *  workflow panel on memory-backend deployments). */
-    gate, 
-    /** MF-Fleet (data contract): publish the workflow's fleet row on every put/update (the same write-observation
-     *  point as the notify journal). Optional — undefined ⇒ no fleet publish. */
-    fleetBus) {
+    constructor(inner, gate, fleetBus) {
         this.inner = inner;
         this.gate = gate;
         this.fleetBus = fleetBus;
     }
-    /** Derive + publish the MF-Fleet workflow row from a WorkflowRun (doneCount/totalCount from agents, tokens from
-     *  stats); a terminal workflow LEAVES the fleet (publish terminal then remove), a running one stays/updates. */
     publishFleet(id, run) {
         if (!this.fleetBus)
             return;
-        // A-002.3(#194 病族 F1 同源性断裂):终态判据走 fleet-terminal-window 的共享谓词(其穷举表对
-        // core WorkflowRunStatus 编译期闭合)——此前手写两值比较是第二份独立定义,core 加终态词时穷举表
-        // 红、这里恒 false ⇒ 行既不 seed 进终态窗也不 removeWorkflow,面板留幽灵 running 行。
         const terminal = isTerminalWorkflowRowStatus(run.status);
-        // 撤行**不挂在发帧成功上**(复审第 2 轮 MEDIUM):「终态行必须离场」是不变量、发终帧是尽力而为。
-        // try/finally ⇒ 发布本体抛错照样撤行(异常仍向上抛,不吞:吞了就是一条未登记的 fail-open 臂)。
-        // 订阅方抛错已在 fleet bus 的 subscribe 隔离层被吞并记 fail-open——本 finally 守的是发布机器本身
-        // 的抛错(理论缝级,fresh 复审盘点后判近死防御但保留:防未来发布本体改动回退)。两腿一处收口。
-        // 行投影本体 = {@link buildFleetWorkflowRow}(#189:快照的终态行窗与本写路径共用同一份投影,
-        // 单源不漂;本函数的发布/撤行语义逐字不变)。
-        // [3156] 轮2 修:终态行**写路径顺手 seed** 进程内终态窗缓存——重启-重连剧本里(boot recover 判死),
-        // fleetWide 连接的 durable pull 没有正确的查询键可用(caller principal ≠ 引擎铸行 scope),seed 是
-        // 唯一同源可达径。放在 publish 之前:seed 是纯内存 push,不会抛;终态行入窗与发帧同拍。
         if (terminal)
             seedTerminalWorkflowRow(buildFleetWorkflowRow(id, run));
         try {
@@ -520,34 +287,24 @@ export class JournalingWorkflowRunStore {
         }
         finally {
             if (terminal)
-                this.fleetBus.removeWorkflow(id); // terminal workflow leaves the active fleet (the shell saw the final frame)
+                this.fleetBus.removeWorkflow(id);
         }
     }
-    /** [2995] recovery projection seam: the same fleet projection as the put/update observation points, exposed so
-     *  the recovery sweep can RETIRE a row for a run it just finalized (terminal input ⇒ final frame, then remove).
-     *  Wire it as `recover`'s `publishTerminalFleetRow` hook — and only ever hand it a TERMINAL run: a `running`
-     *  row published from outside the wrapper's own write path has no guaranteed retirement (see the invariant on
-     *  {@link WorkflowNotifyGate.recover}). */
     republishFleet(id, run) {
         this.publishFleet(id, run);
     }
     async put(id, run) {
-        // Journal FIRST (best-effort, swallowed inside onWorkflowStart) so a started run is always recoverable, THEN
-        // persist. Order matters: if persist throws, the journal entry still lets recovery re-check the (absent) run
-        // and ack-as-abandoned — no leak, no lost notify owed.
         await this.gate?.onWorkflowStart({
             runId: id,
             scope: run.scope,
-            // core threads sourceTaskId/principal to the NOTIFIER, not onto the run row, so they're unavailable here;
-            // the notifier path (deliverOnce) fills them in when it records/delivers. Recovery still has runId+scope.
         });
         await this.inner.put(id, run);
-        this.publishFleet(id, run); // MF-Fleet: the run appeared (running) / its row state changed
+        this.publishFleet(id, run);
     }
     async update(id, scope, run, expect) {
         const ok = await this.inner.update(id, scope, run, expect);
         if (ok)
-            this.publishFleet(id, run); // MF-Fleet: only on a successful CAS (the persisted state is what the fleet shows)
+            this.publishFleet(id, run);
         return ok;
     }
     get(id) {