@agnt-sdk/simon-server 0.0.0-stage → 0.1.1

package/dist/store/store.d.ts

@@ -0,0 +1,400 @@
+/**
+ * Everything the server keeps, behind one interface. The sqlite store implements it; any other store (an
+ * application may write one for its own database) proves itself with the contract suite in `contract.ts`.
+ *
+ * Rules every implementation keeps:
+ *   - **No clock.** Every time is passed in, as an ISO timestamp or a Date, so tests move time freely.
+ *   - **Uniqueness is part of the contract,** stated on each method that depends on it, and atomic: two
+ *     calls racing on the same key never both win. A database index is one way to keep it; it is not the
+ *     contract.
+ *   - **A method is one change.** What a method writes is all there or none of it, so a crash between two
+ *     calls never leaves half of one behind.
+ *   - **Queues are claimed, not read.** Work the server does later (deliveries, arrivals, inbox events, part
+ *     fetches, webhook posts) is a row it settles explicitly; nothing is lost by a crash, and a crash at worst
+ *     repeats work.
+ *   - **Retention is explicit.** Nothing expires except through `sweep`, which says what it removes.
+ *   - Methods return copies; mutating a returned record changes nothing stored.
+ */
+import type { AnyMessage, Claim, Hints, KeyEntry, SignedClaims } from '@agnt-sdk/simon-protocol';
+/** Reference-host admission limits, separate from protocol limits. Accepted retractions are never evicted. */
+export interface RetractionCapacity {
+    maxRecords: number;
+    maxPerAuthor: number;
+    maxBytes: number;
+}
+export declare class StoreCapacityError extends Error {
+    readonly code = "store_capacity";
+    constructor();
+}
+export declare function resolveRetractionCapacity(input?: Partial<RetractionCapacity>): RetractionCapacity;
+/**
+ * The most keys, revoked ones included, that adding a key may leave an agent with: four published
+ * documents' worth (PROTOCOL.md section 4 lists at most 32). A revoked key is kept so it never returns, which
+ * leaves history unbounded without a cap, and a Mongo agent document is limited to 16 MiB. Recovery is never
+ * refused for it: a recovery replaces every key with one, and refusing it would let a key holder block it.
+ */
+export declare const MAX_STORED_KEYS = 128;
+/** A key of an agent here: its entry in the agent's document, and a label for its own clients, never published. */
+export interface AgentKey extends KeyEntry {
+    label?: string;
+}
+/** An agent registered here. Its address and kind are fixed for the life of the address. */
+export interface Agent {
+    /** Private current authorization after recovery; absent for legacy temporal-key authorization. */
+    authorizedKeys?: string[];
+    /** Private Store authority epoch; never part of agent documents or account wire responses. */
+    authorityVersion?: number;
+    /**
+     * Private recovery epoch, advanced only when a recovery ends or authority over the address is reset:
+     * a recovery cancelled, completed or lapsed, a principal recovery, a retirement. Adding or revoking a key
+     * never advances it, so a key holder cannot void a mailbox code (register.ts). Absent means zero.
+     */
+    recoveryEpoch?: number;
+    /** Private last key cancellation, used by the host's recovery cooldown. */
+    recoveryKeyCancelledAt?: string;
+    address: string;
+    kind: 'solo' | 'paired';
+    /** The principal's identifier (the `for` header) of a paired agent; null for a solo one. */
+    principal: string | null;
+    /** Every key ever added, revoked ones included, oldest first. */
+    keys: AgentKey[];
+    /** Whether the address was bound by a code sent to it, so a code can recover it. */
+    mailbox: boolean;
+    createdAt: string;
+    /**
+     * When the address retired: it never serves anyone again and every key is revoked. Publishing optional
+     * retirement evidence is host policy; private hosting may withhold it.
+     */
+    retiredAt: string | null;
+    /** The key principal's unpairing that retired it, when one did, served in its retired document. */
+    unpairing?: string | null;
+}
+/** A message held here: written by an agent here, or accepted from another server. */
+export interface StoredMessage {
+    id: string;
+    message: AnyMessage;
+    /** The origin of the server that carried it; this server's own for a message written here. */
+    carrier: string;
+    /** Claims about the author: made by this server, or accepted from the carrier, as judged here. */
+    claims: Claim[];
+    /** The carrier's claims exactly as it signed them for this message (spec section 6.2), or null with none. */
+    signedClaims: SignedClaims | null;
+    receivedAt: string;
+    /** When `sweep` removes it, with everything tied to it. */
+    expiresAt: string;
+}
+/** A message in an agent's sync stream: one it received, or one it wrote here. */
+export interface SyncEntry {
+    /** Its position in the stream. */
+    cursor: number;
+    address: string;
+    id: string;
+    message: AnyMessage;
+    carrier: string;
+    claims: Claim[];
+    signedClaims: SignedClaims | null;
+    /** When it entered the stream. */
+    receivedAt: string;
+}
+/** A signal held for an agent here (CLIENT.md Signals), in its place in the agent's sync stream. */
+export interface HeldSignal {
+    cursor: number;
+    type: string;
+    from: string;
+    about: string;
+    at: string;
+}
+/** A page of an agent's sync stream. */
+export interface SyncPage {
+    messages: SyncEntry[];
+    signals: HeldSignal[];
+    /** The last position the page covers: the next page starts after it. */
+    cursor: number;
+    more: boolean;
+}
+/** A URL that wakes an agent here when something new reaches it (CLIENT.md sync, "Webhooks"). */
+export interface Webhook {
+    id: string;
+    address: string;
+    url: string;
+    /** The hash of the code posted to the URL, which the agent hands back to verify it. */
+    codeHash: string;
+    verified: boolean;
+    createdAt: string;
+    /** When posts to it began failing, without an answer since; null while it answers. */
+    failingSince: string | null;
+}
+/** A page of a listing, newest first: each record with its cursor, the message's id, which continues after it. */
+export interface Page {
+    records: {
+        cursor: string;
+        message: StoredMessage;
+    }[];
+    more: boolean;
+}
+/** Delivery of one message to the recipients on one domain. */
+export interface Delivery {
+    id: string;
+    domain: string;
+    recipients: string[];
+    /** The hints for these recipients, held only until the delivery ends. */
+    hints: Hints;
+    /** The server the domain last resolved to; null until it resolved. */
+    server: string | null;
+    status: 'pending' | 'delivered' | 'failed';
+    /** Why it failed, or why the last attempt did not succeed: a resolution outcome or an error code. */
+    reason: string | null;
+    attempts: number;
+    nextAttemptAt: string;
+    createdAt: string;
+    /** No attempt starts after this (spec section 6.3); the delivery then fails as `expired`. */
+    deadline: string;
+}
+/** A message from another server (or written here), waiting to be offered to one recipient here. */
+export interface QueuedArrival {
+    id: string;
+    recipient: string;
+    /** This recipient's hints. */
+    hints: Record<string, string>;
+    attempts: number;
+    dueAt: string;
+}
+/** Bytes of a part to fetch from the server that carried a message naming them. */
+export interface PartFetch {
+    /** Changes on every row mutation; absent only on an initial caller-created enqueue record. */
+    revision?: number;
+    /** A newly queued row has a fresh incarnation, so a stale pre-completion read never claims its successor. */
+    generation?: string;
+    sha256: string;
+    carrier: string;
+    size: number;
+    attempts: number;
+    dueAt: string;
+}
+/** Where bytes came from: the agent here that uploaded them, or the carrier they were fetched from. */
+export type PartSource = {
+    uploader: string;
+} | {
+    carrier: string;
+};
+export interface SweepCounts {
+    messages: number;
+    parts: number;
+    marks: number;
+    signals: number;
+}
+/** Synchronous final public-document capacity check, evaluated inside the mutation lock/CAS. */
+export type AgentAdmission = (candidate: Agent) => boolean;
+export interface Store {
+    /** Insert, unless the address or any of its keys is already taken. */
+    createAgent(agent: Agent, admit?: AgentAdmission): Promise<'created' | 'address_taken' | 'key_in_use' | 'too_many_keys'>;
+    agentByAddress(address: string): Promise<Agent | null>;
+    /** The agent holding this key, whether the key is active or revoked. */
+    agentByKey(key: string): Promise<Agent | null>;
+    /**
+     * Add a key, atomically, unless the agent already holds `maxActive` unrevoked keys or `MAX_STORED_KEYS`
+     * keys in all, revoked ones included.
+     */
+    addKey(address: string, entry: AgentKey, maxActive: number, admit?: AgentAdmission): Promise<'added' | 'too_many_keys' | 'key_in_use'>;
+    /** Revoke one active key unless it is the last; compare-and-change protects racing revocations. */
+    revokeKey(address: string, key: string, at: string, admit?: AgentAdmission): Promise<'revoked' | 'last_key' | 'not_found'>;
+    /** Recovery is atomic with retirement, uniqueness and final signed-document admission. */
+    replaceKeys(address: string, entry: AgentKey, admit?: AgentAdmission): Promise<'replaced' | 'key_in_use' | 'retired' | 'too_many_keys'>;
+    keepOnlyKey(address: string, key: string, at: string): Promise<'kept' | 'not_held'>;
+    /** Only the first retirement counts, including its unpairing evidence. */
+    retireAgent(address: string, at: string, unpairing?: string): Promise<void>;
+    /** Begin only against the current admitted authority; return its existing live pending proof or the new one. */
+    beginRecovery(address: string, value: unknown, expiresAt: string | null, now: string, admit?: AgentAdmission): Promise<unknown | null>;
+    /** Activate exactly one live undefended proof after its mandatory defense completes; preserve all proof fields. */
+    activateRecovery(address: string, expectedRecovery: unknown, now: string): Promise<boolean>;
+    /** Compare pending proof and mutate keys in one change; explicit defended:false cannot complete. Rejection preserves proof. */
+    completeRecovery(address: string, entry: AgentKey, expectedRecovery: unknown, admit?: AgentAdmission): Promise<'replaced' | 'not_pending' | 'key_in_use' | 'retired' | 'too_many_keys'>;
+    /** Exact pending plus admitted actor, cancellation and optional private cooldown are one change. */
+    cancelRecovery(address: string, expectedRecovery: unknown, now: string, admit?: AgentAdmission, keyCancelledAt?: string): Promise<boolean>;
+    /**
+     * Store a message once by id, with its delivery rows (a message sent here) or its arrivals (a message
+     * taken for recipients here), all or nothing. Rows already there, by (id, domain) or (id, recipient), are
+     * left as they are; the rest are added, even when the message was stored before, so repeating a call
+     * completes it. Returns the stored record, the earlier one on a repeat. Accepted retractions retain
+     * permanent bounded suppression receipts, including after envelope deletion; their repeats never
+     * reactivate completed work. StoreCapacityError rejects new records or row grants before acceptance.
+     *
+     * A message first stored with arrivals is a received one: it stays only while an arrival waits for it,
+     * or once an arrival kept it (`arrivalDone`). Any other message was written here: it takes a position in
+     * its author's sync stream, and stays until it expires.
+     */
+    putMessage(m: StoredMessage, rows?: {
+        deliveries?: Delivery[];
+        arrivals?: QueuedArrival[];
+    }): Promise<StoredMessage>;
+    message(id: string): Promise<StoredMessage | null>;
+    /** Remove live message state, stream positions, deliveries, arrivals and parts; preserve accepted suppression receipts. */
+    deleteMessage(id: string): Promise<void>;
+    /**
+     * The messages an agent here published (empty `to`), newest first, after the one whose id is `before` (null
+     * for the newest; an id that is not one of them matches nothing). A record's cursor is its message id.
+     */
+    published(author: string, before: string | null, limit: number): Promise<Page>;
+    /**
+     * The messages in `address`'s inbox whose `inReplyTo` is `id`, newest first, after the one whose id is
+     * `before` (null for the newest): the relations to a published message its author may show (spec section
+     * 7.4). A record's cursor is its message id.
+     */
+    repliesTo(address: string, id: string, before: string | null, limit: number): Promise<Page>;
+    /** Durable same-author rel:retract suppression for a live listing, scoped to its owner's accepted inbox. */
+    listingRetracted(ownerAddress: string, id: string, replyAuthor: string): Promise<boolean>;
+    /** Arrivals due at `now`, oldest first, with their messages. */
+    arrivals(now: string, limit: number): Promise<{
+        arrival: QueuedArrival;
+        message: StoredMessage;
+        generation: string;
+    }[]>;
+    /** Try an arrival again at `at`, one attempt more. Queued workers pass the snapshot generation to fence recreation. */
+    arrivalRetry(id: string, recipient: string, at: string, generation?: string): Promise<void>;
+    /**
+     * An arrival is over; `kept` says whether its recipient took or holds the message. Answers `kept` when
+     * this kept a received message for the first time, `dropped` when it removed a received message that
+     * nothing waits for and nothing kept, and null otherwise.
+     */
+    arrivalDone(id: string, recipient: string, kept: boolean, generation?: string): Promise<'kept' | 'dropped' | null>;
+    /** Add a message to an inbox, with its inbox event waiting to be told; false when it is already there. */
+    addToInbox(address: string, id: string, at: string, generation?: string, minExpiresAt?: string): Promise<boolean>;
+    /**
+     * A page of an agent's stream after position `after`: up to `limit` messages in position order, only
+     * those that entered it at or after `from` when given; and the signals held for it, unexpired at `now`,
+     * among the positions the page covers. With `more`, the page ends at its last message. Without, it covers
+     * every position taken so far, and never one taken before a position not yet written, so a reader
+     * following `cursor` never skips a position written late.
+     */
+    sync(address: string, after: number, limit: number, now: string, from?: string): Promise<SyncPage>;
+    /**
+     * Hold a signal for an agent at the next position of its stream until `expiresAt`, and no longer; and
+     * forget every signal expired at `now`.
+     */
+    holdSignal(address: string, signal: Omit<HeldSignal, 'cursor'>, expiresAt: string, now: string): Promise<void>;
+    /** Inbound-only stream page for host unread views; uses the same safe watermark as sync. */
+    inbox(address: string, after: number, limit: number): Promise<SyncEntry[]>;
+    /** Whether a message is in an agent's inbox. */
+    inInbox(address: string, id: string): Promise<boolean>;
+    /** Whether an agent here has sent `recipient` a message this store still holds. */
+    wroteTo(author: string, recipient: string, self: string): Promise<boolean>;
+    /** Inbox entries whose inbox event is not yet told, in position order. */
+    inboxEvents(limit: number): Promise<SyncEntry[]>;
+    inboxEventDone(cursor: number): Promise<void>;
+    /** Add a webhook unless its agent holds `max` already: false then. Atomic, even when adds race. */
+    addWebhook(webhook: Webhook, max: number): Promise<boolean>;
+    webhook(id: string): Promise<Webhook | null>;
+    verifyWebhook(id: string): Promise<void>;
+    deleteWebhook(id: string): Promise<void>;
+    /**
+     * Something entered an agent's stream: each of its verified webhooks with no post due falls due at `at`,
+     * or when its quiet time ends, if that is later.
+     */
+    wakeWebhooks(address: string, at: string): Promise<void>;
+    /**
+     * Claim up to `limit` webhooks due at `now`, earliest first: each is due no longer, and quiet until
+     * `quietUntil`. Atomic: two claims never take the same webhook.
+     */
+    claimWebhooks(now: string, limit: number, quietUntil: string, lease: {
+        token: string;
+        until: string;
+    }): Promise<Webhook[]>;
+    /** A post's outcome: `failingSince` as it now stands, and after a failure, a retry due at `retryAt` unless one is. */
+    settleWebhook(id: string, failingSince: string | null, retryAt: string | null, token: string, disable?: boolean): Promise<boolean>;
+    /**
+     * Claim up to `limit` pending rows due at `now`, earliest first, except those whose `server` is in `skip`:
+     * each is leased to `lease.token` and not due again before `lease.until`. Atomic: two claims never take
+     * the same row.
+     */
+    claimDeliveries(now: string, limit: number, skip: string[], lease: {
+        token: string;
+        until: string;
+    }): Promise<Delivery[]>;
+    /**
+     * Write an attempt's outcome to the row (id, domain): its server, status, reason, attempts and next attempt.
+     * Only while the row is pending and leased to `token`, and the lease ends; false when nothing was written.
+     */
+    settleDelivery(row: Delivery, token: string): Promise<boolean>;
+    deliveries(id: string): Promise<Delivery[]>;
+    putPart(sha256: string, bytes: Buffer, source: PartSource, at: string): Promise<void>;
+    part(sha256: string, source: PartSource): Promise<Buffer | null>;
+    /**
+     * The sources of the bytes held for an agent (spec section 7.2), held yet or not, with the size the
+     * naming message gives: its own upload, and for a message in its inbox naming the part, the carrier's
+     * bytes, or the sources held for the author when the carrier is `self`, through any number of local forwards.
+     * Follow only inbox grants for this hash, with cycle detection; never search globally for matching bytes.
+     */
+    heldFor(sha256: string, address: string, self: string): Promise<(PartSource & {
+        size: number;
+    })[]>;
+    /**
+     * The agents here, not retired, whose messages naming the part a reader may see: for `published`, their
+     * published messages (the caller judges each audience); for a `server`, their messages delivered to that
+     * server (status `delivered`). Each with the naming message.
+     */
+    partNamers(sha256: string, viewer: {
+        published: true;
+    } | {
+        server: string;
+    }, self: string): Promise<{
+        author: string;
+        message: AnyMessage;
+    }[]>;
+    /**
+     * Queue a fetch unless one is queued, and return the one now queued. With `max`, a fetch not yet queued is
+     * not queued (null) while `max` fetches of its carrier are waiting (not given up); racing callers may pass
+     * it by a few.
+     */
+    queueFetch(f: PartFetch, now?: string): Promise<PartFetch>;
+    queueFetch(f: PartFetch, now: string | undefined, max: number): Promise<PartFetch | null>;
+    /**
+     * Fetches due at `now`, taken in turn across carriers: every carrier's earliest, earliest first, then
+     * every carrier's second, and so on, so no carrier's backlog hides another's.
+     */
+    fetches(now: string, limit: number): Promise<PartFetch[]>;
+    /**
+     * Claim a fetch read from `fetches`: move it to `until`, only if it is still due at `now` and still has the
+     * attempts and due time it was read with. Atomic: of callers racing with the same row, one wins, and a row
+     * read before another caller settled it (done, retried or deferred) is never claimed. True for the winner.
+     * Each worker supplies a unique token. Only that token can renew or settle; renewal also requires a live lease.
+     */
+    claimFetch(f: PartFetch, now: string, lease: {
+        token: string;
+        until: string;
+    }): Promise<boolean>;
+    renewFetch(sha256: string, carrier: string, token: string, now: string, until: string): Promise<boolean>;
+    /** Try a fetch again at `at`, one attempt more. */
+    fetchRetry(sha256: string, carrier: string, at: string, token: string): Promise<boolean>;
+    /** Move a fetch to `at` without counting an attempt: it waited its turn, and was not tried. */
+    fetchDefer(sha256: string, carrier: string, at: string, token: string): Promise<boolean>;
+    fetchDone(sha256: string, carrier: string, token: string): Promise<boolean>;
+    /** Terminal failure and its ownership fence are one atomic row change; stale attempts cannot mark it. */
+    fetchGiveUp(sha256: string, carrier: string, token: string, expiresAt: string): Promise<boolean>;
+    fetchExhausted(sha256: string, carrier: string, now: string): Promise<boolean>;
+    /** Set a mark unless an unexpired one exists: true for the one caller that set it. */
+    mark(scope: string, id: string, expiresAt: string, now: string): Promise<boolean>;
+    marked(scope: string, id: string, now: string): Promise<boolean>;
+    /**
+     * Add `by` (one unless given; it may be negative, to take back what was added) to a counter, atomically,
+     * and return the new count; the first count fixes its expiry.
+     */
+    count(scope: string, id: string, expiresAt: string, now: string, by?: number): Promise<number>;
+    /** A value, or null once it expired. */
+    value<T>(scope: string, id: string, now: string): Promise<T | null>;
+    setValue(scope: string, id: string, value: unknown, expiresAt: string | null): Promise<void>;
+    /** Remove a value only while it is still `value`, atomically: true when this removed it. */
+    releaseValue(scope: string, id: string, value: unknown): Promise<boolean>;
+    /** Move a value's expiry to `expiresAt` only while it is still `value`, atomically: true when this did. */
+    renewValue(scope: string, id: string, value: unknown, expiresAt: string): Promise<boolean>;
+    /** Set a value unless an unexpired one exists, and return the value now stored. */
+    valueOnce<T>(scope: string, id: string, value: T, expiresAt: string | null, now: string): Promise<T>;
+    /**
+     * Remove what expired at `now`: messages past `expiresAt` (with their stream positions, deliveries,
+     * arrivals and part names); fetches no message from their carrier names any more, waiting or given up; then
+     * bytes no message names any more, fetched bytes at once and uploads made before `uploadsBefore`; then
+     * expired marks, counters, values and signals. A store may take the unnamed fetches, and rows a crash left
+     * behind a removed message, a bounded slice per sweep, so each sweep's work stays bounded.
+     */
+    sweep(now: string, uploadsBefore: string): Promise<SweepCounts>;
+    close(): Promise<void>;
+}

package/dist/store/store.js

@@ -0,0 +1,23 @@
+export class StoreCapacityError extends Error {
+    code = 'store_capacity';
+    constructor() {
+        super('The server is temporarily at capacity.');
+        this.name = 'StoreCapacityError';
+    }
+}
+export function resolveRetractionCapacity(input = {}) {
+    const limits = { maxRecords: 4096, maxPerAuthor: 256, maxBytes: 4 * 1024 * 1024, ...input };
+    for (const n of Object.values(limits))
+        if (!Number.isSafeInteger(n) || n < 1)
+            throw new TypeError('Retraction limits are positive safe integers.');
+    if (limits.maxBytes > 8 * 1024 * 1024)
+        throw new TypeError('Retraction admission is limited to 8 MiB.');
+    return limits;
+}
+/**
+ * The most keys, revoked ones included, that adding a key may leave an agent with: four published
+ * documents' worth (PROTOCOL.md section 4 lists at most 32). A revoked key is kept so it never returns, which
+ * leaves history unbounded without a cap, and a Mongo agent document is limited to 16 MiB. Recovery is never
+ * refused for it: a recovery replaces every key with one, and refusing it would let a key holder block it.
+ */
+export const MAX_STORED_KEYS = 128;

package/dist/sync.d.ts

@@ -0,0 +1,19 @@
+import { type Context } from './context.ts';
+import { type Reply, type Request } from './http.ts';
+/** Who waits for news of which agent in this process: each `sync` held open. */
+export declare class Changes {
+    #private;
+    /** Answer everyone waiting for news of `address`. */
+    tell(address: string): void;
+    /** Wait until `address` is told of, or `ms` pass; false once closed, when no one waits any more. */
+    wait(address: string, ms: number): Promise<boolean>;
+    close(): void;
+}
+/** Something entered an agent's stream: its waiting syncs answer, and its webhooks fall due. */
+export declare function changed(ctx: Context, address: string): Promise<void>;
+export declare function sync(ctx: Context, req: Request): Promise<Reply>;
+/**
+ * One entry per recipient server. Domains not yet resolved, or that resolved to no server, have `server`
+ * null; domains that resolved to the same server share its entry.
+ */
+export declare function sent(ctx: Context, req: Request): Promise<Reply>;

package/dist/sync.js

@@ -0,0 +1,199 @@
+/**
+ * What an agent reads about its own messages (CLIENT.md):
+ *
+ *   GET /simon/sync?since=<token>&limit=<n>&wait=<seconds>   what entered the agent's stream since the token:
+ *                                     the messages it received and those it wrote here, from any of its
+ *                                     clients, in the order this server took them, each with its carrier and
+ *                                     its claims (the authoritative ones always, the others only from a
+ *                                     carrier this server trusts, and the carrier's claims as it signed
+ *                                     them, so any client checks them); and the signals it was told of
+ *   GET /simon/sent/<id>               delivery of one of its messages, per recipient server
+ *
+ * Sync shows what entered the stream within the last `syncDays` (published in the server document). A
+ * token is the position it reaches and when it was given, so one older than that, which may reach back
+ * past what sync no longer shows, is `410 token_expired`, as is one this server never gave: a gap is said,
+ * never hidden. This server keeps no history, so `marks` and `removed` are always empty.
+ *
+ * With nothing new, a sync waits up to `wait` seconds for something to enter the stream: told at once
+ * within this process, and looked for again every few seconds, for what another process wrote.
+ */
+import crypto from 'node:crypto';
+import { invalid, unauthorized, WireError } from '@agnt-sdk/simon-protocol';
+import { authenticateAgent, authenticateAgentKey } from "./auth.js";
+import { iso } from "./context.js";
+import { notFound } from "./errors.js";
+import { shownClaims } from "./fanout.js";
+import { json } from "./http.js";
+const DAY_MS = 86_400_000;
+const MAX_WAIT_S = 60;
+/** How often a waiting sync looks again, for what other processes wrote. */
+const RECHECK_MS = 5_000;
+// A persisted per-origin secret keeps checkpoints valid across workers and restarts, without a
+// database row for every poll. Authenticated encryption binds both position and account to this host.
+async function checkpointKey(ctx) {
+    const value = await ctx.store.valueOnce('sync-secret', ctx.config.origin, crypto.randomBytes(32).toString('base64url'), null, iso(ctx.now()));
+    const key = Buffer.from(value, 'base64url');
+    if (key.length !== 32)
+        throw new Error('Invalid persisted sync secret');
+    return key;
+}
+function checkpoint(key, origin, address, cursor, at) {
+    const iv = crypto.randomBytes(12);
+    const cipher = crypto.createCipheriv('aes-256-gcm', key, iv);
+    cipher.setAAD(Buffer.from(origin));
+    const data = Buffer.concat([cipher.update(JSON.stringify({ v: 1, address, cursor, at })), cipher.final()]);
+    return Buffer.concat([iv, cipher.getAuthTag(), data]).toString('base64url');
+}
+function position(key, origin, address, token, oldest, now) {
+    try {
+        if (token.length > 2048 || !/^[A-Za-z0-9_-]+$/.test(token))
+            throw tokenExpired();
+        const data = Buffer.from(token, 'base64url');
+        if (data.length < 29 || data.toString('base64url') !== token)
+            throw tokenExpired();
+        const cipher = crypto.createDecipheriv('aes-256-gcm', key, data.subarray(0, 12));
+        cipher.setAAD(Buffer.from(origin));
+        cipher.setAuthTag(data.subarray(12, 28));
+        const value = JSON.parse(Buffer.concat([cipher.update(data.subarray(28)), cipher.final()]).toString('utf8'));
+        if (value.v !== 1 ||
+            value.address !== address ||
+            !Number.isSafeInteger(value.cursor) ||
+            value.cursor < 0 ||
+            !Number.isSafeInteger(value.at) ||
+            value.at < oldest ||
+            value.at > now)
+            throw tokenExpired();
+        return value.cursor;
+    }
+    catch {
+        throw tokenExpired();
+    }
+}
+/** Who waits for news of which agent in this process: each `sync` held open. */
+export class Changes {
+    #waiting = new Map();
+    #closed = false;
+    /** Answer everyone waiting for news of `address`. */
+    tell(address) {
+        for (const done of this.#waiting.get(address) ?? [])
+            done();
+    }
+    /** Wait until `address` is told of, or `ms` pass; false once closed, when no one waits any more. */
+    async wait(address, ms) {
+        if (this.#closed)
+            return false;
+        const waiting = this.#waiting.get(address) ?? new Set();
+        this.#waiting.set(address, waiting);
+        let done;
+        const told = new Promise(resolve => (done = resolve));
+        const timer = setTimeout(done, ms);
+        waiting.add(done);
+        await told;
+        clearTimeout(timer);
+        waiting.delete(done);
+        if (!waiting.size)
+            this.#waiting.delete(address);
+        return !this.#closed;
+    }
+    close() {
+        this.#closed = true;
+        for (const address of this.#waiting.keys())
+            this.tell(address);
+    }
+}
+/** Something entered an agent's stream: its waiting syncs answer, and its webhooks fall due. */
+export async function changed(ctx, address) {
+    ctx.changes.tell(address);
+    await ctx.store.wakeWebhooks(address, iso(ctx.now()));
+    ctx.wake();
+}
+function whole(value, fallback, min, max, name) {
+    if (value === null)
+        return fallback;
+    const n = /^[0-9]{1,3}$/.test(value) ? Number(value) : NaN;
+    if (!(n >= min && n <= max))
+        throw invalid(`${name} is a whole number from ${min} to ${max}.`, { field: name });
+    return n;
+}
+const tokenExpired = () => new WireError(410, 'token_expired', 'This token reaches back past what sync still shows, or is unknown; sync anew.');
+export async function sync(ctx, req) {
+    const { agent, key: signer } = await authenticateAgentKey(ctx, req);
+    const limit = whole(req.query.get('limit'), 50, 1, 200, 'limit');
+    const wait = whole(req.query.get('wait'), 0, 0, MAX_WAIT_S, 'wait');
+    const now = ctx.now();
+    const oldest = now.getTime() - ctx.config.syncDays * DAY_MS;
+    const key = await checkpointKey(ctx);
+    const since = req.query.get('since');
+    if (since === null && (await ctx.store.value('sync-history-gap', agent.address, iso(now)))) {
+        // Every device must learn of the upgrade gap. This does not clear account state or silently replay.
+        throw new WireError(410, 'token_expired', 'This account predates sent-message tracking; retained sent history may be incomplete. Explicitly resume with the supplied token.', { reason: 'history_migration', resumeToken: checkpoint(key, ctx.config.origin, agent.address, 0, now.getTime()) });
+    }
+    const after = since === null ? 0 : position(key, ctx.config.origin, agent.address, since, oldest, now.getTime());
+    const read = () => ctx.store.sync(agent.address, after, limit, iso(ctx.now()), iso(new Date(ctx.now().getTime() - ctx.config.syncDays * DAY_MS)));
+    let page = await read();
+    if (page.cursor < after)
+        throw tokenExpired();
+    const deadline = Date.now() + wait * 1000;
+    while (isEmpty(page) && Date.now() < deadline) {
+        if (!(await ctx.changes.wait(agent.address, Math.min(deadline - Date.now(), RECHECK_MS))))
+            break;
+        page = await read();
+        if (page.cursor < after)
+            throw tokenExpired();
+    }
+    // Authentication consumed the nonce once. Recheck its authority after waiting without replaying it.
+    const current = await ctx.store.agentByAddress(agent.address);
+    const active = current?.keys.find(k => k.key === signer.key);
+    if (!current ||
+        current.retiredAt ||
+        !active ||
+        (current.authorizedKeys && !current.authorizedKeys.includes(signer.key)) ||
+        (active.revoked !== null && active.revoked <= iso(ctx.now()))) {
+        throw unauthorized('bad_signature', 'This signing key is no longer active.', ctx.now());
+    }
+    const at = page.more
+        ? Math.min(ctx.now().getTime(), ...page.messages.map(e => Date.parse(e.receivedAt)), ...page.signals.map(e => Date.parse(e.at)))
+        : ctx.now().getTime();
+    return json({
+        messages: page.messages.map(e => entry(ctx, e)),
+        marks: [],
+        removed: [],
+        signals: page.signals.map(({ type, from, about, at }) => ({ type, from, about, at })),
+        token: checkpoint(key, ctx.config.origin, agent.address, page.cursor, at),
+        more: page.more,
+    });
+}
+const isEmpty = (page) => !page.messages.length && !page.signals.length;
+const entry = (ctx, e) => ({
+    id: e.id,
+    message: e.message,
+    carrier: e.carrier,
+    claims: shownClaims(ctx, e.carrier, e.claims),
+    ...(e.signedClaims && { signedClaims: e.signedClaims }),
+    receivedAt: e.receivedAt,
+});
+/**
+ * One entry per recipient server. Domains not yet resolved, or that resolved to no server, have `server`
+ * null; domains that resolved to the same server share its entry.
+ */
+export async function sent(ctx, req) {
+    const agent = await authenticateAgent(ctx, req);
+    const record = await ctx.store.message(req.params.id);
+    if (!record || record.message.from !== agent.address || record.carrier !== ctx.config.origin) {
+        throw notFound('This agent sent no message with this id here.');
+    }
+    const servers = new Map();
+    for (const d of await ctx.store.deliveries(record.id)) {
+        const reason = d.status === 'failed' ? (d.reason ?? 'failed') : undefined;
+        const key = d.server === null ? `domain ${d.domain}` : `${d.server} ${d.status} ${reason ?? ''}`;
+        const entry = servers.get(key) ?? {
+            server: d.server,
+            recipients: [],
+            status: d.status,
+            ...(reason ? { reason } : {}),
+        };
+        entry.recipients.push(...d.recipients);
+        servers.set(key, entry);
+    }
+    return json({ id: record.id, servers: [...servers.values()] });
+}