spawnfile 0.1.14 → 0.1.18

package/dist/deployment/lifecycleCompletionStore.js

@@ -5,8 +5,8 @@ import path from "node:path";
 import { LIFECYCLE_RECORD_MAX_BYTES } from "./lifecycleCompletionContracts.js";
 import { failLifecycleStore, resolveLifecycleCompletionDirectory } from "./lifecycleCompletionPaths.js";
 import { openLifecycleAuthorityRoot, requireLifecycleRootAuthority, revalidateHeldLifecycleRoot, revalidateLifecycleRootAuthority, syncLifecycleDirectory, validateLifecycleRoot } from "./lifecycleCompletionRoot.js";
-import { matchesSettledLifecyclePublication, readSettledLifecycleRecord } from "./lifecycleCompletionPublication.js";
-export { admissionPath, evidencePath, failLifecycleStore, heartbeatPath, lifecycleRecordName, planPath, recoveryPath, resolveLifecycleCompletionDirectory, resolveLifecycleCompletionPath } from "./lifecycleCompletionPaths.js";
+import { matchesSettledLifecyclePublication, readSettledLifecycleRecord, settleLifecyclePublicationUntil } from "./lifecycleCompletionPublication.js";
+export { admissionPath, evidencePath, failLifecycleStore, heartbeatPath, lifecycleRecordName, planPath, recoveryPath, upCleanupPath, upReservationPath, upStartPath, resolveLifecycleCompletionDirectory, resolveLifecycleCompletionPath } from "./lifecycleCompletionPaths.js";
 export { existingLifecycleRoot, lifecycleRoot, syncLifecycleDirectory } from "./lifecycleCompletionRoot.js";
 const OWNER = process.getuid?.() ?? -1;
 let testHook = null;
@@ -133,17 +133,17 @@ export const publishLifecycleRecord = async (directory, file, content, existing
             }
             return false;
         }
-        for (let attempt = 0; attempt < 16; attempt += 1) {
+        await settleLifecyclePublicationUntil(async () => {
             const exact = await readLifecycleRecord(final, [1, 2]);
             if (exact !== content)
                 failLifecycleStore("publication changed");
             if ((await lstat(final).catch(() => null))?.nlink === 1) {
                 await revalidateHeldLifecycleRoot(authority, rootHandle);
-                return linked;
+                return true;
             }
-            await new Promise((resolve) => setImmediate(resolve));
-        }
-        return failLifecycleStore("publication did not settle");
+            return false;
+        });
+        return linked;
     }
     finally {
         await rootHandle.close().catch(() => undefined);

package/dist/deployment/lifecycleUpRecords.d.ts

@@ -0,0 +1,11 @@
+import { type LifecycleInvocation, type LifecycleOwnerCapability, type LifecycleUpReservation, type LifecycleUpStart } from "./lifecycleCompletionContracts.js";
+export { LIFECYCLE_UP_EXTRA_LABELS, type LifecycleUpReservation, type LifecycleUpStart, } from "./lifecycleCompletionContracts.js";
+export declare const findLifecycleUpReservation: (raw: LifecycleInvocation) => Promise<LifecycleUpReservation | null>;
+export declare const recordLifecycleUpReservation: (raw: LifecycleInvocation, reservation: Omit<LifecycleUpReservation, "invocation" | "version">, capability: LifecycleOwnerCapability) => Promise<void>;
+export interface LifecycleUpStartState {
+    readonly attempt: number;
+    readonly start: LifecycleUpStart;
+}
+export declare const findLifecycleUpStart: (raw: LifecycleInvocation) => Promise<LifecycleUpStartState | null>;
+export declare const recordLifecycleUpStart: (raw: LifecycleInvocation, start: Omit<LifecycleUpStart, "attempt" | "invocation" | "version">, capability: LifecycleOwnerCapability) => Promise<void>;
+export declare const recordLifecycleUpCleanup: (raw: LifecycleInvocation, state: LifecycleUpStartState, capability: LifecycleOwnerCapability) => Promise<void>;

package/dist/deployment/lifecycleUpRecords.js

@@ -0,0 +1,127 @@
+import path from "node:path";
+import { readSettledLifecycleRecord } from "./lifecycleCompletionPublication.js";
+import { canonicalLifecycleJson, lifecycleUpCleanupSchema, lifecycleUpReservationSchema, lifecycleUpStartSchema, LIFECYCLE_UP_CLEANUP_VERSION, LIFECYCLE_UP_RESERVATION_VERSION, LIFECYCLE_UP_START_VERSION, } from "./lifecycleCompletionContracts.js";
+import { assertLifecycleOwnerCapability } from "./lifecycleCompletionOwner.js";
+import { parseLifecycleAdmission, parseLifecycleInvocation } from "./lifecycleCompletionParsing.js";
+import { admissionPath, failLifecycleStore, lifecycleRecordName, lifecycleRoot, publishLifecycleRecord, readLifecycleRecord, recoveryPath, upCleanupPath, upReservationPath, upStartPath, } from "./lifecycleCompletionStore.js";
+export { LIFECYCLE_UP_EXTRA_LABELS, } from "./lifecycleCompletionContracts.js";
+const MAX_ATTEMPTS = 16;
+const canonical = canonicalLifecycleJson;
+const fail = failLifecycleStore;
+const exactAdmission = async (invocation) => {
+    const text = await readSettledLifecycleRecord(admissionPath(invocation.id), readLifecycleRecord);
+    if (text === null)
+        return fail("missing admission");
+    const admission = parseLifecycleAdmission(text);
+    if (canonical(admission.invocation) !== canonical(invocation))
+        fail("invocation id drift");
+    return admission;
+};
+const assertOwner = async (invocation, capability) => {
+    const recoveryText = await readSettledLifecycleRecord(recoveryPath(invocation.id), readLifecycleRecord);
+    const recovered = recoveryText ? parseLifecycleAdmission(recoveryText) : null;
+    assertLifecycleOwnerCapability(invocation, await exactAdmission(invocation), recovered, capability);
+};
+const parseRecord = (text, parse, invocation) => {
+    const value = (() => {
+        try {
+            return parse(JSON.parse(text));
+        }
+        catch {
+            return fail("invalid up lifecycle record");
+        }
+    })();
+    const record = value;
+    if (`${canonical(value)}\n` !== text || canonical(record.invocation) !== canonical(invocation)) {
+        fail("invocation id drift");
+    }
+    return value;
+};
+export const findLifecycleUpReservation = async (raw) => {
+    const invocation = parseLifecycleInvocation(raw);
+    if (invocation.operation !== "up")
+        fail("non-up reservation lookup");
+    await lifecycleRoot();
+    const text = await readSettledLifecycleRecord(upReservationPath(invocation.id), readLifecycleRecord);
+    return text === null ? null : parseRecord(text, (value) => lifecycleUpReservationSchema.parse(value), invocation);
+};
+export const recordLifecycleUpReservation = async (raw, reservation, capability) => {
+    const invocation = parseLifecycleInvocation(raw);
+    if (invocation.operation !== "up")
+        fail("non-up reservation record");
+    const directory = await lifecycleRoot();
+    await assertOwner(invocation, capability);
+    const value = lifecycleUpReservationSchema.parse({
+        ...reservation, invocation, version: LIFECYCLE_UP_RESERVATION_VERSION,
+    });
+    await publishLifecycleRecord(directory, lifecycleRecordName(invocation.id, "up-reservation"), `${canonical(value)}\n`);
+};
+const readStart = async (invocation, attempt) => {
+    const text = await readSettledLifecycleRecord(upStartPath(invocation.id, attempt), readLifecycleRecord);
+    return text === null ? null : parseRecord(text, (value) => lifecycleUpStartSchema.parse(value), invocation);
+};
+const readCleanup = async (invocation, attempt) => {
+    const text = await readSettledLifecycleRecord(upCleanupPath(invocation.id, attempt), readLifecycleRecord);
+    return text === null ? null : parseRecord(text, (value) => lifecycleUpCleanupSchema.parse(value), invocation);
+};
+const findUpAttempt = async (invocation) => {
+    for (let attempt = 0; attempt <= MAX_ATTEMPTS; attempt += 1) {
+        const start = await readStart(invocation, attempt);
+        if (start === null) {
+            if (await readCleanup(invocation, attempt))
+                fail("up cleanup without start");
+            return { active: null, next: attempt };
+        }
+        if (start.attempt !== attempt)
+            fail("up start attempt drift");
+        const cleanup = await readCleanup(invocation, attempt);
+        if (cleanup === null)
+            return { active: { attempt, start }, next: attempt };
+        if (cleanup.attempt !== attempt || cleanup.container_id !== start.container_id)
+            fail("up cleanup drift");
+    }
+    return fail("up retry limit reached");
+};
+export const findLifecycleUpStart = async (raw) => {
+    const invocation = parseLifecycleInvocation(raw);
+    if (invocation.operation !== "up")
+        fail("non-up start lookup");
+    await lifecycleRoot();
+    return (await findUpAttempt(invocation)).active;
+};
+const sameAuthority = (reservation, start) => reservation.container_name === start.container_name
+    && canonical(reservation.label_authority) === canonical(start.label_authority);
+export const recordLifecycleUpStart = async (raw, start, capability) => {
+    const invocation = parseLifecycleInvocation(raw);
+    if (invocation.operation !== "up")
+        fail("non-up start record");
+    const directory = await lifecycleRoot();
+    await assertOwner(invocation, capability);
+    const reservation = await findLifecycleUpReservation(invocation);
+    if (!reservation)
+        return fail("missing up reservation");
+    const current = await findUpAttempt(invocation);
+    const value = lifecycleUpStartSchema.parse({ ...start, attempt: current.next, invocation, version: LIFECYCLE_UP_START_VERSION });
+    if (!sameAuthority(reservation, value))
+        fail("up start authority drift");
+    if (current.active) {
+        if (canonical(current.active.start) !== canonical(value))
+            fail("active up start changed");
+        return;
+    }
+    await publishLifecycleRecord(directory, path.basename(upStartPath(invocation.id, current.next)), `${canonical(value)}\n`);
+};
+export const recordLifecycleUpCleanup = async (raw, state, capability) => {
+    const invocation = parseLifecycleInvocation(raw);
+    const directory = await lifecycleRoot();
+    await assertOwner(invocation, capability);
+    const active = await findUpAttempt(invocation);
+    if (!active.active || active.active.attempt !== state.attempt
+        || canonical(active.active.start) !== canonical(state.start))
+        fail("up cleanup without active start");
+    const value = lifecycleUpCleanupSchema.parse({
+        attempt: state.attempt, container_id: state.start.container_id, invocation,
+        version: LIFECYCLE_UP_CLEANUP_VERSION,
+    });
+    await publishLifecycleRecord(directory, path.basename(upCleanupPath(invocation.id, state.attempt)), `${canonical(value)}\n`);
+};

package/dist/deployment/native/AGENTS.md

@@ -0,0 +1,11 @@
+# Native deployment helpers
+
+This folder contains bounded, package-owned native helpers for deployment
+syscalls Node does not expose. Helpers accept validated single-component names,
+emit one bounded JSON result, and fail closed.
+
+`artifacts/` contains the verified Linux x64 and arm64 package inputs so the
+normal Node build stays offline and Docker-free. `copyArtifacts.ts` verifies
+and copies them into `dist`. Only the explicit maintainer `build:native` path
+may replace them using the digest-pinned compiler image; CI rebuilds and
+syscall-tests both architectures before publication.

package/dist/deployment/native/rename-noreplace-arm64.provenance.json

@@ -0,0 +1 @@
+{"version":"spawnfile.rename-noreplace-build.v1","architecture":"arm64","binary_sha256":"sha256:fb1f0d24fe7dfc4db18e972b9d60d839bf11ed82c78bf89cf6eca3f21502529f","builder_image":"gcc:14.2.0@sha256:b99b86a28812b1e6453a231a947dc43d76fe192788a12f344a9b568bf9f5d24c","compiler":"gcc:14.2.0","source_sha256":"sha256:64458e923931f7ca4df9ac2d19fd0361093e985ab3fbd8bf422ceb31a60b0e79","target":"linux/arm64"}

package/dist/deployment/native/rename-noreplace-x64.provenance.json

@@ -0,0 +1 @@
+{"version":"spawnfile.rename-noreplace-build.v1","architecture":"x64","binary_sha256":"sha256:5c80678b8b1325085eeb56fd8125dbad9a8e00e7a9871994702d95eabd80ab26","builder_image":"gcc:14.2.0@sha256:b99b86a28812b1e6453a231a947dc43d76fe192788a12f344a9b568bf9f5d24c","compiler":"gcc:14.2.0","source_sha256":"sha256:64458e923931f7ca4df9ac2d19fd0361093e985ab3fbd8bf422ceb31a60b0e79","target":"linux/amd64"}

package/dist/deployment/noReplaceActivation.d.ts

@@ -0,0 +1,17 @@
+type HelperResult = {
+    stderr: string;
+    stdout: string;
+};
+type HelperRun = (file: string, args: string[], options: {
+    encoding: "utf8";
+    maxBuffer: number;
+    timeout: number;
+    windowsHide: true;
+}) => Promise<HelperResult>;
+export declare const activateNoReplaceWith: (temporaryPath: string, destinationPath: string, runtime: {
+    arch: string;
+    platform: string;
+    run: HelperRun;
+}) => Promise<void>;
+export declare const activateNoReplace: (temporaryPath: string, destinationPath: string) => Promise<void>;
+export {};

package/dist/deployment/noReplaceActivation.js

@@ -0,0 +1,50 @@
+import { execFile as execFileCallback } from "node:child_process";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { promisify } from "node:util";
+const execFile = promisify(execFileCallback);
+const MAX_OUTPUT = 4096;
+const TIMEOUT_MS = 5_000;
+const component = (value) => value.length > 0 && value !== "." && value !== ".." && !value.includes(path.sep);
+export const activateNoReplaceWith = async (temporaryPath, destinationPath, runtime) => {
+    if (runtime.platform !== "linux" || (runtime.arch !== "x64" && runtime.arch !== "arm64"))
+        throw new Error("Workspace resource atomic no-replace activation is unsupported on this platform");
+    const parent = path.dirname(temporaryPath);
+    if (parent !== path.dirname(destinationPath) || !path.isAbsolute(parent))
+        throw new Error("Workspace resource activation paths must share one canonical parent");
+    const source = path.basename(temporaryPath);
+    const destination = path.basename(destinationPath);
+    if (!component(source) || !component(destination))
+        throw new Error("Workspace resource activation names must be single components");
+    const helper = fileURLToPath(new URL(`./native/rename-noreplace-${runtime.arch}`, import.meta.url));
+    try {
+        const result = await runtime.run(helper, [parent, source, destination], { encoding: "utf8", maxBuffer: MAX_OUTPUT, timeout: TIMEOUT_MS, windowsHide: true });
+        if (result.stderr !== "" || result.stdout !== '{"ok":true}\n')
+            throw new Error("Workspace resource atomic helper returned malformed output");
+    }
+    catch (error) {
+        const failure = error;
+        if (failure.killed || failure.code === "ETIMEDOUT")
+            throw new Error("Workspace resource atomic helper timed out");
+        if (failure.code === "ENOENT")
+            throw new Error("Workspace resource atomic helper is missing");
+        if (typeof failure.stdout === "string" && failure.stdout.length <= MAX_OUTPUT) {
+            try {
+                const parsed = JSON.parse(failure.stdout);
+                if (parsed.ok === false && ["EEXIST", "EXDEV", "ENOSYS", "EOPNOTSUPP"].includes(parsed.error ?? "")) {
+                    const mapped = new Error(`Workspace resource atomic activation failed: ${parsed.error}`);
+                    mapped.code = parsed.error;
+                    throw mapped;
+                }
+            }
+            catch (parsedError) {
+                if (parsedError.code)
+                    throw parsedError;
+            }
+        }
+        if (failure.message.includes("malformed output"))
+            throw failure;
+        throw new Error("Workspace resource atomic helper failed closed");
+    }
+};
+export const activateNoReplace = async (temporaryPath, destinationPath) => await activateNoReplaceWith(temporaryPath, destinationPath, { arch: process.arch, platform: process.platform, run: execFile });

package/dist/deployment/organizationHandoffAuthorityFsBudget.d.ts

@@ -0,0 +1,110 @@
+/**
+ * Diagnostics and convergence budget for the organization handoff filesystem
+ * authority.
+ *
+ * This module is deliberately dependency-free: the authority worker is forked
+ * as a standalone process whose only other imports are `node:fs`, and that
+ * minimal surface is part of its threat model.
+ *
+ * ## Why a wall-clock budget
+ *
+ * Concurrent publishers converge by waiting for a peer to finish writing and
+ * linking a record. That is a wall-clock event — it completes when the peer is
+ * scheduled and its I/O lands. An attempt-counted budget answers a different
+ * question ("have I looked N times?") whose relationship to elapsed time is set
+ * by machine load, so the effective patience of the loop drifts with the very
+ * contention it exists to absorb. The budget below is therefore primarily a
+ * deadline; the attempt cap is only a secondary guard against a pathological
+ * hot loop if a timer or clock misbehaves.
+ *
+ * ## Why one budget per request
+ *
+ * The convergence loops nest (write -> settle -> read-staging -> read). Giving
+ * each loop its own budget bounds no level usefully: each individual loop is
+ * too impatient while their product is effectively unbounded. A single budget
+ * threaded through one request bounds the thing that actually has a deadline —
+ * the request — and is what the client's own request deadline must exceed.
+ */
+/** Uniform public failure message. Detail is appended, never substituted. */
+export declare const ORGANIZATION_HANDOFF_AUTHORITY_ERROR = "Organization handoff authority failed";
+/** Wall-clock convergence budget for one authority request. */
+export declare const PUBLICATION_BUDGET_MS = 2000;
+/**
+ * Secondary bound only. It is far above the attempt count any healthy
+ * convergence needs; it exists so a broken timer cannot spin forever.
+ */
+export declare const PUBLICATION_MAX_ATTEMPTS = 4096;
+/**
+ * Fraction of the budget spent waiting for a peer before a proven, incomplete
+ * staging prefix is retired instead. Patience must expire strictly before the
+ * budget does, or the recovery path could never run.
+ */
+export declare const PUBLICATION_PATIENCE_FRACTION = 0.5;
+/**
+ * Structural diagnostics for a failed authority request.
+ *
+ * `state` describes the *shape* of the contending filesystem state — sidecar
+ * presence, link counts, sizes. It never carries record bytes, leaf names, or
+ * paths: this is the secret-publication path, and the diagnostic must not
+ * become a disclosure channel.
+ */
+export interface OrganizationHandoffAuthorityFailureDetail {
+    readonly attempts?: number;
+    readonly budget?: string;
+    readonly code: string;
+    readonly elapsedMs?: number;
+    readonly limitMs?: number;
+    readonly state?: string;
+}
+/** Render a detail as the suffix appended to the uniform failure message. */
+export declare const describeOrganizationHandoffAuthorityFailure: (detail: OrganizationHandoffAuthorityFailureDetail) => string;
+/** An authority failure that carries its structural diagnostics. */
+export declare class OrganizationHandoffAuthorityFailure extends Error {
+    readonly detail: OrganizationHandoffAuthorityFailureDetail;
+    constructor(detail: OrganizationHandoffAuthorityFailureDetail);
+}
+/**
+ * Build an error for the uniform message plus optional detail. Callers that
+ * have no diagnostics still produce the exact historical message, so existing
+ * substring expectations and the store's opaque public boundary hold.
+ */
+export declare const createOrganizationHandoffAuthorityError: (detail?: OrganizationHandoffAuthorityFailureDetail) => Error;
+/** Narrow an unknown IPC payload to a bounded, well-formed detail. */
+export declare const parseOrganizationHandoffAuthorityFailureDetail: (raw: unknown) => OrganizationHandoffAuthorityFailureDetail | undefined;
+/** Reduce an unknown thrown value to a bounded detail suitable for IPC. */
+export declare const toOrganizationHandoffAuthorityFailureDetail: (error: unknown) => OrganizationHandoffAuthorityFailureDetail;
+export interface OrganizationHandoffAuthorityBudgetOptions {
+    readonly limitMs?: number;
+    readonly maxAttempts?: number;
+    readonly now?: () => number;
+    readonly sleep?: (ms: number) => Promise<void>;
+}
+/**
+ * One request's convergence budget: a wall-clock deadline, a secondary attempt
+ * cap, and adaptive backoff with jitter.
+ *
+ * The jitter matters as much as the deadline. Symmetric publishers waking on a
+ * fixed 2ms timer retry in lockstep, so every peer re-observes the same
+ * unfinished state and burns the budget in phase. Randomised, growing waits
+ * break that convoy so peers observe each other's progress instead.
+ */
+export declare class OrganizationHandoffAuthorityBudget {
+    #private;
+    constructor(options?: OrganizationHandoffAuthorityBudgetOptions);
+    get attempts(): number;
+    get elapsedMs(): number;
+    get limitMs(): number;
+    /** True once no further waiting is permitted for this request. */
+    exhausted(): boolean;
+    /**
+     * True while a peer still deserves the benefit of the doubt. Once false, a
+     * proven incomplete staging prefix may be retired — the caller has already
+     * linked, or is about to link, the immutable final record that prevents that
+     * prefix from winning a later election.
+     */
+    patient(): boolean;
+    /** Snapshot the budget for a failure detail. */
+    snapshot(code: string, budget: string, state?: string): OrganizationHandoffAuthorityFailureDetail;
+    /** Back off before the next observation, never past the deadline. */
+    wait(): Promise<void>;
+}

package/dist/deployment/organizationHandoffAuthorityFsBudget.js

@@ -0,0 +1,156 @@
+/**
+ * Diagnostics and convergence budget for the organization handoff filesystem
+ * authority.
+ *
+ * This module is deliberately dependency-free: the authority worker is forked
+ * as a standalone process whose only other imports are `node:fs`, and that
+ * minimal surface is part of its threat model.
+ *
+ * ## Why a wall-clock budget
+ *
+ * Concurrent publishers converge by waiting for a peer to finish writing and
+ * linking a record. That is a wall-clock event — it completes when the peer is
+ * scheduled and its I/O lands. An attempt-counted budget answers a different
+ * question ("have I looked N times?") whose relationship to elapsed time is set
+ * by machine load, so the effective patience of the loop drifts with the very
+ * contention it exists to absorb. The budget below is therefore primarily a
+ * deadline; the attempt cap is only a secondary guard against a pathological
+ * hot loop if a timer or clock misbehaves.
+ *
+ * ## Why one budget per request
+ *
+ * The convergence loops nest (write -> settle -> read-staging -> read). Giving
+ * each loop its own budget bounds no level usefully: each individual loop is
+ * too impatient while their product is effectively unbounded. A single budget
+ * threaded through one request bounds the thing that actually has a deadline —
+ * the request — and is what the client's own request deadline must exceed.
+ */
+/** Uniform public failure message. Detail is appended, never substituted. */
+export const ORGANIZATION_HANDOFF_AUTHORITY_ERROR = "Organization handoff authority failed";
+/** Wall-clock convergence budget for one authority request. */
+export const PUBLICATION_BUDGET_MS = 2_000;
+/**
+ * Secondary bound only. It is far above the attempt count any healthy
+ * convergence needs; it exists so a broken timer cannot spin forever.
+ */
+export const PUBLICATION_MAX_ATTEMPTS = 4_096;
+/**
+ * Fraction of the budget spent waiting for a peer before a proven, incomplete
+ * staging prefix is retired instead. Patience must expire strictly before the
+ * budget does, or the recovery path could never run.
+ */
+export const PUBLICATION_PATIENCE_FRACTION = 0.5;
+const BASE_WAIT_MS = 1;
+const MAX_WAIT_MS = 25;
+const MAX_CODE_LENGTH = 64;
+const MAX_STATE_LENGTH = 240;
+const clamp = (value, limit) => value.length > limit ? `${value.slice(0, limit - 1)}~` : value;
+const isSafeNumber = (value) => typeof value === "number" && Number.isFinite(value);
+/** Render a detail as the suffix appended to the uniform failure message. */
+export const describeOrganizationHandoffAuthorityFailure = (detail) => {
+    const fields = [];
+    if (detail.budget !== undefined)
+        fields.push(`budget=${detail.budget}`);
+    if (detail.attempts !== undefined)
+        fields.push(`attempts=${detail.attempts}`);
+    if (detail.elapsedMs !== undefined)
+        fields.push(`elapsed=${Math.round(detail.elapsedMs)}ms`);
+    if (detail.limitMs !== undefined)
+        fields.push(`limit=${Math.round(detail.limitMs)}ms`);
+    if (detail.state !== undefined)
+        fields.push(`state=${detail.state}`);
+    return fields.length === 0 ? detail.code : `${detail.code} (${fields.join(" ")})`;
+};
+/** An authority failure that carries its structural diagnostics. */
+export class OrganizationHandoffAuthorityFailure extends Error {
+    detail;
+    constructor(detail) {
+        super(`${ORGANIZATION_HANDOFF_AUTHORITY_ERROR}: ${describeOrganizationHandoffAuthorityFailure(detail)}`);
+        this.name = "OrganizationHandoffAuthorityFailure";
+        this.detail = detail;
+    }
+}
+/**
+ * Build an error for the uniform message plus optional detail. Callers that
+ * have no diagnostics still produce the exact historical message, so existing
+ * substring expectations and the store's opaque public boundary hold.
+ */
+export const createOrganizationHandoffAuthorityError = (detail) => detail === undefined
+    ? new Error(ORGANIZATION_HANDOFF_AUTHORITY_ERROR)
+    : new OrganizationHandoffAuthorityFailure(detail);
+/** Narrow an unknown IPC payload to a bounded, well-formed detail. */
+export const parseOrganizationHandoffAuthorityFailureDetail = (raw) => {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw))
+        return undefined;
+    const value = raw;
+    if (typeof value.code !== "string" || value.code.length === 0)
+        return undefined;
+    return {
+        ...(isSafeNumber(value.attempts) ? { attempts: value.attempts } : {}),
+        ...(typeof value.budget === "string" ? { budget: clamp(value.budget, MAX_CODE_LENGTH) } : {}),
+        code: clamp(value.code, MAX_CODE_LENGTH),
+        ...(isSafeNumber(value.elapsedMs) ? { elapsedMs: value.elapsedMs } : {}),
+        ...(isSafeNumber(value.limitMs) ? { limitMs: value.limitMs } : {}),
+        ...(typeof value.state === "string" ? { state: clamp(value.state, MAX_STATE_LENGTH) } : {})
+    };
+};
+/** Reduce an unknown thrown value to a bounded detail suitable for IPC. */
+export const toOrganizationHandoffAuthorityFailureDetail = (error) => error instanceof OrganizationHandoffAuthorityFailure
+    ? error.detail
+    : { code: "unexpected_error", state: clamp(error instanceof Error ? `${error.name}` : typeof error, MAX_STATE_LENGTH) };
+/**
+ * One request's convergence budget: a wall-clock deadline, a secondary attempt
+ * cap, and adaptive backoff with jitter.
+ *
+ * The jitter matters as much as the deadline. Symmetric publishers waking on a
+ * fixed 2ms timer retry in lockstep, so every peer re-observes the same
+ * unfinished state and burns the budget in phase. Randomised, growing waits
+ * break that convoy so peers observe each other's progress instead.
+ */
+export class OrganizationHandoffAuthorityBudget {
+    #attempts = 0;
+    #limitMs;
+    #maxAttempts;
+    #now;
+    #sleep;
+    #startedAt;
+    constructor(options = {}) {
+        this.#limitMs = options.limitMs ?? PUBLICATION_BUDGET_MS;
+        this.#maxAttempts = options.maxAttempts ?? PUBLICATION_MAX_ATTEMPTS;
+        this.#now = options.now ?? (() => performance.now());
+        this.#sleep = options.sleep ?? (async (ms) => new Promise((resolve) => { setTimeout(resolve, ms); }));
+        this.#startedAt = this.#now();
+    }
+    get attempts() { return this.#attempts; }
+    get elapsedMs() { return this.#now() - this.#startedAt; }
+    get limitMs() { return this.#limitMs; }
+    /** True once no further waiting is permitted for this request. */
+    exhausted() {
+        return this.elapsedMs >= this.#limitMs || this.#attempts >= this.#maxAttempts;
+    }
+    /**
+     * True while a peer still deserves the benefit of the doubt. Once false, a
+     * proven incomplete staging prefix may be retired — the caller has already
+     * linked, or is about to link, the immutable final record that prevents that
+     * prefix from winning a later election.
+     */
+    patient() {
+        return !this.exhausted() && this.elapsedMs < this.#limitMs * PUBLICATION_PATIENCE_FRACTION;
+    }
+    /** Snapshot the budget for a failure detail. */
+    snapshot(code, budget, state) {
+        return {
+            attempts: this.#attempts, budget, code,
+            elapsedMs: this.elapsedMs, limitMs: this.#limitMs,
+            ...(state === undefined ? {} : { state: clamp(state, MAX_STATE_LENGTH) })
+        };
+    }
+    /** Back off before the next observation, never past the deadline. */
+    async wait() {
+        this.#attempts += 1;
+        const growth = Math.min(MAX_WAIT_MS, BASE_WAIT_MS * 2 ** Math.min(this.#attempts - 1, 10));
+        const remaining = Math.max(0, this.#limitMs - this.elapsedMs);
+        const delay = Math.max(0, Math.min(remaining, growth * (0.5 + Math.random() * 0.5)));
+        await this.#sleep(delay);
+    }
+}