spawnfile 0.1.13 → 0.1.17

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);
+    }
+}

package/dist/deployment/organizationHandoffAuthorityFsClient.d.ts

@@ -0,0 +1,17 @@
+import { type ChildProcess } from "node:child_process";
+export interface OrganizationHandoffAuthorityFsClientOptions {
+    readonly cwd: string;
+    readonly dev: number;
+    readonly ino: number;
+    readonly parentPid?: number;
+    readonly uid?: number;
+    readonly workerPath?: string;
+    readonly testOnChildStarted?: (child: ChildProcess) => void;
+}
+export interface OrganizationHandoffAuthorityFsClient {
+    create(name: string, content: string): Promise<boolean>;
+    dispose(): Promise<void>;
+    read(name: string): Promise<string | null>;
+    write(name: string, content: string): Promise<void>;
+}
+export declare const initializeOrganizationHandoffAuthorityFsClient: (options: OrganizationHandoffAuthorityFsClientOptions) => Promise<OrganizationHandoffAuthorityFsClient>;

package/dist/deployment/organizationHandoffAuthorityFsClient.js

@@ -0,0 +1,187 @@
+import { fork } from "node:child_process";
+import { createRequire } from "node:module";
+import { fileURLToPath } from "node:url";
+import { createOrganizationHandoffAuthorityError, parseOrganizationHandoffAuthorityFailureDetail, PUBLICATION_BUDGET_MS } from "./organizationHandoffAuthorityFsBudget.js";
+const VERSION = "spawnfile.organization-handoff-fs-worker.v1";
+const MAX_BYTES = 32_768;
+/**
+ * The client deadline must exceed the worker's own convergence budget, or the
+ * client times out first and replaces a diagnosable worker failure with an
+ * opaque one. The margin covers fork/IPC latency and event-loop lag.
+ */
+const REQUEST_DEADLINE_MS = PUBLICATION_BUDGET_MS + 3_000;
+/**
+ * Startup deadline for the worker's ready handshake. This bounds a hung or
+ * broken helper; it is not a latency budget for process startup.
+ *
+ * Measured ready latency for eight concurrently forked source-mode helpers on
+ * a host at eleven times CPU oversubscription is 67-411ms, so this is margin
+ * rather than a fix — the observed startup failures were the helper's own
+ * liveness watchdog killing it, not this deadline expiring. It is sized above
+ * that measurement because CI forks far more helpers at once, and a caller
+ * initializes several clients in sequence, which bounds the worst case.
+ */
+const READY_DEADLINE_MS = 5_000;
+const DISPOSE_GRACE_MS = 1_000;
+const fail = (code, state) => {
+    throw createOrganizationHandoffAuthorityError({ code, ...(state === undefined ? {} : { state }) });
+};
+const bytes = (value) => Buffer.byteLength(value, "utf8");
+const name = (value) => typeof value === "string" && /^(?:[a-f0-9]{128}|[a-f0-9]{142})\.json$/u.test(value) ? value : fail("invalid_name");
+class Client {
+    #child;
+    #closed = false;
+    #next = 1;
+    #exited;
+    #pending = new Map();
+    constructor(child) {
+        this.#child = child;
+        let settleExit;
+        this.#exited = new Promise((resolve) => { settleExit = resolve; });
+        const settle = () => { this.rejectPending("worker_exited"); settleExit(); };
+        child.on("message", (raw) => this.message(raw));
+        child.on("error", () => this.rejectPending("worker_errored"));
+        child.on("disconnect", () => this.rejectPending("worker_disconnected"));
+        child.once("exit", settle);
+        if (child.exitCode !== null || child.signalCode !== null)
+            settle();
+        // `fork(..., { silent: true })` creates pipes. Consume them so a failing
+        // helper cannot block on a full pipe or accumulate stream listeners.
+        child.stdout?.resume();
+        child.stderr?.resume();
+    }
+    terminal() { return this.#child.exitCode !== null || this.#child.signalCode !== null; }
+    rejectPending(code) {
+        for (const pending of this.#pending.values())
+            pending.reject({ code });
+        this.#pending.clear();
+    }
+    message(raw) {
+        if (!raw || typeof raw !== "object")
+            return;
+        const value = raw;
+        if (value.version !== VERSION)
+            return;
+        if (value.ready === true)
+            return;
+        if (!Number.isSafeInteger(value.id) || typeof value.ok !== "boolean")
+            return;
+        const pending = this.#pending.get(value.id);
+        if (!pending)
+            return;
+        this.#pending.delete(value.id);
+        if (value.ok !== true || value.content !== undefined && typeof value.content !== "string"
+            || value.created !== undefined && typeof value.created !== "boolean") {
+            // The worker reports which budget or invariant failed. Preserve it: a
+            // bare failure here is what made this path undiagnosable from CI logs.
+            pending.reject(parseOrganizationHandoffAuthorityFailureDetail(value.failure) ?? { code: "worker_rejected" });
+            return;
+        }
+        pending.resolve(value);
+    }
+    request(op, file, content) {
+        if (this.#closed)
+            return Promise.reject(createOrganizationHandoffAuthorityError({ code: "client_closed" }));
+        if (content !== undefined && bytes(content) > MAX_BYTES)
+            return Promise.reject(createOrganizationHandoffAuthorityError({ code: "content_too_large", state: `bytes=${bytes(content)} limit=${MAX_BYTES}` }));
+        const id = this.#next++;
+        const packet = { version: VERSION, id, op, name: name(file), ...(content === undefined ? {} : { content }) };
+        const size = bytes(JSON.stringify(packet));
+        if (size > MAX_BYTES)
+            return Promise.reject(createOrganizationHandoffAuthorityError({ code: "packet_too_large", state: `bytes=${size} limit=${MAX_BYTES}` }));
+        return new Promise((resolve, reject) => {
+            const startedAt = performance.now();
+            const settle = (detail) => {
+                clearTimeout(timer);
+                reject(createOrganizationHandoffAuthorityError(detail ?? { code: "request_failed" }));
+            };
+            const timer = setTimeout(() => {
+                this.#pending.delete(id);
+                settle({ budget: "client_request", code: "client_request_deadline", elapsedMs: performance.now() - startedAt, limitMs: REQUEST_DEADLINE_MS, state: `op=${op}` });
+            }, REQUEST_DEADLINE_MS);
+            this.#pending.set(id, {
+                reject: (detail) => settle(detail === undefined ? detail : { ...detail, state: `${detail.state === undefined ? "" : `${detail.state} `}op=${op}` }),
+                resolve: (value) => { clearTimeout(timer); resolve(value); }
+            });
+            if (!this.#child.send(packet)) {
+                clearTimeout(timer);
+                this.#pending.delete(id);
+                reject(createOrganizationHandoffAuthorityError({ code: "worker_send_failed", state: `op=${op}` }));
+            }
+        });
+    }
+    async create(file, content) {
+        const result = await this.request("create", file, content);
+        return result.created === true;
+    }
+    async read(file) { return (await this.request("read", file)).content ?? null; }
+    async write(file, content) { await this.request("write", file, content); }
+    async dispose() {
+        if (this.#closed)
+            return;
+        this.#closed = true;
+        this.rejectPending("client_disposed");
+        if (!this.terminal()) {
+            if (this.#child.connected) {
+                try {
+                    this.#child.disconnect();
+                }
+                catch { /* already disconnected */ }
+            }
+            this.#child.kill();
+        }
+        let clear;
+        const graceful = await Promise.race([this.#exited.then(() => true), new Promise((resolve) => {
+                const timer = setTimeout(() => resolve(false), DISPOSE_GRACE_MS);
+                clear = () => clearTimeout(timer);
+            })]);
+        clear?.();
+        if (!graceful && !this.terminal())
+            this.#child.kill("SIGKILL");
+        await this.#exited;
+        this.#child.stdout?.destroy();
+        this.#child.stderr?.destroy();
+    }
+}
+export const initializeOrganizationHandoffAuthorityFsClient = async (options) => {
+    const source = import.meta.url.endsWith(".ts");
+    const workerPath = options.workerPath ?? fileURLToPath(new URL(source ? "./organizationHandoffAuthorityFsWorker.ts" : "./organizationHandoffAuthorityFsWorker.js", import.meta.url));
+    const tsWorker = workerPath.endsWith(".ts");
+    // The helper's cwd is the protected state directory, which is intentionally
+    // outside the repository. Resolve the source loader before changing cwd so
+    // source-mode tests do not depend on module lookup from that directory.
+    const tsxLoader = tsWorker ? createRequire(import.meta.url).resolve("tsx") : undefined;
+    const child = fork(workerPath, [], { cwd: options.cwd, env: { SPAWNFILE_AUTHORITY_FS_ANCHOR: JSON.stringify({ dev: options.dev, ino: options.ino, uid: options.uid, parent_pid: options.parentPid ?? process.pid }) }, silent: true, ...(tsxLoader === undefined ? {} : { execArgv: ["--import", tsxLoader] }) });
+    const client = new Client(child);
+    options.testOnChildStarted?.(child);
+    const startedAt = performance.now();
+    let detail = { code: "worker_ready_failed" };
+    try {
+        await new Promise((resolve, reject) => {
+            let timer;
+            const message = (raw) => { if (typeof raw === "object" && raw !== null && raw.ready === true)
+                doneResolve(); };
+            const exited = () => doneReject("worker_exited_before_ready");
+            const errored = () => doneReject("worker_errored_before_ready");
+            const clean = () => { clearTimeout(timer); child.off("message", message); child.off("exit", exited); child.off("error", errored); };
+            function doneResolve() { clean(); resolve(); }
+            function doneReject(code) {
+                clean();
+                detail = {
+                    budget: "worker_ready", code, elapsedMs: performance.now() - startedAt, limitMs: READY_DEADLINE_MS,
+                    state: `source=${String(tsWorker)} exit=${String(child.exitCode)} signal=${String(child.signalCode)}`
+                };
+                reject(createOrganizationHandoffAuthorityError(detail));
+            }
+            timer = setTimeout(() => doneReject("worker_ready_deadline"), READY_DEADLINE_MS);
+            child.on("message", message);
+            child.once("exit", exited);
+            child.once("error", errored);
+        });
+        return client;
+    }
+    catch {
+        await client.dispose();
+        throw createOrganizationHandoffAuthorityError(detail);
+    }
+};

package/dist/deployment/organizationHandoffAuthorityFsElection.d.ts

@@ -0,0 +1,21 @@
+import type { Stats } from "node:fs";
+export type AuthorityLeafStat = Stats;
+export type AuthorityLstat = (name: string) => Promise<AuthorityLeafStat>;
+export interface AuthorityLeafInspector {
+    /** Every leaf that could legitimately hold the other end of a two-link publication. */
+    aliasesOf(name: string): readonly string[];
+    /**
+     * Whether an observed publication race is one the caller may retry.
+     *
+     * `true` permits a retry, `false` fails closed, and `null` reports that the
+     * leaf is simply absent.
+     */
+    expectedElectionState(name: string): Promise<boolean | null>;
+    /** Stat a leaf, rejecting anything that is not an ordinary owned record. */
+    statFile(name: string): Promise<AuthorityLeafStat | null>;
+}
+export interface AuthorityLeafInspectorOptions {
+    readonly lstat?: AuthorityLstat;
+    readonly owner?: number;
+}
+export declare const createAuthorityLeafInspector: (options?: AuthorityLeafInspectorOptions) => AuthorityLeafInspector;

package/dist/deployment/organizationHandoffAuthorityFsElection.js

@@ -0,0 +1,57 @@
+import { lstat as nodeLstat } from "node:fs/promises";
+import { OrganizationHandoffAuthorityFailure } from "./organizationHandoffAuthorityFsBudget.js";
+/**
+ * Leaf inspection and link-election admission for the organization handoff
+ * filesystem authority.
+ *
+ * These three functions decide whether a failed read may be retried or must
+ * fail closed, which makes them the authority's most consequential branch and
+ * the reason they live behind an injectable `lstat`: the interesting states
+ * are mid-race interleavings that cannot be staged on a real filesystem.
+ */
+const MAX_BYTES = 32_768;
+const fail = (code) => { throw new OrganizationHandoffAuthorityFailure({ code }); };
+export const createAuthorityLeafInspector = (options = {}) => {
+    const lstat = options.lstat ?? nodeLstat;
+    const owner = options.owner;
+    const statFile = async (name) => {
+        const stat = await lstat(name).catch((error) => error.code === "ENOENT" ? null : fail("lstat_failed"));
+        if (stat === null)
+            return null;
+        if (!stat.isFile() || stat.isSymbolicLink() || stat.nlink > 2 || stat.size > MAX_BYTES || (stat.mode & 0o077) !== 0
+            || owner !== undefined && stat.uid !== owner)
+            return fail("leaf_not_ordinary");
+        return stat;
+    };
+    const aliasesOf = (name) => [
+        `${name}.pending`, `${name}.recovery`,
+        ...(name.endsWith(".pending") ? [name.slice(0, -".pending".length)] : []),
+        ...(name.endsWith(".recovery") ? [name.slice(0, -".recovery".length)] : [])
+    ];
+    const expectedElectionState = async (name) => {
+        let stat = await statFile(name);
+        if (stat === null)
+            return null;
+        if (stat.nlink === 1)
+            return true;
+        for (const alias of aliasesOf(name)) {
+            const counterpart = await lstat(alias).catch((error) => error.code === "ENOENT" ? null : fail("election_lstat_failed"));
+            if (counterpart?.isFile() && !counterpart.isSymbolicLink() && counterpart.nlink === 2 && counterpart.dev === stat.dev && counterpart.ino === stat.ino)
+                return true;
+        }
+        // The counterpart may have disappeared just before this check. Accept only
+        // the resulting ordinary single-link state, never an unknown hard link.
+        //
+        // The leaf itself may also have gone: the helper that won the election
+        // unlinks its staging sidecar immediately after linking the final record,
+        // so a peer that observed the sidecar at two links can find it absent one
+        // syscall later. That is an absence, not an unknown link. Reporting it as
+        // a rejected election turned a benign, converging race into a hard failure
+        // for the losing publisher.
+        stat = await statFile(name);
+        if (stat === null)
+            return null;
+        return stat.nlink === 1;
+    };
+    return { aliasesOf, expectedElectionState, statFile };
+};

package/dist/deployment/organizationHandoffAuthorityFsWorker.d.ts

@@ -0,0 +1 @@
+export {};