botmux 3.10.0 → 3.11.0

package/dist/core/riff-shutdown-detach.d.ts

@@ -0,0 +1,164 @@
+import type { ChildProcess } from 'node:child_process';
+import * as sessionStore from '../services/session-store.js';
+import type { DaemonSession } from './types.js';
+type ShutdownPhaseResult = {
+    ok: boolean;
+    taskId: string | null;
+    error?: string;
+};
+export type PreparedRiffShutdown = {
+    ok: true;
+    fence: 'prepared';
+    requestId: string;
+    taskId: string | null;
+    /** Runtime lineage sampled before the worker fence. A workerless transaction
+     * must still own this exact value at persistence time; a live transaction may
+     * advance only to its drained `taskId`. */
+    runtimeTaskIdAtPrepare: string | null;
+    /** Fresh durable lineage sampled before installing the fence. Phase 2 uses
+     * it as a lock-protected compare-and-set guard, while also accepting an
+     * already-idempotent target written by the ordinary task-id callback. */
+    durableTaskIdAtPrepare: string | null;
+    durableOwnerAtPrepare: {
+        pid: number | null;
+        larkAppId: string | null;
+        backendType: string | null;
+    };
+    /** Set only after the exact cross-process fresh read succeeds. Used when a
+     * prepared worker exits before an all-or-nothing rollback can reach it. */
+    lineageVerified: boolean;
+    /** Exact generation fenced by `requestId`. Null means the active logical
+     * session was already workerless and only its runtime lineage needs an exact
+     * durable verification. */
+    worker: ChildProcess | null;
+};
+export type RiffShutdownFailure = {
+    ok: false;
+    requestId?: string;
+    taskId: string | null;
+    error: string;
+    /** Phase-2 coordinator policy. Ownership ambiguity must stay fenced; a
+     * plain atomic-write I/O failure may restore the exact prepared worker. */
+    rollbackDisposition?: 'abort_safe' | 'retain_fence';
+};
+/** A prepare refusal that is proven to have happened before the worker/backend
+ * fence. It must never be sent an abort request. */
+export type UnfencedRiffShutdownRefusal = RiffShutdownFailure & {
+    fence: 'none';
+};
+/** A prepare attempt whose exact worker may have installed its backend fence.
+ * Preparation deliberately does not restore admission inline; the fleet
+ * coordinator includes this handle in its one concurrent abort wave. */
+export type PossiblyFencedRiffShutdown = RiffShutdownFailure & {
+    fence: 'possible';
+    requestId: string;
+    worker: ChildProcess;
+    expectedAbortTaskId?: string | null;
+};
+export type RiffShutdownPrepareResult = PreparedRiffShutdown | UnfencedRiffShutdownRefusal | PossiblyFencedRiffShutdown;
+export type RiffShutdownPrepareOptions = {
+    drainTimeoutMs?: number;
+    abortTimeoutMs?: number;
+    /** Absolute transaction deadline. A worker is never asked to fence unless
+     * phase-2 plus the configured admission-restore reserve remain after drain. */
+    deadlineMs?: number;
+    now?: () => number;
+    /** One projection sampled by prepareRiffFleetForShutdown before any fence. */
+    durableSnapshot?: sessionStore.ActiveRiffShutdownSnapshot;
+};
+export type RiffFleetPrepareEntry = {
+    ds: DaemonSession;
+    result: RiffShutdownPrepareResult;
+};
+export type FencedRiffShutdownParticipant = PreparedRiffShutdown | PossiblyFencedRiffShutdown;
+export type UniqueDaemonShutdownSessions = {
+    ok: true;
+    sessions: DaemonSession[];
+} | {
+    ok: false;
+    sessionId: string;
+    error: string;
+};
+/** The active registry can retain multiple aliases to one exact runtime object
+ * after transfer/restore. Process that object once, but refuse two distinct
+ * objects claiming the same durable session id: there is no unique generation
+ * that shutdown can safely fence or retire. */
+export declare function collectUniqueDaemonShutdownSessions(candidates: Iterable<DaemonSession>): UniqueDaemonShutdownSessions;
+export type RiffShutdownDetachOutcome = {
+    ok: true;
+    requestId: string;
+    taskId: string | null;
+    disposition: 'lineage_persisted';
+    worker?: ChildProcess;
+} | RiffShutdownFailure;
+/** Phase 1: fence one exact Riff generation and drain task-id materialization.
+ * Nothing exits or restores admission here. A failure after the prepare send
+ * returns an exact possibly-fenced handle so all peers can be restored in one
+ * concurrent fleet wave rather than serial drain+abort chains. */
+export declare function prepareRiffSessionForShutdown(ds: DaemonSession, options?: RiffShutdownPrepareOptions): Promise<RiffShutdownPrepareResult>;
+export type RiffFleetPrepareOptions = Omit<RiffShutdownPrepareOptions, 'durableSnapshot'> & {
+    snapshotTimeoutMs?: number;
+};
+/** Take one fresh projection for the complete candidate set, then (and only
+ * then) publish prepare requests concurrently. */
+export declare function prepareRiffFleetForShutdown(candidates: readonly DaemonSession[], options?: RiffFleetPrepareOptions): Promise<RiffFleetPrepareEntry[]>;
+export type PreparedRiffFleetEntry = {
+    ds: DaemonSession;
+    result: PreparedRiffShutdown;
+};
+export type RiffFleetPersistenceResult = {
+    ok: true;
+} | (RiffShutdownFailure & {
+    sessionIds: readonly string[];
+    retainFencedSessionIds: readonly string[];
+});
+/** Phase 2 fleet transaction: validate every runtime generation, then compare
+ * and publish all durable lineage rows with one lock and one rename. */
+export declare function persistPreparedRiffShutdownFleet(entries: readonly PreparedRiffFleetEntry[], options?: {
+    persistTimeoutMs?: number;
+    deadlineMs?: number;
+    now?: () => number;
+}): RiffFleetPersistenceResult;
+/** Single-session compatibility path. Fleet shutdown uses the batch function
+ * above; this API remains for explicit focused operations and older callers. */
+export declare function persistPreparedRiffShutdown(ds: DaemonSession, prepared: PreparedRiffShutdown): {
+    ok: true;
+} | RiffShutdownFailure;
+export declare function isPreparedRiffSessionCurrent(ds: DaemonSession, prepared: PreparedRiffShutdown): boolean;
+/** After verified lineage persistence, an exact prepared worker that exited
+ * and was cleared by worker-pool can be safely rolled back locally. A new
+ * worker generation or a different fence remains ownership ambiguity. */
+export declare function canAbortVerifiedExitedRiffPreparation(ds: DaemonSession, prepared: PreparedRiffShutdown): boolean;
+/** Roll back one prepared participant. State clears only after the exact worker
+ * ACKs admission restoration; timeout/late ACK remains deliberately fail-closed. */
+export declare function abortPreparedRiffShutdown(ds: DaemonSession, prepared: PreparedRiffShutdown, options?: {
+    abortTimeoutMs?: number;
+}): Promise<ShutdownPhaseResult>;
+export type RiffFleetAbortEntry = {
+    ds: DaemonSession;
+    result: FencedRiffShutdownParticipant;
+};
+export type RiffFleetAbortResult = {
+    ds: DaemonSession;
+    participant: FencedRiffShutdownParticipant;
+    result: ShutdownPhaseResult;
+};
+/** Restore every exact prepared/possibly-fenced generation concurrently. No
+ * participant can consume another's timeout budget. */
+export declare function abortRiffShutdownFleet(entries: readonly RiffFleetAbortEntry[], options?: {
+    abortTimeoutMs?: number;
+    deadlineMs?: number;
+    now?: () => number;
+}): Promise<RiffFleetAbortResult[]>;
+/** Phase 3: synchronous, infallible-after-validation commit. The coordinator
+ * validates every participant first, then calls this without an intervening
+ * await, so one session can never refuse after a peer was detached. */
+export declare function commitPreparedRiffShutdown(ds: DaemonSession, prepared: PreparedRiffShutdown): boolean;
+/** Single-session compatibility wrapper. Daemon shutdown intentionally uses
+ * the explicit three-phase API above so a multi-Riff fleet cannot half-commit. */
+export declare function detachRiffWorkerForShutdown(ds: DaemonSession, options?: {
+    drainTimeoutMs?: number;
+    abortTimeoutMs?: number;
+}): Promise<RiffShutdownDetachOutcome>;
+export {};
+//# sourceMappingURL=riff-shutdown-detach.d.ts.map

package/dist/core/riff-shutdown-detach.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"riff-shutdown-detach.d.ts","sourceRoot":"","sources":["../../src/core/riff-shutdown-detach.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAEvD,OAAO,KAAK,YAAY,MAAM,8BAA8B,CAAC;AAE7D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAUhD,KAAK,mBAAmB,GAAG;IACzB,EAAE,EAAE,OAAO,CAAC;IACZ,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF,MAAM,MAAM,oBAAoB,GAAG;IACjC,EAAE,EAAE,IAAI,CAAC;IACT,KAAK,EAAE,UAAU,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB;;+CAE2C;IAC3C,sBAAsB,EAAE,MAAM,GAAG,IAAI,CAAC;IACtC;;6EAEyE;IACzE,sBAAsB,EAAE,MAAM,GAAG,IAAI,CAAC;IACtC,qBAAqB,EAAE;QACrB,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;QACnB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;QACzB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;KAC5B,CAAC;IACF;+EAC2E;IAC3E,eAAe,EAAE,OAAO,CAAC;IACzB;;+BAE2B;IAC3B,MAAM,EAAE,YAAY,GAAG,IAAI,CAAC;CAC7B,CAAC;AAEF,MAAM,MAAM,mBAAmB,GAAG;IAChC,EAAE,EAAE,KAAK,CAAC;IACV,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,KAAK,EAAE,MAAM,CAAC;IACd;+EAC2E;IAC3E,mBAAmB,CAAC,EAAE,YAAY,GAAG,cAAc,CAAC;CACrD,CAAC;AAEF;oDACoD;AACpD,MAAM,MAAM,2BAA2B,GAAG,mBAAmB,GAAG;IAC9D,KAAK,EAAE,MAAM,CAAC;CACf,CAAC;AAEF;;wEAEwE;AACxE,MAAM,MAAM,0BAA0B,GAAG,mBAAmB,GAAG;IAC7D,KAAK,EAAE,UAAU,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,YAAY,CAAC;IACrB,mBAAmB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACrC,CAAC;AAEF,MAAM,MAAM,yBAAyB,GACjC,oBAAoB,GACpB,2BAA2B,GAC3B,0BAA0B,CAAC;AAE/B,MAAM,MAAM,0BAA0B,GAAG;IACvC,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;mFAC+E;IAC/E,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IACnB,8EAA8E;IAC9E,eAAe,CAAC,EAAE,YAAY,CAAC,0BAA0B,CAAC;CAC3D,CAAC;AAEF,MAAM,MAAM,qBAAqB,GAAG;IAClC,EAAE,EAAE,aAAa,CAAC;IAClB,MAAM,EAAE,yBAAyB,CAAC;CACnC,CAAC;AAEF,MAAM,MAAM,6BAA6B,GACrC,oBAAoB,GACpB,0BAA0B,CAAC;AAE/B,MAAM,MAAM,4BAA4B,GACpC;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,EAAE,aAAa,EAAE,CAAA;CAAE,GACvC;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAEpD;;;+CAG+C;AAC/C,wBAAgB,mCAAmC,CACjD,UAAU,EAAE,QAAQ,CAAC,aAAa,CAAC,GAClC,4BAA4B,CAoB9B;AAED,MAAM,MAAM,yBAAyB,GACjC;IACE,EAAE,EAAE,IAAI,CAAC;IACT,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,WAAW,EAAE,mBAAmB,CAAC;IACjC,MAAM,CAAC,EAAE,YAAY,CAAC;CACvB,GACD,mBAAmB,CAAC;AAqLxB;;;kEAGkE;AAClE,wBAAsB,6BAA6B,CACjD,EAAE,EAAE,aAAa,EACjB,OAAO,GAAE,0BAA+B,GACvC,OAAO,CAAC,yBAAyB,CAAC,CAuKpC;AAED,MAAM,MAAM,uBAAuB,GAAG,IAAI,CACxC,0BAA0B,EAC1B,iBAAiB,CAClB,GAAG;IACF,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B,CAAC;AAEF;kDACkD;AAClD,wBAAsB,2BAA2B,CAC/C,UAAU,EAAE,SAAS,aAAa,EAAE,EACpC,OAAO,GAAE,uBAA4B,GACpC,OAAO,CAAC,qBAAqB,EAAE,CAAC,CAoClC;AA8ED,MAAM,MAAM,sBAAsB,GAAG;IACnC,EAAE,EAAE,aAAa,CAAC;IAClB,MAAM,EAAE,oBAAoB,CAAC;CAC9B,CAAC;AAEF,MAAM,MAAM,0BAA0B,GAAG;IAAE,EAAE,EAAE,IAAI,CAAA;CAAE,GACnD,CAAC,mBAAmB,GAAG;IACvB,UAAU,EAAE,SAAS,MAAM,EAAE,CAAC;IAC9B,sBAAsB,EAAE,SAAS,MAAM,EAAE,CAAC;CAC3C,CAAC,CAAC;AAEH;wEACwE;AACxE,wBAAgB,gCAAgC,CAC9C,OAAO,EAAE,SAAS,sBAAsB,EAAE,EAC1C,OAAO,GAAE;IACP,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACf,GACL,0BAA0B,CAwG5B;AAED;gFACgF;AAChF,wBAAgB,2BAA2B,CACzC,EAAE,EAAE,aAAa,EACjB,QAAQ,EAAE,oBAAoB,GAC7B;IAAE,EAAE,EAAE,IAAI,CAAA;CAAE,GAAG,mBAAmB,CAyEpC;AAED,wBAAgB,4BAA4B,CAC1C,EAAE,EAAE,aAAa,EACjB,QAAQ,EAAE,oBAAoB,GAC7B,OAAO,CAOT;AAED;;yEAEyE;AACzE,wBAAgB,qCAAqC,CACnD,EAAE,EAAE,aAAa,EACjB,QAAQ,EAAE,oBAAoB,GAC7B,OAAO,CAMT;AAED;oFACoF;AACpF,wBAAsB,yBAAyB,CAC7C,EAAE,EAAE,aAAa,EACjB,QAAQ,EAAE,oBAAoB,EAC9B,OAAO,GAAE;IAAE,cAAc,CAAC,EAAE,MAAM,CAAA;CAAO,GACxC,OAAO,CAAC,mBAAmB,CAAC,CA6B9B;AA0BD,MAAM,MAAM,mBAAmB,GAAG;IAChC,EAAE,EAAE,aAAa,CAAC;IAClB,MAAM,EAAE,6BAA6B,CAAC;CACvC,CAAC;AAEF,MAAM,MAAM,oBAAoB,GAAG;IACjC,EAAE,EAAE,aAAa,CAAC;IAClB,WAAW,EAAE,6BAA6B,CAAC;IAC3C,MAAM,EAAE,mBAAmB,CAAC;CAC7B,CAAC;AAEF;uDACuD;AACvD,wBAAsB,sBAAsB,CAC1C,OAAO,EAAE,SAAS,mBAAmB,EAAE,EACvC,OAAO,GAAE;IACP,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACf,GACL,OAAO,CAAC,oBAAoB,EAAE,CAAC,CAyBjC;AAED;;uEAEuE;AACvE,wBAAgB,0BAA0B,CACxC,EAAE,EAAE,aAAa,EACjB,QAAQ,EAAE,oBAAoB,GAC7B,OAAO,CAaT;AAED;kFACkF;AAClF,wBAAsB,2BAA2B,CAC/C,EAAE,EAAE,aAAa,EACjB,OAAO,GAAE;IAAE,cAAc,CAAC,EAAE,MAAM,CAAC;IAAC,cAAc,CAAC,EAAE,MAAM,CAAA;CAAO,GACjE,OAAO,CAAC,yBAAyB,CAAC,CAqDpC"}