@north-light/api 0.3.579 → 0.3.587

package/dist/core/grants/sync.js

@@ -0,0 +1,195 @@
+import { createPrivateKey, randomUUID, sign } from 'node:crypto';
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { crtrHome } from '../canvas/paths.js';
+import { isUnsandboxedMachine } from '../runtime/unsandboxed.js';
+import { emitEvent } from '../events/emit.js';
+import { describeOutboundFailure, outboundFetch, outboundJson, outboundRefusal } from '../events/outbound.js';
+import { dependenciesOf, inferenceEndpointOf, replaceGrants, teamsOf } from './mirror.js';
+import { onGrantSync } from './on-sync.js';
+import { adoptInstallPerson } from '../scoped-state/migrate.js';
+import { PersonOutsideRequestError, PersonUnresolvedError, personId, resolvePerson, retireLocalPerson, setPersonId } from '../canvas/person.js';
+export const GRANT_SYNC_INTERVAL_S = 300;
+/** A `private_key_jwt` client assertion for `endpoint` (the directory's token endpoint), signed by the runtime client key. */
+export function assertion(client, endpoint) {
+    const now = Math.floor(Date.now() / 1000);
+    const header = Buffer.from(JSON.stringify({ alg: 'ES256', typ: 'JWT', kid: client.kid })).toString('base64url');
+    const payload = Buffer.from(JSON.stringify({ iss: client.client_id, sub: client.client_id, aud: endpoint,
+        iat: now, exp: now + 300, jti: randomUUID() })).toString('base64url');
+    const input = `${header}.${payload}`;
+    const signature = sign('sha256', Buffer.from(input), { key: createPrivateKey({ key: client.jwk, format: 'jwk' }), dsaEncoding: 'ieee-p1363' });
+    return `${input}.${signature.toString('base64url')}`;
+}
+export function runtimeClient() {
+    const client = JSON.parse(readFileSync(join(crtrHome(), 'secrets', 'runtime-client.json'), 'utf8'));
+    if (!client.jwk || client.alg !== 'ES256' || !client.kid || !client.client_id || !client.runtime ||
+        client.jwk.kid !== client.kid || client.jwk.kty !== 'EC' || client.jwk.crv !== 'P-256' || !client.jwk.d) {
+        throw new TypeError('invalid runtime client key');
+    }
+    return client;
+}
+/** The runtime's id as storage names it: the directory principal id without `runtime:`. */
+export function runtimeId(client = runtimeClient()) {
+    return client.runtime.startsWith('runtime:') ? client.runtime.slice('runtime:'.length) : client.runtime;
+}
+/** The text a person sees when the directory no longer recognises this machine. */
+export function machineRevokedMessage(issuer) {
+    return `This machine was removed from your Northlight account. To use it again, create a join token at ${issuer.replace(/\/$/, '')}/account/machines, and run \`crtr sys join\` from a plain terminal.`;
+}
+/** The directory answered `invalid_client` to this runtime's key: the machine was revoked. */
+export class MachineRevokedError extends Error {
+    constructor(issuer) { super(machineRevokedMessage(issuer)); this.name = 'MachineRevokedError'; }
+}
+/** A `client_credentials` token for the runtime client. With `audience`, the
+ *  directory issues it for that audience (the storage service); without, for
+ *  the directory's own `/v1`. `expires_at` is epoch ms. */
+export async function mintDirectoryToken(issuer, audience) {
+    const client = runtimeClient();
+    const tokenEndpoint = `${issuer.replace(/\/$/, '')}/token`;
+    const body = new URLSearchParams({ grant_type: 'client_credentials',
+        client_id: client.client_id,
+        client_assertion_type: 'urn:ietf:params:oauth:client-assertion-type:jwt-bearer',
+        client_assertion: assertion(client, tokenEndpoint),
+        ...(audience === undefined ? {} : { audience }) });
+    const tokenResponse = await outboundFetch('directory_token', tokenEndpoint, { method: 'POST', body, signal: AbortSignal.timeout(10_000) });
+    if (!tokenResponse.ok) {
+        if (tokenResponse.status === 401 && isUnsandboxedMachine() && await isInvalidClient(tokenResponse))
+            throw new MachineRevokedError(issuer);
+        throw outboundRefusal('directory_token', tokenEndpoint, `directory token request failed: ${tokenResponse.status}`);
+    }
+    const token = await outboundJson('directory_token', tokenEndpoint, tokenResponse);
+    if (typeof token.access_token !== 'string')
+        throw new TypeError('directory token response has no access_token');
+    return { access_token: token.access_token, expires_at: tokenExpiry(token.access_token, token.expires_in) };
+}
+async function isInvalidClient(response) {
+    try {
+        return (await response.json()).error === 'invalid_client';
+    }
+    catch {
+        return false;
+    }
+}
+function tokenExpiry(accessToken, expiresIn) {
+    if (typeof expiresIn === 'number' && Number.isFinite(expiresIn) && expiresIn > 0)
+        return Date.now() + expiresIn * 1000;
+    try {
+        const payload = JSON.parse(Buffer.from(accessToken.split('.')[1] ?? '', 'base64url').toString('utf8'));
+        if (typeof payload.exp === 'number')
+            return payload.exp * 1000;
+    }
+    catch { /* an opaque token: fall through */ }
+    return Date.now() + 300_000;
+}
+/** An unsandboxed machine's answer also carries the account's hosted-runtime app
+ *  grants (`runtime` = the hosted runtime), mirrored read-only. A sandboxed or
+ *  hosted runtime accepts only its own runtime's records. */
+function responseGrant(value, client) {
+    if (!value || typeof value !== 'object')
+        throw new TypeError('invalid grant sync response');
+    const grant = value;
+    const own = client.runtime.startsWith('runtime:') ? client.runtime : `runtime:${client.runtime}`;
+    // Another runtime's `app:terminal` grant is never mirrored: `terminalGrant(person)` must find only this runtime's.
+    const runtimeOk = grant.runtime === own ||
+        (isUnsandboxedMachine() && typeof grant.runtime === 'string' && grant.runtime.startsWith('runtime:') && grant.grantee !== 'app:terminal');
+    if (!runtimeOk || typeof grant.id !== 'string' || typeof grant.sub !== 'string' ||
+        typeof grant.grantee !== 'string' || !Number.isInteger(grant.rev) ||
+        !Array.isArray(grant.scopes) || !Array.isArray(grant.resolved_scopes) ||
+        !['active', 'revoked', 'removed'].includes(grant.status ?? '') || typeof grant.synced_at !== 'string') {
+        throw new TypeError('invalid grant sync response');
+    }
+    const revisions = value.revisions;
+    const approvedAt = revisions?.find((revision) => revision.rev === grant.rev)?.approved_at;
+    if (typeof approvedAt !== 'string')
+        throw new TypeError('grant revision has no approval time');
+    // An absent or unrecognised payer is `user` (an older directory sends none); the endpoint rides only an app-paid grant.
+    const payer = grant.payer === 'app' ? 'app' : 'user';
+    return { ...grant, spend_cap: grant.spend_cap ?? null, expires_at: grant.expires_at ?? null,
+        revoked_at: grant.revoked_at ?? null, approved_at: approvedAt, payer, dependencies: dependenciesOf(grant.dependencies),
+        inference_endpoint: payer === 'app' ? inferenceEndpointOf(grant.inference_endpoint) : null,
+        run_notice_url: typeof grant.run_notice_url === 'string' && grant.run_notice_url !== '' ? grant.run_notice_url : null };
+}
+/** A hosted first boot has no person until its first snapshot commits: resolve it from the mirror and run the boot one-shot. */
+async function resolveLatePerson() {
+    // A cloud role has no install person to resolve.
+    try {
+        personId();
+        return;
+    }
+    catch (error) {
+        if (error instanceof PersonOutsideRequestError)
+            return;
+        if (!(error instanceof PersonUnresolvedError))
+            throw error;
+    }
+    const resolved = await resolvePerson();
+    if (resolved === null)
+        return;
+    setPersonId(resolved.id);
+    await adoptInstallPerson(resolved.id);
+    const result = await retireLocalPerson();
+    emitEvent({ level: 'info', event: 'daemon.person.resolved', fields: { person_id: resolved.id, source: resolved.source } });
+    emitEvent({ level: 'info', event: 'daemon.person.retired', fields: { person_id: result.person, retired: result.retired, columns: result.columns } });
+}
+let current;
+/** Ask the daemon's grant sync (the latest `createGrantSync`) for a pull; a
+ *  no-op where none exists (v0, a process that is not the daemon). */
+export function requestGrantSync(options) {
+    return current ? current(options) : Promise.resolve();
+}
+/** Calls share one in-flight pull, including the start, periodic, and
+ *  unknown-grant triggers. A `fresh` call (a directory sync notice) needs a pull
+ *  that started after it arrived: while one is in flight it queues exactly one
+ *  more, which every later fresh call shares. A pull resolves once the mirror is
+ *  committed and the R26 stops have started; stop completion and removal
+ *  cascades run as `detach`ed work. */
+export function createGrantSync(issuer, detach = (work) => { void work; }) {
+    let inFlight;
+    const base = issuer.replace(/\/$/, '');
+    const run = async () => {
+        const client = runtimeClient();
+        const token = await mintDirectoryToken(base);
+        const response = await outboundFetch('grant_sync', `${base}/v1/runtime/grants`, { headers: { Authorization: `Bearer ${token.access_token}` }, signal: AbortSignal.timeout(10_000) });
+        if (!response.ok)
+            throw outboundRefusal('grant_sync', `${base}/v1/runtime/grants`, `directory grant sync failed: ${response.status}`);
+        const payload = await outboundJson('grant_sync', `${base}/v1/runtime/grants`, response);
+        if (!Array.isArray(payload.grants) || typeof payload.synced_at !== 'string')
+            throw new TypeError('invalid grant sync response');
+        await replaceGrants(payload.grants.map((grant) => responseGrant(grant, client)), payload.synced_at, base, teamsOf(payload.teams));
+        emitEvent({ level: 'info', event: 'daemon.grants.synced', fields: { grants: payload.grants.length, synced_at: payload.synced_at } });
+        await resolveLatePerson();
+        // The mirror is committed; stops start inside this pull, removals continue detached.
+        try {
+            await onGrantSync(detach);
+        }
+        catch (error) {
+            emitEvent({ level: 'error', event: 'daemon.grants.on_sync_failed', error });
+        }
+    };
+    let queued;
+    const start = () => {
+        const job = run().catch((error) => {
+            // The mirror is kept: nothing is deleted locally when the machine is removed.
+            if (error instanceof MachineRevokedError)
+                emitEvent({ level: 'error', event: 'daemon.grants.machine_revoked', error });
+            else
+                emitEvent({ level: 'error', event: 'daemon.grants.sync_failed', error, fields: describeOutboundFailure(error) });
+            throw error;
+        }).finally(() => { if (inFlight === job)
+            inFlight = undefined; });
+        inFlight = job;
+        return job;
+    };
+    const sync = (options = {}) => {
+        if (!inFlight)
+            return start();
+        if (!options.fresh)
+            return inFlight;
+        // The running pull may have fetched before the change this caller announces.
+        // A pull another caller started after this point is just as fresh; share it.
+        queued ??= inFlight.catch(() => { }).then(() => { queued = undefined; return inFlight ?? start(); });
+        return queued;
+    };
+    current = sync;
+    return sync;
+}

package/dist/core/grants/terminal.d.ts

@@ -0,0 +1,10 @@
+import { type ActiveGrant } from './mirror.js';
+/** The request's person, or on a Mac the install's person. Null when there is none: a hosted first boot before its first grant snapshot, or a cloud
+ *  role outside a request (a lane there works for the person on the row it claimed; it never borrows "the only grant"). */
+export declare function callerPerson(): Promise<string | null>;
+/** The terminal grant of the request person (or, on a Mac, the install's person); null when the call has no person. */
+export declare function callerTerminalGrant(): Promise<ActiveGrant | null>;
+/** The terminal grant of the person a node row belongs to: its own `sub`, else (a node born before its person was known) the caller's. */
+export declare function nodeTerminalGrant(node: {
+    sub?: string | null;
+}): Promise<ActiveGrant | null>;

package/dist/core/grants/terminal.js

@@ -0,0 +1,25 @@
+// Which person a terminal-app call is for, and that person's terminal grant. One runtime serves many people on the fleet,
+// so no caller asks for "the" terminal grant: it asks for a person's.
+import { PersonOutsideRequestError, PersonUnresolvedError, personIdAsync } from '../canvas/person.js';
+import { terminalGrant } from './mirror.js';
+/** The request's person, or on a Mac the install's person. Null when there is none: a hosted first boot before its first grant snapshot, or a cloud
+ *  role outside a request (a lane there works for the person on the row it claimed; it never borrows "the only grant"). */
+export async function callerPerson() {
+    try {
+        return await personIdAsync();
+    }
+    catch (error) {
+        if (error instanceof PersonUnresolvedError || error instanceof PersonOutsideRequestError)
+            return null;
+        throw error;
+    }
+}
+/** The terminal grant of the request person (or, on a Mac, the install's person); null when the call has no person. */
+export async function callerTerminalGrant() {
+    const person = await callerPerson();
+    return person === null ? null : await terminalGrant(person);
+}
+/** The terminal grant of the person a node row belongs to: its own `sub`, else (a node born before its person was known) the caller's. */
+export async function nodeTerminalGrant(node) {
+    return node.sub ? await terminalGrant(node.sub) : await callerTerminalGrant();
+}

package/dist/core/graph/access.d.ts

@@ -0,0 +1,13 @@
+import type { CanvasDb } from '../canvas/db.js';
+import type { ObjectRow, Reader } from './types.js';
+/** The top of the object's owner chain (the object itself when it has no owner): its app, person or repo. */
+export declare function spaceOf(db: CanvasDb, object: ObjectRow): Promise<ObjectRow>;
+/** A shipped document: one a package reconciler owns (`documents.source_path` is set, as provenance and the shipped marker). Only the reconciler writes it. */
+export declare function isShipped(db: CanvasDb, object: ObjectRow): Promise<boolean>;
+/** Callers turn `false` into `not_found`. */
+export declare function canRead(db: CanvasDb, reader: Reader, object: ObjectRow): Promise<boolean>;
+/** A shipped document is changed by nobody, its own app included: only the package reconciler writes it, and it asks no reader. A repo owns only
+ *  public documents, so a non-public one under a repo is never changed, whoever asks. */
+export declare function canChange(db: CanvasDb, reader: Reader, object: ObjectRow): Promise<boolean>;
+/** Whether a non-person reader reaches `object` through `crtr:objects:<verb>:<target>`: the ceiling for that verb, then the schema. A person holds no scope. */
+export declare function holdsObjectsScope(db: CanvasDb, reader: Reader, verb: 'read' | 'watch' | 'link' | 'write', object: ObjectRow): Promise<boolean>;

package/dist/core/graph/access.js

@@ -0,0 +1,37 @@
+import { check, resolveReader } from '../permissions/evaluator.js';
+/** The top of the object's owner chain (the object itself when it has no owner): its app, person or repo. */
+export async function spaceOf(db, object) {
+    const top = await db.prepare(`WITH RECURSIVE chain(id, owner, depth) AS (
+      SELECT id, owner, 0 FROM objects WHERE id = ?
+      UNION ALL
+      SELECT o.id, o.owner, c.depth + 1 FROM objects o JOIN chain c ON o.id = c.owner WHERE c.depth < 12
+    ) SELECT o.* FROM chain c JOIN objects o ON o.id = c.id ORDER BY c.depth DESC LIMIT 1`).get(object.id);
+    return top ?? object;
+}
+/** A shipped document: one a package reconciler owns (`documents.source_path` is set, as provenance and the shipped marker). Only the reconciler writes it. */
+export async function isShipped(db, object) {
+    if (object.type !== 'document')
+        return false;
+    const row = await db.prepare('SELECT source_path FROM documents WHERE object = ?').get(object.id);
+    return row?.source_path != null;
+}
+/** Callers turn `false` into `not_found`. */
+export async function canRead(db, reader, object) {
+    return await check(db, reader, 'read', object.id);
+}
+/** A shipped document is changed by nobody, its own app included: only the package reconciler writes it, and it asks no reader. A repo owns only
+ *  public documents, so a non-public one under a repo is never changed, whoever asks. */
+export async function canChange(db, reader, object) {
+    if (await isShipped(db, object))
+        return false;
+    if (object.privacy !== 'public' && (await spaceOf(db, object)).type === 'repo' && object.owner !== null)
+        return false;
+    return await check(db, reader, 'edit', object.id);
+}
+/** Whether a non-person reader reaches `object` through `crtr:objects:<verb>:<target>`: the ceiling for that verb, then the schema. A person holds no scope. */
+export async function holdsObjectsScope(db, reader, verb, object) {
+    if (reader.class === 'person')
+        return false;
+    const ev = await resolveReader(db, reader);
+    return verb === 'write' ? await check(db, ev, 'edit', object.id) : await check(db, ev, 'read', object.id, verb === 'read' ? {} : { verb });
+}

package/dist/core/graph/bodies.d.ts

@@ -0,0 +1,22 @@
+import type { CanvasDb } from '../canvas/db.js';
+export declare function hashOf(body: string): string;
+/** Postgres `text` cannot hold U+0000, so each NUL is stored as U+FFFD. The one rule for a new write, the Mac boot copy and repo sync. */
+export declare function storable(text: string): string;
+/** The pair a body is stored and exchanged as: the text `storable` makes of `original` and the hash of that text.
+ *  A `suppliedHash` is the hash `original` arrived with (a repo ref, a retained file); it is checked against `original`, never used as the key. */
+export declare function canonical(original: string, suppliedHash?: string): {
+    text: string;
+    hash: string;
+};
+/** Insert `text` under `hash`, or confirm the row already there holds exactly that text: a different text under a key is corruption, not a duplicate.
+ *  Returns whether a row was added. */
+export declare function store(db: CanvasDb, hash: string, text: string): Promise<boolean>;
+/** Store a body and return its hash, which is the hash of the text as stored (see `canonical`). Call inside the transaction that writes the
+ *  revision naming it, so a rolled-back write leaves neither.
+ *  `suppliedHash` is for text that arrives with the hash its source named (repo sync): it must be the hash of `body` as given; the row is keyed by the hash of the stored text. */
+export declare function put(db: CanvasDb, body: string, suppliedHash?: string): Promise<string>;
+export declare function get(db: CanvasDb, hash: string): Promise<string>;
+/** The bodies that exist among `hashes`, in one query. A hash with no row is absent from the map. */
+export declare function findMany(db: CanvasDb, hashes: readonly string[]): Promise<Map<string, string>>;
+/** Several bodies in one query. A hash with no row is `no body <hash>`, as for `get`. */
+export declare function getMany(db: CanvasDb, hashes: readonly string[]): Promise<Map<string, string>>;

package/dist/core/graph/bodies.js

@@ -0,0 +1,68 @@
+import { createHash } from 'node:crypto';
+import { notFound } from '../errors.js';
+/** Content-addressed document text: the `bodies` table, `hash` = sha256 of the text (hex). A revision names its text by `body_hash`.
+ *  Rows are immutable; only the boot repair removes a proven invalid old-key duplicate left by #822. */
+const HASH = /^[0-9a-f]{64}$/;
+function checked(hash) {
+    if (!HASH.test(hash))
+        throw new Error(`invalid body hash: ${hash}`);
+    return hash;
+}
+export function hashOf(body) {
+    return createHash('sha256').update(body, 'utf8').digest('hex');
+}
+/** Postgres `text` cannot hold U+0000, so each NUL is stored as U+FFFD. The one rule for a new write, the Mac boot copy and repo sync. */
+export function storable(text) {
+    return text.replaceAll('\u0000', '\uFFFD');
+}
+/** The pair a body is stored and exchanged as: the text `storable` makes of `original` and the hash of that text.
+ *  A `suppliedHash` is the hash `original` arrived with (a repo ref, a retained file); it is checked against `original`, never used as the key. */
+export function canonical(original, suppliedHash) {
+    if (suppliedHash !== undefined && hashOf(original) !== checked(suppliedHash))
+        throw new Error(`body does not match its hash ${suppliedHash}`);
+    const text = storable(original);
+    return { text, hash: hashOf(text) };
+}
+/** Insert `text` under `hash`, or confirm the row already there holds exactly that text: a different text under a key is corruption, not a duplicate.
+ *  Returns whether a row was added. */
+export async function store(db, hash, text) {
+    if ((await db.prepare('INSERT INTO bodies (hash, text) VALUES (?, ?) ON CONFLICT (hash) DO NOTHING').run(checked(hash), text)).changes === 1)
+        return true;
+    const held = await db.prepare('SELECT text FROM bodies WHERE hash = ?').get(hash);
+    if (held === undefined || held.text !== text)
+        throw new Error(`body ${hash} already holds different text`);
+    return false;
+}
+/** Store a body and return its hash, which is the hash of the text as stored (see `canonical`). Call inside the transaction that writes the
+ *  revision naming it, so a rolled-back write leaves neither.
+ *  `suppliedHash` is for text that arrives with the hash its source named (repo sync): it must be the hash of `body` as given; the row is keyed by the hash of the stored text. */
+export async function put(db, body, suppliedHash) {
+    const { text, hash } = canonical(body, suppliedHash);
+    await store(db, hash, text);
+    return hash;
+}
+export async function get(db, hash) {
+    const row = await db.prepare('SELECT text FROM bodies WHERE hash = ?').get(checked(hash));
+    if (row === undefined)
+        throw notFound(`no body ${hash}`);
+    return row.text;
+}
+/** The bodies that exist among `hashes`, in one query. A hash with no row is absent from the map. */
+export async function findMany(db, hashes) {
+    const wanted = [...new Set(hashes)].map(checked);
+    const out = new Map();
+    if (wanted.length === 0)
+        return out;
+    const rows = await db.prepare('SELECT hash, text FROM bodies WHERE hash = ANY(?::text[])').all(wanted);
+    for (const row of rows)
+        out.set(row.hash, row.text);
+    return out;
+}
+/** Several bodies in one query. A hash with no row is `no body <hash>`, as for `get`. */
+export async function getMany(db, hashes) {
+    const out = await findMany(db, hashes);
+    for (const hash of hashes)
+        if (!out.has(hash))
+            throw notFound(`no body ${hash}`);
+    return out;
+}

package/dist/core/graph/custom.d.ts

@@ -0,0 +1,98 @@
+import type { Level, ObjectRow, Privacy, Reader } from './types.js';
+import { onQueueSignal } from './receivers.js';
+import type { CanvasDb } from '../canvas/db.js';
+/** Whether this reader may register, publish or watch as an object owned by `owner`. */
+export declare function mayActAs(db: CanvasDb, reader: Reader, owner: ObjectRow): Promise<boolean>;
+/** Whether the reader reaches the custom object: it may read it. */
+export declare function customReachable(db: CanvasDb, reader: Reader, object: ObjectRow): Promise<boolean>;
+export { onQueueSignal };
+export type CustomReceiver = 'queue' | {
+    url: string;
+} | {
+    argv: string[];
+    cwd: string;
+};
+export type CustomEvents = Record<string, {
+    level: Level;
+    supersedes?: boolean;
+    ends_wait?: boolean;
+}>;
+export interface QueueLine {
+    delivery_id: string;
+    message_id: string;
+    seq: number;
+    event: string;
+    level: number;
+    object: {
+        id: string;
+        type: string;
+        name: string;
+        owner: string | null;
+    };
+    actor: string | null;
+    attrs: Record<string, unknown>;
+    summary?: string;
+    state?: unknown;
+    pointer?: string;
+    depth: number;
+    created_at: string;
+}
+/** Register a kind and a named instance in the caller's write transaction. */
+export declare function registerCustomObject(db: CanvasDb, reader: Reader, input: {
+    kind: string;
+    name: string;
+    owner: ObjectRow;
+    description: string;
+    /** Omitted: create or return only the instance of a kind an installed plugin (or a peer) declares; the catalog is untouched. */
+    events?: CustomEvents;
+    receiver?: CustomReceiver | null;
+    rotateToken?: boolean;
+    privacy?: Privacy;
+}): Promise<{
+    object: ObjectRow;
+    token?: string;
+    created: boolean;
+    changed: string[];
+}>;
+export type KindSource = 'register' | 'manifest' | 'peer';
+export type KindChange = 'events' | 'description' | 'read';
+/**
+ * The only writer of `object_kinds`. `source` says who is writing: an app's `register` call, an installed plugin's
+ * manifest, or a declaration that crossed from another machine (`peer`). Precedence: `manifest` and `register` rows
+ * are never overwritten by `peer`; a `manifest` write takes over a row it already owns and replaces a `peer` row;
+ * a `register` write leaves a `manifest` row alone (`skipped`) and replaces a `peer` row; another owner's
+ * `manifest` or `register` row is `kind_owned`. `read_json` is written only by `manifest`. A catalog is replaced,
+ * never merged. Runs in the caller's write transaction.
+ */
+export declare function upsertKind(db: CanvasDb, input: {
+    name: string;
+    owner: ObjectRow;
+    description: string;
+    events: CustomEvents;
+    read: {
+        command: string[];
+    } | null;
+    source: KindSource;
+}): Promise<{
+    outcome: 'inserted' | 'updated' | 'unchanged' | 'skipped';
+    changed: KindChange[];
+}>;
+export declare function publishCustom(db: CanvasDb, object: ObjectRow, actor: ObjectRow | null, input: {
+    event: string;
+    summary: string;
+    state?: unknown;
+    cause?: string;
+}): Promise<{
+    message_id: string | null;
+    delivered: number;
+    depth: number;
+}>;
+export declare function unregisterCustomObject(db: CanvasDb, object: ObjectRow, actor: ObjectRow | null): Promise<void>;
+export declare function pendingFor(db: CanvasDb, object: ObjectRow, afterSeq?: number): Promise<QueueLine[]>;
+/** A claimed push delivery has the identical document as a pending queue delivery. */
+export declare function pushLineFor(db: CanvasDb, deliveryId: string): Promise<QueueLine | null>;
+export declare function acknowledge(db: CanvasDb, object: ObjectRow, deliveryIds: string[]): Promise<{
+    acknowledged: number;
+    unknown?: string[];
+}>;
+export declare function verifyPublishToken(db: CanvasDb, object: ObjectRow, token: string): Promise<boolean>;