@north-light/api 0.3.580 → 0.3.587

package/dist/core/peer/directory.d.ts

@@ -0,0 +1,71 @@
+import { normalizeMachineId } from './names.js';
+import { type TokenCache } from './token.js';
+/** How long a machine's reach answer is trusted. */
+export declare const REACH_TTL_MS: number;
+/** Budget for one directory call. */
+export declare const DIRECTORY_CALL_TIMEOUT_MS = 10000;
+export type Reach = {
+    kind: 'stable';
+} | {
+    kind: 'relay';
+    relay: string;
+};
+export interface Machine {
+    machine_id: string;
+    name: string;
+    /** The machine's callable address, also the audience of its peer call tokens. */
+    url: string;
+    reach: Reach;
+    crtr_version: string | null;
+    last_seen: string | null;
+    is_default?: boolean;
+    /** `runtime` (a crtr peer) or `device` (a call target only, never a peer). A missing kind from an older directory is `runtime`. */
+    kind: MachineKind;
+    /** The plugins the machine reported; `[]` when none. */
+    plugins: string[];
+}
+export type MachineKind = 'runtime' | 'device';
+export interface MachineStatus {
+    machine_id: string;
+    url: string;
+    reach: Reach | null;
+}
+/** The directory refused or failed a call. `status` is 0 when it could not be reached at all. */
+export declare class DirectoryError extends Error {
+    readonly status: number;
+    constructor(status: number, message: string);
+}
+export interface DirectoryDeps {
+    /** The directory base URL, or null when this daemon has no directory. */
+    issuer(): string | null;
+    tokens: TokenCache;
+    fetch: typeof fetch;
+    now(): number;
+}
+export interface DirectoryClient {
+    /** Every live machine of the account. Refreshes the reach cache. */
+    list(): Promise<Machine[]>;
+    /** The last `list()` answer, however old; null before the first one. For a caller that can use a stale list when the directory is down. */
+    lastList(): Machine[] | null;
+    /** One machine's reach, cached; null when the directory does not know it (not_found, revoked). */
+    reach(machineId: string): Promise<Machine | null>;
+    /** `PUT /v1/machines/<own id>/status`. */
+    status(body: {
+        plugins?: string[];
+        crtr_version?: string;
+    }): Promise<MachineStatus>;
+    /** Forget one cached reach answer, or all. */
+    invalidate(machineId?: string): void;
+}
+export { normalizeMachineId };
+export declare function createDirectoryClient(deps: DirectoryDeps, ownId: () => string): DirectoryClient;
+/** This machine's id as the directory names it (`runtime:<id>`). */
+export declare function ownMachineId(): string;
+export declare const directory: DirectoryClient;
+export declare const listMachines: () => Promise<Machine[]>;
+export declare const machineReach: (machineId: string) => Promise<Machine | null>;
+/** The URL peers call this machine at, as the directory last reported it from a status call; null before the first one. */
+export declare function machineUrl(): Promise<string | null>;
+/** Tell the directory this machine is up (its plugins and crtr version) and store the URL it answers with as `machine_url`.
+ *  Returns the stored URL, or null when this daemon has no directory identity. Throws `DirectoryError` when the directory fails. */
+export declare function reportMachineStatus(client?: DirectoryClient): Promise<MachineStatus | null>;

package/dist/core/peer/directory.js

@@ -0,0 +1,167 @@
+// The directory's machine routes (spec-machines §15.5), called with this
+// runtime's directory `/v1` token (`aud` = `<issuer>/v1`, `sub` = `runtime:<id>`).
+// A peer or relay call token is never accepted on these routes.
+//
+// Reach answers are cached for `REACH_TTL_MS`. A directory that cannot be reached
+// serves the stale entry rather than failing a peer call that has an address.
+import { normalizeMachineId, rememberMachineName } from './names.js';
+import { openDb } from '../canvas/db.js';
+import { directoryIssuer } from '../directory/issuer.js';
+import { runtimeClient } from '../grants/sync.js';
+import { crtrVersion } from '../../shared/crtr-version.js';
+import { installedPluginIds } from '../directory/join.js';
+import { peerTokens } from './token.js';
+/** How long a machine's reach answer is trusted. */
+export const REACH_TTL_MS = 5 * 60_000;
+/** Budget for one directory call. */
+export const DIRECTORY_CALL_TIMEOUT_MS = 10_000;
+/** The directory refused or failed a call. `status` is 0 when it could not be reached at all. */
+export class DirectoryError extends Error {
+    status;
+    constructor(status, message) {
+        super(message);
+        this.status = status;
+        this.name = 'DirectoryError';
+    }
+}
+export { normalizeMachineId };
+function asReach(value) {
+    if (!value || typeof value !== 'object')
+        return null;
+    const { kind, relay } = value;
+    if (kind === 'stable')
+        return { kind: 'stable' };
+    if (kind === 'relay' && typeof relay === 'string')
+        return { kind: 'relay', relay };
+    return null;
+}
+function asMachine(value) {
+    const row = value;
+    const reach = asReach(row?.['reach']);
+    if (!row || typeof row['machine_id'] !== 'string' || typeof row['url'] !== 'string' || reach === null) {
+        throw new DirectoryError(502, 'the directory answered a machine record with a missing machine_id, url or reach');
+    }
+    return { machine_id: row['machine_id'], name: typeof row['name'] === 'string' ? row['name'] : row['machine_id'], url: row['url'].replace(/\/$/, ''), reach,
+        crtr_version: typeof row['crtr_version'] === 'string' ? row['crtr_version'] : null,
+        last_seen: typeof row['last_seen'] === 'string' ? row['last_seen'] : null,
+        kind: row['kind'] === 'device' ? 'device' : 'runtime',
+        plugins: Array.isArray(row['plugins']) ? row['plugins'].filter((plugin) => typeof plugin === 'string') : [],
+        ...(typeof row['is_default'] === 'boolean' ? { is_default: row['is_default'] } : {}) };
+}
+export function createDirectoryClient(deps, ownId) {
+    const cache = new Map();
+    let listed = null;
+    async function call(method, path, body) {
+        const issuer = deps.issuer();
+        if (issuer === null)
+            throw new DirectoryError(0, 'this daemon has no directory');
+        const base = issuer.replace(/\/$/, '');
+        for (let attempt = 0;; attempt++) {
+            let response;
+            try {
+                const token = await deps.tokens.get(base);
+                response = await deps.fetch(`${base}${path}`, { method,
+                    headers: { authorization: `Bearer ${token}`, ...(body === undefined ? {} : { 'content-type': 'application/json' }) },
+                    ...(body === undefined ? {} : { body: JSON.stringify(body) }), signal: AbortSignal.timeout(DIRECTORY_CALL_TIMEOUT_MS) });
+            }
+            catch (error) {
+                throw new DirectoryError(0, `the directory could not be reached: ${error instanceof Error ? error.message : String(error)}`);
+            }
+            // A token the directory no longer accepts (clock skew, rotated key): mint once more.
+            if (response.status === 401 && attempt === 0) {
+                deps.tokens.drop(base);
+                continue;
+            }
+            if (!response.ok)
+                throw new DirectoryError(response.status, `directory ${method} ${path} answered ${response.status}`);
+            try {
+                return await response.json();
+            }
+            catch {
+                throw new DirectoryError(502, `directory ${method} ${path} answered a body that is not JSON`);
+            }
+        }
+    }
+    return {
+        async list() {
+            const answer = await call('GET', '/v1/machines');
+            if (!Array.isArray(answer))
+                throw new DirectoryError(502, 'the directory answered a machine list that is not an array');
+            const machines = answer.map(asMachine);
+            const at = deps.now();
+            for (const machine of machines) {
+                cache.set(machine.machine_id, { machine, at });
+                rememberMachineName(machine.machine_id, machine.name);
+            }
+            listed = { machines, at };
+            return machines;
+        },
+        lastList() { return listed === null ? null : listed.machines; },
+        async reach(machineId) {
+            const id = normalizeMachineId(machineId);
+            const held = cache.get(id);
+            if (held && deps.now() - held.at < REACH_TTL_MS)
+                return held.machine;
+            try {
+                const machine = asMachine(await call('GET', `/v1/machines/${encodeURIComponent(id)}/reach`));
+                cache.set(id, { machine, at: deps.now() });
+                rememberMachineName(machine.machine_id, machine.name);
+                return machine;
+            }
+            catch (error) {
+                if (error instanceof DirectoryError && error.status === 404) {
+                    cache.delete(id);
+                    return null;
+                }
+                if (held && error instanceof DirectoryError && error.status === 0)
+                    return held.machine;
+                throw error;
+            }
+        },
+        async status(body) {
+            const id = ownId();
+            const answer = await call('PUT', `/v1/machines/${encodeURIComponent(id)}/status`, body);
+            if (!answer || typeof answer['machine_id'] !== 'string' || typeof answer['url'] !== 'string') {
+                throw new DirectoryError(502, 'the directory answered a status record with a missing machine_id or url');
+            }
+            return { machine_id: answer['machine_id'], url: answer['url'].replace(/\/$/, ''), reach: asReach(answer['reach']) };
+        },
+        invalidate(machineId) { if (machineId === undefined) {
+            cache.clear();
+            listed = null;
+        }
+        else
+            cache.delete(normalizeMachineId(machineId)); },
+    };
+}
+/** This machine's id as the directory names it (`runtime:<id>`). */
+export function ownMachineId() { return normalizeMachineId(runtimeClient().runtime); }
+export const directory = createDirectoryClient({ issuer: directoryIssuer, tokens: peerTokens, fetch: (input, init) => fetch(input, init), now: Date.now }, ownMachineId);
+export const listMachines = () => directory.list();
+export const machineReach = (machineId) => directory.reach(machineId);
+const MACHINE_URL_KEY = 'machine_url';
+/** The URL peers call this machine at, as the directory last reported it from a status call; null before the first one. */
+export async function machineUrl() {
+    const row = await (await openDb()).prepare('SELECT value FROM runtime_state WHERE key = ?').get(MACHINE_URL_KEY);
+    return row?.value ?? null;
+}
+async function storeMachineUrl(url) {
+    await (await openDb()).prepare('INSERT INTO runtime_state (key, value) VALUES (?, ?) ON CONFLICT(key) DO UPDATE SET value = excluded.value').run(MACHINE_URL_KEY, url);
+}
+/** Tell the directory this machine is up (its plugins and crtr version) and store the URL it answers with as `machine_url`.
+ *  Returns the stored URL, or null when this daemon has no directory identity. Throws `DirectoryError` when the directory fails. */
+export async function reportMachineStatus(client = directory) {
+    if (directoryIssuer() === null)
+        return null;
+    try {
+        runtimeClient();
+    }
+    catch {
+        return null;
+    }
+    const answer = await client.status({ plugins: installedPluginIds(), crtr_version: crtrVersion() });
+    if (answer.machine_id !== ownMachineId())
+        throw new DirectoryError(502, 'the directory answered a status for another machine');
+    await storeMachineUrl(answer.url);
+    return answer;
+}

package/dist/core/peer/envelope.d.ts

@@ -0,0 +1,46 @@
+import type { RequestPrincipal } from '../../daemon/api/router.js';
+import type { ProviderCaller } from '../../daemon/api/handlers/providers.js';
+import { type RunPlace } from '../permissions/ceiling.js';
+export declare const ENVELOPE_HEADER = "Crtr-Envelope";
+/** A header larger than this is refused unread. */
+export declare const MAX_ENVELOPE_BYTES: number;
+/** The largest header a sender builds. Node's HTTP parser answers 431 once a request's headers together pass 16 KiB, so this leaves 4 KiB for the bearer token and the other headers. */
+export declare const MAX_SENT_ENVELOPE_BYTES: number;
+/** The app (and its node) a call is made for. `node` is null for a cron with no anchor node. */
+export interface EnvelopeApp {
+    sub: string;
+    node: string | null;
+    node_scopes: string[] | null;
+    place: RunPlace | null;
+}
+export interface Envelope {
+    sub: string;
+    act: {
+        sub: string;
+        act?: EnvelopeApp;
+    };
+}
+/** The caller kinds that originate a peer call. A forwarded caller never re-forwards, so it is not here. */
+export type EnvelopeCaller = Extract<RequestPrincipal, {
+    class: 'person' | 'broker' | 'cron';
+}>;
+export declare class EnvelopeError extends Error {
+    constructor(message: string);
+}
+export interface EnvelopeContext {
+    /** The account owner (`user:<id>`) the call is made for. */
+    owner?: string;
+    /** This machine's id (`runtime:<id>`). */
+    via?: string;
+    /** A node's run place. */
+    placeOf?: (nodeId: string) => Promise<RunPlace | null>;
+}
+/** The envelope for a call made by `principal` on this machine. Broker → its app, node, stored scopes and run place; cron → its app, anchor node
+ *  (null when unanchored), stored scopes and origin run; person → no inner `act`. */
+export declare function envelopeFor(principal: EnvelopeCaller, context?: EnvelopeContext): Promise<Envelope>;
+export declare function encodeEnvelope(envelope: Envelope): string;
+/** Parse and validate a `Crtr-Envelope` header value. Throws `EnvelopeError` for anything that is not the documented shape. */
+export declare function decodeEnvelope(header: string): Envelope;
+/** The envelope for a `provider.call` made by `caller` to a device machine: the account owner (`sub`), this machine, and the calling app and node
+ *  (a person has no inner `act`). The device shows it in its recent-activity list and checks nothing in it. */
+export declare function envelopeForProviderCaller(caller: ProviderCaller, sub: string, context?: Pick<EnvelopeContext, 'via' | 'placeOf'>): Promise<Envelope>;

package/dist/core/peer/envelope.js

@@ -0,0 +1,98 @@
+// The call envelope (design-multi-machine-graph, "The call envelope"): who a
+// peer call is made for, asserted by the calling daemon and trusted because only
+// that daemon holds its peer token. The receiver checks `act.sub` against the
+// token's presenting machine (the outermost `act` link) and `sub` against the
+// token's `sub`; it takes the sender of a message from here and never from the
+// request body.
+//
+// Wire form: `Crtr-Envelope: <base64url JSON>` of
+//   {sub:"user:<id>", act:{sub:"runtime:<via>", act?:{sub:"app:<x>", node, node_scopes, place}}}
+// A missing inner `act` means the person.
+import { joinedOwner } from '../directory/join.js';
+import { nodePlace } from '../permissions/ceiling.js';
+import { openDb } from '../canvas/db.js';
+import { ownMachineId } from './directory.js';
+export const ENVELOPE_HEADER = 'Crtr-Envelope';
+/** A header larger than this is refused unread. */
+export const MAX_ENVELOPE_BYTES = 16 * 1024;
+/** The largest header a sender builds. Node's HTTP parser answers 431 once a request's headers together pass 16 KiB, so this leaves 4 KiB for the bearer token and the other headers. */
+export const MAX_SENT_ENVELOPE_BYTES = 12 * 1024;
+export class EnvelopeError extends Error {
+    constructor(message) { super(message); this.name = 'EnvelopeError'; }
+}
+/** The envelope for a call made by `principal` on this machine. Broker → its app, node, stored scopes and run place; cron → its app, anchor node
+ *  (null when unanchored), stored scopes and origin run; person → no inner `act`. */
+export async function envelopeFor(principal, context = {}) {
+    return fits(await buildEnvelope(principal, context));
+}
+async function buildEnvelope(principal, context) {
+    const via = context.via ?? ownMachineId();
+    const named = principal.class === 'person' ? '' : principal.sub;
+    const sub = context.owner ?? (named.startsWith('user:') ? named : joinedOwner());
+    if (sub === null || sub === undefined)
+        throw new EnvelopeError('this machine has no account owner to make a peer call for');
+    if (principal.class === 'person')
+        return { sub, act: { sub: via } };
+    if (principal.class === 'broker') {
+        const place = await (context.placeOf ?? (async (id) => await nodePlace(await openDb(), id)))(principal.node);
+        return { sub, act: { sub: via, act: { sub: principal.app, node: principal.node, node_scopes: principal.scopes === null ? null : [...principal.scopes], place } } };
+    }
+    return { sub, act: { sub: via, act: { sub: principal.app, node: principal.anchor, node_scopes: principal.scopes === null ? null : [...principal.scopes],
+                place: { run: principal.origin_run ?? '', isolated: principal.isolated } } } };
+}
+/** `envelope` itself when it fits in the header; otherwise an `EnvelopeError` naming the scope list, which is the only unbounded part. */
+function fits(envelope) {
+    const size = encodeEnvelope(envelope).length;
+    if (size > MAX_SENT_ENVELOPE_BYTES) {
+        const count = envelope.act.act?.node_scopes?.length;
+        throw new EnvelopeError(`the call's identity is ${size} bytes, over the ${MAX_SENT_ENVELOPE_BYTES}-byte limit for a call to another machine${count === undefined ? '' : ` (the node holds ${count} scopes)`}; narrow the node's scopes`);
+    }
+    return envelope;
+}
+export function encodeEnvelope(envelope) {
+    return Buffer.from(JSON.stringify(envelope), 'utf8').toString('base64url');
+}
+const isString = (value) => typeof value === 'string' && value !== '';
+const isRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+/** Parse and validate a `Crtr-Envelope` header value. Throws `EnvelopeError` for anything that is not the documented shape. */
+export function decodeEnvelope(header) {
+    if (header.length > MAX_ENVELOPE_BYTES)
+        throw new EnvelopeError('the envelope is too large');
+    if (!/^[A-Za-z0-9_-]+$/.test(header))
+        throw new EnvelopeError('the envelope is not base64url');
+    let raw;
+    try {
+        raw = JSON.parse(Buffer.from(header, 'base64url').toString('utf8'));
+    }
+    catch {
+        throw new EnvelopeError('the envelope is not JSON');
+    }
+    if (!isRecord(raw) || !isString(raw['sub']) || !raw['sub'].startsWith('user:'))
+        throw new EnvelopeError('the envelope names no user');
+    const act = raw['act'];
+    if (!isRecord(act) || !isString(act['sub']) || !act['sub'].startsWith('runtime:'))
+        throw new EnvelopeError('the envelope names no calling machine');
+    const inner = act['act'];
+    if (inner === undefined)
+        return { sub: raw['sub'], act: { sub: act['sub'] } };
+    if (!isRecord(inner) || !isString(inner['sub']) || !inner['sub'].startsWith('app:'))
+        throw new EnvelopeError('the envelope names no calling app');
+    const { node, node_scopes: scopes, place } = inner;
+    if (node !== null && !isString(node))
+        throw new EnvelopeError('the envelope node is not a node id');
+    if (scopes !== null && !(Array.isArray(scopes) && scopes.every(isString)))
+        throw new EnvelopeError('the envelope node_scopes is not a list of scopes');
+    if (place !== null && !(isRecord(place) && typeof place['run'] === 'string' && typeof place['isolated'] === 'boolean'))
+        throw new EnvelopeError('the envelope place is malformed');
+    return { sub: raw['sub'], act: { sub: act['sub'], act: { sub: inner['sub'], node: node, node_scopes: scopes,
+                place: place === null ? null : { run: place['run'], isolated: place['isolated'] } } } };
+}
+/** The envelope for a `provider.call` made by `caller` to a device machine: the account owner (`sub`), this machine, and the calling app and node
+ *  (a person has no inner `act`). The device shows it in its recent-activity list and checks nothing in it. */
+export async function envelopeForProviderCaller(caller, sub, context = {}) {
+    const via = context.via ?? ownMachineId();
+    if (caller.class === 'person' || caller.grantee === null)
+        return { sub, act: { sub: via } };
+    const place = caller.node_id === null ? null : await (context.placeOf ?? (async (id) => await nodePlace(await openDb(), id)))(caller.node_id);
+    return fits({ sub, act: { sub: via, act: { sub: caller.grantee, node: caller.node_id, node_scopes: caller.nodeScopes === null ? null : [...caller.nodeScopes], place } } });
+}

package/dist/core/peer/names.d.ts

@@ -0,0 +1,5 @@
+export declare const rememberMachineName: (machineId: string, name: string) => void;
+/** What to call a machine in text a person reads: its directory name when this daemon has seen it, else its id. */
+export declare const machineNameOf: (machineId: string) => string;
+/** A machine id as the directory spells it: `runtime:<id>`. Here, not in the directory client, so graph code can use it without importing the client. */
+export declare const normalizeMachineId: (id: string) => string;

package/dist/core/peer/names.js

@@ -0,0 +1,8 @@
+// The names the directory gave this account's machines, as this daemon last saw them. A leaf module (no imports) so graph code that renders
+// text can read it without importing the directory client, which reaches back into the graph.
+const names = new Map();
+export const rememberMachineName = (machineId, name) => { names.set(machineId, name); };
+/** What to call a machine in text a person reads: its directory name when this daemon has seen it, else its id. */
+export const machineNameOf = (machineId) => names.get(machineId) ?? machineId;
+/** A machine id as the directory spells it: `runtime:<id>`. Here, not in the directory client, so graph code can use it without importing the client. */
+export const normalizeMachineId = (id) => id.startsWith('runtime:') ? id : `runtime:${id}`;

package/dist/core/peer/outbox-store.d.ts

@@ -0,0 +1,76 @@
+import type { ObjectRef } from './stubs.js';
+import type { CanvasDb } from '../canvas/db.js';
+export type OutboxState = 'pending' | 'waiting' | 'claimed' | 'done' | 'expired';
+/** What one event looks like on the wire, in both directions (`peer.events` body, `peer.outbox.claim` rows). */
+export interface PeerEventPayload {
+    key: string;
+    /** The sending machine's message id: the receiver's idempotency identity for the event. */
+    message_id: string;
+    event: string;
+    level: number;
+    object: ObjectRef;
+    actor: ObjectRef | null;
+    attrs: Record<string, unknown>;
+    /** The message's own fields other than `push` (a report's kind, label and disposition; a notice's summary), minus `bodyRef`. */
+    body?: Record<string, unknown>;
+    /** The text of the report document the event points at, inlined because the receiver cannot read the sender's documents. */
+    body_text?: string;
+    /** The home delivered this to the destination on the strength of an app's `link` (not the destination's read access): the receiver records the same link on its half of the watch. */
+    linked?: true;
+}
+export interface OutboxRow {
+    id: number;
+    peer: string;
+    kind: string;
+    payload_json: string;
+    idempotency_key: string;
+    state: OutboxState;
+    attempts: number;
+    next_at: number | null;
+    claimed_by: string | null;
+    claimed_at: number | null;
+    first_failed_at: number | null;
+    created_at: number;
+}
+/** A claim not acked within this long is lost (the caller crashed or its answer never arrived) and may be taken again. */
+export declare const CLAIM_LEASE_MS: number;
+/** A row not delivered within this long is given up on. */
+export declare const OUTBOX_MAX_AGE_MS: number;
+/** A row the receiver refused only because its plugin catalog lags the sender's (`isCatalogLag`) is retried this long from creation,
+ *  then given up on: the receiver syncs within minutes, so a longer refusal is a real mismatch. Matches the app side's 24 h. */
+export declare const CATALOG_LAG_RETRY_MS: number;
+/** Subscribe to enqueues (the delivery lane pushes a relay peer's row at once). Returns the unsubscribe. */
+export declare function onPeerEnqueued(listener: (peer: string) => void): () => void;
+/** Write one row; a key already present adds nothing. Returns whether a row was added. Runs in the caller's transaction. */
+export declare function enqueuePeerRow(db: CanvasDb, row: {
+    peer: string;
+    kind: string;
+    key: string;
+    payload: unknown;
+}, now?: number): Promise<boolean>;
+/** Rows the lane may push now: pending and due. */
+export declare function dueRows(db: CanvasDb, now: number, limit?: number): Promise<OutboxRow[]>;
+/** Pending rows to one peer that are new or due (a relay peer's push at enqueue; a row that already failed waits for its backoff). */
+export declare function pendingFor(db: CanvasDb, peer: string, now: number, limit?: number): Promise<OutboxRow[]>;
+export declare const markDone: (db: CanvasDb, id: number) => Promise<void>;
+export declare const markWaiting: (db: CanvasDb, id: number, attempts: number) => Promise<void>;
+export declare const markRetry: (db: CanvasDb, id: number, attempts: number, nextAt: number, firstFailedAt: number) => Promise<void>;
+export declare const markExpired: (db: CanvasDb, id: number) => Promise<void>;
+export interface ClaimedRow {
+    key: string;
+    claim_token: string;
+    payload: PeerEventPayload;
+}
+/** The calling machine's own rows (`peer = via`, never another's), fenced with a fresh token. Takes pending and waiting rows
+ *  and claims whose lease ran out; a row still under a live lease is left alone. */
+export declare function claimRows(db: CanvasDb, via: string, limit: number, now?: number): Promise<ClaimedRow[]>;
+/** Mark done the rows the caller still holds: `peer = via`, the same token, still `claimed`. Returns the keys acked. */
+export declare function ackRows(db: CanvasDb, via: string, acks: ReadonlyArray<{
+    key: string;
+    claim_token: string;
+}>): Promise<string[]>;
+/** Retire rows done long ago, so the table stays small. */
+export declare function pruneOutbox(db: CanvasDb, now: number, keepMs?: number): Promise<void>;
+/** Give up on rows older than `OUTBOX_MAX_AGE_MS` that were never delivered, and on rows whose claim lapsed unacked (the receiver
+ *  refused them as catalog lag and left them to be claimed again) once they are older than `CATALOG_LAG_RETRY_MS`. Returns how many. */
+export declare function expireOld(db: CanvasDb, now: number): Promise<number>;

package/dist/core/peer/outbox-store.js

@@ -0,0 +1,84 @@
+// The peer outbox (first crossing C4): events owed to another machine, kept in `peer_outbox`.
+//
+// One row per (message, destination stub), keyed `ev:<message_id>:<destination>` so a replayed
+// enqueue adds nothing. A row is `pending` (the lane may push it), `waiting` (only the peer's own
+// pull may take it), `claimed` (a pull has it, fenced by `claimed_by`), `done` or `expired`.
+// This module is pure database; the delivery lane that pushes rows is `src/daemon/peer/outbox.ts`.
+import { randomBytes } from 'node:crypto';
+import { filterAsync, mapAsync } from '../async-array.js';
+/** A claim not acked within this long is lost (the caller crashed or its answer never arrived) and may be taken again. */
+export const CLAIM_LEASE_MS = 10 * 60_000;
+/** A row not delivered within this long is given up on. */
+export const OUTBOX_MAX_AGE_MS = 30 * 24 * 60 * 60_000;
+/** A row the receiver refused only because its plugin catalog lags the sender's (`isCatalogLag`) is retried this long from creation,
+ *  then given up on: the receiver syncs within minutes, so a longer refusal is a real mismatch. Matches the app side's 24 h. */
+export const CATALOG_LAG_RETRY_MS = 24 * 60 * 60_000;
+const enqueueListeners = new Set();
+/** Subscribe to enqueues (the delivery lane pushes a relay peer's row at once). Returns the unsubscribe. */
+export function onPeerEnqueued(listener) {
+    enqueueListeners.add(listener);
+    return () => { enqueueListeners.delete(listener); };
+}
+/** Write one row; a key already present adds nothing. Returns whether a row was added. Runs in the caller's transaction. */
+export async function enqueuePeerRow(db, row, now = Date.now()) {
+    const inserted = await db.prepare(`INSERT INTO peer_outbox (peer, kind, payload_json, idempotency_key, state, attempts, next_at, created_at)
+    VALUES (?, ?, ?, ?, 'pending', 0, ?, ?) ON CONFLICT (idempotency_key) DO NOTHING`)
+        .run(row.peer, row.kind, JSON.stringify(row.payload), row.key, now, now);
+    if (Number(inserted.changes) === 0)
+        return false;
+    // Tell the lane after the surrounding transaction has had its chance to commit.
+    setImmediate(() => { for (const listener of [...enqueueListeners]) {
+        try {
+            listener(row.peer);
+        }
+        catch { /* a listener never fails an enqueue */ }
+    } });
+    return true;
+}
+/** Rows the lane may push now: pending and due. */
+export async function dueRows(db, now, limit = 200) {
+    return await db.prepare("SELECT * FROM peer_outbox WHERE state = 'pending' AND next_at <= ? ORDER BY id LIMIT ?").all(now, limit);
+}
+/** Pending rows to one peer that are new or due (a relay peer's push at enqueue; a row that already failed waits for its backoff). */
+export async function pendingFor(db, peer, now, limit = 50) {
+    return await db.prepare("SELECT * FROM peer_outbox WHERE state = 'pending' AND peer = ? AND (attempts = 0 OR next_at <= ?) ORDER BY id LIMIT ?").all(peer, now, limit);
+}
+export const markDone = async (db, id) => {
+    await db.prepare("UPDATE peer_outbox SET state = 'done', claimed_by = NULL, next_at = NULL WHERE id = ? AND state IN ('pending', 'waiting')").run(id);
+};
+export const markWaiting = async (db, id, attempts) => {
+    await db.prepare("UPDATE peer_outbox SET state = 'waiting', attempts = ?, next_at = NULL WHERE id = ? AND state = 'pending'").run(attempts, id);
+};
+export const markRetry = async (db, id, attempts, nextAt, firstFailedAt) => {
+    await db.prepare("UPDATE peer_outbox SET attempts = ?, next_at = ?, first_failed_at = ? WHERE id = ? AND state = 'pending'").run(attempts, nextAt, firstFailedAt, id);
+};
+export const markExpired = async (db, id) => {
+    await db.prepare("UPDATE peer_outbox SET state = 'expired', next_at = NULL WHERE id = ? AND state IN ('pending', 'waiting')").run(id);
+};
+/** The calling machine's own rows (`peer = via`, never another's), fenced with a fresh token. Takes pending and waiting rows
+ *  and claims whose lease ran out; a row still under a live lease is left alone. */
+export async function claimRows(db, via, limit, now = Date.now()) {
+    const take = Math.max(1, Math.min(limit, 100));
+    const rows = await db.prepare(`SELECT * FROM peer_outbox WHERE peer = ?
+    AND (state IN ('pending', 'waiting') OR (state = 'claimed' AND claimed_at <= ?)) ORDER BY id LIMIT ?`).all(via, now - CLAIM_LEASE_MS, take);
+    const token = randomBytes(16).toString('hex');
+    const claim = db.prepare("UPDATE peer_outbox SET state = 'claimed', claimed_by = ?, claimed_at = ?, next_at = NULL WHERE id = ?");
+    return (await mapAsync(rows, async (row) => { await claim.run(token, now, row.id); return { key: row.idempotency_key, claim_token: token, payload: JSON.parse(row.payload_json) }; }));
+}
+/** Mark done the rows the caller still holds: `peer = via`, the same token, still `claimed`. Returns the keys acked. */
+export async function ackRows(db, via, acks) {
+    const done = db.prepare(`UPDATE peer_outbox SET state = 'done', claimed_by = NULL WHERE idempotency_key = ? AND peer = ?
+    AND state = 'claimed' AND claimed_by = ?`);
+    return (await filterAsync(acks, async (ack) => Number((await done.run(ack.key, via, ack.claim_token)).changes) > 0)).map((ack) => ack.key);
+}
+/** Retire rows done long ago, so the table stays small. */
+export async function pruneOutbox(db, now, keepMs = 24 * 60 * 60_000) {
+    await db.prepare("DELETE FROM peer_outbox WHERE state IN ('done', 'expired') AND created_at < ?").run(now - keepMs);
+}
+/** Give up on rows older than `OUTBOX_MAX_AGE_MS` that were never delivered, and on rows whose claim lapsed unacked (the receiver
+ *  refused them as catalog lag and left them to be claimed again) once they are older than `CATALOG_LAG_RETRY_MS`. Returns how many. */
+export async function expireOld(db, now) {
+    return Number((await db.prepare(`UPDATE peer_outbox SET state = 'expired', next_at = NULL
+    WHERE (state IN ('pending', 'waiting') AND created_at < ?) OR (state = 'claimed' AND claimed_at <= ? AND created_at < ?)`)
+        .run(now - OUTBOX_MAX_AGE_MS, now - CLAIM_LEASE_MS, now - CATALOG_LAG_RETRY_MS)).changes);
+}

package/dist/core/peer/receiver.d.ts

@@ -0,0 +1,8 @@
+import type { Receiver } from '../graph/receivers.js';
+import { type PeerEventPayload } from './outbox-store.js';
+import type { CanvasDb } from '../canvas/db.js';
+/** The outbox key of one event to one destination stub. */
+export declare const eventKey: (messageId: string, destination: string) => string;
+/** The event as it crosses the wire: the object and actor by identity, the attributes, and the body inline. */
+export declare function payloadFor(db: CanvasDb, messageId: string, key: string): Promise<PeerEventPayload>;
+export declare const peerReceiver: Receiver;

package/dist/core/peer/receiver.js

@@ -0,0 +1,54 @@
+// The `peer` receiver (first crossing C4): a destination that is a stub of a watcher on another
+// machine gets its event as an outbox row instead of an inbox delivery. `publish` hands it the
+// stub destinations already filtered by `readerForObject(stub)` (current grant, never cached),
+// so a revoked or unreadable stub never reaches here.
+import { heads } from '../graph/documents.js';
+import { get as getBody } from '../graph/bodies.js';
+import { getById } from '../graph/objects.js';
+import { enqueuePeerRow } from './outbox-store.js';
+import { describeObject, stubOf } from './stubs.js';
+/** The outbox key of one event to one destination stub. */
+export const eventKey = (messageId, destination) => `ev:${messageId}:${destination}`;
+async function reportText(db, push) {
+    const id = typeof push?.pointer === 'string' ? push.pointer : undefined;
+    const doc = id === undefined ? null : await getById(db, id);
+    if (doc === null || doc.type !== 'document' || doc.deleted_at !== null)
+        return undefined;
+    const head = (await heads(db, doc))[0];
+    if (head === undefined)
+        return undefined;
+    return await getBody(db, head.body_hash);
+}
+/** The event as it crosses the wire: the object and actor by identity, the attributes, and the body inline. */
+export async function payloadFor(db, messageId, key) {
+    const message = await db.prepare('SELECT message_id, event, object_id, level, actor_id, body_ref, body_json FROM messages WHERE message_id = ?').get(messageId);
+    if (message === undefined)
+        throw new Error(`no message ${messageId}`);
+    const object = await getById(db, message.object_id);
+    if (object === null)
+        throw new Error(`no object ${message.object_id}`);
+    const actor = message.actor_id === null ? null : await getById(db, message.actor_id);
+    const json = message.body_json === null ? {} : JSON.parse(message.body_json);
+    const { push, bodyRef: _bodyRef, ...rest } = json;
+    const bodyText = message.body_ref === null ? undefined : await reportText(db, push);
+    return {
+        key, message_id: message.message_id, event: message.event, level: message.level,
+        object: await describeObject(db, object), actor: actor === null ? null : await describeObject(db, actor),
+        attrs: push?.attrs ?? {},
+        ...(Object.keys(rest).length > 0 ? { body: rest } : {}),
+        ...(bodyText === undefined ? {} : { body_text: bodyText }),
+    };
+}
+export const peerReceiver = {
+    bodyOwner: () => null,
+    /** Writes one `peer_outbox` row per stub destination, key `ev:<message_id>:<destination>`. Runs in publish's transaction. */
+    async enqueue(db, message, destinations) {
+        for (const destination of destinations) {
+            const stub = await stubOf(db, destination.id);
+            if (stub === null)
+                continue;
+            const key = eventKey(message.messageId, destination.id);
+            await enqueuePeerRow(db, { peer: stub.home_machine, kind: 'event', key, payload: { ...await payloadFor(db, message.messageId, key), ...(destination.linked ? { linked: true } : {}) } });
+        }
+    },
+};