@smartmemory/stratum 0.4.5 → 0.5.0

package/dist/engine/flow_cancel.js

@@ -0,0 +1,158 @@
+import { reapFlowAgents, signalFlowAgents } from "../connectors/foreground_registry.js";
+export const EMPTY_AGENTS = Object.freeze({
+    signalled: 0, reaped: 0, gone: 0, unreachable: 0, alreadySettled: 0, unresolved: 0, unsettled: 0, unreaped: 0,
+});
+function emptyAgents() { return { ...EMPTY_AGENTS }; }
+function cancelError(code, fields, message) {
+    const text = message ?? (fields.reason === "run_lock_held"
+        ? `run ${fields.runId} lock is held${fields.holderPid !== undefined ? ` by pid ${fields.holderPid}` : ""}; cancel was not applied`
+        : `cancel of run ${fields.runId} was not acknowledged`);
+    return Object.assign(new Error(text), { code }, fields);
+}
+function codeOf(error) {
+    return typeof error === "object" && error !== null && "code" in error
+        ? String(error.code) : undefined;
+}
+function pidOf(error) {
+    const pid = error?.holderPid;
+    return typeof pid === "number" ? pid : undefined;
+}
+function reasonOf(error) {
+    const reason = error?.reason;
+    return reason === "run_lock_held" || reason === "engine_dispatch_active" || reason === "local_teardown_timeout"
+        ? reason : undefined;
+}
+/** F6. `Number("soon")` is NaN, `Date.now() + NaN` is NaN, and every `Date.now() >= deadline`
+ *  test against it is false — so a mistyped budget did not shorten the teardown, it removed the
+ *  deadline entirely and let the reap loop run forever. A bad value fails here instead. */
+function timeoutBudgetMs(options) {
+    const value = options.timeoutMs ?? Number(process.env.STRATUM_CANCEL_TIMEOUT_MS ?? 15000);
+    if (!Number.isFinite(value) || value < 0) {
+        throw new Error(`${options.timeoutMs !== undefined ? "timeoutMs" : "STRATUM_CANCEL_TIMEOUT_MS"} must be a nonnegative finite number`);
+    }
+    return value;
+}
+/** F2. `graceMs` is validated HERE rather than deep in the registry, for the same reason as the
+ *  budget: the registry only sees it after the run has been settled. */
+function requireGraceMs(options) {
+    if (options.graceMs === undefined)
+        return;
+    if (!Number.isFinite(options.graceMs) || options.graceMs < 0) {
+        throw new Error("graceMs must be a nonnegative finite number");
+    }
+}
+/** The phases of a foreground cancel, shared by the MCP tool and the CLI. Both surfaces call
+ *  this and NOTHING else (R1-4) — a phase implemented at one call site is a phase the other
+ *  surface silently lacks.
+ *
+ *  Order (R2-5): SETTLE → signal every recorded group → await the local abort's settlement →
+ *  await the reap and the registry settlement → compute `acknowledged`.
+ *
+ *  Settling first (D4) means the acknowledgement is never lost to a hung teardown: the run is
+ *  durably cancelled before a single signal is sent, and a teardown failure is reported ON TOP
+ *  of a completed settle. Signalling before awaiting the local abort matters because the two
+ *  teardowns overlap — SIGTERM to a group and an AbortController on the same run are the same
+ *  child from two directions — and serialising them would add a full grace window per agent.
+ *  Awaiting the local settlement BEFORE the reap pass is what stops the sweep from reading
+ *  `running` entries whose teardown this very call started (R2-5).
+ *
+ *  A terminal run that was not cancelled skips the agent phases entirely (R2-4): there are no
+ *  agents of ours to reap, and sweeping would manufacture a teardown verdict about work that
+ *  was never ours. An ALREADY-cancelled run does not skip them — re-running the sweep is how a
+ *  caller recovers from an earlier CANCELLATION_TEARDOWN_TIMEOUT. */
+export async function cancelFlow(engine, runId, options = {}) {
+    // Phase 1: settle, and SETTLE FIRST IS ABSOLUTE. A refusal here means the flow is still
+    // running, so NO agent is signalled or reaped: killing a live driver's agents without
+    // settling the flow leaves a live flow with dead agents, which is the hazard R1-4 forbids.
+    // The refusal returns an all-zero agents summary because no teardown was attempted.
+    //
+    // A RUN_LOCK_TIMEOUT or a live driver lease here means nothing was mutated
+    // (§2.1b) — normalise both rather than letting a raw engine error reach a surface that has
+    // no envelope for it (R3-5). Every other error (ENOENT for an unknown flow above all)
+    // propagates untouched: the CLI maps it, and inventing a cancellation code for it would
+    // report a teardown verdict about a run we never found.
+    // EVERY budget is validated BEFORE the engine is touched (F2). Validating them after the
+    // settle meant a mistyped timeout produced the worst possible outcome: the run was already
+    // durably cancelled, no agent had been signalled, and the caller got an argument error that
+    // reads as "nothing happened". The clock only starts once the run is settled, further down.
+    const budgetMs = timeoutBudgetMs(options);
+    requireGraceMs(options);
+    let settled;
+    try {
+        settled = await engine.flowCancel(runId, options.reason);
+    }
+    catch (error) {
+        const code = codeOf(error);
+        if (code !== "RUN_LOCK_TIMEOUT" && code !== "CANCELLATION_UNCONFIRMED")
+            throw error;
+        const holderPid = pidOf(error);
+        throw cancelError("CANCELLATION_UNCONFIRMED", {
+            runId,
+            status: "running",
+            flowSettled: false,
+            agents: emptyAgents(),
+            reason: code === "RUN_LOCK_TIMEOUT" ? "run_lock_held" : (reasonOf(error) ?? "engine_dispatch_active"),
+            ...(holderPid !== undefined ? { holderPid } : {}),
+        }, error instanceof Error ? error.message : undefined);
+    }
+    if (!settled.flowSettled) {
+        // completed / failed / budget_exhausted: nothing of ours is running (R2-4).
+        return { ...settled, acknowledged: false, agents: emptyAgents() };
+    }
+    // R3-5: ONE absolute teardown deadline, computed here — after settlement, so the lock wait
+    // never eats into it — and shared by every phase. Three independent per-phase timeouts is how
+    // a caller ends up waiting 3x the budget it configured, and how a slow signal pass silently
+    // leaves no time to reap.
+    const deadline = Date.now() + budgetMs;
+    const remaining = () => Math.max(0, deadline - Date.now());
+    const registryOptions = {
+        ...(options.registryRoot !== undefined ? { registryRoot: options.registryRoot } : {}),
+        ...(options.graceMs !== undefined ? { graceMs: options.graceMs } : {}),
+        ...(options.identity !== undefined ? { identity: options.identity } : {}),
+        ...(options.probes !== undefined ? { probes: options.probes } : {}),
+        deadlineAt: deadline,
+    };
+    // The signal pass gets the SAME absolute deadline as the reap. A signal pass with no deadline
+    // can spend the whole budget probing and then hand the reap nothing, and can keep sending
+    // SIGTERMs after the caller has stopped waiting for an answer to any of them.
+    const signalled = await signalFlowAgents(runId, registryOptions);
+    // An abortLocal that times out does NOT abort the cancel: the groups were already signalled
+    // and the reap is the authority on whether they died. Record it and keep going (R3-5).
+    let localTimedOut = false;
+    try {
+        await options.abortLocal?.(runId, remaining());
+    }
+    catch (error) {
+        if (codeOf(error) !== "CANCELLATION_TEARDOWN_TIMEOUT")
+            throw error;
+        localTimedOut = true;
+    }
+    const agents = await reapFlowAgents(runId, signalled, registryOptions);
+    // R1-5: acknowledged is a GUARANTEE, not a summary. Anything unresolved is an error.
+    // R3-6: unsettled is the strongest of the three and subsumes "groups reaped but the owning
+    // dispatcher is still unwinding". All four must be clear.
+    // Acknowledgement is "every group reached a final resolved state and nothing is outstanding",
+    // NOT the old `signalled === reaped` equality. That equality failed both ways: a group that
+    // had already exited before our SIGTERM is never counted `signalled`, so a flow whose agent
+    // died on its own could never be acknowledged; and a group signalled and later found
+    // unreachable satisfied it by accident.
+    const acknowledged = settled.flowSettled
+        && agents.unsettled === 0
+        && agents.unresolved === 0
+        && agents.unreachable === 0
+        && agents.unreaped === 0;
+    if (!acknowledged) {
+        const code = agents.unreachable > 0 && agents.unresolved === 0 && agents.unreaped === 0
+            ? "CANCELLATION_UNCONFIRMED"
+            : "CANCELLATION_TEARDOWN_TIMEOUT";
+        // R3-5: every failure leaves this function as ONE structured error with the same fields,
+        // so the MCP and CLI projections have exactly one shape to render. `status` and
+        // `flowSettled` come from the engine, never from an assumption (R1-5).
+        throw cancelError(code, {
+            runId, status: settled.status, flowSettled: settled.flowSettled, agents,
+            ...(localTimedOut ? { reason: "local_teardown_timeout" } : {}),
+        });
+    }
+    return { ...settled, acknowledged, agents };
+}
+//# sourceMappingURL=flow_cancel.js.map

package/dist/engine/flow_cancel.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"flow_cancel.js","sourceRoot":"","sources":["../../src/engine/flow_cancel.ts"],"names":[],"mappings":"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"}