@nicknisi/pi-relay 0.2.0 → 0.3.1

package/dist/mailbox.js

@@ -4,94 +4,184 @@
  * Guarantees (each pinned by a test):
  * - A reader never sees half a letter: writers rename into place; readers
  *   only look at `*.json`.
- * - Nothing is delivered twice: a letter is unlinked as it is read, BEFORE
- *   the caller handles it.
+ * - A letter is deleted only once consumed: drain unlinks as it reads, and
+ *   the durable claim flow deletes only on explicit ack — a crashed or
+ *   failed delivery leaves the letter recoverable (recoverInboxClaims) or
+ *   requeueable.
  * - A corrupt letter is discarded on read, so it cannot poison every drain.
  * - Consumption is the receipt: the sender learns "delivered" only when the
- *   letter actually disappeared from the target's inbox.
+ *   letter actually disappeared from the target's inbox and durable claims.
  * - Every deposit and every delivery appends one append-only audit line —
  *   drain-as-receipt must not destroy evidence. The log never holds a full
  *   body, only a short preview.
  */
-import * as fs from 'node:fs';
+import { randomBytes } from 'node:crypto';
 import * as path from 'node:path';
-import { asksDir, inboxDir } from './registry.js';
+import { assertPathSegment, openRelayRoot, rethrowFilesystemError, RelayDirectoryHandle, RelayFilesystemError, } from './filesystem.js';
 export const MAX_BODY_CHARS = 32 * 1024;
+const MESSAGE_ID_PATTERN = /^[a-zA-Z0-9][a-zA-Z0-9_-]{0,127}$/;
+const INBOX_FILE_TOKEN_PATTERN = /^(0|[1-9][0-9]*)-([a-zA-Z0-9][a-zA-Z0-9_-]{0,127})\.json$/;
+const INBOX_CLAIM_TOKEN_PATTERN = /^[a-f0-9]{32}$/;
 function letterFileName(letter) {
-    return `${letter.ts}-${letter.id.slice(0, 6)}.json`;
+    if (!MESSAGE_ID_PATTERN.test(letter.id))
+        throw new TypeError(`Invalid relay message id: ${letter.id}`);
+    if (!Number.isSafeInteger(letter.ts) || letter.ts < 0) {
+        throw new TypeError(`Invalid relay letter timestamp: ${letter.ts}`);
+    }
+    const name = `${letter.ts}-${letter.id}.json`;
+    assertPathSegment(name, 'relay letter file name');
+    return name;
+}
+function inboxFileTokenParts(fileToken) {
+    const match = INBOX_FILE_TOKEN_PATTERN.exec(fileToken);
+    if (match === null)
+        return null;
+    const ts = Number(match[1]);
+    return Number.isSafeInteger(ts) ? { ts, id: match[2] } : null;
+}
+function assertInboxClaimToken(claimToken) {
+    if (!INBOX_CLAIM_TOKEN_PATTERN.test(claimToken)) {
+        throw new TypeError(`Invalid relay inbox claim token: ${claimToken}`);
+    }
 }
-/** Atomic deposit: write to a tmp sibling, then rename into place. */
+function assertInboxFileToken(fileToken) {
+    if (inboxFileTokenParts(fileToken) === null) {
+        throw new TypeError(`Invalid relay inbox file token: ${fileToken}`);
+    }
+}
+/** Atomic deposit: write to a random exclusive tmp sibling, then rename into place. */
 export function deposit(root, toAddr, letter) {
-    const dir = inboxDir(root, toAddr);
-    fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
-    const name = letterFileName(letter);
-    const tmp = path.join(dir, `${name}.${process.pid}.tmp`);
-    fs.writeFileSync(tmp, JSON.stringify(letter), { mode: 0o600 });
-    fs.renameSync(tmp, path.join(dir, name));
-    // Send-side choke point: every send/ask/reply/cancel goes through here.
-    appendAudit(root, {
-        ts: Date.now(),
-        event: 'deposit',
-        kind: letter.kind,
-        from: letter.from.addr,
-        to: toAddr,
-        messageId: letter.id,
-        preview: previewBody(letter.body),
-    });
+    assertPathSegment(toAddr, 'relay address');
+    const relay = openRelayRoot(root, true);
+    try {
+        // Refuse an unsafe audit target before committing the atomic letter; this
+        // avoids reporting failure after a delivery has already landed.
+        relay.verifyFile('audit.log');
+        const inbox = relay.openDirectory(`${toAddr}.inbox`, true);
+        try {
+            inbox.writeFileAtomic(letterFileName(letter), JSON.stringify(letter));
+        }
+        finally {
+            inbox.close();
+        }
+        // Send-side choke point: every send/ask/reply/cancel goes through here.
+        appendAuditToDirectory(relay, {
+            ts: Date.now(),
+            event: 'deposit',
+            kind: letter.kind,
+            from: letter.from.addr,
+            to: toAddr,
+            messageId: letter.id,
+            preview: previewBody(letter.body),
+        });
+    }
+    finally {
+        relay.close();
+    }
 }
 /**
  * Take every letter in the inbox, oldest first. Each letter is unlinked as
  * it is read — before parsing — so it can never be delivered twice. The
- * tradeoff: a drained letter that is never delivered would be lost, so the
- * caller must re-deposit any letter it fails to deliver (checkInbox does).
+ * tradeoff: a drained letter that is never delivered is lost, so callers
+ * that can fail delivery should prefer the durable claim flow (claimInbox →
+ * readClaimedLetter → ackClaimedLetter/requeueClaimedLetter), which only
+ * deletes a letter once it has actually been handed off. The pi entry point
+ * (index.ts checkInbox) uses claims; drain remains for core consumers that
+ * handle drained letters synchronously.
  */
 export function drain(root, addr) {
-    const dir = inboxDir(root, addr);
-    let names;
-    try {
-        names = fs
-            .readdirSync(dir)
-            .filter((f) => f.endsWith('.json'))
-            .sort();
-    }
-    catch {
+    assertPathSegment(addr, 'relay address');
+    const relay = openRelayRoot(root);
+    if (relay === null)
         return [];
-    }
-    const out = [];
-    for (const name of names) {
-        const file = path.join(dir, name);
-        let raw;
-        try {
-            raw = fs.readFileSync(file, 'utf8');
-        }
-        catch {
-            continue;
-        }
-        try {
-            fs.unlinkSync(file);
-        }
-        catch {
-            continue; // another drainer took it
-        }
+    try {
+        const inbox = relay.openDirectory(`${addr}.inbox`);
+        if (inbox === null)
+            return [];
         try {
-            const parsed = JSON.parse(raw);
-            if (parsed && typeof parsed.id === 'string' && typeof parsed.body === 'string') {
-                out.push(parsed);
+            const names = inbox
+                .readDirectory()
+                .filter((entry) => {
+                if (!entry.name.endsWith('.json'))
+                    return false;
+                if (entry.isSymbolicLink())
+                    throw new RelayFilesystemError(`Refusing symlinked relay letter: ${entry.name}`);
+                return entry.isFile();
+            })
+                .map((entry) => entry.name)
+                .sort();
+            const out = [];
+            for (const name of names) {
+                let raw;
+                try {
+                    raw = inbox.readFile(name);
+                }
+                catch (error) {
+                    rethrowFilesystemError(error);
+                    continue;
+                }
+                if (raw === null)
+                    continue;
+                try {
+                    if (!inbox.unlinkFile(name))
+                        continue; // another drainer took it
+                }
+                catch (error) {
+                    rethrowFilesystemError(error);
+                    continue;
+                }
+                try {
+                    const parsed = JSON.parse(raw);
+                    if (parsed && typeof parsed.id === 'string' && typeof parsed.body === 'string')
+                        out.push(parsed);
+                }
+                catch {
+                    // corrupt letter — discarded, cannot fail future drains
+                }
             }
+            return out;
         }
-        catch {
-            // corrupt letter — discarded, cannot fail future drains
+        finally {
+            inbox.close();
         }
     }
-    return out;
+    catch (error) {
+        rethrowFilesystemError(error);
+        return [];
+    }
+    finally {
+        relay.close();
+    }
 }
 export function unreadCount(root, addr) {
+    assertPathSegment(addr, 'relay address');
+    const relay = openRelayRoot(root);
+    if (relay === null)
+        return 0;
     try {
-        return fs.readdirSync(inboxDir(root, addr)).filter((f) => f.endsWith('.json')).length;
+        const inbox = relay.openDirectory(`${addr}.inbox`);
+        if (inbox === null)
+            return 0;
+        try {
+            return inbox.readDirectory().filter((entry) => {
+                if (!entry.name.endsWith('.json'))
+                    return false;
+                if (entry.isSymbolicLink())
+                    throw new RelayFilesystemError(`Refusing symlinked relay letter: ${entry.name}`);
+                return entry.isFile();
+            }).length;
+        }
+        finally {
+            inbox.close();
+        }
     }
-    catch {
+    catch (error) {
+        rethrowFilesystemError(error);
         return 0;
     }
+    finally {
+        relay.close();
+    }
 }
 /**
  * Watch an inbox for new mail. fs.watch with a 3s poll fallback (watch can
@@ -100,85 +190,407 @@ export function unreadCount(root, addr) {
  * a process alive.
  */
 export function watchInbox(root, addr, onMail) {
-    const dir = inboxDir(root, addr);
-    fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+    assertPathSegment(addr, 'relay address');
+    let relay = null;
+    let inbox = null;
     let watcher;
     try {
-        watcher = fs.watch(dir, () => onMail());
+        relay = openRelayRoot(root, true);
+        inbox = relay.openDirectory(`${addr}.inbox`, true);
+        watcher = inbox.watch(onMail);
         watcher.unref();
     }
-    catch {
-        // poll-only fallback
+    catch (error) {
+        inbox?.close();
+        relay?.close();
+        inbox = null;
+        relay = null;
+        rethrowFilesystemError(error);
+        // poll-only fallback for ordinary watch failures
     }
     const poll = setInterval(onMail, 3000);
     poll.unref();
     return () => {
         watcher?.close();
         clearInterval(poll);
+        inbox?.close();
+        relay?.close();
     };
 }
+function claimsDirectoryName(addr) {
+    return `${addr}.claims`;
+}
+function inboxFileTokens(directory) {
+    return directory
+        .readDirectory()
+        .filter((entry) => {
+        if (inboxFileTokenParts(entry.name) === null)
+            return false;
+        if (entry.isSymbolicLink())
+            throw new RelayFilesystemError(`Refusing symlinked claimed letter: ${entry.name}`);
+        return entry.isFile();
+    })
+        .map((entry) => entry.name)
+        .sort();
+}
+/** Atomically detach the current non-empty inbox and return its durable tokens. */
+export function claimInbox(root, addr) {
+    assertPathSegment(addr, 'relay address');
+    const relay = openRelayRoot(root, true);
+    try {
+        const inboxName = `${addr}.inbox`;
+        const inbox = relay.openDirectory(inboxName);
+        if (inbox === null)
+            return null;
+        try {
+            if (inboxFileTokens(inbox).length === 0)
+                return null;
+        }
+        finally {
+            inbox.close();
+        }
+        const claims = relay.openDirectory(claimsDirectoryName(addr), true);
+        try {
+            let claimToken = '';
+            for (let attempt = 0; attempt < 10; attempt++) {
+                const candidate = randomBytes(16).toString('hex');
+                const existing = claims.openDirectory(candidate);
+                if (existing === null) {
+                    claimToken = candidate;
+                    break;
+                }
+                existing.close();
+            }
+            if (claimToken === '')
+                throw new Error('Could not allocate an exclusive relay inbox claim token');
+            const claimed = relay.moveDirectoryTo(inboxName, claims, claimToken);
+            if (claimed === null)
+                return null;
+            try {
+                claimed.sync();
+                claims.sync();
+                const replacement = relay.openDirectory(inboxName, true);
+                replacement.close();
+                relay.sync();
+                return { claimToken, fileTokens: inboxFileTokens(claimed) };
+            }
+            finally {
+                claimed.close();
+            }
+        }
+        finally {
+            claims.close();
+        }
+    }
+    finally {
+        relay.close();
+    }
+}
+/** Enumerate durable claims left by this or a crashed consumer. */
+export function recoverInboxClaims(root, addr) {
+    assertPathSegment(addr, 'relay address');
+    const relay = openRelayRoot(root);
+    if (relay === null)
+        return [];
+    try {
+        const claims = relay.openDirectory(claimsDirectoryName(addr));
+        if (claims === null)
+            return [];
+        try {
+            const out = [];
+            for (const entry of claims.readDirectory()) {
+                if (!INBOX_CLAIM_TOKEN_PATTERN.test(entry.name))
+                    continue;
+                if (entry.isSymbolicLink())
+                    throw new RelayFilesystemError(`Refusing symlinked inbox claim: ${entry.name}`);
+                if (!entry.isDirectory())
+                    continue;
+                const claim = claims.openDirectory(entry.name);
+                if (claim === null)
+                    continue;
+                try {
+                    out.push({ claimToken: entry.name, fileTokens: inboxFileTokens(claim) });
+                }
+                finally {
+                    claim.close();
+                }
+            }
+            return out.sort((left, right) => left.claimToken.localeCompare(right.claimToken));
+        }
+        finally {
+            claims.close();
+        }
+    }
+    finally {
+        relay.close();
+    }
+}
+/** Read and validate one claimed letter without exposing or following a path. */
+export function readClaimedLetter(root, addr, claimToken, fileToken) {
+    assertPathSegment(addr, 'relay address');
+    assertInboxClaimToken(claimToken);
+    assertInboxFileToken(fileToken);
+    const expected = inboxFileTokenParts(fileToken);
+    const relay = openRelayRoot(root);
+    if (relay === null)
+        return null;
+    try {
+        const claims = relay.openDirectory(claimsDirectoryName(addr));
+        if (claims === null)
+            return null;
+        try {
+            const claim = claims.openDirectory(claimToken);
+            if (claim === null)
+                return null;
+            try {
+                const raw = claim.readFile(fileToken);
+                if (raw === null)
+                    return null;
+                const parsed = JSON.parse(raw);
+                if (parsed === null ||
+                    typeof parsed !== 'object' ||
+                    parsed.id !== expected.id ||
+                    parsed.ts !== expected.ts ||
+                    typeof parsed.body !== 'string') {
+                    return null;
+                }
+                return parsed;
+            }
+            catch (error) {
+                rethrowFilesystemError(error);
+                return null;
+            }
+            finally {
+                claim.close();
+            }
+        }
+        finally {
+            claims.close();
+        }
+    }
+    finally {
+        relay.close();
+    }
+}
+function finishClaimedLetter(root, addr, claimToken, fileToken, requeue) {
+    assertPathSegment(addr, 'relay address');
+    assertInboxClaimToken(claimToken);
+    assertInboxFileToken(fileToken);
+    const relay = openRelayRoot(root, requeue);
+    if (relay === null)
+        return false;
+    try {
+        const claims = relay.openDirectory(claimsDirectoryName(addr));
+        if (claims === null)
+            return false;
+        try {
+            const claim = claims.openDirectory(claimToken);
+            if (claim === null)
+                return false;
+            let finished;
+            try {
+                if (requeue) {
+                    const inbox = relay.openDirectory(`${addr}.inbox`, true);
+                    try {
+                        finished = claim.moveFileTo(fileToken, inbox);
+                        relay.sync();
+                    }
+                    finally {
+                        inbox.close();
+                    }
+                }
+                else {
+                    finished = claim.unlinkFile(fileToken);
+                    if (finished)
+                        claim.sync();
+                }
+            }
+            finally {
+                claim.close();
+            }
+            if (finished)
+                claims.removeEmptyDirectory(claimToken);
+            return finished;
+        }
+        finally {
+            claims.close();
+        }
+    }
+    finally {
+        relay.close();
+    }
+}
+/** Permanently acknowledge/delete one claimed letter. Idempotent. */
+export function ackClaimedLetter(root, addr, claimToken, fileToken) {
+    return finishClaimedLetter(root, addr, claimToken, fileToken, false);
+}
+/** Atomically return one claimed letter to the current inbox. */
+export function requeueClaimedLetter(root, addr, claimToken, fileToken) {
+    return finishClaimedLetter(root, addr, claimToken, fileToken, true);
+}
 const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+function fileExistsInClaims(relay, addr, fileName) {
+    const claims = relay.openDirectory(claimsDirectoryName(addr));
+    if (claims === null)
+        return false;
+    try {
+        for (const entry of claims.readDirectory()) {
+            if (!INBOX_CLAIM_TOKEN_PATTERN.test(entry.name))
+                continue;
+            if (entry.isSymbolicLink())
+                throw new RelayFilesystemError(`Refusing symlinked inbox claim: ${entry.name}`);
+            if (!entry.isDirectory())
+                continue;
+            const claim = claims.openDirectory(entry.name);
+            if (claim === null)
+                continue;
+            try {
+                if (claim.fileExists(fileName))
+                    return true;
+            }
+            finally {
+                claim.close();
+            }
+        }
+        return false;
+    }
+    finally {
+        claims.close();
+    }
+}
+function receiptFileExists(relay, addr, fileName) {
+    // Check claims on both sides of the live inbox. This avoids observing a
+    // false absence while a descriptor-relative rename moves in either
+    // direction between a claim and the current inbox.
+    if (fileExistsInClaims(relay, addr, fileName))
+        return true;
+    const inbox = relay.openDirectory(`${addr}.inbox`);
+    if (inbox !== null) {
+        try {
+            if (inbox.fileExists(fileName))
+                return true;
+        }
+        finally {
+            inbox.close();
+        }
+    }
+    return fileExistsInClaims(relay, addr, fileName);
+}
 /**
  * Consumption receipt: after depositing to a LIVE target, wait briefly for
- * the letter to vanish. 'delivered' means the receiver's drainer took it —
- * stronger than any transport ack.
+ * the exact letter to vanish from both the live inbox and durable claims.
+ * 'delivered' means the receiver acknowledged it, not merely claimed it.
  */
 export async function awaitReceipt(root, toAddr, letter, timeoutMs = 1500) {
-    const file = path.join(inboxDir(root, toAddr), letterFileName(letter));
-    const deadline = Date.now() + timeoutMs;
-    while (Date.now() < deadline) {
-        if (!fs.existsSync(file))
-            return 'delivered';
-        await sleep(100);
+    assertPathSegment(toAddr, 'relay address');
+    const relay = openRelayRoot(root);
+    if (relay === null)
+        return 'delivered';
+    try {
+        const fileName = letterFileName(letter);
+        const deadline = Date.now() + timeoutMs;
+        while (Date.now() < deadline) {
+            if (!receiptFileExists(relay, toAddr, fileName))
+                return 'delivered';
+            await sleep(100);
+        }
+        return receiptFileExists(relay, toAddr, fileName) ? 'queued' : 'delivered';
+    }
+    finally {
+        relay.close();
     }
-    return fs.existsSync(file) ? 'queued' : 'delivered';
 }
-function asksPath(root, addr, askId) {
-    return path.join(asksDir(root, addr), `${askId}.json`);
+function askFileName(askId) {
+    assertPathSegment(askId, 'relay ask id');
+    return `${askId}.json`;
 }
-function outAskPath(root, addr, askId) {
-    return path.join(asksDir(root, addr), `out-${askId}.json`);
+function outAskFileName(askId) {
+    assertPathSegment(askId, 'relay ask id');
+    return `out-${askId}.json`;
 }
-function writeJson0600(file, value) {
-    fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
-    const tmp = `${file}.${process.pid}.tmp`;
-    fs.writeFileSync(tmp, JSON.stringify(value), { mode: 0o600 });
-    fs.renameSync(tmp, file);
+function writeAskJson(root, addr, fileName, value) {
+    assertPathSegment(addr, 'relay address');
+    const relay = openRelayRoot(root, true);
+    try {
+        const asks = relay.openDirectory(`${addr}.asks`, true);
+        try {
+            asks.writeFileAtomic(fileName, JSON.stringify(value));
+        }
+        finally {
+            asks.close();
+        }
+    }
+    finally {
+        relay.close();
+    }
 }
 export function trackIncomingAsk(root, addr, letter) {
-    writeJson0600(asksPath(root, addr, letter.id), letter);
+    writeAskJson(root, addr, askFileName(letter.id), letter);
 }
 export function trackOutgoingAsk(root, addr, out) {
-    writeJson0600(outAskPath(root, addr, out.askId), out);
+    writeAskJson(root, addr, outAskFileName(out.askId), out);
 }
-export function readIncomingAsk(root, addr, askId) {
+function readAskFile(root, addr, fileName) {
+    assertPathSegment(addr, 'relay address');
+    const relay = openRelayRoot(root);
+    if (relay === null)
+        return null;
     try {
-        const parsed = JSON.parse(fs.readFileSync(asksPath(root, addr, askId), 'utf8'));
-        return parsed && typeof parsed.id === 'string' ? parsed : null;
+        const asks = relay.openDirectory(`${addr}.asks`);
+        if (asks === null)
+            return null;
+        try {
+            const raw = asks.readFile(fileName);
+            return raw === null ? null : JSON.parse(raw);
+        }
+        finally {
+            asks.close();
+        }
     }
-    catch {
+    catch (error) {
+        rethrowFilesystemError(error);
         return null;
     }
+    finally {
+        relay.close();
+    }
+}
+export function readIncomingAsk(root, addr, askId) {
+    const parsed = readAskFile(root, addr, askFileName(askId));
+    return parsed && typeof parsed.id === 'string' ? parsed : null;
 }
 export function readOutgoingAsk(root, addr, askId) {
-    try {
-        const parsed = JSON.parse(fs.readFileSync(outAskPath(root, addr, askId), 'utf8'));
-        return parsed && typeof parsed.toAddr === 'string' ? parsed : null;
-    }
-    catch {
-        return null;
-    }
+    const parsed = readAskFile(root, addr, outAskFileName(askId));
+    return parsed && typeof parsed.toAddr === 'string' ? parsed : null;
 }
 /** Remove both sides of an ask id (incoming and/or outgoing). Idempotent. */
 export function clearAsk(root, addr, askId) {
-    for (const file of [asksPath(root, addr, askId), outAskPath(root, addr, askId)]) {
+    assertPathSegment(addr, 'relay address');
+    const relay = openRelayRoot(root);
+    if (relay === null)
+        return;
+    try {
+        const asks = relay.openDirectory(`${addr}.asks`);
+        if (asks === null)
+            return;
         try {
-            fs.unlinkSync(file);
+            for (const fileName of [askFileName(askId), outAskFileName(askId)]) {
+                try {
+                    asks.unlinkFile(fileName);
+                }
+                catch (error) {
+                    rethrowFilesystemError(error);
+                    // deletion remains best-effort for ordinary I/O failures
+                }
+            }
         }
-        catch {
-            // already gone
+        finally {
+            asks.close();
         }
     }
+    finally {
+        relay.close();
+    }
 }
 const AUDIT_PREVIEW_CHARS = 80;
 /** Whitespace-collapsed body preview — never the full payload. */
@@ -197,40 +609,57 @@ export function auditLogPath(root) {
 }
 /** Audit log cap: at ~1 MB the current log becomes audit.log.1 (single generation) and a fresh log starts. */
 const AUDIT_MAX_BYTES = 1024 * 1024;
+function appendAuditToDirectory(directory, record) {
+    try {
+        const size = directory.appendFile('audit.log', `${JSON.stringify(record)}\n`);
+        // Bounded growth: rotate once past the cap, keeping one previous generation.
+        if (size > AUDIT_MAX_BYTES)
+            directory.renameFile('audit.log', 'audit.log.1');
+    }
+    catch {
+        // audit failure (including an unsafe path) never breaks the mail path
+    }
+}
 /** Append one audit record. Best-effort: never throws (audit must not break delivery). */
 export function appendAudit(root, record) {
+    let relay = null;
     try {
-        const file = auditLogPath(root);
-        if (!fs.existsSync(file))
-            fs.writeFileSync(file, '', { mode: 0o600 });
-        fs.appendFileSync(file, `${JSON.stringify(record)}\n`);
-        // Bounded growth: rotate once past the cap, keeping one previous generation.
-        if (fs.statSync(file).size > AUDIT_MAX_BYTES) {
-            fs.renameSync(file, `${file}.1`);
-        }
+        relay = openRelayRoot(root, true);
+        appendAuditToDirectory(relay, record);
     }
     catch {
-        // audit failure never breaks the mail path
+        // audit failure (including an unsafe path) never breaks the mail path
+    }
+    finally {
+        relay?.close();
     }
 }
 /** Read the last `limit` audit entries (oldest-first within that tail). */
 export function readAudit(root, limit = 50) {
+    const relay = openRelayRoot(root);
+    if (relay === null)
+        return [];
     let raw;
     try {
-        raw = fs.readFileSync(auditLogPath(root), 'utf8');
+        raw = relay.readFile('audit.log');
     }
-    catch {
+    catch (error) {
+        rethrowFilesystemError(error);
         return [];
     }
+    finally {
+        relay.close();
+    }
+    if (raw === null)
+        return [];
     const out = [];
     for (const line of raw.split('\n')) {
         if (line.length === 0)
             continue;
         try {
             const parsed = JSON.parse(line);
-            if (parsed && typeof parsed.ts === 'number' && typeof parsed.event === 'string') {
+            if (parsed && typeof parsed.ts === 'number' && typeof parsed.event === 'string')
                 out.push(parsed);
-            }
         }
         catch {
             // skip corrupt line — append-only, never fatal
@@ -246,26 +675,86 @@ export function resolveAskByRef(root, addr, replyTo) {
 }
 /** Asks we have received and not yet answered, oldest first. */
 export function pendingAsks(root, addr) {
-    let names;
+    assertPathSegment(addr, 'relay address');
+    const relay = openRelayRoot(root);
+    if (relay === null)
+        return [];
     try {
-        names = fs
-            .readdirSync(asksDir(root, addr))
-            .filter((f) => f.endsWith('.json') && !f.startsWith('out-'))
-            .sort();
+        const asks = relay.openDirectory(`${addr}.asks`);
+        if (asks === null)
+            return [];
+        try {
+            const names = asks
+                .readDirectory()
+                .filter((entry) => {
+                if (!entry.name.endsWith('.json') || entry.name.startsWith('out-'))
+                    return false;
+                if (entry.isSymbolicLink())
+                    throw new RelayFilesystemError(`Refusing symlinked relay ask: ${entry.name}`);
+                return entry.isFile();
+            })
+                .map((entry) => entry.name)
+                .sort();
+            const out = [];
+            for (const name of names) {
+                try {
+                    const raw = asks.readFile(name);
+                    if (raw === null)
+                        continue;
+                    const parsed = JSON.parse(raw);
+                    if (parsed && typeof parsed.id === 'string')
+                        out.push(parsed);
+                }
+                catch (error) {
+                    rethrowFilesystemError(error);
+                    // skip corrupt entry
+                }
+            }
+            return out;
+        }
+        finally {
+            asks.close();
+        }
     }
-    catch {
+    catch (error) {
+        rethrowFilesystemError(error);
         return [];
     }
-    const out = [];
-    for (const name of names) {
+    finally {
+        relay.close();
+    }
+}
+/** Outgoing ask ids, used by the Pi entry point for prefix resolution. */
+export function outgoingAskIds(root, addr) {
+    assertPathSegment(addr, 'relay address');
+    const relay = openRelayRoot(root);
+    if (relay === null)
+        return [];
+    try {
+        const asks = relay.openDirectory(`${addr}.asks`);
+        if (asks === null)
+            return [];
         try {
-            const parsed = JSON.parse(fs.readFileSync(path.join(asksDir(root, addr), name), 'utf8'));
-            if (parsed && typeof parsed.id === 'string')
-                out.push(parsed);
+            return asks
+                .readDirectory()
+                .filter((entry) => {
+                if (!entry.name.startsWith('out-') || !entry.name.endsWith('.json'))
+                    return false;
+                if (entry.isSymbolicLink())
+                    throw new RelayFilesystemError(`Refusing symlinked relay ask: ${entry.name}`);
+                return entry.isFile();
+            })
+                .map((entry) => entry.name.slice('out-'.length, -'.json'.length));
         }
-        catch {
-            // skip corrupt entry
+        finally {
+            asks.close();
         }
     }
-    return out;
+    catch (error) {
+        rethrowFilesystemError(error);
+        return [];
+    }
+    finally {
+        relay.close();
+    }
 }