@zq-silk/yui 0.6.0 → 0.6.2

package/dist/release/releaseHandover.js

@@ -0,0 +1,475 @@
+/**
+ * Atomic Controller handover orchestration (Issue 02).
+ *
+ * The activator (`yui release activate`) drives one versioned handover:
+ *
+ *   preflight (read-only) -> handover lock -> fence the old Controller
+ *   -> start the candidate -> read back its identity -> switch the active
+ *   release pointer -> commit the old Controller -> wait for promotion
+ *   -> handover receipt.
+ *
+ * Every phase is recoverable from the durable fence + pointer state. A failed
+ * candidate rolls back to the old Controller; a stuck old Controller leaves
+ * the candidate read-only and reports dual-owner; a crashed activator resumes
+ * from the recorded phase.
+ */
+import { acquireHandoverLock, isOwnerLive, newHandoverId, readActiveReleasePointer, readCandidateDiscovery, readHandoverFence, readHandoverReceipt, readRuntimeIdentity, removeCandidateDiscovery, removeHandoverFence, writeActiveReleasePointer, writeHandoverFence, writeHandoverReceipt } from "./runtimeRelease.js";
+export const DEFAULT_CANDIDATE_READY_TIMEOUT_MS = 30_000;
+export const DEFAULT_PROMOTION_TIMEOUT_MS = 45_000;
+export const DEFAULT_POLL_INTERVAL_MS = 100;
+/**
+ * Optional confirmation debounce after the candidate latches `dualOwner:
+ * true`. Defaults to 0: the candidate's own exit grace
+ * (`DEFAULT_DUAL_OWNER_GRACE_MS` in `handoverCandidate.ts`, 30s) is the single
+ * authoritative old-owner exit window, and the activator trusts the candidate's
+ * latched signal. A non-zero value only adds a short extra confirmation before
+ * reporting dual-owner; it must never be used to re-litigate the exit grace.
+ */
+export const DEFAULT_DUAL_OWNER_GRACE_MS = 0;
+export async function activateRelease(ports, options) {
+    const { home, manifest } = options;
+    const releaseId = `${manifest.version}-${manifest.packageDigest}`;
+    const pollIntervalMs = options.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
+    const candidateReadyTimeoutMs = options.candidateReadyTimeoutMs
+        ?? DEFAULT_CANDIDATE_READY_TIMEOUT_MS;
+    const promotionTimeoutMs = options.promotionTimeoutMs ?? DEFAULT_PROMOTION_TIMEOUT_MS;
+    const dualOwnerGraceMs = options.dualOwnerGraceMs ?? DEFAULT_DUAL_OWNER_GRACE_MS;
+    const active = readActiveReleasePointer(home);
+    // An in-flight handover (durable fence) always takes precedence over the
+    // already-active shortcut: the pointer may name this release while a
+    // crashed activation left the old Controller live or the candidate
+    // unpromoted. Recovery must run first.
+    if (active !== null && active.releaseId === releaseId && readHandoverFence(home) === null) {
+        return { outcome: "already-active", releaseId };
+    }
+    // 1) Read-only storage compatibility preflight. A failure leaves the old
+    // Controller and pointer untouched.
+    try {
+        ports.runPreflight(options.releaseDir, home);
+    }
+    catch (error) {
+        return {
+            outcome: "aborted",
+            phase: "preflight",
+            message: `Storage compatibility preflight failed: ${messageOf(error)}`,
+            action: "The current Controller and active release pointer are unchanged.",
+            recoverable: true
+        };
+    }
+    const lock = acquireHandoverLock(home);
+    try {
+        return await activateLocked(ports, {
+            home,
+            releaseDir: options.releaseDir,
+            manifest,
+            releaseId,
+            active,
+            pollIntervalMs,
+            candidateReadyTimeoutMs,
+            promotionTimeoutMs,
+            dualOwnerGraceMs
+        });
+    }
+    finally {
+        lock.release();
+    }
+}
+async function activateLocked(ports, locked) {
+    const { home, manifest, releaseDir } = locked;
+    const { releaseId, active } = locked;
+    // 2) Crash recovery: a durable fence records the exact phase a previous
+    // activator reached. Resume or roll back deterministically.
+    const recovery = await recoverInterruptedHandover(ports, home, locked);
+    if (recovery !== null)
+        return recovery;
+    // 3) Capture the old Controller identity. When no Controller is running,
+    // activation only needs the pointer switch plus a fresh start.
+    const old = await readOldController(ports, home);
+    if (old === null) {
+        return await activateWithoutOldController(ports, home, manifest, releaseDir, releaseId, active);
+    }
+    // 4) Begin the handover: the old Controller fences mutations and records
+    // the durable fence.
+    const handoverId = newHandoverId();
+    let beginResult;
+    try {
+        beginResult = await ports.call(home, "controller.begin-handover", {
+            handoverId,
+            fromReleaseId: active?.releaseId ?? null,
+            toReleaseId: releaseId
+        });
+    }
+    catch (error) {
+        return {
+            outcome: "aborted",
+            phase: "begin-handover",
+            message: `Old Controller rejected the handover: ${messageOf(error)}`,
+            action: "The old Controller is still serving; inspect it and retry.",
+            recoverable: true
+        };
+    }
+    const fence = readHandoverFence(home);
+    if (fence === null || fence.handoverId !== handoverId) {
+        return {
+            outcome: "aborted",
+            phase: "begin-handover",
+            message: "Old Controller did not record the handover fence.",
+            action: "The old Controller is still serving; inspect it and retry.",
+            recoverable: true
+        };
+    }
+    void beginResult;
+    // 5) Start the candidate and wait for its identity read-back.
+    ports.spawnCandidate(home, releaseDir, handoverId);
+    const candidateReady = await waitForCandidateReady(ports, home, manifest, locked.candidateReadyTimeoutMs, locked.pollIntervalMs);
+    if (candidateReady === null) {
+        await rollbackHandover(ports, home, fence, "candidate did not become ready");
+        return {
+            outcome: "aborted",
+            phase: "candidate-ready",
+            message: "The new Controller candidate did not become ready in time.",
+            action: "The old Controller has resumed accepting mutations; retry the activation.",
+            recoverable: true
+        };
+    }
+    // 6) Switch the active release pointer. This is the atomic commit point:
+    // after it succeeds, the stable launcher and new Sessions resolve the new
+    // release.
+    const pointer = Object.freeze({
+        schemaVersion: 1,
+        releaseId,
+        version: manifest.version,
+        buildId: manifest.buildId,
+        packageDigest: manifest.packageDigest,
+        activatedAt: ports.now().toISOString()
+    });
+    writeActiveReleasePointer(home, pointer);
+    // 7) Commit the old Controller: it closes its socket and exits.
+    try {
+        await ports.call(home, "controller.commit-handover", { handoverId });
+    }
+    catch (error) {
+        // The commit RPC may fail because the old Controller exited after
+        // responding. The promotion wait below resolves the true state.
+        if (!isConnectionError(error))
+            throw error;
+    }
+    // 8) Wait for the candidate to promote itself (old owner gone + pointer
+    // switched). A stuck old owner leaves the candidate read-only.
+    const promotion = await waitForPromotion(ports, home, fence, locked.promotionTimeoutMs, locked.pollIntervalMs, locked.dualOwnerGraceMs);
+    if (promotion === "promoted") {
+        return { outcome: "activated", releaseId, handoverId, oldPid: old.pid };
+    }
+    if (promotion === "dual-owner") {
+        return {
+            outcome: "dual-owner",
+            releaseId,
+            handoverId,
+            message: "The old Controller did not exit after the handover commit; "
+                + "the candidate is read-only and no Controller is writing.",
+            action: "Stop the old Controller with a fenced `controller stop` "
+                + `(PID ${old.pid}); the candidate will then promote itself.`
+        };
+    }
+    // Promotion timed out without a clear dual-owner signal. The receipt and
+    // fence record the exact state for manual recovery.
+    return {
+        outcome: "aborted",
+        phase: "promotion",
+        message: "The candidate did not promote within the timeout.",
+        action: "Inspect the handover fence and receipt; the old Controller may "
+            + "still be running or the candidate may have exited.",
+        recoverable: false
+    };
+}
+async function activateWithoutOldController(ports, home, manifest, releaseDir, releaseId, active) {
+    const handoverId = newHandoverId();
+    const pointer = Object.freeze({
+        schemaVersion: 1,
+        releaseId,
+        version: manifest.version,
+        buildId: manifest.buildId,
+        packageDigest: manifest.packageDigest,
+        activatedAt: ports.now().toISOString()
+    });
+    writeActiveReleasePointer(home, pointer);
+    try {
+        await ports.startControllerFromRelease(home, releaseDir);
+    }
+    catch (error) {
+        // Restore the previous pointer so the launcher keeps resolving the old
+        // release.
+        if (active !== null)
+            writeActiveReleasePointer(home, active);
+        return {
+            outcome: "aborted",
+            phase: "start-controller",
+            message: `The new Controller did not start: ${messageOf(error)}`,
+            action: "The active release pointer was restored; the old release is unchanged.",
+            recoverable: true
+        };
+    }
+    writeHandoverReceipt(home, Object.freeze({
+        schemaVersion: 1,
+        handoverId,
+        outcome: "completed",
+        old: null,
+        candidate: null,
+        previousReleaseId: active?.releaseId ?? null,
+        activatedReleaseId: releaseId,
+        startedAt: ports.now().toISOString(),
+        completedAt: ports.now().toISOString()
+    }));
+    return { outcome: "activated", releaseId, handoverId };
+}
+async function readOldController(ports, home) {
+    try {
+        const identity = await ports.call(home, "controller.identity", {});
+        if (typeof identity !== "object"
+            || identity === null
+            || typeof identity.pid !== "number") {
+            return null;
+        }
+        const record = identity;
+        if (record.releaseDrifted === true) {
+            throw new Error("The old Controller's release has drifted from its installed manifest; "
+                + "refusing to hand over. Reinstall or restore the active release before activating.");
+        }
+        const startIdentity = typeof record.processStartIdentity === "string"
+            ? record.processStartIdentity
+            : undefined;
+        if (startIdentity === undefined)
+            return null;
+        return Object.freeze({
+            pid: record.pid,
+            processStartIdentity: startIdentity,
+            buildId: typeof record.buildId === "string" ? record.buildId : "unknown",
+            version: typeof record.version === "string" ? record.version : "unknown"
+        });
+    }
+    catch (error) {
+        if (isControllerNotRunning(error))
+            return null;
+        throw error;
+    }
+}
+async function waitForCandidateReady(ports, home, manifest, timeoutMs, pollIntervalMs) {
+    const deadline = Date.now() + timeoutMs;
+    for (;;) {
+        const candidate = readCandidateDiscovery(home);
+        if (candidate !== null) {
+            const identity = readRuntimeIdentity(home);
+            if (identity !== null
+                && identity.mode === "candidate"
+                && identity.buildId === manifest.buildId
+                && identity.pid === candidate.pid) {
+                return Object.freeze({
+                    pid: candidate.pid,
+                    processStartIdentity: candidate.processStartIdentity,
+                    buildId: identity.buildId,
+                    version: identity.version
+                });
+            }
+        }
+        if (Date.now() >= deadline)
+            return null;
+        await ports.sleep(pollIntervalMs);
+    }
+}
+async function waitForPromotion(ports, home, fence, timeoutMs, pollIntervalMs, dualOwnerGraceMs) {
+    const deadline = Date.now() + timeoutMs;
+    let dualOwnerSince = null;
+    for (;;) {
+        const receipt = readHandoverReceipt(home);
+        if (receipt !== null
+            && receipt.handoverId === fence.handoverId
+            && receipt.outcome === "completed") {
+            return "promoted";
+        }
+        const identity = readRuntimeIdentity(home);
+        if (identity !== null && identity.mode === "candidate" && identity.dualOwner) {
+            if (dualOwnerSince === null)
+                dualOwnerSince = Date.now();
+            // Give the old owner a short grace window to exit before declaring
+            // dual-owner.
+            if (Date.now() - dualOwnerSince > dualOwnerGraceMs)
+                return "dual-owner";
+        }
+        else {
+            dualOwnerSince = null;
+        }
+        if (Date.now() >= deadline)
+            return "timeout";
+        await ports.sleep(pollIntervalMs);
+    }
+}
+async function rollbackHandover(ports, home, fence, reason) {
+    const candidate = readCandidateDiscovery(home);
+    if (candidate !== null) {
+        try {
+            ports.killOwnedProcess({
+                pid: candidate.pid,
+                processStartIdentity: candidate.processStartIdentity,
+                buildId: "candidate",
+                version: "candidate"
+            });
+        }
+        catch {
+            // A dead candidate is the desired end state; ignore kill failures.
+        }
+        removeCandidateDiscovery(home);
+    }
+    try {
+        await ports.call(home, "controller.rollback-handover", {
+            handoverId: fence.handoverId
+        });
+    }
+    catch {
+        // The old Controller may have exited; the fence phase records the truth.
+    }
+    writeHandoverFence(home, Object.freeze({
+        ...fence,
+        phase: "rolled-back",
+        updatedAt: new Date().toISOString()
+    }));
+    writeHandoverReceipt(home, Object.freeze({
+        schemaVersion: 1,
+        handoverId: fence.handoverId,
+        outcome: "rolled-back",
+        old: fence.old,
+        candidate: fence.candidate,
+        previousReleaseId: fence.fromReleaseId,
+        activatedReleaseId: fence.toReleaseId,
+        startedAt: fence.createdAt,
+        completedAt: new Date().toISOString()
+    }));
+    void reason;
+}
+async function recoverInterruptedHandover(ports, home, locked) {
+    const fence = readHandoverFence(home);
+    if (fence === null)
+        return null;
+    if (fence.phase === "rolled-back") {
+        removeHandoverFence(home);
+        return null;
+    }
+    const candidateLive = readCandidateDiscovery(home) !== null
+        && (() => {
+            const discovery = readCandidateDiscovery(home);
+            return discovery !== null && isOwnerLive({
+                pid: discovery.pid,
+                processStartIdentity: discovery.processStartIdentity,
+                buildId: "candidate",
+                version: "candidate"
+            });
+        })();
+    const oldLive = isOwnerLive(fence.old);
+    if (fence.phase === "committed") {
+        if (candidateLive) {
+            const promotion = await waitForPromotion(ports, home, fence, locked.promotionTimeoutMs, locked.pollIntervalMs, locked.dualOwnerGraceMs);
+            if (promotion === "promoted") {
+                return {
+                    outcome: "activated",
+                    releaseId: fence.toReleaseId,
+                    handoverId: fence.handoverId,
+                    oldPid: fence.old.pid
+                };
+            }
+            if (promotion === "dual-owner") {
+                return {
+                    outcome: "dual-owner",
+                    releaseId: fence.toReleaseId,
+                    handoverId: fence.handoverId,
+                    message: "The old Controller did not exit after the handover commit; "
+                        + "the candidate is read-only and no Controller is writing.",
+                    action: "Stop the old Controller with a fenced `controller stop`; "
+                        + "the candidate will then promote itself."
+                };
+            }
+        }
+        if (!oldLive) {
+            // Both old and candidate are gone; the pointer may already be switched.
+            removeHandoverFence(home);
+            return null;
+        }
+        return {
+            outcome: "dual-owner",
+            releaseId: fence.toReleaseId,
+            handoverId: fence.handoverId,
+            message: "The handover was committed but the candidate is gone and the "
+                + "old Controller is still live.",
+            action: "Stop the old Controller with a fenced `controller stop`, then "
+                + "retry the activation."
+        };
+    }
+    // phase "fenced" or "candidate-ready"
+    if (candidateLive) {
+        // Resume the in-flight handover: wait for readiness, switch pointer,
+        // commit, promote. The simplest safe resume is to re-drive from the
+        // candidate-ready wait.
+        const candidateReady = await waitForCandidateReady(ports, home, locked.manifest, locked.candidateReadyTimeoutMs, locked.pollIntervalMs);
+        if (candidateReady === null) {
+            await rollbackHandover(ports, home, fence, "candidate did not become ready");
+            return null;
+        }
+        const pointer = Object.freeze({
+            schemaVersion: 1,
+            releaseId: locked.releaseId,
+            version: locked.manifest.version,
+            buildId: locked.manifest.buildId,
+            packageDigest: locked.manifest.packageDigest,
+            activatedAt: ports.now().toISOString()
+        });
+        writeActiveReleasePointer(home, pointer);
+        try {
+            await ports.call(home, "controller.commit-handover", {
+                handoverId: fence.handoverId
+            });
+        }
+        catch (error) {
+            if (!isConnectionError(error))
+                throw error;
+        }
+        const promotion = await waitForPromotion(ports, home, fence, locked.promotionTimeoutMs, locked.pollIntervalMs, locked.dualOwnerGraceMs);
+        if (promotion === "promoted") {
+            return {
+                outcome: "activated",
+                releaseId: locked.releaseId,
+                handoverId: fence.handoverId,
+                oldPid: fence.old.pid
+            };
+        }
+        return null;
+    }
+    // Candidate is dead: roll back the old Controller and start fresh.
+    if (oldLive) {
+        try {
+            await ports.call(home, "controller.rollback-handover", {
+                handoverId: fence.handoverId
+            });
+        }
+        catch {
+            // Old Controller may be unresponsive; the fence phase records the truth.
+        }
+    }
+    removeHandoverFence(home);
+    return null;
+}
+function isControllerNotRunning(error) {
+    return typeof error === "object"
+        && error !== null
+        && "code" in error
+        && error.code === "CONTROLLER_NOT_RUNNING";
+}
+function isConnectionError(error) {
+    if (typeof error !== "object" || error === null || !("code" in error))
+        return false;
+    const code = error.code;
+    return code === "CONTROLLER_NOT_RUNNING"
+        || code === "ECONNREFUSED"
+        || code === "ECONNRESET"
+        || code === "EPIPE";
+}
+function messageOf(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/dist/release/releaseIdempotencyStore.js

@@ -0,0 +1,165 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { writeTextFileAtomically } from "../storage/durableFile.js";
+/**
+ * Durable adapter-level idempotency for the real release-workflow adapter.
+ *
+ * The engine already prevents duplicate effects within a workflow run (it
+ * never re-submits a step it has marked terminal, and re-attempts after a
+ * crash are serialized by a cross-process lock). The residual window is the
+ * crash AFTER the external effect landed but BEFORE the engine persisted the
+ * step result: a resumed process re-invokes `executeStep` under the same
+ * idempotency key, and without this store the shell command runs a second
+ * time. This store makes `executeStep` idempotent across processes: a
+ * recorded successful effect is replayed instead of re-executed.
+ *
+ * Only SUCCEEDED effects are recorded. A failed effect produced no confirmed
+ * landing (and the engine retries failed steps), so caching it would strand
+ * recoverable failures; a timeout is re-queried authoritatively by the
+ * engine and re-executed only when the effect is proven absent.
+ *
+ * Layout
+ * ------
+ * Each key is its own record file under `release-idempotency/`, named by the
+ * percent-encoded key. There is deliberately no whole-map cache and no
+ * whole-file rewrite: two processes that record different keys touch
+ * different files, so neither can clobber the other, and a process that
+ * crashes mid-write leaves at most one stale temp file (the atomic
+ * temp+rename in `writeTextFileAtomically` never exposes a partial record).
+ * The temp filename carries the writer pid and a UUID, so two processes
+ * never share a temp pathname.
+ *
+ * Every record carries `schemaVersion: 1`. A record whose version is unknown,
+ * whose key does not match the file it was read from, or whose effect is not
+ * a succeeded effect fails closed (the read throws) rather than being
+ * silently skipped: at-most-once cannot be proven from a corrupt record.
+ *
+ * A persistence failure is propagated, never swallowed. The adapter converts
+ * an unpersisted success into an ambiguous/fail-closed outcome; reporting
+ * success for an effect whose dedup record did not land would let a crash
+ * re-run the effect.
+ *
+ * Unsupported layouts
+ * -------------------
+ * The per-key `schemaVersion: 1` layout is the only supported format. A
+ * legacy whole-map file (`release-idempotency.json`) from an unsupported
+ * older layout is never auto-migrated: it fails closed with a bounded
+ * diagnostic so the operator can inspect and clean it up deliberately.
+ */
+export const RELEASE_IDEMPOTENCY_SCHEMA_VERSION = 1;
+const DIRECTORY_NAME = "release-idempotency";
+const LEGACY_FILE_NAME = "release-idempotency.json";
+export function createFileReleaseIdempotencyStore(home, now = () => new Date()) {
+    const directory = join(home, DIRECTORY_NAME);
+    const legacyPath = join(home, LEGACY_FILE_NAME);
+    function recordPath(key) {
+        // encodeURIComponent is injective and leaves only Linux-filename-safe
+        // characters unescaped, so distinct keys never collide on disk.
+        return join(directory, `${encodeURIComponent(key)}.json`);
+    }
+    /**
+     * Fail closed when an unsupported legacy whole-map file is present.
+     * The per-key layout is the only supported format; a whole-map file
+     * from an unsupported older layout must not be silently trusted.
+     */
+    function rejectLegacyLayout() {
+        if (existsSync(legacyPath)) {
+            throw new Error(`unsupported legacy release idempotency layout: ${legacyPath} ` +
+                `(whole-map file). Remove it after inspecting its contents; ` +
+                `the per-key schemaVersion 1 layout is the only supported format.`);
+        }
+    }
+    return {
+        async load(key) {
+            try {
+                rejectLegacyLayout();
+                const path = recordPath(key);
+                if (!existsSync(path))
+                    return undefined;
+                const parsed = JSON.parse(readFileSync(path, "utf8"));
+                return requireRecord(parsed, key).effect;
+            }
+            catch (error) {
+                throw new Error(`release idempotency store cannot be read: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        },
+        async recordSuccess(key, effect) {
+            if (effect.outcome !== "succeeded") {
+                throw new Error(`release idempotency store only records succeeded effects: ${effect.outcome}`);
+            }
+            try {
+                rejectLegacyLayout();
+                const record = Object.freeze({
+                    schemaVersion: RELEASE_IDEMPOTENCY_SCHEMA_VERSION,
+                    key,
+                    effect,
+                    recordedAt: now().toISOString()
+                });
+                writeTextFileAtomically(recordPath(key), JSON.stringify(record, null, 2));
+            }
+            catch (error) {
+                // Propagate: the adapter must not turn an unpersisted success into a
+                // successful return.
+                throw new Error(`release idempotency store cannot be written: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        }
+    };
+}
+/** An in-memory store for tests; two instances over the same map simulate processes. */
+export function createInMemoryReleaseIdempotencyStore(backing) {
+    const records = backing ?? new Map();
+    return {
+        async load(key) {
+            return records.get(key)?.effect;
+        },
+        async recordSuccess(key, effect) {
+            if (effect.outcome !== "succeeded") {
+                throw new Error(`release idempotency store only records succeeded effects: ${effect.outcome}`);
+            }
+            records.set(key, {
+                schemaVersion: RELEASE_IDEMPOTENCY_SCHEMA_VERSION,
+                key,
+                effect,
+                recordedAt: new Date(0).toISOString()
+            });
+        }
+    };
+}
+/**
+ * Strictly validate one per-key record. Fails closed on any drift: an unknown
+ * schema version, a key that does not name the file it was read from, or a
+ * non-succeeded effect.
+ */
+function requireRecord(value, expectedKey) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        throw new Error("idempotency record is not an object");
+    }
+    const record = value;
+    if (record.schemaVersion !== RELEASE_IDEMPOTENCY_SCHEMA_VERSION) {
+        throw new Error(`idempotency record schemaVersion is ${String(record.schemaVersion)}, ` +
+            `expected ${RELEASE_IDEMPOTENCY_SCHEMA_VERSION}`);
+    }
+    if (typeof record.key !== "string" || record.key !== expectedKey) {
+        throw new Error(`idempotency record key ${String(record.key)} does not match ${expectedKey}`);
+    }
+    const effect = requireSucceededEffect(record.effect);
+    if (typeof record.recordedAt !== "string" || record.recordedAt.length === 0) {
+        throw new Error("idempotency record recordedAt is invalid");
+    }
+    return Object.freeze({
+        schemaVersion: RELEASE_IDEMPOTENCY_SCHEMA_VERSION,
+        key: record.key,
+        effect,
+        recordedAt: record.recordedAt
+    });
+}
+function requireSucceededEffect(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        throw new Error("idempotency record effect is not an object");
+    }
+    const effect = value;
+    if (effect.outcome !== "succeeded") {
+        throw new Error(`idempotency record effect outcome is ${String(effect.outcome)}, expected succeeded`);
+    }
+    return value;
+}