@north-light/api 0.3.580 → 0.3.588

package/dist/core/graph/kinds/dto.d.ts

@@ -0,0 +1,5 @@
+/** An object row as the `/v1/objects` wire shape. */
+import type { ObjectDTO } from '../../../api/dto/objects.js';
+import type { ObjectRow } from '../types.js';
+import type { CanvasDb } from '../../canvas/db.js';
+export declare function objectDTO(db: CanvasDb, o: ObjectRow): Promise<ObjectDTO>;

package/dist/core/graph/kinds/dto.js

@@ -0,0 +1,11 @@
+import { getById } from '../objects.js';
+export async function objectDTO(db, o) {
+    const owner = o.owner === null ? null : await getById(db, o.owner);
+    const ownerDTO = owner
+        ? { id: owner.id, type: owner.type, handle: owner.type === 'node' ? owner.id : owner.name }
+        : null;
+    return {
+        id: o.id, type: o.type, kind: o.kind, owner: ownerDTO, privacy: o.privacy,
+        name: o.name, preview: o.preview ?? '', created_at: o.created_at, deleted_at: o.deleted_at,
+    };
+}

package/dist/core/graph/kinds/environment.d.ts

@@ -0,0 +1,2 @@
+import { type ObjectKind } from './kind.js';
+export declare const environmentKind: ObjectKind;

package/dist/core/graph/kinds/environment.js

@@ -0,0 +1,21 @@
+/** The environment kind: a place objects run. Today only the machine an install runs on. */
+import { objectDTO } from './dto.js';
+import { withBase } from './kind.js';
+import { recordLiveRead } from './live-read.js';
+import { attr, header } from './render.js';
+export const environmentKind = {
+    name: 'environment',
+    addressable: 'id',
+    events: withBase(),
+    async read(db, reader, environment, opts) {
+        const row = await db.prepare('SELECT kind, machine_id, last_seen_at FROM environments WHERE object = ?').get(environment.id);
+        if (!row)
+            throw new Error(`environment object ${environment.id} has no environments row`);
+        await recordLiveRead(db, reader, environment, opts.reposFn);
+        const o = await objectDTO(db, environment);
+        const data = { kind: row.kind, machine_id: row.machine_id, last_seen_at: row.last_seen_at };
+        const text = [header('object', o, attr('machine_id', data.machine_id) + attr('last_seen_at', data.last_seen_at)),
+            `Kind: ${data.kind}`, `Machine: ${data.machine_id}`, `Last seen: ${data.last_seen_at}`].join('\n');
+        return { data, text };
+    },
+};

package/dist/core/graph/kinds/job.d.ts

@@ -0,0 +1,2 @@
+import { type ObjectKind } from './kind.js';
+export declare const jobKind: ObjectKind;

package/dist/core/graph/kinds/job.js

@@ -0,0 +1,24 @@
+/** The job kind: a backgrounded bash command a node started. */
+import { jobRow } from '../jobs.js';
+import { objectDTO } from './dto.js';
+import { withBase } from './kind.js';
+import { recordLiveRead } from './live-read.js';
+import { attr, header } from './render.js';
+export const jobKind = {
+    name: 'job',
+    addressable: 'id',
+    events: withBase({ exited: { level: 7 }, killed: { level: 7 }, silent: { level: 7 } }),
+    async read(db, reader, job, opts) {
+        const row = await jobRow(db, job);
+        if (!row)
+            throw new Error(`job object ${job.id} has no jobs row`);
+        await recordLiveRead(db, reader, job, opts.reposFn);
+        const o = await objectDTO(db, job);
+        const data = { command: row.command, status: row.status, exit_code: row.exit_code, output_key: row.output_key };
+        const text = [
+            header('object', o, attr('status', data.status) + attr('exit_code', data.exit_code)),
+            `Command: ${data.command}`, `Output: \`crtr node bash log ${job.id}${job.owner === null ? '' : ` --node ${job.owner}`}\``,
+        ].join('\n');
+        return { data, text };
+    },
+};

package/dist/core/graph/kinds/kind.d.ts

@@ -0,0 +1,67 @@
+/** The one interface every canvas object kind implements: its declared events, how it is
+ *  addressed, and how it reads. The kind name is what `objects.type` stores. */
+import type { ReposFn } from '../reader.js';
+import type { ReceiverName } from '../receivers.js';
+import type { CanvasEvent, Level, ObjectRow, Reader } from '../types.js';
+import type { CanvasDb } from '../../canvas/db.js';
+/** A superseding event's attrs: built from the superseded pending delivery's attrs (null when it
+ *  supersedes nothing) and the new event. */
+export type SupersedeMerge = (prior: Record<string, unknown> | null, ev: CanvasEvent) => Record<string, unknown>;
+/** One declared event: its default level and, only where a sender may choose, the levels it may pick. */
+export interface EventSpec {
+    level: Level;
+    levels?: readonly Level[];
+    /** A newer event replaces each destination's pending, unclaimed delivery of the same event on
+     *  the same object, so a destination holds at most one of them. */
+    supersedes?: boolean;
+    /** With `supersedes`: the replacement's attrs. Omitted: the newer event's attrs replace the older. */
+    merge?: SupersedeMerge;
+    /** Reaches every watcher that can receive at all (`objects.reception >= 1`), including a done
+     *  node, which the inbox receiver never wakes. Omitted: only fully receiving watchers
+     *  (`reception = 2`). */
+    durable?: boolean;
+    /** The publisher's `messageBody` rides in the message (a report's label and pointer, a notice's
+     *  sentence and data). */
+    carriesBody?: boolean;
+    /** Raise a terminal-lifecycle inbox's normal/deferred tier for this event. */
+    elevatesTier?: boolean;
+    /** The inbox kind the message is filed under. Omitted: `urgent` at level 7 and above, else `update`. */
+    inboxKind?: 'final' | 'completed';
+    /** A node that watches an object of this kind is waiting on it until this event (a run's
+     *  `completed`, a pull request's `merged`); `publish` settles that wait (`waits`, kind `object`). */
+    endsWait?: boolean;
+}
+export type EventCatalog = Readonly<Record<string, EventSpec>>;
+/** What a read answers: the kind's structured fields and exactly the text `crtr canvas read` prints. */
+export interface KindRead {
+    data: Record<string, unknown>;
+    text: string;
+}
+export interface ReadOpts {
+    /** A document read also returns its optional fields. */
+    fields: boolean;
+    reposFn: ReposFn;
+}
+export interface ObjectKind {
+    /** Stored in `objects.type`. */
+    name: string;
+    /** The base events merged with the kind's own. */
+    events: EventCatalog;
+    /** `name`: found by `<owner>/<name>`; `id`: by id only; `handle`: an owner's handle. */
+    addressable: 'name' | 'id' | 'handle';
+    /** How a watcher of this kind receives events (a key of `receivers.ts`). Absent: it cannot watch. */
+    receiver?: ReceiverName;
+    /** Resolve a receiver from this particular object, when it is configured per instance. */
+    receiverFor?(db: CanvasDb, object: ObjectRow): Promise<ReceiverName | undefined>;
+    /** A kind may fence claimed deliveries when a superseding event replaces them. Return true
+     *  only if the claimed delivery was replaced; model handoffs are not retractable. */
+    supersedeClaimed?(db: CanvasDb, deliveryId: string): Promise<boolean>;
+    /** Records the read (a watch and a `read` event) and renders the object. */
+    read(db: CanvasDb, reader: Reader, object: ObjectRow, opts: ReadOpts): Promise<KindRead>;
+    /** Extra fields a list or search row carries. */
+    listItem?(db: CanvasDb, object: ObjectRow): Promise<Record<string, unknown>>;
+}
+/** Events every kind inherits. */
+export declare const BASE_EVENTS: EventCatalog;
+/** The base events with a kind's own merged over them. */
+export declare function withBase(own?: EventCatalog): EventCatalog;

package/dist/core/graph/kinds/kind.js

@@ -0,0 +1,15 @@
+/** Events every kind inherits. */
+export const BASE_EVENTS = {
+    created: { level: 4 },
+    read: { level: 1 },
+    watched: { level: 1 },
+    deleted: { level: 5 },
+    configured: { level: 1 },
+    // A share fact written or revoked on the object (`crtr canvas share`); attrs {resource, relation, subject}.
+    'relation.written': { level: 1 },
+    'relation.deleted': { level: 1 },
+};
+/** The base events with a kind's own merged over them. */
+export function withBase(own = {}) {
+    return { ...BASE_EVENTS, ...own };
+}

package/dist/core/graph/kinds/live-read.d.ts

@@ -0,0 +1,5 @@
+import type { ReposFn } from '../reader.js';
+import type { ObjectRow, Reader } from '../types.js';
+import type { CanvasDb } from '../../canvas/db.js';
+/** A live read of a non-document object: the reader watches it and its other watchers hear `read`. */
+export declare function recordLiveRead(db: CanvasDb, reader: Reader, object: ObjectRow, reposFn: ReposFn): Promise<void>;

package/dist/core/graph/kinds/live-read.js

@@ -0,0 +1,11 @@
+import { actorOf } from '../documents.js';
+import { publish } from '../events.js';
+import { recordWatch } from '../watches.js';
+/** A live read of a non-document object: the reader watches it and its other watchers hear `read`. */
+export async function recordLiveRead(db, reader, object, reposFn) {
+    const actor = actorOf(reader);
+    if (actor.id === object.id)
+        return; // reading yourself is not an act on anything
+    await recordWatch(db, actor, object, 'read');
+    await publish(db, { event: 'read', object, actor, attrs: {} }, reposFn);
+}

package/dist/core/graph/kinds/node.d.ts

@@ -0,0 +1,12 @@
+import type { Receiver } from '../receivers.js';
+import { type ObjectKind } from './kind.js';
+/**
+ * The node inbox receiver: one `deliveries` row per destination node against the event's message.
+ * The listening delivery maps to a tier and wake (`listenDeliveryTier`); a destination that can
+ * receive only durable events (reception 1: done, dead, canceled) is never woken. A body-carrying
+ * event declared to elevate tiers raises a terminal-lifecycle destination's normal or deferred tier to urgent. Each delivery
+ * settles a controller wait on the sender, and a waking one cancels the destination's
+ * wake-cancellable crons. Runs inside publish's write transaction.
+ */
+export declare const nodeInbox: Receiver;
+export declare const nodeKind: ObjectKind;

package/dist/core/graph/kinds/node.js

@@ -0,0 +1,87 @@
+/** The node kind: an agent on the canvas — its catalog, its render, and the inbox receiver every
+ *  node watcher receives events through. */
+import { settleMatchingControllerWait } from '../../canvas/waits.js';
+import { consumeDeadlineOnWake, effectiveTier, listenDeliveryTier, newId } from '../../feed/messages.js';
+import { readGoal } from '../../runtime/kickoff.js';
+import { permits, resolveReader } from '../../permissions/evaluator.js';
+import { objectDTO } from './dto.js';
+import { withBase } from './kind.js';
+import { recordLiveRead } from './live-read.js';
+import { attr, header, section } from './render.js';
+import { mapAsync } from '../../async-array.js';
+const TIERED = [3, 5, 7];
+function firstLine(text) {
+    return text?.split('\n').map((l) => l.trim()).find((l) => l !== '') ?? '';
+}
+/**
+ * The node inbox receiver: one `deliveries` row per destination node against the event's message.
+ * The listening delivery maps to a tier and wake (`listenDeliveryTier`); a destination that can
+ * receive only durable events (reception 1: done, dead, canceled) is never woken. A body-carrying
+ * event declared to elevate tiers raises a terminal-lifecycle destination's normal or deferred tier to urgent. Each delivery
+ * settles a controller wait on the sender, and a waking one cancels the destination's
+ * wake-cancellable crons. Runs inside publish's write transaction.
+ */
+export const nodeInbox = {
+    bodyOwner: (destinations) => destinations[0]?.id ?? null,
+    async enqueue(db, message, destinations) {
+        const now = Date.now();
+        const sender = message.senderNodeId;
+        // One lookup each for the destinations with an open controller wait on the sender and with a
+        // wake-cancellable cron; only those take the per-node settle and cancel.
+        const ids = destinations.map((d) => d.id);
+        const inIds = `(${ids.map(() => '?').join(',')})`;
+        const waiting = sender === null ? new Set() : new Set((await db.prepareUncached(`SELECT DISTINCT node_id FROM waits WHERE kind = 'controller' AND target_id = ? AND satisfied_at IS NULL AND node_id IN ${inIds}`).all(sender, ...ids)).map((r) => r.node_id));
+        const cronAnchors = new Set((await db.prepareUncached(`SELECT DISTINCT anchor_node FROM crons WHERE cancel_on_wake = 1 AND anchor_node IN ${inIds}`).all(...ids)).map((r) => r.anchor_node));
+        const insert = db.prepare(`INSERT INTO deliveries (delivery_id, message_id, destination_id, urgency, wake, state, created_at, updated_at, idempotency_key)
+       VALUES (?, ?, ?, ?, ?, 'pending', ?, ?, ?)`);
+        for (const destination of destinations) {
+            const tier = listenDeliveryTier(destination.delivery);
+            const wake = destination.reception === 2 ? tier.wake : 0;
+            const urgency = message.elevatesTier ? await effectiveTier(destination.id, tier.urgency) : tier.urgency;
+            await insert.run(newId(), message.messageId, destination.id, urgency, wake, now, now, message.idempotencyKey === undefined ? null : `${message.idempotencyKey}:${destination.id}`);
+            if (waiting.has(destination.id))
+                await settleMatchingControllerWait(destination.id, sender, now, db);
+            if (wake === 1 && urgency !== 'deferred' && cronAnchors.has(destination.id))
+                await consumeDeadlineOnWake(destination.id);
+        }
+    },
+};
+export const nodeKind = {
+    name: 'node',
+    addressable: 'id',
+    receiver: 'inbox',
+    // A stub of a node on another machine receives through the peer outbox; it has no inbox.
+    receiverFor: async (db, object) => await db.prepare('SELECT 1 FROM peer_stubs WHERE object = ?').get(object.id) === undefined ? 'inbox' : 'peer',
+    // A node's own events (and `configured`) are durable: a done watcher still gets them, unwoken.
+    events: withBase({
+        configured: { level: 1, durable: true },
+        messaged: { level: 2, durable: true },
+        sent: { level: 1, durable: true },
+        'report.update': { level: 5, levels: TIERED, durable: true, carriesBody: true, elevatesTier: true },
+        'report.final': { level: 7, durable: true, carriesBody: true, elevatesTier: true, inboxKind: 'final' },
+        outcome: { level: 1, durable: true, supersedes: true, carriesBody: true },
+        'report.result': { level: 5, durable: true, carriesBody: true, elevatesTier: true, inboxKind: 'completed' },
+        'notice.crash': { level: 5, levels: TIERED, durable: true, carriesBody: true, elevatesTier: true },
+        'notice.deadline': { level: 5, levels: TIERED, durable: true, carriesBody: true, elevatesTier: true },
+        'notice.close': { level: 5, levels: TIERED, durable: true, carriesBody: true, elevatesTier: true },
+    }),
+    async read(db, reader, node, opts) {
+        const row = await db.prepare('SELECT status FROM nodes WHERE node_id = ?').get(node.id);
+        const read = await permits(db, await resolveReader(db, reader), 'read', 'o');
+        const visible = async (rows) => await mapAsync(rows, async (o) => await objectDTO(db, o));
+        const children = await db.prepareUncached(`SELECT o.* FROM nodes n JOIN objects o ON o.id = n.node_id
+      WHERE n.parent = ? AND o.deleted_at IS NULL AND ${read.sql} ORDER BY o.seq`).all(node.id, ...read.params);
+        const owned = await db.prepareUncached(`SELECT o.* FROM objects o WHERE o.owner = ? AND o.deleted_at IS NULL AND ${read.sql} ORDER BY o.seq`).all(node.id, ...read.params);
+        await recordLiveRead(db, reader, node, opts.reposFn);
+        const data = {
+            status: row?.status ?? 'deleted', mandate_first_line: firstLine(await readGoal(node.id)), children: await visible(children),
+            owned: await visible(owned.filter((o) => o.type !== 'job')), jobs: await visible(owned.filter((o) => o.type === 'job')),
+        };
+        const text = [
+            header('object', await objectDTO(db, node), attr('status', data.status)),
+            `Mandate: ${data.mandate_first_line}`,
+            ...section('Children', data.children), ...section('Owns', data.owned), ...section('Jobs', data.jobs),
+        ].join('\n');
+        return { data, text };
+    },
+};

package/dist/core/graph/kinds/owner.d.ts

@@ -0,0 +1,2 @@
+import { type ObjectKind } from './kind.js';
+export declare const ownerKinds: ObjectKind[];

package/dist/core/graph/kinds/owner.js

@@ -0,0 +1,26 @@
+/** The owner kinds — person, app, repo, profile: identities that own objects. Base events only. */
+import { objectDTO } from './dto.js';
+import { withBase } from './kind.js';
+import { recordLiveRead } from './live-read.js';
+import { header } from './render.js';
+function ownerKind(name) {
+    return {
+        name,
+        addressable: 'handle',
+        events: withBase(),
+        async read(db, reader, owner, opts) {
+            const id = await db.prepare('SELECT scheme, external_id FROM identities WHERE object = ?').get(owner.id);
+            await recordLiveRead(db, reader, owner, opts.reposFn);
+            const data = {
+                handle: owner.name, display_name: owner.preview || owner.name,
+                identity: { scheme: id?.scheme ?? '', external_id: id?.external_id ?? '' },
+            };
+            const text = [
+                header('object', await objectDTO(db, owner)),
+                `Handle: ${data.handle}`, `Display name: ${data.display_name}`, `Identity: ${data.identity.scheme}:${data.identity.external_id}`,
+            ].join('\n');
+            return { data, text };
+        },
+    };
+}
+export const ownerKinds = [ownerKind('person'), ownerKind('app'), ownerKind('repo'), ownerKind('profile')];

package/dist/core/graph/kinds/registry.d.ts

@@ -0,0 +1,10 @@
+import type { EventSpec, ObjectKind } from './kind.js';
+import type { CanvasDb } from '../../canvas/db.js';
+/** A registration write invalidates the in-process copy before its next lookup. */
+export declare function invalidateCustomKind(db: CanvasDb, name: string): void;
+export declare function kindNames(db: CanvasDb): Promise<string[]>;
+export declare function isKind(db: CanvasDb, name: string): Promise<boolean>;
+/** The kind named `name`, or throws `unknown_kind`. */
+export declare function kindOf(db: CanvasDb, name: string): Promise<ObjectKind>;
+/** The declared spec of `event` on `kind`, or throws `unknown_event` naming the declared events. */
+export declare function eventSpec(db: CanvasDb, kind: string, event: string): Promise<EventSpec>;

package/dist/core/graph/kinds/registry.js

@@ -0,0 +1,58 @@
+import { CrtrError } from '../../errors.js';
+import { ExitCode } from '../../../types.js';
+import { documentKind } from './document.js';
+import { environmentKind } from './environment.js';
+import { jobKind } from './job.js';
+import { nodeKind } from './node.js';
+import { actionKind } from './action.js';
+import { ownerKinds } from './owner.js';
+import { customKind } from './custom.js';
+// Built lazily: the kind modules import graph code that imports this registry back.
+let builtIn = null;
+function kinds() {
+    builtIn ??= new Map([documentKind, nodeKind, actionKind, jobKind, environmentKind, ...ownerKinds].map((k) => [k.name, k]));
+    return builtIn;
+}
+/** The names of every declared kind. */
+const custom = new WeakMap();
+/** A registration write invalidates the in-process copy before its next lookup. */
+export function invalidateCustomKind(db, name) { custom.get(db)?.delete(name); }
+export async function kindNames(db) {
+    return [...kinds().keys(), ...(await db.prepare('SELECT name FROM object_kinds ORDER BY name').all()).map((r) => r.name)];
+}
+export async function isKind(db, name) {
+    return kinds().has(name) || await kindOfCustom(db, name) !== null;
+}
+async function kindOfCustom(db, name) {
+    let cache = custom.get(db);
+    if (!cache) {
+        cache = new Map();
+        custom.set(db, cache);
+    }
+    const cached = cache.get(name);
+    if (cached)
+        return cached;
+    const row = await db.prepare('SELECT events_json FROM object_kinds WHERE name = ?').get(name);
+    if (!row)
+        return null;
+    const kind = customKind(name, JSON.parse(row.events_json));
+    cache.set(name, kind);
+    return kind;
+}
+/** The kind named `name`, or throws `unknown_kind`. */
+export async function kindOf(db, name) {
+    const kind = kinds().get(name) ?? await kindOfCustom(db, name);
+    if (kind === null || kind === undefined) {
+        throw new CrtrError('unknown_kind', `no object kind named ${JSON.stringify(name)}; the kinds are ${(await kindNames(db)).join(', ')}`, ExitCode.USAGE, { kind: name });
+    }
+    return kind;
+}
+/** The declared spec of `event` on `kind`, or throws `unknown_event` naming the declared events. */
+export async function eventSpec(db, kind, event) {
+    const catalog = (await kindOf(db, kind)).events;
+    const spec = Object.hasOwn(catalog, event) ? catalog[event] : undefined;
+    if (spec === undefined) {
+        throw new CrtrError('unknown_event', `${kind} declares no event ${JSON.stringify(event)}; it declares ${Object.keys(catalog).join(', ')}`, ExitCode.USAGE, { kind, event, declared: Object.keys(catalog) });
+    }
+    return spec;
+}

package/dist/core/graph/kinds/render.d.ts

@@ -0,0 +1,9 @@
+/** Text helpers every kind's `read` renders with, and the CLI renders deleted answers with.
+ *  Pure: imports only DTO types, so the CLI can load it without the canvas. */
+import type { ObjectDTO } from '../../../api/dto/objects.js';
+export declare function attr(name: string, value: string | number | null | undefined): string;
+/** One line per object: id, name, type/kind, owner handle and preview. */
+export declare function objectRow(o: ObjectDTO): string;
+/** `<tag type kind id name owner …extra>` */
+export declare function header(tag: string, o: ObjectDTO, extra?: string): string;
+export declare function section(title: string, rows: ObjectDTO[]): string[];

package/dist/core/graph/kinds/render.js

@@ -0,0 +1,17 @@
+export function attr(name, value) {
+    return value === null || value === undefined || value === '' ? '' : ` ${name}="${String(value).replace(/"/g, '"')}"`;
+}
+/** One line per object: id, name, type/kind, owner handle and preview. */
+export function objectRow(o) {
+    const typeKind = o.kind ? `${o.type}/${o.kind}` : o.type;
+    const owner = o.owner ? ` owner=${o.owner.handle}` : '';
+    const deleted = o.deleted_at ? ' (deleted)' : '';
+    return `- ${o.id} [[${o.name}]] ${typeKind}${owner}${deleted} — ${o.preview}`;
+}
+/** `<tag type kind id name owner …extra>` */
+export function header(tag, o, extra = '') {
+    return `<${tag}${attr('type', o.type)}${attr('kind', o.kind)}${attr('id', o.id)}${attr('name', o.name)}${attr('owner', o.owner?.handle)}${extra}>`;
+}
+export function section(title, rows) {
+    return rows.length === 0 ? [] : [`${title}:`, ...rows.map(objectRow)];
+}

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

@@ -0,0 +1,57 @@
+import { type EvalReader } from '../permissions/evaluator.js';
+import { type Frag } from '../permissions/sql.js';
+import type { ObjectRow, Reader } from './types.js';
+import type { CanvasDb } from '../canvas/db.js';
+export type Resolution = {
+    object: ObjectRow;
+} | {
+    deleted: ObjectRow;
+} | {
+    remote: string;
+} | {
+    ambiguous: ObjectRow[];
+} | {
+    missing: true;
+};
+/** The owners a bare name is looked up under, in order: own node, repos nearest
+ *  first, the profile's project repos, profile, app, you, then the apps whose tools the run may use (installed
+ *  plugins) with `crtr` last. */
+export declare function viewOf(db: CanvasDb, reader: Reader): Promise<ObjectRow[]>;
+/** SQL true when the reader may read the candidate `alias`, live or deleted. A live object is `permits(read)`. A deleted object other than a node
+ *  has lost its parent in the evaluator's `relation_source` (a reaped node keeps it, so its live documents stay readable), so a deleted one without a schema type is read through the facts on itself and on each owner up its
+ *  chain (the authority it held before deletion), within the reader's ceiling. The "every app is visible" rule is not such a grant. A deleted
+ *  schema-typed object has had its facts removed, so only the `permits` branch answers it: its own namespace's app. */
+export declare function readableOrDeleted(db: CanvasDb, ev: EvalReader, alias: string): Promise<Frag>;
+/** Whether the reader may read the object `id`, live or deleted. */
+export declare function canReadOrDeleted(db: CanvasDb, ev: EvalReader, id: string): Promise<boolean>;
+/** The owner types that carry a handle; `<type>:<handle>/<name>` names one exactly. */
+export declare const HANDLE_TYPES: readonly ["person", "app", "repo", "profile"];
+/** A ref without its `[[ ]]` wrapper. */
+export declare const unwrapRef: (raw: string) => string;
+/** Every owner a handle names: a node by id, and each handle-carrying owner type
+ *  holding that handle (handles are unique per type, not across types). Any owner
+ *  also answers to its object id, so `<owner object id>/<name>` names a document
+ *  whatever its owner's type. */
+export declare function ownersByHandle(db: CanvasDb, handle: string, type?: string): Promise<ObjectRow[]>;
+/** `name` may be wrapped in `[[ ]]`, a raw object id, a bare document name,
+ *  `<owner handle>/<name>`, or `<type>:<owner handle>/<name>`. Under a handle
+ *  several owner types share, owners in the reader's view come first in view
+ *  order; otherwise exactly one holder wins and more are `ambiguous`. Anything
+ *  the reader cannot read answers `missing`. */
+/** Precomputed for one reader across many resolutions (a corpus names every document). */
+export interface ResolveContext {
+    view: ObjectRow[];
+    ev: EvalReader;
+}
+/** For each of `names`, the id of the live object `resolveName(name, context)` answers, or null when it answers none (a deleted, ambiguous or
+ *  missing name, or a live object under the name's own split, which is named otherwise), computed for all of them in two queries. No entry
+ *  when only `resolveName` itself can tell: a wrapped or old-report name, or a name that is an object id. A corpus resolves every document's
+ *  name to choose its display name; one `resolveName` each walks the whole view, twice for a name it misses, with a permission-checked
+ *  query per owner. */
+export declare function viewResolutions(db: CanvasDb, context: ResolveContext, names: readonly string[]): Promise<Map<string, string | null>>;
+export declare function resolveName(db: CanvasDb, reader: Reader, raw: string, context?: ResolveContext): Promise<Resolution>;
+/** Every readable stub of another machine's object that `raw` (`<owner handle>/<name>`, `<type>:<owner handle>/<name>` or a bare name) names:
+ *  empty when none does, more than one when the name is ambiguous. `resolveName` never answers a stub, so a stub cannot shadow a local
+ *  object; this is the lookup a forwarding handler makes only after `resolveName` found no local object, to learn that the name belongs
+ *  to an object another machine homes. */
+export declare function stubsNamed(db: CanvasDb, reader: Reader, raw: string): Promise<ObjectRow[]>;