spawnfile 0.1.14 → 0.1.18

package/dist/deployment/organizationHandoffAuthorityFsWorker.js

@@ -1,28 +1,47 @@
 import { constants } from "node:fs";
 import { link, lstat, open, unlink } from "node:fs/promises";
+import { OrganizationHandoffAuthorityBudget, OrganizationHandoffAuthorityFailure, toOrganizationHandoffAuthorityFailureDetail } from "./organizationHandoffAuthorityFsBudget.js";
+import { createAuthorityLeafInspector } from "./organizationHandoffAuthorityFsElection.js";
 const VERSION = "spawnfile.organization-handoff-fs-worker.v1";
 const MAX_BYTES = 32_768;
 // Store keys encode either a 64-character pending key or a 71-character
 // `opaque_` handoff handle. No other leaf namespace is reachable.
 const NAME = /^(?:[a-f0-9]{128}|[a-f0-9]{142})\.json$/u;
 const owner = typeof process.getuid === "function" ? process.getuid() : undefined;
-const fail = () => { throw new Error("Organization handoff authority failed"); };
+const fail = (code, state) => {
+    throw new OrganizationHandoffAuthorityFailure({ code, ...(state === undefined ? {} : { state }) });
+};
+/** Fail with the budget's attempt/wall-clock accounting and the contending shape. */
+const failBudget = (budget, code, loop, state) => {
+    throw new OrganizationHandoffAuthorityFailure(budget.snapshot(code, loop, state));
+};
+/**
+ * Re-raise a race failure that the election check refused to retry, recording
+ * the verdict. Without it a fail-closed admission decision is indistinguishable
+ * from the underlying race in a log.
+ */
+const failElection = (error, election, loop) => {
+    const detail = toOrganizationHandoffAuthorityFailureDetail(error);
+    throw new OrganizationHandoffAuthorityFailure({
+        ...detail,
+        state: `${detail.state === undefined ? "" : `${detail.state} `}loop=${loop} election=${String(election)}`
+    });
+};
 const bytes = (value) => Buffer.byteLength(value, "utf8");
-const waitForPublisher = async () => new Promise((resolve) => setTimeout(resolve, 2));
-const validName = (value) => typeof value === "string" && NAME.test(value) ? value : fail();
+const validName = (value) => typeof value === "string" && NAME.test(value) ? value : fail("invalid_name");
 const validRequest = (raw) => {
     if (!raw || typeof raw !== "object" || Array.isArray(raw) || Object.getPrototypeOf(raw) !== Object.prototype)
-        return fail();
+        return fail("malformed_request");
     const value = raw;
     if (value.version !== VERSION || !Number.isSafeInteger(value.id) || typeof value.op !== "string" || (value.op !== "read" && value.op !== "write" && value.op !== "create"))
-        return fail();
+        return fail("unsupported_request");
     const content = value.content;
     const keys = Object.keys(value).sort();
     const expected = value.op === "read" ? ["id", "name", "op", "version"] : ["content", "id", "name", "op", "version"];
     if (keys.length !== expected.length || keys.some((key, index) => key !== expected[index]))
-        return fail();
+        return fail("unexpected_request_keys");
     if (content !== undefined && (typeof content !== "string" || bytes(content) > MAX_BYTES))
-        return fail();
+        return fail("oversized_content");
     return { version: VERSION, id: value.id, op: value.op, name: validName(value.name), ...(content === undefined ? {} : { content }) };
 };
 const send = (value) => {
@@ -31,31 +50,34 @@ const send = (value) => {
         process.exit(1);
     process.send(JSON.parse(serialized));
 };
-const statFile = async (name) => {
-    const stat = await lstat(name).catch((error) => error.code === "ENOENT" ? null : fail());
-    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();
-    return stat;
+const { aliasesOf, expectedElectionState, statFile } = createAuthorityLeafInspector(owner === undefined ? {} : { owner });
+const publicationSidecars = (name) => [`${name}.pending`, `${name}.recovery`];
+/**
+ * Structural description of the contending state for a diagnostic. Reports
+ * only shape — presence, link count, size, mode. Never record bytes, leaf
+ * names, or paths: this is the secret-publication path.
+ */
+const describeContention = async (name) => {
+    const roles = [["final", name], ["pending", `${name}.pending`], ["recovery", `${name}.recovery`]];
+    const parts = await Promise.all(roles.map(async ([role, leaf]) => {
+        const stat = await lstat(leaf).catch(() => null);
+        return stat === null
+            ? `${role}:absent`
+            : `${role}:nlink=${stat.nlink},size=${stat.size},mode=${(stat.mode & 0o777).toString(8)}`;
+    }));
+    return parts.join(" ");
 };
 const read = async (name) => {
     let before = await statFile(name);
     if (before === null)
         return null;
     if (before.nlink === 2) {
-        const aliases = [
-            `${name}.pending`, `${name}.recovery`,
-            ...(name.endsWith(".pending") ? [name.slice(0, -".pending".length)] : []),
-            ...(name.endsWith(".recovery") ? [name.slice(0, -".recovery".length)] : [])
-        ];
         let match;
-        for (const alias of aliases) {
-            const stat = await lstat(alias).catch((error) => error.code === "ENOENT" ? null : fail());
+        for (const alias of aliasesOf(name)) {
+            const stat = await lstat(alias).catch((error) => error.code === "ENOENT" ? null : fail("alias_lstat_failed"));
             if (stat && stat.isFile() && !stat.isSymbolicLink() && stat.nlink === 2 && stat.dev === before.dev && stat.ino === before.ino) {
                 if (match)
-                    return fail();
+                    return fail("ambiguous_link_alias");
                 match = alias;
             }
         }
@@ -67,7 +89,7 @@ const read = async (name) => {
             if (current === null)
                 return null;
             if (current.nlink !== 1)
-                return fail();
+                return fail("unresolved_second_link");
             before = current;
         }
         // Reading the canonical record completes a crashed publisher. An
@@ -75,14 +97,14 @@ const read = async (name) => {
         // observes the linked content and lets its normal publish path converge.
         if (match && !name.endsWith(".pending") && !name.endsWith(".recovery")) {
             await unlink(match).catch((error) => { if (error.code !== "ENOENT")
-                fail(); });
+                fail("alias_unlink_failed"); });
             await sync();
             before = await statFile(name);
             if (before === null)
-                return fail();
+                return fail("record_vanished_after_join");
         }
     }
-    const handle = await open(name, constants.O_RDONLY | constants.O_NOFOLLOW).catch((error) => error.code === "ENOENT" ? null : fail());
+    const handle = await open(name, constants.O_RDONLY | constants.O_NOFOLLOW).catch((error) => error.code === "ENOENT" ? null : fail("open_failed"));
     if (handle === null)
         return null;
     try {
@@ -92,93 +114,185 @@ const read = async (name) => {
         // sole permitted link-count transition; inode, device, size, and all
         // increases remain fail-closed.
         if (!stat.isFile() || stat.nlink < 1 || stat.nlink > before.nlink || stat.dev !== before.dev || stat.ino !== before.ino || stat.size !== before.size)
-            return fail();
+            return fail("record_drifted_while_open");
         return await handle.readFile({ encoding: "utf8" });
     }
-    catch {
-        return fail();
+    catch (error) {
+        if (error instanceof OrganizationHandoffAuthorityFailure)
+            throw error;
+        return fail("read_failed");
     }
     finally {
         await handle.close().catch(() => undefined);
     }
 };
-const sync = async () => { const handle = await open(".", constants.O_RDONLY | constants.O_DIRECTORY).catch(fail); try {
+const sync = async () => { const handle = await open(".", constants.O_RDONLY | constants.O_DIRECTORY).catch(() => fail("directory_open_failed")); try {
     await handle.sync();
 }
 finally {
     await handle.close().catch(() => undefined);
 } };
-const expectedElectionState = async (name) => {
-    let stat = await statFile(name);
-    if (stat === null)
-        return null;
-    if (stat.nlink === 1)
-        return true;
-    const aliases = [
-        `${name}.pending`, `${name}.recovery`,
-        ...(name.endsWith(".pending") ? [name.slice(0, -".pending".length)] : []),
-        ...(name.endsWith(".recovery") ? [name.slice(0, -".recovery".length)] : [])
-    ];
-    for (const alias of aliases) {
-        const counterpart = await lstat(alias).catch((error) => error.code === "ENOENT" ? null : fail());
-        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.
-    stat = await statFile(name);
-    return stat?.nlink === 1;
-};
-const readDuringPublication = async (name, attempt = 0) => {
+const readDuringPublication = async (name, budget) => {
     try {
         return await read(name);
     }
-    catch {
+    catch (error) {
         // Re-validate the leaf before retrying. This permits only a checked,
         // ordinary one/two-link publication race; symlinks, mode/owner drift,
         // extra links, and other malformed states still fail immediately.
         const election = await expectedElectionState(name);
         if (election === null)
             return null;
-        if (attempt >= 32 || election !== true)
-            return fail();
-        await waitForPublisher();
-        return readDuringPublication(name, attempt + 1);
+        if (election !== true)
+            return failElection(error, election, "read");
+        if (budget.exhausted())
+            return failBudget(budget, "read_budget_exhausted", "read", await describeContention(name));
+        await budget.wait();
+        return readDuringPublication(name, budget);
     }
 };
-const write = async (name, content, attempt = 0) => {
-    if (attempt > 32)
-        return fail();
+/**
+ * A sidecar may change between lstat and fd inspection while another worker
+ * publishes. Re-prove an exact immutable final first, then retry the sidecar
+ * so cleanup still relies on a stable checked sidecar rather than an inference.
+ */
+const readStaging = async (staging, final, content, budget) => {
+    try {
+        const observed = await read(staging);
+        if (observed === null)
+            return "absent";
+        if (observed === content)
+            return "exact";
+        return content.startsWith(observed) ? "expected-prefix" : fail("staging_content_unrelated");
+    }
+    catch (error) {
+        if (error instanceof OrganizationHandoffAuthorityFailure && error.detail.budget !== undefined)
+            throw error;
+        const published = await readDuringPublication(final, budget);
+        if (published !== null) {
+            if (published !== content)
+                return fail("published_content_mismatch");
+            if (budget.exhausted())
+                return failBudget(budget, "staging_budget_exhausted", "staging", await describeContention(final));
+            await budget.wait();
+            return readStaging(staging, final, content, budget);
+        }
+        const election = await expectedElectionState(staging);
+        if (election === null)
+            return "absent";
+        if (election !== true)
+            return failElection(error, election, "staging");
+        if (budget.exhausted())
+            return failBudget(budget, "staging_budget_exhausted", "staging", await describeContention(final));
+        await budget.wait();
+        return readStaging(staging, final, content, budget);
+    }
+};
+/**
+ * A successful link election can race a peer which had already created the
+ * other staging leaf.  The final immutable record is authoritative, but the
+ * stale leaf must not survive a completed join: it would otherwise be
+ * mistaken for an in-progress publication after restart. Delete exact bytes
+ * immediately. An incomplete expected prefix may still belong to a publisher,
+ * so wait for it first; once the budget's patience expires, removing that
+ * proven prefix is safe because the final record already prevents it from
+ * winning a later link election.
+ */
+const settlePublished = async (name, content, budget) => {
+    if (budget.exhausted())
+        return failBudget(budget, "settle_budget_exhausted", "settle", await describeContention(name));
+    if (await readDuringPublication(name, budget) !== content)
+        return fail("settle_record_mismatch");
+    let incomplete = false;
+    for (const sidecar of publicationSidecars(name)) {
+        const observed = await readStaging(sidecar, name, content, budget);
+        if (observed === "absent")
+            continue;
+        if (observed === "expected-prefix" && budget.patient()) {
+            incomplete = true;
+            continue;
+        }
+        await unlink(sidecar).catch((error) => { if (error.code !== "ENOENT")
+            fail("sidecar_unlink_failed"); });
+        await sync();
+    }
+    if (incomplete) {
+        await budget.wait();
+        return settlePublished(name, content, budget);
+    }
+    if (await readDuringPublication(name, budget) !== content)
+        return fail("settle_record_mismatch");
+    const remaining = await Promise.all(publicationSidecars(name).map(async (sidecar) => readStaging(sidecar, name, content, budget)));
+    if (remaining.every((sidecar) => sidecar === "absent"))
+        return;
+    if (budget.exhausted())
+        return failBudget(budget, "settle_budget_exhausted", "settle", await describeContention(name));
+    await budget.wait();
+    return settlePublished(name, content, budget);
+};
+const readPublished = async (name, budget) => {
+    const content = await readDuringPublication(name, budget);
+    if (content === null)
+        return null;
+    await settlePublished(name, content, budget);
+    return content;
+};
+const write = async (name, content, budget) => {
+    if (budget.exhausted())
+        return failBudget(budget, "write_budget_exhausted", "write", await describeContention(name));
     const joinOrRetry = async () => {
-        const published = await readDuringPublication(name);
+        const published = await readDuringPublication(name, budget);
         if (published !== null) {
             if (published !== content)
-                return fail();
+                return fail("join_content_mismatch");
+            await settlePublished(name, content, budget);
             return false;
         }
-        await waitForPublisher();
-        return write(name, content, attempt + 1);
+        await budget.wait();
+        return write(name, content, budget);
     };
-    const existing = await readDuringPublication(name);
+    const reproveStaging = async () => {
+        const published = await readDuringPublication(name, budget);
+        if (published === content) {
+            await settlePublished(name, content, budget);
+            return true;
+        }
+        if (published !== null)
+            return fail("reprove_content_mismatch");
+        await budget.wait();
+        return false;
+    };
+    const existing = await readDuringPublication(name, budget);
     if (existing !== null) {
         if (existing !== content)
-            fail();
+            fail("existing_content_mismatch");
+        await settlePublished(name, content, budget);
         return false;
     }
     const pending = `${name}.pending`;
     const recovery = `${name}.recovery`;
-    const incomplete = await readDuringPublication(pending);
-    if (incomplete !== null && incomplete !== content && !content.startsWith(incomplete))
-        return fail();
-    if (incomplete !== null && incomplete !== content) {
-        const recovered = await readDuringPublication(recovery);
-        if (recovered !== null && recovered !== content)
-            return fail();
-        if (recovered === null) {
-            const handle = await open(recovery, constants.O_CREAT | constants.O_EXCL | constants.O_WRONLY | constants.O_NOFOLLOW, 0o600).catch((error) => error.code === "EEXIST" ? null : fail());
+    const incomplete = await readStaging(pending, name, content, budget);
+    if (incomplete === "expected-prefix") {
+        let recovered = await readStaging(recovery, name, content, budget);
+        if (recovered === "expected-prefix") {
+            if (budget.patient()) {
+                await budget.wait();
+                return write(name, content, budget);
+            }
+            // A crashed recovery publisher can leave the same bounded prefix. It
+            // cannot win after this writer links the immutable final record, so
+            // retire it only after the budget's patience expires and reconstruct it
+            // below.
+            await unlink(recovery).catch((error) => { if (error.code !== "ENOENT")
+                fail("recovery_unlink_failed"); });
+            await sync();
+            recovered = "absent";
+        }
+        if (recovered === "absent") {
+            const handle = await open(recovery, constants.O_CREAT | constants.O_EXCL | constants.O_WRONLY | constants.O_NOFOLLOW, 0o600).catch((error) => error.code === "EEXIST" ? null : fail("recovery_create_failed"));
             if (handle === null) {
-                await waitForPublisher();
-                return write(name, content, attempt + 1);
+                await budget.wait();
+                return write(name, content, budget);
             }
             try {
                 await handle.writeFile(content, "utf8");
@@ -187,11 +301,12 @@ const write = async (name, content, attempt = 0) => {
             finally {
                 await handle.close().catch(() => undefined);
             }
-            const staged = await readDuringPublication(recovery);
-            if (staged === null && await readDuringPublication(name) === content)
-                return false;
-            if (staged !== content)
-                return fail();
+            const staged = await readStaging(recovery, name, content, budget);
+            if (staged !== "exact") {
+                if (await reproveStaging())
+                    return false;
+                return write(name, content, budget);
+            }
             await sync();
         }
         const recoveredLinked = await link(recovery, name).then(() => true).catch((error) => {
@@ -199,23 +314,24 @@ const write = async (name, content, attempt = 0) => {
                 return false;
             if (error.code === "ENOENT")
                 return null;
-            return fail();
+            return fail("recovery_link_failed");
         });
         if (recoveredLinked !== true)
             return joinOrRetry();
         await sync();
         await unlink(recovery).catch((error) => { if (error.code !== "ENOENT")
-            fail(); });
+            fail("recovery_unlink_failed"); });
         await sync();
-        if (await readDuringPublication(name) !== content)
-            fail();
+        if (await readDuringPublication(name, budget) !== content)
+            fail("recovery_publish_mismatch");
+        await settlePublished(name, content, budget);
         return true;
     }
-    if (incomplete === null) {
-        const handle = await open(pending, constants.O_CREAT | constants.O_EXCL | constants.O_WRONLY | constants.O_NOFOLLOW, 0o600).catch((error) => error.code === "EEXIST" ? null : fail());
+    if (incomplete === "absent") {
+        const handle = await open(pending, constants.O_CREAT | constants.O_EXCL | constants.O_WRONLY | constants.O_NOFOLLOW, 0o600).catch((error) => error.code === "EEXIST" ? null : fail("pending_create_failed"));
         if (handle === null) {
-            await waitForPublisher();
-            return write(name, content, attempt + 1);
+            await budget.wait();
+            return write(name, content, budget);
         }
         try {
             await handle.writeFile(content, "utf8");
@@ -224,11 +340,12 @@ const write = async (name, content, attempt = 0) => {
         finally {
             await handle.close().catch(() => undefined);
         }
-        const staged = await readDuringPublication(pending);
-        if (staged === null && await readDuringPublication(name) === content)
-            return false;
-        if (staged !== content)
-            return fail();
+        const staged = await readStaging(pending, name, content, budget);
+        if (staged !== "exact") {
+            if (await reproveStaging())
+                return false;
+            return write(name, content, budget);
+        }
         await sync();
     }
     const linked = await link(pending, name).then(() => true).catch((error) => {
@@ -236,16 +353,17 @@ const write = async (name, content, attempt = 0) => {
             return false;
         if (error.code === "ENOENT")
             return null;
-        return fail();
+        return fail("pending_link_failed");
     });
     if (linked !== true)
         return joinOrRetry();
     await sync();
     await unlink(pending).catch((error) => { if (error.code !== "ENOENT")
-        fail(); });
+        fail("pending_unlink_failed"); });
     await sync();
-    if (await readDuringPublication(name) !== content)
-        fail();
+    if (await readDuringPublication(name, budget) !== content)
+        fail("pending_publish_mismatch");
+    await settlePublished(name, content, budget);
     return true;
 };
 let anchor;
@@ -253,13 +371,13 @@ let queue = Promise.resolve();
 const start = async () => {
     const raw = process.env.SPAWNFILE_AUTHORITY_FS_ANCHOR;
     if (!raw)
-        return fail();
+        return fail("missing_anchor");
     const expected = JSON.parse(raw);
     const stat = await lstat(".");
     if (!stat.isDirectory() || stat.isSymbolicLink() || stat.dev !== expected.dev || stat.ino !== expected.ino
         || (stat.mode & 0o077) !== 0 || owner !== undefined && stat.uid !== expected.uid
         || !Number.isSafeInteger(expected.parent_pid) || expected.parent_pid < 1 || process.ppid !== expected.parent_pid)
-        return fail();
+        return fail("anchor_mismatch");
     anchor = expected;
     send({ version: VERSION, ready: true });
 };
@@ -267,19 +385,47 @@ process.on("message", (raw) => {
     queue = queue.then(async () => {
         const request = validRequest(raw);
         if (!anchor)
-            return fail();
+            return fail("not_ready");
         const stat = await lstat(".");
         if (stat.dev !== anchor.dev || stat.ino !== anchor.ino || (stat.mode & 0o077) !== 0)
-            return fail();
+            return fail("anchor_drifted");
+        // One budget per request: the request is the thing with a deadline, and
+        // the client's own request deadline must exceed it.
+        const budget = new OrganizationHandoffAuthorityBudget();
         const result = request.op === "read"
-            ? { content: await read(request.name) }
-            : { created: request.content === undefined ? fail() : await write(request.name, request.content) };
+            ? { content: await readPublished(request.name, budget) }
+            : { created: request.content === undefined ? fail("missing_content") : await write(request.name, request.content, budget) };
         send({ version: VERSION, id: request.id, ok: true, ...(result.content === null ? {} : { content: result.content }), ...(request.op === "create" ? { created: result.created } : {}) });
-    }).catch(() => send({ version: VERSION, id: typeof raw === "object" && raw !== null && Number.isSafeInteger(raw.id) ? raw.id : 0, ok: false }));
+    }).catch((error) => send({
+        version: VERSION,
+        id: typeof raw === "object" && raw !== null && Number.isSafeInteger(raw.id) ? raw.id : 0,
+        ok: false,
+        failure: toOrganizationHandoffAuthorityFailureDetail(error)
+    }));
 });
 process.on("disconnect", () => process.exit(0));
+/**
+ * Expected parent pid read synchronously at module load, before any await.
+ *
+ * The watchdog below previously exited whenever `anchor` was still unset. That
+ * made a liveness net race the startup path: on a loaded host the interpreter
+ * and the anchor's `lstat` can take longer than one 100ms tick, and the helper
+ * killed itself before it could ever report ready. Deriving the pid from the
+ * environment removes the dependency on startup having finished, without
+ * weakening anything: `start` still validates the full anchor independently,
+ * and no request is served until it does.
+ */
+const watchedParentPid = (() => {
+    try {
+        const value = JSON.parse(process.env.SPAWNFILE_AUTHORITY_FS_ANCHOR ?? "{}");
+        return Number.isSafeInteger(value.parent_pid) ? value.parent_pid : undefined;
+    }
+    catch {
+        return undefined;
+    }
+})();
 // IPC disconnect covers a cooperative parent shutdown. ppid surveillance also
 // covers abrupt parent death, where an orphan might otherwise retain its cwd.
-setInterval(() => { if (!anchor || process.ppid !== anchor.parent_pid)
+setInterval(() => { if (watchedParentPid === undefined || process.ppid !== watchedParentPid)
     process.exit(0); }, 100).unref();
 void start().catch(() => process.exit(1));

package/dist/deployment/organizationHandoffAuthorityFsWorkerStall.fixture.d.ts

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

package/dist/deployment/organizationHandoffAuthorityFsWorkerStall.fixture.js

@@ -0,0 +1,16 @@
+import { pbkdf2 } from "node:crypto";
+/**
+ * Test-only preload that delays the authority worker's startup filesystem call.
+ *
+ * The worker validates its anchor with an `lstat`, which libuv runs on the
+ * threadpool. Forked with `UV_THREADPOOL_SIZE=1`, this preload occupies that
+ * single slot long enough that the anchor cannot be established until well
+ * after the worker's 100ms liveness watchdog has ticked several times — the
+ * deterministic equivalent of what CPU contention does to worker startup on a
+ * loaded host, and the condition under which the watchdog used to reap the
+ * helper before it could ever report readiness.
+ *
+ * The event loop itself stays free throughout, so the watchdog does tick.
+ */
+const STALL_ITERATIONS = 1_500_000;
+pbkdf2("spawnfile-stall", "spawnfile-stall", STALL_ITERATIONS, 64, "sha512", () => undefined);

package/dist/deployment/organizationHandoffAuthorityStore.js

@@ -8,7 +8,14 @@ import { ORGANIZATION_HANDOFF_AUTHORITY_ERROR, createOrganizationHandoffCapabili
 import { parseOrganizationHandoff } from "./organizationHandoffTypes.js";
 import { initializeOrganizationHandoffAuthorityFsClient } from "./organizationHandoffAuthorityFsClient.js";
 const owner = typeof process.getuid === "function" ? process.getuid() : undefined;
-const fail = () => { throw new Error(ORGANIZATION_HANDOFF_AUTHORITY_ERROR); };
+/**
+ * The store's public message stays uniform: it reaches CLI output and must not
+ * describe private resolution state. Diagnostics from the helper are preserved
+ * on `cause` so an operator log still shows which budget or invariant failed.
+ */
+const fail = (cause) => {
+    throw new Error(ORGANIZATION_HANDOFF_AUTHORITY_ERROR, ...(cause === undefined ? [] : [{ cause }]));
+};
 const key = (value) => Buffer.from(value, "utf8").toString("hex");
 const same = (left, right) => JSON.stringify(left) === JSON.stringify(right);
 const pendingKey = (value) => typeof value === "string" && /^[a-f0-9]{64}$/u.test(value) ? value : fail();
@@ -27,8 +34,8 @@ const closeRequest = (value) => {
             organizationHandoffHandle: parseOpaqueTargetHandle(input.organizationHandoffHandle)
         });
     }
-    catch {
-        return fail();
+    catch (error) {
+        return fail(error);
     }
 };
 export const resolveOrganizationHandoffAuthorityRoot = () => path.join(resolveSpawnfileHome(), "deployments", "organization-handoff-authority");
@@ -309,8 +316,8 @@ class Store {
                     network_attachment_handle: final.handoff.network_attachment_handle }), selected_target_binding: Object.freeze({ receipt: final.selected_target,
                     receipt_digest: final.selected_target_receipt_digest }) });
         }
-        catch {
-            return fail();
+        catch (error) {
+            return fail(error);
         }
     }
 }
@@ -339,10 +346,10 @@ export const initializeOrganizationHandoffAuthorityStore = async (options = {})
             clients.set(part, client);
         }
     }
-    catch {
+    catch (error) {
         await Promise.all([...clients.values()].map(async (client) => client.dispose()));
         await Promise.all([...anchors.values()].map(async ({ handle }) => { await handle.close().catch(() => undefined); }));
-        return fail();
+        return fail(error);
     }
     return new Store(root, anchors, clients, options.testHooks);
 };

package/dist/deployment/organizationHandoffAuthorityTypes.d.ts

@@ -1,8 +1,9 @@
 import { type OpaqueTargetHandle, type SelectedTargetReceipt } from "../target/index.js";
+import { ORGANIZATION_HANDOFF_AUTHORITY_ERROR } from "./organizationHandoffAuthorityFsBudget.js";
 import { type OrganizationHandoff } from "./organizationHandoffTypes.js";
 export declare const ORGANIZATION_HANDOFF_CAPABILITY_VERSION: "spawnfile.organization-handoff-capability.private.v1";
 export declare const ORGANIZATION_HANDOFF_RECOVERY_VERSION: "spawnfile.organization-handoff-recovery.private.v1";
-export declare const ORGANIZATION_HANDOFF_AUTHORITY_ERROR = "Organization handoff authority failed";
+export { ORGANIZATION_HANDOFF_AUTHORITY_ERROR };
 declare const labels: ("com.spawnfile.compile_fingerprint" | "com.spawnfile.project" | "com.spawnfile.deployment" | "com.spawnfile.run_id" | "com.spawnfile.unit" | "com.spawnfile.version")[];
 export type OrganizationHandoffCapabilityState = "pending" | "finalized" | "attach_closed";
 export type OrganizationHandoffDeploymentLabels = Readonly<Record<(typeof labels)[number], string>>;
@@ -73,4 +74,3 @@ export declare const parseOrganizationAttachmentAuthorizationForDeployment: (raw
     };
     readonly version: "spawnfile.target-organization-attachment.authorization.v1";
 };
-export {};

package/dist/deployment/organizationHandoffAuthorityTypes.js

@@ -1,10 +1,11 @@
 import { createHash } from "node:crypto";
 import { assertOrdinaryJsonGraph, createCanonicalSelectedTargetReceiptBytes, parseOpaqueTargetHandle, parseRunId, parseSelectedTargetReceipt } from "../target/index.js";
 import { dockerDeploymentLabelKeys } from "./dockerLabels.js";
+import { ORGANIZATION_HANDOFF_AUTHORITY_ERROR } from "./organizationHandoffAuthorityFsBudget.js";
 import { parseOrganizationHandoff } from "./organizationHandoffTypes.js";
 export const ORGANIZATION_HANDOFF_CAPABILITY_VERSION = "spawnfile.organization-handoff-capability.private.v1";
 export const ORGANIZATION_HANDOFF_RECOVERY_VERSION = "spawnfile.organization-handoff-recovery.private.v1";
-export const ORGANIZATION_HANDOFF_AUTHORITY_ERROR = "Organization handoff authority failed";
+export { ORGANIZATION_HANDOFF_AUTHORITY_ERROR };
 const DIGEST = /^sha256:[a-f0-9]{64}$/u;
 const CONTAINER = /^[a-f0-9]{64}$/u;
 const NAME = /^[A-Za-z0-9][A-Za-z0-9_.-]{0,127}$/u;

package/dist/deployment/organizationReady.d.ts

@@ -16,7 +16,9 @@ export interface OrganizationReadiness {
     readonly reason?: string;
 }
 export interface OrganizationReadinessProbeData {
+    readonly daimonReceipt?: string | null;
     readonly configs: ReadonlyMap<string, string>;
+    readonly attachmentReceipts?: ReadonlyMap<string, string>;
     readonly networks: readonly {
         readonly healthOk: boolean;
         readonly id: string;