@mono-agent/a2a-adapter 0.11.2 → 0.11.4

package/README.md

@@ -120,21 +120,78 @@ omits the namespace; they never silently start without the advertised guard.
 
 ## Public API
 
-- `startA2AProvider`
-- `createA2AChannelDriver`
-- `createChannelDriver`
-- `createA2AAgentCard`
-- `createA2AConsumer`
-- `dispatchA2AMessage`
-- `discoverA2AAgent`
-- `sendA2AMessage`
-- `createA2AConsumerResponder`
-- `A2A_CONFIG_FIELDS`
-- `loadA2AAdapterConfig`
-- `redactA2AAdapterConfig`
+<!-- public-api-inventory:start -->
+<!-- Generated by scripts/generate-public-api-docs.mjs. Do not edit by hand. -->
+
+Every symbol exported by each public code entrypoint is listed below.
+
+**`@mono-agent/a2a-adapter`**
+
+```text
+A2AAdapterAgentConfig
+A2AAdapterConfig
+A2AAdapterConsumerConfig
+A2AAdapterProviderConfig
+A2AAdapterRawConfig
+A2AAgentCardOptions
+A2AAgentRequest
+A2AAgentSkillOptions
+A2AChannelDriverOptions
+A2AConsumer
+A2AConsumerDispatch
+A2AConsumerDispatchCancelOptions
+A2AConsumerDispatchMessageInput
+A2AConsumerDispatchObservationOptions
+A2AConsumerError
+A2AConsumerErrorCode
+A2AConsumerErrorDetails
+A2AConsumerOptions
+A2AConsumerResponderOptions
+A2AConsumerResponse
+A2AConsumerResponseMetadata
+A2AConsumerSendMessageInput
+A2AConsumerTerminalOutcome
+A2AProviderError
+A2AProviderErrorCode
+A2AProviderErrorDetails
+A2AProviderIdempotencyOptions
+A2AProviderLogger
+A2AProviderOptions
+A2AProviderStartResult
+A2ARequestMetadata
+A2A_CONFIG_FIELDS
+A2A_IDEMPOTENCY_EXTENSION_URI
+A2A_IDEMPOTENCY_METADATA_KEY
+A2A_IDEMPOTENCY_SCHEMA_VERSION
+AgentCard
+LoadA2AAdapterConfigInput
+Message
+RedactedA2AAdapterConfig
+SendMessageResult
+Task
+createA2AAgentCard
+createA2AChannelDriver
+createA2AConsumer
+createA2AConsumerResponder
+createChannelDriver
+defaultA2AIdempotencyStateDir
+discoverA2AAgent
+dispatchA2AMessage
+loadA2AAdapterConfig
+normalizeA2AIdempotencyKey
+normalizeBaseUrl
+redactA2AAdapterConfig
+sendA2AMessage
+startA2AProvider
+```
+
+<!-- public-api-inventory:end -->
 
 Config can be loaded from a `channels.plugins[]` entry or explicit environment variables:
 
+Set `MONO_AGENT_A2A_BEARER_TOKEN` in `.env` when `requireBearer` is enabled;
+the source-config example omits the credential.
+
 ```json
 {
   "agent": {
@@ -151,7 +208,6 @@ Config can be loaded from a `channels.plugins[]` entry or explicit environment v
             "host": "127.0.0.1",
             "port": 4300,
             "requireBearer": true,
-            "bearerToken": "redacted-value",
             "idempotency": {
               "namespace": "agent-a-production",
               "stateDir": ".mono-agent/a2a-agent-a",

package/dist/idempotency.d.ts

@@ -17,6 +17,17 @@ interface IdempotencyEnvelope {
     readonly schemaVersion: 1;
     readonly key: string;
 }
+interface FileIdempotencyStoreHooks {
+    /** Deterministic test seam after the admission is durable but before it is published. */
+    readonly beforeAdmissionPublish?: () => Promise<void>;
+    /** Deterministic test seam after publication but before the staging link is removed. */
+    readonly afterAdmissionPublish?: () => Promise<void>;
+    /** Deterministic test seam after opening a canonical record but before pathname revalidation. */
+    readonly afterRecordOpen?: (input: {
+        readonly keyHash: string;
+        readonly attempt: number;
+    }) => Promise<void>;
+}
 export declare function createIdempotentA2ARequestHandler(input: {
     readonly delegate: A2ARequestHandler;
     readonly taskStore: TaskStore;
@@ -25,6 +36,8 @@ export declare function createIdempotentA2ARequestHandler(input: {
         warn?(message: string, metadata?: Record<string, unknown>): void;
         error?(message: string, metadata?: Record<string, unknown>): void;
     };
+    /** @internal Deterministic filesystem scheduling hooks for adversarial tests. */
+    readonly storeHooks?: FileIdempotencyStoreHooks;
 }): Promise<A2ARequestHandler>;
 export declare function validateA2AProviderIdempotencyOptions(options: A2AProviderIdempotencyOptions): void;
 export declare function guardUnsupportedA2AIdempotency(delegate: A2ARequestHandler): A2ARequestHandler;

package/dist/idempotency.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"idempotency.d.ts","sourceRoot":"","sources":["../src/idempotency.ts"],"names":[],"mappings":"AAwBA,OAAO,EAEL,KAAK,iBAAiB,EAEtB,KAAK,SAAS,EACf,MAAM,oBAAoB,CAAC;AAI5B,eAAO,MAAM,4BAA4B,sCAAsC,CAAC;AAChF,eAAO,MAAM,8BAA8B,IAAI,CAAC;AAChD,eAAO,MAAM,6BAA6B,yDAAyD,CAAC;AAmBpG,MAAM,WAAW,6BAA6B;IAC5C,2CAA2C;IAC3C,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,gFAAgF;IAChF,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,0EAA0E;IAC1E,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,yEAAyE;IACzE,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED,MAAM,MAAM,yBAAyB,GACjC,oBAAoB,GACpB,UAAU,GACV,UAAU,GACV,aAAa,GACb,gBAAgB,GAChB,aAAa,CAAC;AAElB,UAAU,mBAAmB;IAC3B,QAAQ,CAAC,aAAa,EAAE,CAAC,CAAC;IAC1B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;CACtB;AAqED,wBAAsB,iCAAiC,CAAC,KAAK,EAAE;IAC7D,QAAQ,CAAC,QAAQ,EAAE,iBAAiB,CAAC;IACrC,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC;IAC9B,QAAQ,CAAC,OAAO,EAAE,6BAA6B,CAAC;IAChD,QAAQ,CAAC,MAAM,CAAC,EAAE;QAChB,IAAI,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;QACjE,KAAK,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;KACnE,CAAC;CACH,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAa7B;AAED,wBAAgB,qCAAqC,CACnD,OAAO,EAAE,6BAA6B,GACrC,IAAI,CAWN;AAED,wBAAgB,8BAA8B,CAC5C,QAAQ,EAAE,iBAAiB,GAC1B,iBAAiB,CAEnB;AAED,wBAAgB,0BAA0B,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAUhE;AAED,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,MAAM,GAAG,mBAAmB,CAKvE;AAED,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAEtD;AAED,wBAAgB,6BAA6B,CAAC,GAAG,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAIpF;AAED,wBAAgB,oCAAoC,CAAC,MAAM,EAAE,MAAM,GAAG,yBAAyB,GAAG,SAAS,CAuB1G"}
+{"version":3,"file":"idempotency.d.ts","sourceRoot":"","sources":["../src/idempotency.ts"],"names":[],"mappings":"AAyBA,OAAO,EAEL,KAAK,iBAAiB,EAEtB,KAAK,SAAS,EACf,MAAM,oBAAoB,CAAC;AAI5B,eAAO,MAAM,4BAA4B,sCAAsC,CAAC;AAChF,eAAO,MAAM,8BAA8B,IAAI,CAAC;AAChD,eAAO,MAAM,6BAA6B,yDAAyD,CAAC;AAqBpG,MAAM,WAAW,6BAA6B;IAC5C,2CAA2C;IAC3C,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,gFAAgF;IAChF,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,0EAA0E;IAC1E,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,yEAAyE;IACzE,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED,MAAM,MAAM,yBAAyB,GACjC,oBAAoB,GACpB,UAAU,GACV,UAAU,GACV,aAAa,GACb,gBAAgB,GAChB,aAAa,CAAC;AAElB,UAAU,mBAAmB;IAC3B,QAAQ,CAAC,aAAa,EAAE,CAAC,CAAC;IAC1B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;CACtB;AAgDD,UAAU,yBAAyB;IACjC,yFAAyF;IACzF,QAAQ,CAAC,sBAAsB,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IACtD,wFAAwF;IACxF,QAAQ,CAAC,qBAAqB,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IACrD,iGAAiG;IACjG,QAAQ,CAAC,eAAe,CAAC,EAAE,CAAC,KAAK,EAAE;QAAE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;KAAE,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CAC7G;AAuBD,wBAAsB,iCAAiC,CAAC,KAAK,EAAE;IAC7D,QAAQ,CAAC,QAAQ,EAAE,iBAAiB,CAAC;IACrC,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC;IAC9B,QAAQ,CAAC,OAAO,EAAE,6BAA6B,CAAC;IAChD,QAAQ,CAAC,MAAM,CAAC,EAAE;QAChB,IAAI,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;QACjE,KAAK,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;KACnE,CAAC;IACF,iFAAiF;IACjF,QAAQ,CAAC,UAAU,CAAC,EAAE,yBAAyB,CAAC;CACjD,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAmB7B;AAED,wBAAgB,qCAAqC,CACnD,OAAO,EAAE,6BAA6B,GACrC,IAAI,CAWN;AAED,wBAAgB,8BAA8B,CAC5C,QAAQ,EAAE,iBAAiB,GAC1B,iBAAiB,CAEnB;AAED,wBAAgB,0BAA0B,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAUhE;AAED,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,MAAM,GAAG,mBAAmB,CAKvE;AAED,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAEtD;AAED,wBAAgB,6BAA6B,CAAC,GAAG,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAIpF;AAED,wBAAgB,oCAAoC,CAAC,MAAM,EAAE,MAAM,GAAG,yBAAyB,GAAG,SAAS,CAuB1G"}

package/dist/idempotency.js

@@ -1,6 +1,6 @@
 import { createHash, randomUUID } from "node:crypto";
 import { constants as fsConstants } from "node:fs";
-import { lstat, mkdir, open, readFile, readdir, realpath, rename, stat, unlink, } from "node:fs/promises";
+import { link, lstat, mkdir, open, readFile, readdir, realpath, rename, stat, unlink, } from "node:fs/promises";
 import { basename, dirname, resolve } from "node:path";
 import { TaskState, } from "@a2a-js/sdk";
 import { RequestMalformedError, } from "@a2a-js/sdk/server";
@@ -14,9 +14,11 @@ const STORE_MANIFEST_FILE = "manifest.json";
 const SLOTS_DIRECTORY = "slots";
 const RECORD_FILE_PATTERN = /^[a-f0-9]{64}\.json$/u;
 const SLOT_FILE_PATTERN = /^slot-([0-9]{1,7})\.json$/u;
+const TEMPORARY_RECORD_FILE_PATTERN = /^\.[a-f0-9]{64}\.[a-f0-9-]+\.tmp$/u;
 const SHA256_PATTERN = /^[a-f0-9]{64}$/u;
 const IDEMPOTENCY_KEY_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._:@-]{0,199}$/u;
 const MAX_RECORD_BYTES = 4 * 1024 * 1024;
+const MAX_RECORD_READ_ATTEMPTS = 20;
 const ACTIVE_POLL_MS = 50;
 const DEFAULT_RETENTION_MS = 30 * 24 * 60 * 60 * 1_000;
 const MIN_RETENTION_MS = 60_000;
@@ -29,7 +31,7 @@ export async function createIdempotentA2ARequestHandler(input) {
     const retentionMs = normalizeRetentionMs(input.options.retentionMs);
     const maxRecords = normalizeMaxRecords(input.options.maxRecords);
     const providerScope = idempotencyNamespaceHash(input.options.namespace);
-    const store = await FileIdempotencyStore.create(input.options.stateDir.trim(), retentionMs, maxRecords, providerScope);
+    const store = await FileIdempotencyStore.create(input.options.stateDir.trim(), retentionMs, maxRecords, providerScope, input.storeHooks);
     return new IdempotentA2ARequestHandler(input.delegate, input.taskStore, store, providerScope, input.logger);
 }
 export function validateA2AProviderIdempotencyOptions(options) {
@@ -339,7 +341,8 @@ class FileIdempotencyStore {
     providerScope;
     slotsDir;
     slotsDirIdentity;
-    constructor(stateDir, stateDirIdentity, retentionMs, maxRecords, providerScope, slotsDir, slotsDirIdentity) {
+    hooks;
+    constructor(stateDir, stateDirIdentity, retentionMs, maxRecords, providerScope, slotsDir, slotsDirIdentity, hooks) {
         this.stateDir = stateDir;
         this.stateDirIdentity = stateDirIdentity;
         this.retentionMs = retentionMs;
@@ -347,11 +350,12 @@ class FileIdempotencyStore {
         this.providerScope = providerScope;
         this.slotsDir = slotsDir;
         this.slotsDirIdentity = slotsDirIdentity;
+        this.hooks = hooks;
     }
-    static async create(inputPath, retentionMs, maxRecords, providerScope) {
+    static async create(inputPath, retentionMs, maxRecords, providerScope, hooks = {}) {
         const stateDirectory = await ensurePrivateStateDir(resolve(inputPath));
         const slotsDirectory = await ensurePrivateStateDir(resolve(stateDirectory.path, SLOTS_DIRECTORY));
-        const store = new FileIdempotencyStore(stateDirectory.path, stateDirectory.identity, retentionMs, maxRecords, providerScope, slotsDirectory.path, slotsDirectory.identity);
+        const store = new FileIdempotencyStore(stateDirectory.path, stateDirectory.identity, retentionMs, maxRecords, providerScope, slotsDirectory.path, slotsDirectory.identity, hooks);
         await store.ensureManifest();
         await store.pruneExpiredTerminalRecords();
         await store.reconcileOrphanSlots();
@@ -363,10 +367,10 @@ class FileIdempotencyStore {
         const path = resolve(this.stateDir, `${keyHash}.json`);
         let raw;
         try {
-            raw = await secureReadPrivateFile(path, RECORD_FILE_PATTERN);
+            raw = await secureReadPublishedRecord(path, this.stateDir, keyHash, this.hooks);
         }
         catch (error) {
-            if (isErrno(error, "ENOENT")) {
+            if (error instanceof RecordNotFoundError) {
                 await this.assertDirectories();
                 return undefined;
             }
@@ -422,40 +426,65 @@ class FileIdempotencyStore {
         const slot = await this.allocateSlot(record.keyHash);
         const admitted = { ...record, slot };
         const destination = resolve(this.stateDir, `${record.keyHash}.json`);
+        const temporary = resolve(this.stateDir, `.${record.keyHash}.${randomUUID()}.tmp`);
         const contents = Buffer.from(`${canonicalJson(admitted)}\n`, "utf8");
         let handle;
         try {
-            handle = await open(destination, fsConstants.O_WRONLY | fsConstants.O_CREAT | fsConstants.O_EXCL | (fsConstants.O_NOFOLLOW ?? 0), 0o600);
+            handle = await open(temporary, fsConstants.O_WRONLY | fsConstants.O_CREAT | fsConstants.O_EXCL | (fsConstants.O_NOFOLLOW ?? 0), 0o600);
         }
         catch (error) {
-            if (isErrno(error, "EEXIST")) {
-                await this.assertDirectories();
-                return undefined;
-            }
-            throw storeError("Failed to create the durable A2A idempotency admission.", error);
+            throw storeError("Failed to stage the durable A2A idempotency admission.", error);
         }
         try {
             await handle.writeFile(contents);
             await handle.chmod(0o600);
             await handle.sync();
+            await handle.close();
+            handle = undefined;
         }
         catch (error) {
-            await handle.close().catch(() => undefined);
-            await unlink(destination).catch(() => undefined);
+            await handle?.close().catch(() => undefined);
+            await unlink(temporary).catch(() => undefined);
             throw storeError("Failed to persist the durable A2A idempotency admission.", error);
         }
+        let published = false;
         try {
-            await handle.close();
+            await this.hooks.beforeAdmissionPublish?.();
+            await this.assertDirectories();
+            try {
+                // A hard link is the portable no-clobber publication primitive: the
+                // canonical name appears atomically and already references the fully
+                // written, fsynced inode. Concurrent publishers cannot replace it.
+                await link(temporary, destination);
+                published = true;
+            }
+            catch (error) {
+                if (!isErrno(error, "EEXIST")) {
+                    throw error;
+                }
+                // Persist the shared winner's directory entry before allowing this
+                // process to observe and fail closed on its active admission.
+                await fsyncDirectory(this.stateDir, this.stateDirIdentity);
+                await this.assertDirectories();
+                return undefined;
+            }
+            await this.hooks.afterAdmissionPublish?.();
+            await unlink(temporary);
             await fsyncDirectory(this.stateDir, this.stateDirIdentity);
             await this.verifySlot(slot, record.keyHash);
             await this.assertDirectories();
             return admitted;
         }
         catch (error) {
-            await handle.close().catch(() => undefined);
-            await unlink(destination).catch(() => undefined);
-            await fsyncDirectory(this.stateDir, this.stateDirIdentity).catch(() => undefined);
-            throw storeError("Failed to finalize the durable A2A idempotency admission.", error);
+            if (published) {
+                // The canonical record is complete and may already be observed. Never
+                // remove it after publication: retaining it is the fail-closed result.
+                throw storeError("Failed to finalize the durable A2A idempotency admission.", error);
+            }
+            throw storeError("Failed to publish the durable A2A idempotency admission.", error);
+        }
+        finally {
+            await unlink(temporary).catch(() => undefined);
         }
     }
     async assertDirectories() {
@@ -639,7 +668,7 @@ class FileIdempotencyStore {
             if (!entry.isFile() || !RECORD_FILE_PATTERN.test(entry.name)) {
                 // Atomic-write remnants are retained for operator inspection; they do
                 // not count as admissions because capacity is held by slot files.
-                if (/^\.[a-f0-9]{64}\.[a-f0-9-]+\.tmp$/u.test(entry.name)) {
+                if (TEMPORARY_RECORD_FILE_PATTERN.test(entry.name)) {
                     continue;
                 }
                 throw storeError(`Unexpected entry in A2A idempotency stateDir: ${entry.name}`);
@@ -647,7 +676,7 @@ class FileIdempotencyStore {
             const keyHash = entry.name.slice(0, -".json".length);
             let record;
             try {
-                record = parseRecord(JSON.parse((await secureReadPrivateFile(resolve(this.stateDir, entry.name), RECORD_FILE_PATTERN)).toString("utf8")), keyHash);
+                record = parseRecord(JSON.parse((await secureReadPublishedRecord(resolve(this.stateDir, entry.name), this.stateDir, keyHash, this.hooks)).toString("utf8")), keyHash);
             }
             catch (error) {
                 throw storeError("A2A idempotency state is malformed during startup scan.", error);
@@ -832,9 +861,6 @@ function isTerminalState(state) {
 function cloneResult(value) {
     return revivePersistedResult(value);
 }
-function cloneRecord(value) {
-    return structuredClone(value);
-}
 function parseRecord(value, expectedKeyHash) {
     if (!isRecord(value)) {
         throw new Error("record must be an object");
@@ -1260,6 +1286,139 @@ async function secureReadPrivateFile(path, allowedName) {
         await handle.close();
     }
 }
+class RecordPathChangedError extends Error {
+    constructor() {
+        super("A2A idempotency record pathname changed during a secure read.");
+        this.name = "RecordPathChangedError";
+    }
+}
+class RecordNotFoundError extends Error {
+    constructor() {
+        super("A2A idempotency record does not exist.");
+        this.name = "RecordNotFoundError";
+    }
+}
+async function secureReadPublishedRecord(path, stateDir, keyHash, hooks = {}) {
+    assertKeyHash(keyHash);
+    if (basename(path) !== `${keyHash}.json`) {
+        throw new Error("invalid record path");
+    }
+    let observedCanonical = false;
+    let lastPathChange;
+    for (let attempt = 1; attempt <= MAX_RECORD_READ_ATTEMPTS; attempt += 1) {
+        let handle;
+        try {
+            handle = await open(path, fsConstants.O_RDONLY | (fsConstants.O_NOFOLLOW ?? 0) | (fsConstants.O_NONBLOCK ?? 0));
+            observedCanonical = true;
+        }
+        catch (error) {
+            if (!isErrno(error, "ENOENT")) {
+                throw error;
+            }
+            if (!observedCanonical) {
+                throw new RecordNotFoundError();
+            }
+            lastPathChange = new RecordPathChangedError();
+            continue;
+        }
+        try {
+            await hooks.afterRecordOpen?.({ keyHash, attempt });
+            let details = await handle.stat();
+            await assertCurrentRecordPath(path, details);
+            const uid = typeof process.getuid === "function" ? process.getuid() : undefined;
+            assertSafeOpenedRecord(details, uid);
+            let validatedTemporaryLink = false;
+            if (details.nlink !== 1) {
+                if (details.nlink !== 2) {
+                    throw new Error("record identity or permissions are unsafe");
+                }
+                const expectedPrefix = `.${keyHash}.`;
+                let matchingTemporaryLinks = 0;
+                for (const entry of await readdir(stateDir, { withFileTypes: true })) {
+                    if (!entry.name.startsWith(expectedPrefix)
+                        || !TEMPORARY_RECORD_FILE_PATTERN.test(entry.name)) {
+                        continue;
+                    }
+                    let candidate;
+                    try {
+                        candidate = await lstat(resolve(stateDir, entry.name));
+                    }
+                    catch (error) {
+                        if (isErrno(error, "ENOENT")) {
+                            continue;
+                        }
+                        throw error;
+                    }
+                    if (candidate.isFile()
+                        && !candidate.isSymbolicLink()
+                        && candidate.dev === details.dev
+                        && candidate.ino === details.ino
+                        && (candidate.mode & 0o777) === 0o600
+                        && (uid === undefined || candidate.uid === uid)) {
+                        matchingTemporaryLinks += 1;
+                    }
+                }
+                // The publisher may unlink its staging name while the directory is
+                // scanned. Re-read the opened inode before deciding whether its second
+                // link is the one expected from atomic publication.
+                details = await handle.stat();
+                assertSafeOpenedRecord(details, uid);
+                if (details.nlink !== 1 && (details.nlink !== 2 || matchingTemporaryLinks !== 1)) {
+                    throw new Error("record identity or permissions are unsafe");
+                }
+                validatedTemporaryLink = details.nlink === 2;
+            }
+            await assertCurrentRecordPath(path, details);
+            const raw = await readFile(handle);
+            const finalDetails = await handle.stat();
+            assertSafeOpenedRecord(finalDetails, uid);
+            if (finalDetails.dev !== details.dev
+                || finalDetails.ino !== details.ino
+                || finalDetails.size !== raw.byteLength
+                || (finalDetails.nlink !== 1 && !(validatedTemporaryLink && finalDetails.nlink === 2))) {
+                throw new Error("record identity or permissions are unsafe");
+            }
+            await assertCurrentRecordPath(path, finalDetails);
+            return raw;
+        }
+        catch (error) {
+            if (!(error instanceof RecordPathChangedError)) {
+                throw error;
+            }
+            lastPathChange = error;
+        }
+        finally {
+            await handle.close();
+        }
+    }
+    throw lastPathChange ?? new RecordPathChangedError();
+}
+function assertSafeOpenedRecord(details, uid) {
+    if (!details.isFile()
+        || (details.mode & 0o777) !== 0o600
+        || details.size > MAX_RECORD_BYTES
+        || (uid !== undefined && details.uid !== uid)) {
+        throw new Error("record identity or permissions are unsafe");
+    }
+}
+async function assertCurrentRecordPath(path, opened) {
+    let current;
+    try {
+        current = await lstat(path);
+    }
+    catch (error) {
+        if (isErrno(error, "ENOENT")) {
+            throw new RecordPathChangedError();
+        }
+        throw error;
+    }
+    if (!current.isFile() || current.isSymbolicLink()) {
+        throw new Error("record identity or permissions are unsafe");
+    }
+    if (current.dev !== opened.dev || current.ino !== opened.ino) {
+        throw new RecordPathChangedError();
+    }
+}
 async function assertReplaceableRecord(path) {
     try {
         const details = await lstat(path);