@nicknisi/pi-relay 0.2.0 → 0.3.1

package/README.md

@@ -9,6 +9,20 @@ Architecture follows [shift-labs/pi-peer](https://github.com/shift-labs-ai/pi-pe
 - **`relay` tool** — actions: `list`, `list-cwd`, `send`, `ask`, `reply`, `pending`, `cancel`, `status`, `claim`, `watch`
 - **`/relay` command** — prints the session listing; `/relay log [N]` prints the last N audit entries (default 50)
 
+## Pi-free core API
+
+Node applications can use the registry, mailbox, and transport-policy primitives without loading the pi extension or its TUI dependencies:
+
+```ts
+import { OutboundPolicy, claimInbox, deposit, deriveAddr, type Letter } from '@nicknisi/pi-relay/core';
+```
+
+The `@nicknisi/pi-relay/core` subpath exports a narrow record and alias registry, mailbox and ask/audit operations, presence and sweep utilities, policy guards and constants, and their public types. Filesystem-facing operations validate canonical relay addresses, aliases, claim tokens, and ask/message IDs before accessing the relay root; path constructors and raw persistence helpers remain internal. Core uses Node built-ins plus Koffi's prebuilt native bridge for descriptor-relative Unix syscalls; Pi and TUI remain optional peers, so core-only installations do not fetch them. The package root remains the pi extension entry point; import `/core` from plain Node services and CLIs.
+
+### Durable core inbox claims
+
+A non-Pi consumer can atomically detach the current inbox with `claimInbox(root, addr)`. It receives only a stable `claimToken` and stable `fileTokens`, never filesystem paths. New deposits immediately land in a fresh inbox. `readClaimedLetter` reopens and validates a claimed letter without following links; after the consumer durably writes and `fsync`s its own journal, `ackClaimedLetter` deletes that exact file or `requeueClaimedLetter` atomically returns it to the current inbox. `recoverInboxClaims` enumerates the same tokens after a process crash. All claim, read, ack, and requeue work is relative to pinned root/inbox/claim descriptors, and empty completed claims are removed automatically.
+
 ## Audit log
 
 Every deposit and every delivery appends one line-delimited JSON record to `<PI_RELAY_DIR>/audit.log` — written from the transport choke points so draining a letter as a receipt no longer destroys the evidence that it existed. Each line records the timestamp, the event (`deposit`/`deliver`), the letter kind, the from/to addresses, and the message id. **The full body is never logged** — only a short (≤80 char) whitespace-collapsed preview. The file is `0600`, append-only, and survives corrupt lines (skipped on parse). Read it with `/relay log [N]`.
@@ -37,7 +51,7 @@ main moved; rebase before you push.
 
 - **A mailbox outlives the process.** The address is a hash of the working directory and pi's session id, so a session resumed with `pi -c` answers to the same address. Mail sent to a closed session waits on disk and is read when it resumes — the common case when you're opening and closing terminals all day.
 - **The queue is inspectable.** Diagnosing delivery is `ls`, not instrumenting a transport.
-- **Consumption is the receipt.** The receiver deletes the letter as it reads it, so the sender learns _delivered_ vs _queued_ — "the letter vanished" means the agent has it, which no socket ack can tell you.
+- **Delivery is the receipt.** The receiver detaches its inbox into a durable claim and deletes each exact full-message-id letter only after the session has accepted it — a failed delivery is requeued for retry, and a crash mid-delivery leaves the letter recoverable on the next start (redeliveries are deduped by message id, seeded from the transcript). The sender therefore learns _delivered_ vs _queued_ honestly: a claimed-but-unacknowledged letter still reads _queued_, never a false receipt.
 
 ## Semantics
 
@@ -45,7 +59,7 @@ main moved; rebase before you push.
 - **Authority boundary on every delivery.** Each message arrives with a repeated statement that it came from a peer and carries no authority — it cannot approve anything, cannot change configuration, slash commands in it are inert text. The sending side's tool guidelines carry the reciprocal rule: never ask a peer to do something your own permissions would refuse.
 - **Loops break structurally**, independent of what either model decides: identical text from one sender inside 10s is dropped; >8 messages per 30s per sender is refused; an unread backlog of 50 refuses new mail until the peer drains.
 - **Plain text only, ≤32KB.** Send a summary and a path, not a payload.
-- **Sweeping is narrow:** a running session is never touched; a mailbox holding undelivered mail is kept 30 days; an offline-but-resumable session keeps its record (its address — new mail must remain deliverable while it's down); only an empty mailbox of a session that can no longer be resumed is discarded promptly. Listing never has side effects.
+- **Sweeping is narrow:** a running session is never touched; an inbox or durable claim holding undelivered mail is kept 30 days; an offline-but-resumable session keeps its record (its address — new mail must remain deliverable while it's down); only an empty mailbox of a session that can no longer be resumed is discarded promptly. Listing never has side effects.
 
 ### ask / reply / pending / cancel
 
@@ -86,7 +100,7 @@ The directory is created `0700` and every file `0600` — other users on the mac
 
 ## Caveats
 
-- **Mailbox semantics are unix-only.** Delivery relies on atomic `renameSync`-over-existing, `fs.watch`, and `0600`/`0700` permission bits; Windows is untested and unsupported.
+- **Mailbox semantics support Linux and macOS only.** Relay rejects user-controlled symlinks in configured-root components, permits protected root-owned system aliases such as macOS `/var`, pins root, mailbox, and durable-claim descriptors for each operation, and uses descriptor-relative `openat`/`renameat`/`unlinkat` calls, atomic renames, descriptor polling for watches, and `0600`/`0700` permission bits. Windows is unsupported.
 - **One machine.** Delivery is a file landing in a directory; two sessions reach each other exactly when they share a filesystem. A container and its host cannot.
 - **Presence is heartbeat-accurate**, not instantaneous (within ~45s).
 - Delivery injects with `deliverAs: "steer"` (lands between tool calls) and `triggerTurn: true` (wakes an idle session).

package/core.ts

@@ -0,0 +1,314 @@
+/** Pi-free relay registry, mailbox, and policy API for non-extension consumers. */
+import {
+  ackClaimedLetter as ackClaimedLetterInternal,
+  awaitReceipt as awaitReceiptInternal,
+  claimInbox as claimInboxInternal,
+  clearAsk as clearAskInternal,
+  deposit as depositInternal,
+  drain as drainInternal,
+  pendingAsks as pendingAsksInternal,
+  readAudit as readAuditInternal,
+  readClaimedLetter as readClaimedLetterInternal,
+  readIncomingAsk as readIncomingAskInternal,
+  readOutgoingAsk as readOutgoingAskInternal,
+  recoverInboxClaims as recoverInboxClaimsInternal,
+  requeueClaimedLetter as requeueClaimedLetterInternal,
+  resolveAskByRef as resolveAskByRefInternal,
+  trackIncomingAsk as trackIncomingAskInternal,
+  trackOutgoingAsk as trackOutgoingAskInternal,
+  unreadCount as unreadCountInternal,
+  watchInbox as watchInboxInternal,
+  type AuditRecord,
+  type InboxClaim,
+  type Letter,
+  type OutAsk,
+} from './mailbox.js';
+import {
+  claimAlias as claimAliasInternal,
+  clearAlias as clearAliasInternal,
+  isValidAliasName as isValidAliasNameInternal,
+  listAliases as listAliasesInternal,
+  listRecords as listRecordsInternal,
+  presenceOf as presenceOfInternal,
+  readAlias as readAliasInternal,
+  readRecord as readRecordInternal,
+  sweep as sweepInternal,
+  type AliasRecord,
+  type Presence,
+  type SessionRecord,
+} from './registry.js';
+
+export {
+  MAX_BODY_CHARS,
+  previewBody,
+  type AuditRecord,
+  type InboxClaim,
+  type Letter,
+  type LetterKind,
+  type OutAsk,
+} from './mailbox.js';
+export {
+  BACKLOG_CAP,
+  DEDUPE_WINDOW_MS,
+  OutboundPolicy,
+  RATE_LIMIT_MAX,
+  RATE_LIMIT_WINDOW_MS,
+  inboundAccepts,
+  type OutboundVerdict,
+} from './policy.js';
+export {
+  HEARTBEAT_STALE_MS,
+  SWEEP_MAIL_KEEP_MS,
+  deriveAddr,
+  isValidAliasName,
+  type AliasRecord,
+  type Presence,
+  type SessionRecord,
+} from './registry.js';
+
+const ADDRESS_PATTERN = /^[a-f0-9]{12}$/;
+const ASK_ID_PATTERN = /^[a-zA-Z0-9][a-zA-Z0-9_-]{0,127}$/;
+const INBOX_CLAIM_TOKEN_PATTERN = /^[a-f0-9]{32}$/;
+const INBOX_FILE_TOKEN_PATTERN = /^(0|[1-9][0-9]*)-[a-zA-Z0-9][a-zA-Z0-9_-]{0,127}\.json$/;
+
+function assertAddress(addr: string): void {
+  if (!ADDRESS_PATTERN.test(addr)) throw new TypeError(`Invalid relay address: ${addr}`);
+}
+
+function assertAliasName(name: string): void {
+  if (!isValidAliasNameInternal(name)) throw new TypeError(`Invalid relay alias: ${name}`);
+}
+
+function assertAskId(id: string): void {
+  if (!ASK_ID_PATTERN.test(id)) throw new TypeError(`Invalid relay ask/message id: ${id}`);
+}
+
+function assertInboxClaimToken(token: string): void {
+  if (!INBOX_CLAIM_TOKEN_PATTERN.test(token)) throw new TypeError(`Invalid relay inbox claim token: ${token}`);
+}
+
+function assertInboxFileToken(token: string): void {
+  if (!INBOX_FILE_TOKEN_PATTERN.test(token)) throw new TypeError(`Invalid relay inbox file token: ${token}`);
+}
+
+function assertLetter(letter: Letter): void {
+  if (typeof letter !== 'object' || letter === null) throw new TypeError('Invalid relay letter');
+  assertAskId(letter.id);
+  if (typeof letter.from !== 'object' || letter.from === null) throw new TypeError('Invalid relay letter sender');
+  assertAddress(letter.from.addr);
+  if (typeof letter.from.name !== 'string' || typeof letter.from.cwd !== 'string') {
+    throw new TypeError('Invalid relay letter sender');
+  }
+  if (!['message', 'ask', 'reply', 'cancel'].includes(letter.kind) || typeof letter.body !== 'string') {
+    throw new TypeError('Invalid relay letter payload');
+  }
+  if (letter.replyTo !== undefined) assertAskId(letter.replyTo);
+  if (!Number.isSafeInteger(letter.ts) || letter.ts < 0) {
+    throw new TypeError(`Invalid relay letter timestamp: ${letter.ts}`);
+  }
+}
+
+function isSafeLetter(letter: Letter): boolean {
+  try {
+    assertLetter(letter);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function isSafeRecord(record: SessionRecord): boolean {
+  try {
+    assertAddress(record.addr);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function isSafeAlias(alias: AliasRecord): boolean {
+  try {
+    assertAliasName(alias.name);
+    assertAddress(alias.addr);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function isSafeOutAsk(out: OutAsk): boolean {
+  try {
+    assertAskId(out.askId);
+    assertAddress(out.toAddr);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function isSafeAuditRecord(record: AuditRecord): boolean {
+  try {
+    assertAddress(record.from);
+    assertAddress(record.to);
+    assertAskId(record.messageId);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export function readRecord(root: string, addr: string): SessionRecord | null {
+  assertAddress(addr);
+  const record = readRecordInternal(root, addr);
+  return record && isSafeRecord(record) ? record : null;
+}
+
+export function listRecords(root: string): SessionRecord[] {
+  return listRecordsInternal(root).filter(isSafeRecord);
+}
+
+export function presenceOf(record: SessionRecord, now: number = Date.now()): Presence {
+  assertAddress(record.addr);
+  return presenceOfInternal(record, now);
+}
+
+export function readAlias(root: string, name: string): AliasRecord | null {
+  assertAliasName(name);
+  const alias = readAliasInternal(root, name);
+  return alias && isSafeAlias(alias) ? alias : null;
+}
+
+export function listAliases(root: string): AliasRecord[] {
+  return listAliasesInternal(root).filter(isSafeAlias);
+}
+
+export function claimAlias(root: string, name: string, addr: string, sessionId: string): AliasRecord {
+  assertAliasName(name);
+  assertAddress(addr);
+  return claimAliasInternal(root, name, addr, sessionId);
+}
+
+export function clearAlias(root: string, name: string): void {
+  assertAliasName(name);
+  clearAliasInternal(root, name);
+}
+
+export function sweep(root: string, now: number = Date.now(), sessionExists?: (sessionId: string) => boolean): void {
+  if (!listRecordsInternal(root).every(isSafeRecord) || !listAliasesInternal(root).every(isSafeAlias)) {
+    throw new TypeError('Relay root contains an invalid address or alias');
+  }
+  sweepInternal(root, now, sessionExists);
+}
+
+export function deposit(root: string, toAddr: string, letter: Letter): void {
+  assertAddress(toAddr);
+  assertLetter(letter);
+  depositInternal(root, toAddr, letter);
+}
+
+export function drain(root: string, addr: string): Letter[] {
+  assertAddress(addr);
+  return drainInternal(root, addr).filter(isSafeLetter);
+}
+
+export function unreadCount(root: string, addr: string): number {
+  assertAddress(addr);
+  return unreadCountInternal(root, addr);
+}
+
+export function claimInbox(root: string, addr: string): InboxClaim | null {
+  assertAddress(addr);
+  return claimInboxInternal(root, addr);
+}
+
+export function recoverInboxClaims(root: string, addr: string): InboxClaim[] {
+  assertAddress(addr);
+  return recoverInboxClaimsInternal(root, addr);
+}
+
+export function readClaimedLetter(root: string, addr: string, claimToken: string, fileToken: string): Letter | null {
+  assertAddress(addr);
+  assertInboxClaimToken(claimToken);
+  assertInboxFileToken(fileToken);
+  const letter = readClaimedLetterInternal(root, addr, claimToken, fileToken);
+  return letter && isSafeLetter(letter) ? letter : null;
+}
+
+export function ackClaimedLetter(root: string, addr: string, claimToken: string, fileToken: string): boolean {
+  assertAddress(addr);
+  assertInboxClaimToken(claimToken);
+  assertInboxFileToken(fileToken);
+  return ackClaimedLetterInternal(root, addr, claimToken, fileToken);
+}
+
+export function requeueClaimedLetter(root: string, addr: string, claimToken: string, fileToken: string): boolean {
+  assertAddress(addr);
+  assertInboxClaimToken(claimToken);
+  assertInboxFileToken(fileToken);
+  return requeueClaimedLetterInternal(root, addr, claimToken, fileToken);
+}
+
+export function watchInbox(root: string, addr: string, onMail: () => void): () => void {
+  assertAddress(addr);
+  return watchInboxInternal(root, addr, onMail);
+}
+
+export async function awaitReceipt(
+  root: string,
+  toAddr: string,
+  letter: Letter,
+  timeoutMs = 1500,
+): Promise<'delivered' | 'queued'> {
+  assertAddress(toAddr);
+  assertLetter(letter);
+  return awaitReceiptInternal(root, toAddr, letter, timeoutMs);
+}
+
+export function trackIncomingAsk(root: string, addr: string, letter: Letter): void {
+  assertAddress(addr);
+  assertLetter(letter);
+  trackIncomingAskInternal(root, addr, letter);
+}
+
+export function trackOutgoingAsk(root: string, addr: string, out: OutAsk): void {
+  assertAddress(addr);
+  assertAskId(out.askId);
+  assertAddress(out.toAddr);
+  trackOutgoingAskInternal(root, addr, out);
+}
+
+export function readIncomingAsk(root: string, addr: string, askId: string): Letter | null {
+  assertAddress(addr);
+  assertAskId(askId);
+  const letter = readIncomingAskInternal(root, addr, askId);
+  return letter && isSafeLetter(letter) ? letter : null;
+}
+
+export function readOutgoingAsk(root: string, addr: string, askId: string): OutAsk | null {
+  assertAddress(addr);
+  assertAskId(askId);
+  const out = readOutgoingAskInternal(root, addr, askId);
+  return out && isSafeOutAsk(out) ? out : null;
+}
+
+export function clearAsk(root: string, addr: string, askId: string): void {
+  assertAddress(addr);
+  assertAskId(askId);
+  clearAskInternal(root, addr, askId);
+}
+
+export function resolveAskByRef(root: string, addr: string, replyTo: string): Letter | null {
+  assertAddress(addr);
+  assertAskId(replyTo);
+  const letter = resolveAskByRefInternal(root, addr, replyTo);
+  return letter && isSafeLetter(letter) ? letter : null;
+}
+
+export function pendingAsks(root: string, addr: string): Letter[] {
+  assertAddress(addr);
+  return pendingAsksInternal(root, addr).filter(isSafeLetter);
+}
+
+export function readAudit(root: string, limit = 50): AuditRecord[] {
+  return readAuditInternal(root, limit).filter(isSafeAuditRecord);
+}

package/dist/core.d.ts

@@ -0,0 +1,32 @@
+/** Pi-free relay registry, mailbox, and policy API for non-extension consumers. */
+import { type AuditRecord, type InboxClaim, type Letter, type OutAsk } from './mailbox.js';
+import { type AliasRecord, type Presence, type SessionRecord } from './registry.js';
+export { MAX_BODY_CHARS, previewBody, type AuditRecord, type InboxClaim, type Letter, type LetterKind, type OutAsk, } from './mailbox.js';
+export { BACKLOG_CAP, DEDUPE_WINDOW_MS, OutboundPolicy, RATE_LIMIT_MAX, RATE_LIMIT_WINDOW_MS, inboundAccepts, type OutboundVerdict, } from './policy.js';
+export { HEARTBEAT_STALE_MS, SWEEP_MAIL_KEEP_MS, deriveAddr, isValidAliasName, type AliasRecord, type Presence, type SessionRecord, } from './registry.js';
+export declare function readRecord(root: string, addr: string): SessionRecord | null;
+export declare function listRecords(root: string): SessionRecord[];
+export declare function presenceOf(record: SessionRecord, now?: number): Presence;
+export declare function readAlias(root: string, name: string): AliasRecord | null;
+export declare function listAliases(root: string): AliasRecord[];
+export declare function claimAlias(root: string, name: string, addr: string, sessionId: string): AliasRecord;
+export declare function clearAlias(root: string, name: string): void;
+export declare function sweep(root: string, now?: number, sessionExists?: (sessionId: string) => boolean): void;
+export declare function deposit(root: string, toAddr: string, letter: Letter): void;
+export declare function drain(root: string, addr: string): Letter[];
+export declare function unreadCount(root: string, addr: string): number;
+export declare function claimInbox(root: string, addr: string): InboxClaim | null;
+export declare function recoverInboxClaims(root: string, addr: string): InboxClaim[];
+export declare function readClaimedLetter(root: string, addr: string, claimToken: string, fileToken: string): Letter | null;
+export declare function ackClaimedLetter(root: string, addr: string, claimToken: string, fileToken: string): boolean;
+export declare function requeueClaimedLetter(root: string, addr: string, claimToken: string, fileToken: string): boolean;
+export declare function watchInbox(root: string, addr: string, onMail: () => void): () => void;
+export declare function awaitReceipt(root: string, toAddr: string, letter: Letter, timeoutMs?: number): Promise<'delivered' | 'queued'>;
+export declare function trackIncomingAsk(root: string, addr: string, letter: Letter): void;
+export declare function trackOutgoingAsk(root: string, addr: string, out: OutAsk): void;
+export declare function readIncomingAsk(root: string, addr: string, askId: string): Letter | null;
+export declare function readOutgoingAsk(root: string, addr: string, askId: string): OutAsk | null;
+export declare function clearAsk(root: string, addr: string, askId: string): void;
+export declare function resolveAskByRef(root: string, addr: string, replyTo: string): Letter | null;
+export declare function pendingAsks(root: string, addr: string): Letter[];
+export declare function readAudit(root: string, limit?: number): AuditRecord[];

package/dist/core.js

@@ -0,0 +1,223 @@
+/** Pi-free relay registry, mailbox, and policy API for non-extension consumers. */
+import { ackClaimedLetter as ackClaimedLetterInternal, awaitReceipt as awaitReceiptInternal, claimInbox as claimInboxInternal, clearAsk as clearAskInternal, deposit as depositInternal, drain as drainInternal, pendingAsks as pendingAsksInternal, readAudit as readAuditInternal, readClaimedLetter as readClaimedLetterInternal, readIncomingAsk as readIncomingAskInternal, readOutgoingAsk as readOutgoingAskInternal, recoverInboxClaims as recoverInboxClaimsInternal, requeueClaimedLetter as requeueClaimedLetterInternal, resolveAskByRef as resolveAskByRefInternal, trackIncomingAsk as trackIncomingAskInternal, trackOutgoingAsk as trackOutgoingAskInternal, unreadCount as unreadCountInternal, watchInbox as watchInboxInternal, } from './mailbox.js';
+import { claimAlias as claimAliasInternal, clearAlias as clearAliasInternal, isValidAliasName as isValidAliasNameInternal, listAliases as listAliasesInternal, listRecords as listRecordsInternal, presenceOf as presenceOfInternal, readAlias as readAliasInternal, readRecord as readRecordInternal, sweep as sweepInternal, } from './registry.js';
+export { MAX_BODY_CHARS, previewBody, } from './mailbox.js';
+export { BACKLOG_CAP, DEDUPE_WINDOW_MS, OutboundPolicy, RATE_LIMIT_MAX, RATE_LIMIT_WINDOW_MS, inboundAccepts, } from './policy.js';
+export { HEARTBEAT_STALE_MS, SWEEP_MAIL_KEEP_MS, deriveAddr, isValidAliasName, } from './registry.js';
+const ADDRESS_PATTERN = /^[a-f0-9]{12}$/;
+const ASK_ID_PATTERN = /^[a-zA-Z0-9][a-zA-Z0-9_-]{0,127}$/;
+const INBOX_CLAIM_TOKEN_PATTERN = /^[a-f0-9]{32}$/;
+const INBOX_FILE_TOKEN_PATTERN = /^(0|[1-9][0-9]*)-[a-zA-Z0-9][a-zA-Z0-9_-]{0,127}\.json$/;
+function assertAddress(addr) {
+    if (!ADDRESS_PATTERN.test(addr))
+        throw new TypeError(`Invalid relay address: ${addr}`);
+}
+function assertAliasName(name) {
+    if (!isValidAliasNameInternal(name))
+        throw new TypeError(`Invalid relay alias: ${name}`);
+}
+function assertAskId(id) {
+    if (!ASK_ID_PATTERN.test(id))
+        throw new TypeError(`Invalid relay ask/message id: ${id}`);
+}
+function assertInboxClaimToken(token) {
+    if (!INBOX_CLAIM_TOKEN_PATTERN.test(token))
+        throw new TypeError(`Invalid relay inbox claim token: ${token}`);
+}
+function assertInboxFileToken(token) {
+    if (!INBOX_FILE_TOKEN_PATTERN.test(token))
+        throw new TypeError(`Invalid relay inbox file token: ${token}`);
+}
+function assertLetter(letter) {
+    if (typeof letter !== 'object' || letter === null)
+        throw new TypeError('Invalid relay letter');
+    assertAskId(letter.id);
+    if (typeof letter.from !== 'object' || letter.from === null)
+        throw new TypeError('Invalid relay letter sender');
+    assertAddress(letter.from.addr);
+    if (typeof letter.from.name !== 'string' || typeof letter.from.cwd !== 'string') {
+        throw new TypeError('Invalid relay letter sender');
+    }
+    if (!['message', 'ask', 'reply', 'cancel'].includes(letter.kind) || typeof letter.body !== 'string') {
+        throw new TypeError('Invalid relay letter payload');
+    }
+    if (letter.replyTo !== undefined)
+        assertAskId(letter.replyTo);
+    if (!Number.isSafeInteger(letter.ts) || letter.ts < 0) {
+        throw new TypeError(`Invalid relay letter timestamp: ${letter.ts}`);
+    }
+}
+function isSafeLetter(letter) {
+    try {
+        assertLetter(letter);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function isSafeRecord(record) {
+    try {
+        assertAddress(record.addr);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function isSafeAlias(alias) {
+    try {
+        assertAliasName(alias.name);
+        assertAddress(alias.addr);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function isSafeOutAsk(out) {
+    try {
+        assertAskId(out.askId);
+        assertAddress(out.toAddr);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function isSafeAuditRecord(record) {
+    try {
+        assertAddress(record.from);
+        assertAddress(record.to);
+        assertAskId(record.messageId);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export function readRecord(root, addr) {
+    assertAddress(addr);
+    const record = readRecordInternal(root, addr);
+    return record && isSafeRecord(record) ? record : null;
+}
+export function listRecords(root) {
+    return listRecordsInternal(root).filter(isSafeRecord);
+}
+export function presenceOf(record, now = Date.now()) {
+    assertAddress(record.addr);
+    return presenceOfInternal(record, now);
+}
+export function readAlias(root, name) {
+    assertAliasName(name);
+    const alias = readAliasInternal(root, name);
+    return alias && isSafeAlias(alias) ? alias : null;
+}
+export function listAliases(root) {
+    return listAliasesInternal(root).filter(isSafeAlias);
+}
+export function claimAlias(root, name, addr, sessionId) {
+    assertAliasName(name);
+    assertAddress(addr);
+    return claimAliasInternal(root, name, addr, sessionId);
+}
+export function clearAlias(root, name) {
+    assertAliasName(name);
+    clearAliasInternal(root, name);
+}
+export function sweep(root, now = Date.now(), sessionExists) {
+    if (!listRecordsInternal(root).every(isSafeRecord) || !listAliasesInternal(root).every(isSafeAlias)) {
+        throw new TypeError('Relay root contains an invalid address or alias');
+    }
+    sweepInternal(root, now, sessionExists);
+}
+export function deposit(root, toAddr, letter) {
+    assertAddress(toAddr);
+    assertLetter(letter);
+    depositInternal(root, toAddr, letter);
+}
+export function drain(root, addr) {
+    assertAddress(addr);
+    return drainInternal(root, addr).filter(isSafeLetter);
+}
+export function unreadCount(root, addr) {
+    assertAddress(addr);
+    return unreadCountInternal(root, addr);
+}
+export function claimInbox(root, addr) {
+    assertAddress(addr);
+    return claimInboxInternal(root, addr);
+}
+export function recoverInboxClaims(root, addr) {
+    assertAddress(addr);
+    return recoverInboxClaimsInternal(root, addr);
+}
+export function readClaimedLetter(root, addr, claimToken, fileToken) {
+    assertAddress(addr);
+    assertInboxClaimToken(claimToken);
+    assertInboxFileToken(fileToken);
+    const letter = readClaimedLetterInternal(root, addr, claimToken, fileToken);
+    return letter && isSafeLetter(letter) ? letter : null;
+}
+export function ackClaimedLetter(root, addr, claimToken, fileToken) {
+    assertAddress(addr);
+    assertInboxClaimToken(claimToken);
+    assertInboxFileToken(fileToken);
+    return ackClaimedLetterInternal(root, addr, claimToken, fileToken);
+}
+export function requeueClaimedLetter(root, addr, claimToken, fileToken) {
+    assertAddress(addr);
+    assertInboxClaimToken(claimToken);
+    assertInboxFileToken(fileToken);
+    return requeueClaimedLetterInternal(root, addr, claimToken, fileToken);
+}
+export function watchInbox(root, addr, onMail) {
+    assertAddress(addr);
+    return watchInboxInternal(root, addr, onMail);
+}
+export async function awaitReceipt(root, toAddr, letter, timeoutMs = 1500) {
+    assertAddress(toAddr);
+    assertLetter(letter);
+    return awaitReceiptInternal(root, toAddr, letter, timeoutMs);
+}
+export function trackIncomingAsk(root, addr, letter) {
+    assertAddress(addr);
+    assertLetter(letter);
+    trackIncomingAskInternal(root, addr, letter);
+}
+export function trackOutgoingAsk(root, addr, out) {
+    assertAddress(addr);
+    assertAskId(out.askId);
+    assertAddress(out.toAddr);
+    trackOutgoingAskInternal(root, addr, out);
+}
+export function readIncomingAsk(root, addr, askId) {
+    assertAddress(addr);
+    assertAskId(askId);
+    const letter = readIncomingAskInternal(root, addr, askId);
+    return letter && isSafeLetter(letter) ? letter : null;
+}
+export function readOutgoingAsk(root, addr, askId) {
+    assertAddress(addr);
+    assertAskId(askId);
+    const out = readOutgoingAskInternal(root, addr, askId);
+    return out && isSafeOutAsk(out) ? out : null;
+}
+export function clearAsk(root, addr, askId) {
+    assertAddress(addr);
+    assertAskId(askId);
+    clearAskInternal(root, addr, askId);
+}
+export function resolveAskByRef(root, addr, replyTo) {
+    assertAddress(addr);
+    assertAskId(replyTo);
+    const letter = resolveAskByRefInternal(root, addr, replyTo);
+    return letter && isSafeLetter(letter) ? letter : null;
+}
+export function pendingAsks(root, addr) {
+    assertAddress(addr);
+    return pendingAsksInternal(root, addr).filter(isSafeLetter);
+}
+export function readAudit(root, limit = 50) {
+    return readAuditInternal(root, limit).filter(isSafeAuditRecord);
+}

package/dist/core.test.d.ts

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