@cotal-ai/workspace 0.68.0 → 0.70.0

package/dist/auth-paths.d.ts

@@ -1,4 +1,4 @@
-import { type BrokerAuth, type SecretStore, type SpaceAccountAuth, type SpaceAuth } from "@cotal-ai/core";
+import { type BrokerAuth, type Identity, type SecretStore, type SpaceAccountAuth, type SpaceAuth } from "@cotal-ai/core";
 export declare function authDir(root: string): string;
 /** The ONE injective, case-safe space key: lowercase hex of the space's UTF-8 bytes. Every
  *  tenant-keyed namespace derives its key from this — the account filename, the user-auth state
@@ -101,7 +101,7 @@ export declare function brokerAuthPath(dir: string): string;
  *  (i) fence bites) + the serve nkey identity (so re-registration reuses the SAME gate principal —
  *  provisionEndpointGateOpen stays idempotent, no core barrier change, and eviction targets a
  *  stable principal). Holds a private seed, so it lands in a HARDENED secret file in the space's
- *  segment of this root (see {@link managerIdentityFile}). */
+ *  segment of this root (see {@link rootIdentityFile}). */
 export interface ManagerInstanceIdentity {
     instanceId: string;
     serveIdentity: {
@@ -109,20 +109,16 @@ export interface ManagerInstanceIdentity {
         seed: string;
     };
 }
+/** The nkey identity a persisted record holds at `v`, or undefined when `v` is not one: the check
+ *  every identity record's `parse` applies to each nkey it holds. */
+export declare function identityOf(v: unknown): Identity | undefined;
 /** Load this workspace root's persisted manager instance identity for `space`, or undefined if a
  *  manager has never registered here. A present-but-MALFORMED file fails LOUD: minting a fresh id
  *  over it would orphan the prior registration and break the restart-fence guarantee, so a restart
  *  never silently becomes a fresh instance (no-fallbacks). */
 export declare function loadManagerInstanceIdentity(root: string, space: string): ManagerInstanceIdentity | undefined;
-/** Persist this workspace root's manager instance identity for `space` (hardened secret file). */
-export declare function saveManagerInstanceIdentity(root: string, space: string, identity: ManagerInstanceIdentity): void;
-/**
- * First-start identity mint: of N concurrent creators on a fresh root, exactly one creates the
- * file and the others adopt the winner. The publication primitive is exclusive create
- * (`writeSecretFileCreateOnly` / `link` or `O_EXCL`), not a read-then-write and not an atomic
- * rename. A loser never keeps the identity it minted in memory: it re-reads the winner or
- * refuses with a named error (`manager-instance-identity-create-lost`).
- */
+/** First-start identity mint through {@link claimIdentityRecord}: of N concurrent creators on a
+ *  fresh root, exactly one creates the file and the others adopt the winner. */
 export declare function createManagerInstanceIdentity(root: string, space: string, candidate: ManagerInstanceIdentity): ManagerInstanceIdentity;
 /** The manager's goal-writer and session-ledger nkeys for `space`. Both are siblings of the serve
  *  identity in its §13.1 credential family and persist for the same reason: the family never drops
@@ -139,8 +135,7 @@ export interface ManagerSiblingIdentities {
     };
 }
 /** This root's manager sibling identities for `space`, minted on the first start and read back on
- *  every later one. The mint publishes by exclusive create, as {@link createManagerInstanceIdentity}
- *  does, so concurrent first starts adopt one pair. */
+ *  every later one through {@link claimIdentityRecord}, so concurrent first starts adopt one pair. */
 export declare function claimManagerSiblingIdentities(root: string, space: string): ManagerSiblingIdentities;
 /** The AUTH PLANE's persisted instance identity (#399 M2): a stable `instanceId` + serve nkey so
  *  a restart re-registers the SAME `svc.auth.<instanceId>` instance (`registerServiceInstance`
@@ -158,12 +153,7 @@ export interface AuthInstanceIdentity {
  *  the auth plane has never registered here. A present-but-MALFORMED file fails LOUD: minting a
  *  fresh id over it would orphan the prior registration and break the restart-fence guarantee. */
 export declare function loadAuthInstanceIdentity(root: string, space: string): AuthInstanceIdentity | undefined;
-/** Persist this workspace root's auth-plane instance identity for `space` (hardened secret file). */
-export declare function saveAuthInstanceIdentity(root: string, space: string, identity: AuthInstanceIdentity): void;
-/**
- * First-start identity mint for the auth plane: of N concurrent creators on a fresh root, exactly
- * one creates the file and the others adopt the winner (mirrors {@link createManagerInstanceIdentity}).
- */
+/** First-start identity mint for the auth plane, as {@link createManagerInstanceIdentity}. */
 export declare function createAuthInstanceIdentity(root: string, space: string, candidate: AuthInstanceIdentity): AuthInstanceIdentity;
 /** The outcome of {@link retireManagerInstanceIdentity}. `removed` means this call deleted the
  *  record that matched `expected`. `absent` means no record exists for the space: a retry after an
@@ -247,6 +237,13 @@ export declare function loadSeatWriterGeneration(root: string, space: string, na
  * primitive, opposite disposition.
  */
 export declare function advanceSeatWriterGeneration(root: string, claim: SeatWriterGeneration): SeatWriterGeneration;
+/**
+ * A persisted identity record of this root: the stored one, or on a fresh root `mint()`'s,
+ * published by exclusive create. Of N concurrent first mints exactly one creates the file and the
+ * others adopt it, so a loser never keeps the identity it minted in memory; an atomic rename would
+ * let it. A loser that cannot read the winner refuses with `identity-record-create-lost`.
+ */
+export declare function claimIdentityRecord<T>(path: string, what: string, parse: (raw: unknown) => T | undefined, mint: () => T): T;
 /** Where one space's own account record lives: a FLAT file beside `broker.json`, keyed by
  *  {@link accountFileKey}. Flat (not `<space>/account.json`) because `<authDir>/<space>/` is
  *  {@link userAuthStateDir}; hex-keyed because a raw space name in the filename both aliased that

package/dist/auth-paths.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"auth-paths.d.ts","sourceRoot":"","sources":["../src/auth-paths.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"auth-paths.d.ts","sourceRoot":"","sources":["../src/auth-paths.ts"],"names":[],"mappings":"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"}

package/dist/auth-paths.js

@@ -351,196 +351,109 @@ const SPACE_ACCOUNT_SUFFIX = ".json";
 export function brokerAuthPath(dir) {
     return join(dir, BROKER_FILE);
 }
-/** A manager identity record of this root, `<root>/.cotal/space.<hex>/<name>`. It is state of this
- *  root, so it stays out of `.cotal/auth`: that folder is what an operator copies to give another
- *  root a mesh's trust, and an identity copied with it made the other root's manager this root's
- *  logical instance. An older build kept the record in `.cotal/auth` as `legacyName`; the first
- *  touch moves it here, so an upgraded root restarts as the same instance (SPEC 13.6). */
-function managerIdentityFile(root, space, name, legacyName) {
+const MANAGER_INSTANCE = "the manager instance identity";
+/** The nkey identity a persisted record holds at `v`, or undefined when `v` is not one: the check
+ *  every identity record's `parse` applies to each nkey it holds. */
+export function identityOf(v) {
+    const k = v;
+    if (typeof k?.id !== "string" || k.id.length === 0 || typeof k.seed !== "string" || k.seed.length === 0)
+        return undefined;
+    return { id: k.id, seed: k.seed };
+}
+/** The shape both the manager and the auth plane persist as their instance identity. */
+function instanceIdentityOf(raw) {
+    const r = raw;
+    const serveIdentity = identityOf(r?.serveIdentity);
+    if (typeof r?.instanceId !== "string" || r.instanceId.length === 0 || serveIdentity === undefined)
+        return undefined;
+    return { instanceId: r.instanceId, serveIdentity };
+}
+/** An identity record of this root, `<root>/.cotal/space.<hex>/<name>`. It is state of this root,
+ *  so it stays out of `.cotal/auth`: that folder is what an operator copies to give another root a
+ *  mesh's trust, and an identity copied with it made the other root's manager this root's logical
+ *  instance. An older build kept the record at a `legacy` path; the first touch moves it here, so an
+ *  upgraded root restarts as the same instance (SPEC 13.6). A `legacy` entry that is not a regular
+ *  file is refused like the record itself, so a dangling link cannot pass for a fresh root and mint
+ *  a new identity. */
+function rootIdentityFile(root, space, name, ...legacy) {
     const path = join(root, ".cotal", spaceSegment(space), name);
-    const legacy = join(authDir(root), legacyName);
-    if (!existsSync(legacy))
-        return path;
-    mkSecretDir(dirname(path));
-    // A link, not a rename: it never replaces a record already at `path`, and a concurrent first
-    // touch that linked first is the same inode, which tells it apart from a second record.
-    try {
-        linkSync(legacy, path);
-    }
-    catch (e) {
-        const code = e.code;
-        if (code === "ENOENT")
-            return path;
-        if (code !== "EEXIST")
-            throw e;
-        const old = statSync(legacy, { throwIfNoEntry: false });
-        const current = statSync(path);
-        if (old && (old.ino !== current.ino || old.dev !== current.dev))
-            throw new Error(`both ${path} and the older ${legacy} hold a manager identity for space "${space}" - refusing to guess which belongs to this root. Remove the one that did not come from this root, then retry.`);
+    for (const from of legacy) {
+        if (!hasAuthRecord(from, "an identity record"))
+            continue;
+        mkSecretDir(dirname(path));
+        // A link, not a rename: it never replaces a record already at `path`, and a concurrent first
+        // touch that linked first is the same inode, which tells it apart from a second record.
+        try {
+            linkSync(from, path);
+        }
+        catch (e) {
+            const code = e.code;
+            if (code === "ENOENT")
+                continue;
+            if (code !== "EEXIST")
+                throw e;
+            const old = statSync(from, { throwIfNoEntry: false });
+            const current = statSync(path);
+            if (old && (old.ino !== current.ino || old.dev !== current.dev))
+                throw new Error(`both ${path} and the older ${from} hold an identity record for space "${space}" - refusing to guess which belongs to this root. Remove the one that did not come from this root, then retry.`);
+        }
+        rmSync(from, { force: true });
     }
-    rmSync(legacy, { force: true });
     return path;
 }
 function managerInstanceFile(root, space) {
-    return managerIdentityFile(root, space, "manager-instance.json", `manager-instance.${spaceKey(space)}.json`);
+    return rootIdentityFile(root, space, "manager-instance.json", join(authDir(root), `manager-instance.${spaceKey(space)}.json`));
 }
 /** Load this workspace root's persisted manager instance identity for `space`, or undefined if a
  *  manager has never registered here. A present-but-MALFORMED file fails LOUD: minting a fresh id
  *  over it would orphan the prior registration and break the restart-fence guarantee, so a restart
  *  never silently becomes a fresh instance (no-fallbacks). */
 export function loadManagerInstanceIdentity(root, space) {
-    const f = managerInstanceFile(root, space);
-    if (!existsSync(f))
-        return undefined;
-    let parsed;
-    try {
-        parsed = JSON.parse(readFileSync(f, "utf8"));
-    }
-    catch (e) {
-        throw new Error(`the persisted manager instance identity at ${f} does not parse (${e.message}); refusing to mint a fresh id over it - a restart must preserve the logical instanceId (SPEC 13.6)`);
-    }
-    if (parsed === null || typeof parsed !== "object"
-        || typeof parsed.instanceId !== "string" || parsed.instanceId.length === 0
-        || parsed.serveIdentity === null || typeof parsed.serveIdentity !== "object"
-        || typeof parsed.serveIdentity.id !== "string" || parsed.serveIdentity.id.length === 0
-        || typeof parsed.serveIdentity.seed !== "string" || parsed.serveIdentity.seed.length === 0)
-        throw new Error(`the persisted manager instance identity at ${f} is malformed; refusing to mint a fresh id over it - a restart must preserve the logical instanceId (SPEC 13.6)`);
-    return { instanceId: parsed.instanceId, serveIdentity: { id: parsed.serveIdentity.id, seed: parsed.serveIdentity.seed } };
-}
-/** Persist this workspace root's manager instance identity for `space` (hardened secret file). */
-export function saveManagerInstanceIdentity(root, space, identity) {
-    const path = managerInstanceFile(root, space);
-    mkSecretDir(dirname(path)); // harden the dir BEFORE the secret (with its seed) lands
-    writeSecretFile(path, JSON.stringify(identity, null, 2));
+    return readManagerInstanceRecord(managerInstanceFile(root, space));
 }
-/**
- * First-start identity mint: of N concurrent creators on a fresh root, exactly one creates the
- * file and the others adopt the winner. The publication primitive is exclusive create
- * (`writeSecretFileCreateOnly` / `link` or `O_EXCL`), not a read-then-write and not an atomic
- * rename. A loser never keeps the identity it minted in memory: it re-reads the winner or
- * refuses with a named error (`manager-instance-identity-create-lost`).
- */
+/** First-start identity mint through {@link claimIdentityRecord}: of N concurrent creators on a
+ *  fresh root, exactly one creates the file and the others adopt the winner. */
 export function createManagerInstanceIdentity(root, space, candidate) {
-    const path = managerInstanceFile(root, space);
-    mkSecretDir(dirname(path));
-    try {
-        writeSecretFileCreateOnly(path, JSON.stringify(candidate, null, 2));
-        return candidate;
-    }
-    catch (e) {
-        if (e.code !== "EEXIST")
-            throw e;
-        const winner = loadManagerInstanceIdentity(root, space);
-        if (winner === undefined)
-            throw new Error(`manager-instance-identity-create-lost: exclusive create for space "${space}" at ${path} lost and the existing file could not be adopted`);
-        return winner;
-    }
+    return claimIdentityRecord(managerInstanceFile(root, space), MANAGER_INSTANCE, instanceIdentityOf, () => candidate);
 }
 function managerSiblingFile(root, space) {
-    return managerIdentityFile(root, space, "manager-siblings.json", `manager-siblings.${spaceKey(space)}.json`);
+    return rootIdentityFile(root, space, "manager-siblings.json", join(authDir(root), `manager-siblings.${spaceKey(space)}.json`));
 }
-function readManagerSiblingRecord(f, space) {
-    const raw = readAuthRecord(f, `the manager sibling identities for space "${space}"`);
-    if (raw === undefined)
-        return undefined;
-    const nkey = (k) => typeof k?.id === "string" && k.id.length > 0 && typeof k.seed === "string" && k.seed.length > 0;
-    if (!nkey(raw?.goalWriter) || !nkey(raw?.sessionLedger))
-        throw new Error(`${f} is malformed; refusing to mint fresh sibling identities over it`);
-    return {
-        goalWriter: { id: raw.goalWriter.id, seed: raw.goalWriter.seed },
-        sessionLedger: { id: raw.sessionLedger.id, seed: raw.sessionLedger.seed },
-    };
+function siblingIdentitiesOf(raw) {
+    const r = raw;
+    const goalWriter = identityOf(r?.goalWriter);
+    const sessionLedger = identityOf(r?.sessionLedger);
+    return goalWriter && sessionLedger ? { goalWriter, sessionLedger } : undefined;
 }
 /** This root's manager sibling identities for `space`, minted on the first start and read back on
- *  every later one. The mint publishes by exclusive create, as {@link createManagerInstanceIdentity}
- *  does, so concurrent first starts adopt one pair. */
+ *  every later one through {@link claimIdentityRecord}, so concurrent first starts adopt one pair. */
 export function claimManagerSiblingIdentities(root, space) {
-    const path = managerSiblingFile(root, space);
-    const stored = readManagerSiblingRecord(path, space);
-    if (stored !== undefined)
-        return stored;
-    mkSecretDir(dirname(path));
-    const candidate = { goalWriter: newIdentity(), sessionLedger: newIdentity() };
-    try {
-        writeSecretFileCreateOnly(path, JSON.stringify(candidate, null, 2));
-        return candidate;
-    }
-    catch (e) {
-        if (e.code !== "EEXIST")
-            throw e;
-        const winner = readManagerSiblingRecord(path, space);
-        if (winner === undefined)
-            throw new Error(`manager-sibling-identities-create-lost: exclusive create for space "${space}" at ${path} lost and the existing file could not be adopted`);
-        return winner;
-    }
+    return claimIdentityRecord(managerSiblingFile(root, space), "the manager sibling identities", siblingIdentitiesOf, () => ({ goalWriter: newIdentity(), sessionLedger: newIdentity() }));
 }
+const AUTH_INSTANCE = "the auth instance identity";
+/** The auth plane's record sits beside the manager's. An older build kept it in `.cotal/auth` under
+ *  the plane's state dir. For a CLI root that dir is the root's user-auth state dir, inside the folder
+ *  an operator copies; a hosted context passes its state dir as the root, so its record sat in the
+ *  root's own `.cotal/auth`. */
 function authInstanceFile(root, space) {
-    return join(authDir(root), `auth-instance.${Buffer.from(space, "utf8").toString("hex")}.json`);
+    const legacyName = `auth-instance.${spaceKey(space)}.json`;
+    return rootIdentityFile(root, space, "auth-instance.json", join(authDir(userAuthStateDir(root, space)), legacyName), join(authDir(root), legacyName));
 }
 /** Load this workspace root's persisted auth-plane instance identity for `space`, or undefined if
  *  the auth plane has never registered here. A present-but-MALFORMED file fails LOUD: minting a
  *  fresh id over it would orphan the prior registration and break the restart-fence guarantee. */
 export function loadAuthInstanceIdentity(root, space) {
-    const f = authInstanceFile(root, space);
-    if (!existsSync(f))
-        return undefined;
-    let parsed;
-    try {
-        parsed = JSON.parse(readFileSync(f, "utf8"));
-    }
-    catch (e) {
-        throw new Error(`the persisted auth instance identity at ${f} does not parse (${e.message}); refusing to mint a fresh id over it - a restart must preserve the logical instanceId (SPEC 13.6)`);
-    }
-    if (parsed === null || typeof parsed !== "object"
-        || typeof parsed.instanceId !== "string" || parsed.instanceId.length === 0
-        || parsed.serveIdentity === null || typeof parsed.serveIdentity !== "object"
-        || typeof parsed.serveIdentity.id !== "string" || parsed.serveIdentity.id.length === 0
-        || typeof parsed.serveIdentity.seed !== "string" || parsed.serveIdentity.seed.length === 0)
-        throw new Error(`the persisted auth instance identity at ${f} is malformed; refusing to mint a fresh id over it - a restart must preserve the logical instanceId (SPEC 13.6)`);
-    return { instanceId: parsed.instanceId, serveIdentity: { id: parsed.serveIdentity.id, seed: parsed.serveIdentity.seed } };
-}
-/** Persist this workspace root's auth-plane instance identity for `space` (hardened secret file). */
-export function saveAuthInstanceIdentity(root, space, identity) {
-    const dir = authDir(root);
-    mkSecretDir(dir); // harden the auth dir BEFORE the secret (with its seed) lands
-    writeSecretFile(authInstanceFile(root, space), JSON.stringify(identity, null, 2));
+    return readIdentityRecord(authInstanceFile(root, space), AUTH_INSTANCE, instanceIdentityOf);
 }
-/**
- * First-start identity mint for the auth plane: of N concurrent creators on a fresh root, exactly
- * one creates the file and the others adopt the winner (mirrors {@link createManagerInstanceIdentity}).
- */
+/** First-start identity mint for the auth plane, as {@link createManagerInstanceIdentity}. */
 export function createAuthInstanceIdentity(root, space, candidate) {
-    const dir = authDir(root);
-    mkSecretDir(dir);
-    const path = authInstanceFile(root, space);
-    try {
-        writeSecretFileCreateOnly(path, JSON.stringify(candidate, null, 2));
-        return candidate;
-    }
-    catch (e) {
-        if (e.code !== "EEXIST")
-            throw e;
-        const winner = loadAuthInstanceIdentity(root, space);
-        if (winner === undefined)
-            throw new Error(`auth-instance-identity-create-lost: exclusive create for space "${space}" at ${path} lost and the existing file could not be adopted`);
-        return winner;
-    }
+    return claimIdentityRecord(authInstanceFile(root, space), AUTH_INSTANCE, instanceIdentityOf, () => candidate);
 }
 function sameManagerInstanceIdentity(a, b) {
     return a.instanceId === b.instanceId && a.serveIdentity.id === b.serveIdentity.id && a.serveIdentity.seed === b.serveIdentity.seed;
 }
-function readManagerInstanceRecord(f, space) {
-    const what = `the manager instance identity for space "${space}"`;
-    const raw = readAuthRecord(f, what);
-    if (raw === undefined)
-        return undefined;
-    if (raw === null || typeof raw !== "object"
-        || typeof raw.instanceId !== "string" || raw.instanceId.length === 0
-        || raw.serveIdentity === null || typeof raw.serveIdentity !== "object"
-        || typeof raw.serveIdentity.id !== "string" || raw.serveIdentity.id.length === 0
-        || typeof raw.serveIdentity.seed !== "string" || raw.serveIdentity.seed.length === 0)
-        throw new Error(`${f} is malformed`);
-    return { instanceId: raw.instanceId, serveIdentity: { id: raw.serveIdentity.id, seed: raw.serveIdentity.seed } };
+function readManagerInstanceRecord(f) {
+    return readIdentityRecord(f, MANAGER_INSTANCE, instanceIdentityOf);
 }
 /**
  * Delete this root's persisted manager instance identity for `space`, only when the stored record
@@ -563,7 +476,7 @@ export function retireManagerInstanceIdentity(root, space, expected, opts) {
     };
     let current;
     try {
-        current = readManagerInstanceRecord(path, space);
+        current = readManagerInstanceRecord(path);
     }
     catch (e) {
         return refuse(e.message);
@@ -584,7 +497,7 @@ export function retireManagerInstanceIdentity(root, space, expected, opts) {
     }
     let held;
     try {
-        held = readManagerInstanceRecord(captured, space);
+        held = readManagerInstanceRecord(captured);
     }
     catch {
         held = undefined;
@@ -717,26 +630,32 @@ export function advanceSeatWriterGeneration(root, claim) {
         throw new Error(`seat-writer-generation-create-lost: generation ${claim.generation} of seat ${JSON.stringify(claim.name)} in space ${JSON.stringify(claim.space)} is already claimed; refusing to resume as a second writer`);
     }
 }
-/** Read one auth-material record: the file's raw text, or undefined when absent. lstat-disciplined
- *  and framed, shared by every load/save below so the readers cannot disagree:
- *   - a non-regular entry at a trust path (symlink, directory, fifo) is REFUSED, never followed —
- *     nothing in this module writes one, so following it would trust material this module cannot
- *     vouch for (and enumeration counts the same entry as corrupt: one answer everywhere);
- *   - only ENOENT means absent; any other errno is uncertainty about trust material and throws;
- *   - the JSON parse is wrapped so a truncated/hand-edited record surfaces as one legible sentence
- *     naming the file, never a raw SyntaxError deep in a caller. */
-function readAuthRecord(f, what) {
+/** Whether a trust path holds an auth-material record, lstat-disciplined:
+ *   - a non-regular entry (symlink, directory, fifo) is REFUSED, never followed — nothing in this
+ *     module writes one, so following it would trust material this module cannot vouch for (and
+ *     enumeration counts the same entry as corrupt: one answer everywhere);
+ *   - only ENOENT means absent; any other errno is uncertainty about trust material and throws. */
+function hasAuthRecord(f, what) {
     let st;
     try {
         st = lstatSync(f);
     }
     catch (e) {
         if (e.code === "ENOENT")
-            return undefined;
+            return false;
         throw e;
     }
     if (!st.isFile())
         throw new Error(`${f} is not a regular file - refusing to read ${what} through it; remove or restore the real record`);
+    return true;
+}
+/** Read one auth-material record: the file's raw text, or undefined when absent. Shared by every
+ *  load/save below so the readers cannot disagree: the entry is checked by {@link hasAuthRecord},
+ *  and the JSON parse is wrapped so a truncated/hand-edited record surfaces as one legible sentence
+ *  naming the file, never a raw SyntaxError deep in a caller. */
+function readAuthRecord(f, what) {
+    if (!hasAuthRecord(f, what))
+        return undefined;
     try {
         return JSON.parse(readFileSync(f, "utf8"));
     }
@@ -744,6 +663,43 @@ function readAuthRecord(f, what) {
         throw new Error(`${f} does not parse as ${what} (${e instanceof Error ? e.message : String(e)}) - restore it from backup or remove it deliberately`);
     }
 }
+/** A persisted identity record, or undefined when absent. Every identity reads through
+ *  {@link readAuthRecord}, so they refuse the same entries, and a record `parse` rejects fails LOUD:
+ *  minting over it would orphan the identity it held. */
+function readIdentityRecord(f, what, parse) {
+    const raw = readAuthRecord(f, what);
+    if (raw === undefined)
+        return undefined;
+    const record = parse(raw);
+    if (record === undefined)
+        throw new Error(`${f} is not a well-formed record of ${what} - restore it from backup or remove it deliberately`);
+    return record;
+}
+/**
+ * A persisted identity record of this root: the stored one, or on a fresh root `mint()`'s,
+ * published by exclusive create. Of N concurrent first mints exactly one creates the file and the
+ * others adopt it, so a loser never keeps the identity it minted in memory; an atomic rename would
+ * let it. A loser that cannot read the winner refuses with `identity-record-create-lost`.
+ */
+export function claimIdentityRecord(path, what, parse, mint) {
+    const stored = readIdentityRecord(path, what, parse);
+    if (stored !== undefined)
+        return stored;
+    mkSecretDir(dirname(path));
+    const candidate = mint();
+    try {
+        writeSecretFileCreateOnly(path, JSON.stringify(candidate, null, 2));
+        return candidate;
+    }
+    catch (e) {
+        if (e.code !== "EEXIST")
+            throw e;
+        const winner = readIdentityRecord(path, what, parse);
+        if (winner === undefined)
+            throw new Error(`identity-record-create-lost: exclusive create of ${what} at ${path} lost and the existing record could not be adopted`);
+        return winner;
+    }
+}
 /** The space a canonical account filename encodes, or undefined when the name is not one THIS module
  *  wrote (wrong prefix/suffix, non-hex body, or a body that does not round-trip back to the same
  *  filename). Enumeration treats an undefined result as a corrupt/foreign record, never as a tenant. */