@north-light/api 0.3.580 → 0.3.587

package/dist/core/feed/messages.js

@@ -0,0 +1,206 @@
+import { randomBytes, randomUUID } from 'node:crypto';
+import { join } from 'node:path';
+import { cancelCronsOnWake } from '../canvas/crons.js';
+import { withCanvasWrite, openDb } from '../canvas/db.js';
+import { getRow } from '../canvas/canvas.js';
+import { messagesDir } from '../canvas/paths.js';
+import { settleDeadControllerWait, settleMatchingControllerWait } from '../canvas/waits.js';
+import { generateOperationId, operationIdContext, validateOperationId } from '../events/operation-id.js';
+import { clipBody } from '../../shared/inbox-entry-body.js';
+export function newId() {
+    let id;
+    do
+        id = randomBytes(16).toString('hex');
+    while (id === '00000000000000000000000000000000');
+    return id;
+}
+function stringify(value, name) {
+    const json = JSON.stringify(value);
+    if (json === undefined)
+        throw new TypeError(`${name} must be JSON-serializable`);
+    return json;
+}
+/** A terminal-lifecycle destination's normal or deferred mail is raised to urgent. */
+export async function effectiveTier(nodeId, urgency) {
+    if (urgency !== 'normal' && urgency !== 'deferred')
+        return urgency;
+    return (await getRow(nodeId))?.lifecycle === 'terminal' ? 'urgent' : urgency;
+}
+/** The path a spilled body is read at. The full text lives in the message row (`body_json.body_full`); a broker
+ *  writes it to this path in its own filesystem, so the agent reads it the way it always has. */
+function overflowBodyPath(nodeId, createdAt) {
+    return join(messagesDir(nodeId), `${createdAt.replace(/[^0-9]/g, '')}-${randomUUID().slice(0, 6)}.md`);
+}
+function inlineBody(bodyJson) {
+    if (typeof bodyJson !== 'object' || bodyJson === null)
+        return '';
+    const body = bodyJson['body'];
+    return typeof body === 'string' ? body.trim() : '';
+}
+export async function insertMessage(db, input) {
+    const messageId = input.messageId ?? newId();
+    const seq = Number((await db.prepare('UPDATE message_sequence SET seq = seq + 1 WHERE id = 1 RETURNING seq').get()).seq);
+    await db.prepare(`INSERT INTO messages
+       (message_id, seq, operation_id, created_at, sender_node_id, sender_name, kind, label, body_ref, body_json, disposition,
+        event, object_id, level, actor_id, cause_message_id, depth)
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`).run(messageId, seq, input.operationId, input.createdAt, input.senderNodeId, input.senderName, input.kind, input.label, input.bodyRef, input.bodyJson === undefined ? null : stringify(input.bodyJson, 'message body'), input.disposition, input.event?.event ?? null, input.event?.objectId ?? null, input.event?.level ?? null, input.event?.actorId ?? null, input.causeMessageId ?? null, input.depth ?? 0);
+    return messageId;
+}
+async function insertNodeDelivery(db, messageId, destinationId, urgency, wake, now, idempotencyKey) {
+    const deliveryId = newId();
+    await db.prepare(`INSERT INTO deliveries
+       (delivery_id, message_id, destination_id, urgency, wake, state, idempotency_key, created_at, updated_at)
+     VALUES (?, ?, ?, ?, ?, 'pending', ?, ?, ?)`).run(deliveryId, messageId, destinationId, urgency, wake, idempotencyKey ?? null, now, now);
+    return deliveryId;
+}
+/** The message's creation time, operation id and body — an oversized inline body is clipped
+ *  into `destinationNodeId`'s messages dir and referenced; with no destination it stays inline. */
+export function finalizeNodeMail(input, destinationNodeId) {
+    const createdAt = new Date().toISOString();
+    const operationId = input.operationId === undefined
+        ? operationIdContext.current() ?? generateOperationId()
+        : validateOperationId(input.operationId);
+    let bodyRef = input.bodyRef ?? null;
+    let bodyJson = input.bodyJson;
+    if (bodyRef === null && destinationNodeId !== null && input.senderNodeId !== 'human') {
+        const body = inlineBody(bodyJson);
+        const clipped = clipBody(body);
+        if (clipped.clipped) {
+            bodyRef = overflowBodyPath(destinationNodeId, createdAt);
+            bodyJson = { ...bodyJson, body: clipped.text, body_full: body };
+        }
+    }
+    return { createdAt, operationId, bodyRef, bodyJson };
+}
+/** Insert one immutable message and one node-inbox obligation into the caller's write transaction. */
+export async function enqueueNodeMail(destinationNodeId, input) {
+    const prepared = finalizeNodeMail(input, destinationNodeId);
+    return await withCanvasWrite(async (db) => {
+        const target = await db.prepare('SELECT run_id FROM nodes WHERE node_id = ?').get(destinationNodeId);
+        if (target?.run_id && (await db.prepare('SELECT deleting_at FROM nodes WHERE node_id = ?').get(target.run_id))?.deleting_at)
+            throw new Error('run is deleting');
+        if (input.idempotencyKey !== undefined) {
+            const existing = await db.prepare(`SELECT d.delivery_id, d.message_id, d.urgency, m.created_at
+        FROM deliveries d JOIN messages m ON m.message_id = d.message_id WHERE d.idempotency_key = ?`).get(input.idempotencyKey);
+            if (existing !== undefined)
+                return { messageId: existing.message_id, deliveryId: existing.delivery_id, urgency: existing.urgency, createdAt: existing.created_at };
+        }
+        const now = Date.now();
+        const urgency = await effectiveTier(destinationNodeId, input.urgency);
+        const messageId = await insertMessage(db, {
+            messageId: input.messageId,
+            operationId: prepared.operationId,
+            createdAt: prepared.createdAt,
+            senderNodeId: input.senderNodeId ?? null,
+            senderName: input.senderName ?? null,
+            kind: input.kind,
+            label: input.label,
+            bodyRef: prepared.bodyRef,
+            bodyJson: prepared.bodyJson,
+            disposition: input.disposition ?? null,
+        });
+        const deliveryId = await insertNodeDelivery(db, messageId, destinationNodeId, urgency, input.wake, now, input.idempotencyKey);
+        await settleMatchingControllerWait(destinationNodeId, input.senderNodeId ?? null, now, db);
+        await input.withinEnqueue?.(db, messageId);
+        if (input.wake === 1 && urgency !== 'deferred')
+            await consumeDeadlineOnWake(destinationNodeId);
+        return { messageId, deliveryId, urgency, createdAt: prepared.createdAt };
+    });
+}
+/** Contract §1: a listening delivery maps 1:1 onto an inbox tier; only `next-turn` does not wake. */
+export function listenDeliveryTier(delivery) {
+    switch (delivery) {
+        case 'interrupt': return { urgency: 'critical', wake: 1 };
+        case 'steer': return { urgency: 'urgent', wake: 1 };
+        case 'after-turn': return { urgency: 'normal', wake: 1 };
+        case 'next-turn': return { urgency: 'deferred', wake: 0 };
+    }
+}
+/** Insert one runtime notice (no sender) and its delivery; never cancels crons. */
+async function insertNodeNotice(db, nodeId, notice) {
+    const input = { kind: 'update', label: notice.label ?? 'notice', bodyJson: { body: notice.body }, urgency: notice.tier, wake: notice.wake };
+    const prepared = finalizeNodeMail(input, nodeId);
+    const now = Date.now();
+    const messageId = await insertMessage(db, {
+        operationId: prepared.operationId,
+        createdAt: prepared.createdAt,
+        senderNodeId: null,
+        senderName: null,
+        kind: input.kind,
+        label: input.label,
+        bodyRef: prepared.bodyRef,
+        bodyJson: prepared.bodyJson,
+        disposition: null,
+    });
+    const deliveryId = await insertNodeDelivery(db, messageId, nodeId, notice.tier, notice.wake, now);
+    return { messageId, deliveryId, urgency: notice.tier, createdAt: prepared.createdAt };
+}
+/** A wake reached `nodeId`: delete its cancel-on-wake deadline and, in the same write, queue a
+ *  notice naming each deleted deadline so the node knows its timer is gone. The notice is inserted
+ *  directly rather than through `queueNodeNotice`, so it cancels nothing and a deadline the node
+ *  arms afterwards survives it. A deadline that fires on its own deletes its row first, so finds
+ *  nothing here and no notice is queued. */
+export async function consumeDeadlineOnWake(nodeId) {
+    await withCanvasWrite(async (db) => {
+        for (const cron of await cancelCronsOnWake(nodeId)) {
+            await insertNodeNotice(db, nodeId, {
+                body: `Your cron ${cron.name}, next scheduled for ${cron.fire_at}, was canceled by this wake. Re-create it if you still need it.`,
+                label: 'cron canceled',
+                tier: 'normal',
+                wake: 1,
+            });
+        }
+    });
+}
+/** Queue one runtime notice to a node's inbox inside the caller's write transaction (no sender). */
+export async function queueNodeNotice(db, nodeId, notice) {
+    const queued = await insertNodeNotice(db, nodeId, notice);
+    if (notice.wake === 1 && notice.tier !== 'deferred')
+        await consumeDeadlineOnWake(nodeId);
+    return queued;
+}
+/** Retract an obligation without fabricating a terminal receipt. */
+export async function cancelDelivery(deliveryId, now = Date.now()) {
+    return Number((await (await openDb()).prepare('UPDATE deliveries SET canceled_at = ?, updated_at = ? WHERE delivery_id = ? AND canceled_at IS NULL').run(now, now, deliveryId)).changes) === 1;
+}
+export async function cancelPendingNodeMail(nodeId, select = {}) {
+    return await withCanvasWrite(async (db) => {
+        const clauses = ['d.destination_id = ?', 'd.canceled_at IS NULL', "d.state IN ('pending', 'handed_off')"];
+        const params = [nodeId];
+        if (select.senderNodeId !== undefined) {
+            clauses.push('m.sender_node_id IS NOT DISTINCT FROM ?');
+            params.push(select.senderNodeId);
+        }
+        if (select.kind !== undefined) {
+            clauses.push('m.kind = ?');
+            params.push(select.kind);
+        }
+        const rows = await db.prepareUncached(`SELECT d.delivery_id FROM deliveries d JOIN messages m ON m.message_id = d.message_id WHERE ${clauses.join(' AND ')}`).all(...params);
+        if (rows.length === 0)
+            return [];
+        const now = Date.now();
+        await db.prepareUncached(`UPDATE deliveries SET canceled_at = ?, updated_at = ? WHERE delivery_id IN (${rows.map(() => '?').join(',')})`)
+            .run(now, now, ...rows.map((row) => row.delivery_id));
+        return rows.map((row) => row.delivery_id);
+    });
+}
+/** Enqueue the one notice only if the same live controller wait is still dead. */
+export async function enqueueControllerDeathNotice(nodeId, controllerId) {
+    return await withCanvasWrite(async (db) => {
+        const now = Date.now();
+        const row = await db.prepare(`SELECT target.status AS controller_status FROM waits w LEFT JOIN nodes target ON target.node_id = w.target_id
+        WHERE w.node_id = ? AND w.kind = 'controller' AND w.target_id = ? AND w.satisfied_at IS NULL`).get(nodeId, controllerId);
+        if (row === undefined || row.controller_status === 'active' || row.controller_status === 'idle')
+            return null;
+        const result = await enqueueNodeMail(nodeId, {
+            kind: 'urgent',
+            label: 'declared controller is no longer live',
+            bodyJson: { body: `Controller ${controllerId} is no longer live; the declared message wait was cleared.` },
+            urgency: 'urgent',
+            wake: 1,
+        });
+        if (!await settleDeadControllerWait(nodeId, controllerId, now, db))
+            throw new Error(`controller wait changed while notifying ${nodeId}`);
+        return result;
+    });
+}

package/dist/core/feed/reports.d.ts

@@ -0,0 +1,10 @@
+/** Whether `nodeId` owns any live report document — proof it already did work. */
+export declare function hasReportDocuments(nodeId: string): Promise<boolean>;
+/** `<nodeId>/<name>` of `nodeId`'s newest live report document — the name
+ *  `crtr canvas read` takes — or null when it pushed none. */
+export declare function newestReportName(nodeId: string): Promise<string | null>;
+/** Body of `nodeId`'s newest live report document, trimmed; '' when it pushed none. */
+export declare function newestReportBody(nodeId: string): Promise<string>;
+/** Body of the report document a push's `<nodeId>/reports/<name>` ref names;
+ *  null when the ref is not that shape or the document is gone. */
+export declare function reportBodyByName(ref: string): Promise<string | null>;

package/dist/core/feed/reports.js

@@ -0,0 +1,58 @@
+// Report documents a node pushed, read by in-daemon callers that must not
+// import the daemon's report handler (core never imports daemon/api).
+import { openDb } from '../canvas/db.js';
+import { findMany as findBodies } from '../graph/bodies.js';
+import { heads } from '../graph/documents.js';
+import { getById } from '../graph/objects.js';
+/** Whether `nodeId` owns any live report document — proof it already did work. */
+export async function hasReportDocuments(nodeId) {
+    const db = await openDb();
+    const node = await getById(db, nodeId);
+    if (node === null || node.type !== 'node')
+        return false;
+    return await db.prepare(`SELECT 1 FROM objects WHERE owner = ? AND type = 'document' AND kind = 'report' AND deleted_at IS NULL LIMIT 1`)
+        .get(node.id) !== undefined;
+}
+async function newestReport(nodeId) {
+    const db = await openDb();
+    const node = await getById(db, nodeId);
+    if (node === null || node.type !== 'node')
+        return undefined;
+    return await db.prepare(`SELECT * FROM objects WHERE owner = ? AND type = 'document' AND kind = 'report' AND deleted_at IS NULL
+    ORDER BY created_at DESC, name DESC LIMIT 1`).get(node.id);
+}
+/** `<nodeId>/<name>` of `nodeId`'s newest live report document — the name
+ *  `crtr canvas read` takes — or null when it pushed none. */
+export async function newestReportName(nodeId) {
+    const doc = await newestReport(nodeId);
+    return doc === undefined ? null : `${nodeId}/${doc.name}`;
+}
+/** Body of `nodeId`'s newest live report document, trimmed; '' when it pushed none. */
+export async function newestReportBody(nodeId) {
+    const db = await openDb();
+    const doc = await newestReport(nodeId);
+    if (doc === undefined)
+        return '';
+    const head = (await heads(db, doc))[0];
+    if (head === undefined)
+        return '';
+    // A revision whose text is not stored (written before the text moved into the database) reads as empty; a database error still propagates.
+    return ((await findBodies(db, [head.body_hash])).get(head.body_hash) ?? '').trim();
+}
+/** Body of the report document a push's `<nodeId>/reports/<name>` ref names;
+ *  null when the ref is not that shape or the document is gone. */
+export async function reportBodyByName(ref) {
+    const slash = ref.indexOf('/');
+    if (slash <= 0 || !ref.startsWith('reports/', slash + 1))
+        return null;
+    const db = await openDb();
+    const node = await getById(db, ref.slice(0, slash));
+    if (node === null || node.type !== 'node')
+        return null;
+    const doc = await db.prepare(`SELECT * FROM objects WHERE owner = ? AND type = 'document' AND name = ? AND deleted_at IS NULL`)
+        .get(node.id, ref.slice(slash + 1));
+    const head = doc === undefined ? undefined : (await heads(db, doc))[0];
+    if (head === undefined)
+        return null;
+    return (await findBodies(db, [head.body_hash])).get(head.body_hash) ?? null;
+}

package/dist/core/frontmatter.d.ts

@@ -0,0 +1,8 @@
+export interface ParsedFrontmatterGeneric {
+    /** Raw, uncoerced key/value record from the YAML block (null when absent). */
+    data: Record<string, unknown> | null;
+    body: string;
+    raw: string;
+}
+/** Parse a frontmatter block as a raw key/value record. */
+export declare function parseFrontmatterGeneric(source: string): ParsedFrontmatterGeneric;

package/dist/core/frontmatter.js

@@ -0,0 +1,35 @@
+import { parse as parseYaml } from 'yaml';
+const FRONTMATTER_RE = /^---\s*\r?\n([\s\S]*?)\r?\n---\s*\r?\n?/;
+/** Parse a frontmatter block as a raw key/value record. */
+export function parseFrontmatterGeneric(source) {
+    const match = source.match(FRONTMATTER_RE);
+    if (!match) {
+        return { data: null, body: source, raw: '' };
+    }
+    const raw = match[1];
+    const body = source.slice(match[0].length);
+    return { data: parseYamlBlock(raw), body, raw };
+}
+/** Parse the inner YAML of a frontmatter block into a key/value record.
+ *
+ *  ONE strict parser, no fallback. The frontmatter contract IS "valid YAML":
+ *  the single `yaml`-package path handles the substrate's nested `gate:` maps,
+ *  inline `{…}` objects, and native scalar typing — and a doc whose frontmatter
+ *  is NOT valid YAML THROWS, by design. There is deliberately no second lenient
+ *  parser; a dual parsing strategy is the hedge we reject. Callers that iterate
+ *  MANY docs isolate a per-doc throw at the COLLECTION layer (a clear scoped
+ *  notice naming the bad file, then continue); single-doc callers let the error
+ *  surface so the user learns their one requested doc is malformed.
+ *
+ *  A VALID non-object document (a bare scalar, a top-level list, or an empty
+ *  block) normalizes to an empty record, preserving the contract that callers
+ *  always receive a Record for well-formed-but-non-mapping frontmatter. */
+function parseYamlBlock(raw) {
+    return normalizeToRecord(parseYaml(raw));
+}
+function normalizeToRecord(parsed) {
+    if (parsed !== null && typeof parsed === 'object' && !Array.isArray(parsed)) {
+        return parsed;
+    }
+    return {};
+}

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

@@ -0,0 +1,14 @@
+import { type ActiveGrant } from './mirror.js';
+/** Pulls the directory's grants into the mirror; `fresh` demands a pull that starts after the call. */
+export type GrantSync = (options?: {
+    fresh?: boolean;
+}) => Promise<void>;
+/** Make the mirror cover grant `grantId` at `rev`, pulling once when it is behind. Throws `RunError` 503
+ *  `service_unavailable` (failed pull, or a pull that stayed behind) or 401 `grant_revoked` (absent after a pull). */
+export declare function ensureCovers(grantId: string, rev: number, syncGrants: GrantSync): Promise<void>;
+/** The mirrored grant a caller names, read now, when it is still the caller's: active, the same `sub` and
+ *  `grantee`, and not past `expires_at`. Otherwise 401 `grant_revoked`. */
+export declare function callerGrantOf(grantId: string, sub: string, grantee: string): Promise<ActiveGrant>;
+/** The grant a token's app link names: the mirror made to cover `rev`, then the grant itself checked against
+ *  `sub` and `grantee`. Errors are `ensureCovers`' and `callerGrantOf`'s `RunError`s. */
+export declare function coverGrant(grantId: string, rev: number, sub: string, grantee: string, syncGrants: GrantSync): Promise<ActiveGrant>;

package/dist/core/grants/cover.js

@@ -0,0 +1,66 @@
+// The grant-revision cover rule (contract 1 "Grant sync"), shared by every path that turns a token's
+// `grant`/`rev` into the mirrored grant it names. This is a copy of `AppPrincipalResolver.ensureCovers`
+// plus `callerGrant`; the app listener's resolver switches onto it in the next unit and drops its own.
+//
+// The ordering rule: the mirror covers a token stamped `rev = N` when it holds the grant at `rev >= N`, and
+// the decision is then the mirror's alone. Otherwise one fresh pull — one that starts after this call — is
+// awaited first. A failed pull answers 503; a successful pull that still does not cover the token is a
+// directory fault: an absent grant is refused `grant_revoked`, a grant below the token's rev answers 503,
+// and repeats of either answer without pulling. No clock or timer enters the decision.
+import { emitEvent } from '../events/emit.js';
+import { RunError } from '../runs/operations.js';
+import { activeGrant, grantExpired, grantSyncState, grantsGeneration } from './mirror.js';
+/** grant id → the highest token `rev` a successful fresh pull failed to cover, valid only for the mirror
+ *  generation it was recorded under: any later `replaceGrants` clears it. */
+let behind = new Map();
+let behindGeneration = -1;
+async function behindRev(grant) {
+    const generation = await grantsGeneration();
+    if (generation !== behindGeneration) {
+        behind = new Map();
+        behindGeneration = generation;
+    }
+    return behind.get(grant);
+}
+const covered = (state, rev) => state !== null && state.rev >= rev;
+/** Make the mirror cover grant `grantId` at `rev`, pulling once when it is behind. Throws `RunError` 503
+ *  `service_unavailable` (failed pull, or a pull that stayed behind) or 401 `grant_revoked` (absent after a pull). */
+export async function ensureCovers(grantId, rev, syncGrants) {
+    if (covered(await grantSyncState(grantId), rev))
+        return;
+    const known = await behindRev(grantId);
+    if (known === undefined || rev > known) {
+        try {
+            await syncGrants({ fresh: true });
+        }
+        catch {
+            throw new RunError(503, 'service_unavailable', 'grant sync failed');
+        }
+        const state = await grantSyncState(grantId);
+        if (covered(state, rev))
+            return;
+        // Read the generation this pull committed before recording against it.
+        await behindRev(grantId);
+        behind.set(grantId, Math.max(rev, behind.get(grantId) ?? 0));
+        emitEvent({ level: 'error', event: 'daemon.grants.behind_token', fields: { grant: grantId, token_rev: rev, mirror_rev: state?.rev ?? 0 } });
+    }
+    if (!await grantSyncState(grantId))
+        throw new RunError(401, 'grant_revoked', 'grant is not active');
+    throw new RunError(503, 'service_unavailable', 'the directory answered grant sync below the access token\'s grant revision');
+}
+/** The mirrored grant a caller names, read now, when it is still the caller's: active, the same `sub` and
+ *  `grantee`, and not past `expires_at`. Otherwise 401 `grant_revoked`. */
+export async function callerGrantOf(grantId, sub, grantee) {
+    const grant = await activeGrant(grantId);
+    if (!grant || grant.sub !== sub || grant.grantee !== grantee ||
+        grantExpired(grant)) {
+        throw new RunError(401, 'grant_revoked', 'grant is not active');
+    }
+    return grant;
+}
+/** The grant a token's app link names: the mirror made to cover `rev`, then the grant itself checked against
+ *  `sub` and `grantee`. Errors are `ensureCovers`' and `callerGrantOf`'s `RunError`s. */
+export async function coverGrant(grantId, rev, sub, grantee, syncGrants) {
+    await ensureCovers(grantId, rev, syncGrants);
+    return await callerGrantOf(grantId, sub, grantee);
+}

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

@@ -0,0 +1,4 @@
+/** A runtime without an issuer has exactly one grant, owned by its terminal app: id `terminal:<install id>`, subject the install's person.
+ *  Joins the caller's `withCanvasWrite` transaction when one is open. A mirror that already holds exactly that grant is left alone,
+ *  so a restart changes no grant rows and does not start a new grant generation. */
+export declare function installLocalTerminalGrant(installId: string, person: string): Promise<void>;

package/dist/core/grants/local.js

@@ -0,0 +1,26 @@
+import { withCanvasWrite } from '../canvas/db.js';
+import { replaceGrants } from './mirror.js';
+const TERMINAL_SCOPES = [
+    'crtr:llm', 'crtr:act', 'crtr:schedule', 'crtr:memory:rw:user',
+    'crtr:memory:manage:user', 'crtr:files:rw:user:.',
+].map((scope) => ({ scope, mode: 'always' }));
+/** A runtime without an issuer has exactly one grant, owned by its terminal app: id `terminal:<install id>`, subject the install's person.
+ *  Joins the caller's `withCanvasWrite` transaction when one is open. A mirror that already holds exactly that grant is left alone,
+ *  so a restart changes no grant rows and does not start a new grant generation. */
+export async function installLocalTerminalGrant(installId, person) {
+    const id = `terminal:${installId}`;
+    const scopes = JSON.stringify(TERMINAL_SCOPES);
+    const current = await withCanvasWrite(async (db) => {
+        const source = await db.prepare("SELECT value FROM runtime_state WHERE key = 'grants_source'").get();
+        const rows = await db.prepare('SELECT id, runtime, sub, grantee, status, scopes_json, resolved_scopes_json FROM grants').all();
+        return source?.value === 'local' && rows.length === 1 && rows[0].id === id && rows[0].runtime === installId && rows[0].sub === person
+            && rows[0].grantee === 'app:terminal' && rows[0].status === 'active' && rows[0].scopes_json === scopes && rows[0].resolved_scopes_json === scopes;
+    });
+    if (current)
+        return;
+    const now = new Date().toISOString();
+    await replaceGrants([{ id, runtime: installId, sub: person,
+            grantee: 'app:terminal', rev: 1, scopes: TERMINAL_SCOPES,
+            resolved_scopes: TERMINAL_SCOPES, spend_cap: null, expires_at: null,
+            status: 'active', revoked_at: null, approved_at: now, payer: 'user', dependencies: {}, synced_at: now }], now, 'local');
+}

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

@@ -0,0 +1,155 @@
+import { type Scope } from '@north-light/identity';
+import { type CanvasDb } from '../canvas/db.js';
+import type { ProviderDependency } from '../../api/dto/grants.js';
+import type { ModelStrength } from '../../types.js';
+export interface GrantScope {
+    scope: string;
+    mode: 'always' | 'ask';
+}
+export type GrantDependencies = Record<string, ProviderDependency>;
+/** An app-paid grant's inference endpoint: where its model calls go and the catalog model each strength (rung) names. */
+export interface InferenceEndpoint {
+    base_url: string;
+    rungs: Partial<Record<ModelStrength, string>>;
+}
+export interface GrantRecord {
+    id: string;
+    runtime: string;
+    sub: string;
+    grantee: string;
+    rev: number;
+    scopes: GrantScope[];
+    resolved_scopes: GrantScope[];
+    spend_cap: number | null;
+    expires_at: string | null;
+    status: 'active' | 'revoked' | 'removed';
+    revoked_at: string | null;
+    approved_at: string | null;
+    payer: 'user' | 'app' | null;
+    /** The directory's setup entry (`{ state, message?, next, step? }`) per setup id the grantee requires. Absent (an older directory) reads as `{}`. */
+    dependencies?: GrantDependencies;
+    /** The grantee's registered run-notice endpoint (https), or null: runs of this grant send no notice. */
+    run_notice_url?: string | null;
+    /** The endpoint of an app-paid grant (`payer: 'app'`); null on a user-paid grant or one the directory sent no valid endpoint for. */
+    inference_endpoint?: InferenceEndpoint | null;
+    synced_at: string;
+}
+export interface ActiveGrant extends GrantRecord {
+    resolved: Scope[];
+}
+/** The `dependencies` a grant sync answer carried. Advisory data, so a missing or
+ *  malformed value never fails the sync (which also carries every grant's
+ *  authorization): absent or non-object reads as `{}`, and a malformed entry
+ *  (see `dependencyOf`) is dropped. A directory older than the Context stage sends none. */
+export declare function dependenciesOf(value: unknown): GrantDependencies;
+/** The `inference_endpoint` a grant sync answer carried: `{ base_url, rungs }` with a non-empty string `base_url` and at
+ *  least one known strength naming a catalog model id. Anything else reads as null — an app-paid grant without a usable
+ *  endpoint is refused `model_unavailable` at its first call, never served from the owner's routes. */
+export declare function inferenceEndpointOf(value: unknown): InferenceEndpoint | null;
+/** A grant this machine only mirrors. An unsandboxed machine runs only
+ *  `app:terminal`; the directory also fans the account's hosted-runtime app
+ *  grants out to it, read-only, so a forwarded app caller can be authorized
+ *  (`grantFor`, `activeGrant`). They drive nothing here: no sandbox stop, removal
+ *  cascade, provider install, or run notice. */
+export declare function mirrorOnly(grant: Pick<GrantRecord, 'grantee'>): boolean;
+/** Every mirrored grant this machine acts on: `allGrants()` without the mirror-only ones. */
+export declare function localGrants(): Promise<GrantRecord[]>;
+/** Every provider id a scope of an active grant's resolved set names: a
+ *  `<id>:<group>` string whose id is not `crtr` (the runtime's own namespace). */
+export declare function providerIdsFromGrants(grants: readonly GrantRecord[]): string[];
+/** The provider ids an active grant of `person` names: the directory's provider bundles that person has, and so the only
+ *  rows of their plugin list that a provider call installs on its own (`ensureProviderBundle`) rather than from a source. */
+export declare function grantedProviderIds(person: string): Promise<Set<string>>;
+/** Whether a `scope_plugins` row is a directory provider bundle rather than a plugin that has no source this process can read:
+ *  it carries neither a marketplace nor a path (what `ensureProviderBundle` writes) AND its name is a provider an active grant of the
+ *  person names. A source-less row for any other name (a git, local or HTTP-bundle install) is not one. */
+export declare function isProviderBundleRow(row: {
+    name: string;
+    source_marketplace: string | null;
+    source_path: string | null;
+}, granted: ReadonlySet<string>): boolean;
+/** `person`'s (`user:<id>`) active, unexpired grants on this runtime, every grantee: what a cloud role reads for one request's person, where `localGrants()`
+ *  would hand back every person the fleet serves. */
+export declare function activeGrantsOfPerson(person: string): Promise<ActiveGrant[]>;
+/** Every mirrored grant, whatever its status. */
+export declare function allGrants(): Promise<GrantRecord[]>;
+/** Whether a grant's `expires_at` has passed. An unparsable time reads as expired (fail closed). */
+export declare function grantExpired(grant: Pick<GrantRecord, 'expires_at'>): boolean;
+/** The active form of a grant record read earlier, or null when it is not active, is past `expires_at`, or is unparsable. */
+export declare function activeRecord(grant: GrantRecord): ActiveGrant | null;
+/** `grant.get`'s `version`: an opaque string that changes exactly when what an app
+ *  reads from its grant changes — `rev`, `resolved_scopes` (order kept), `spend_cap`,
+ *  `payer`, `inference_endpoint`, `dependencies`. `synced_at` and the token's claims are left out, so a
+ *  periodic sync with the same content (or a daemon restart) keeps it. */
+export declare function grantVersion(grant: Pick<GrantRecord, 'rev' | 'resolved_scopes' | 'spend_cap' | 'payer' | 'dependencies' | 'inference_endpoint'>): string;
+export declare function hasGrant(grantId: string): Promise<boolean>;
+/** The grant state the freshness ordering reads (contract 1 "Grant sync"):
+ *  the mirrored grant's revision and status, whatever its status. */
+export interface GrantSyncState {
+    rev: number;
+    status: GrantRecord['status'];
+}
+/** The mirrored state of grant `grantId`, or null when the mirror lacks it. */
+export declare function grantSyncState(grantId: string): Promise<GrantSyncState | null>;
+/** The mirrored state of the grant `sub` gave `grantee`, whatever its status, or null when the mirror lacks it. */
+export declare function grantSyncStateFor(grantee: string, sub: string): Promise<GrantSyncState | null>;
+/** The mirrored grant `grantId`, whatever its status, or null when the mirror lacks it or the row is unparsable. */
+export declare function grantRecord(grantId: string): Promise<GrantRecord | null>;
+/** How a grant stands for the effects of a change (`grant-effects`): `inactive` is a missing, revoked, removed or expired grant;
+ *  `lagging` is an active grant whose computed columns do not yet match its revision (it reads as no grant for requests but
+ *  stops nothing, because the directory's second write completes it). `sub`, `grantee` and `removal_done_at` come from the row
+ *  even when its computed columns lag; all are null when the row is gone. */
+export interface GrantStanding {
+    standing: 'active' | 'inactive' | 'lagging';
+    sub: string | null;
+    grantee: string | null;
+    status: GrantRecord['status'] | null;
+    removal_done_at: string | null;
+    record: GrantRecord | null;
+}
+export declare function grantStanding(grantId: string): Promise<GrantStanding>;
+/** Ids of the grants in `status` (this runtime's), for a catch-up pass. */
+export declare function grantIdsWhere(where: string): Promise<string[]>;
+/** Who a grant's model calls are charged to: `app` only for a mirrored grant the directory marked app-paid, else the person. */
+export declare function payerOfGrant(grantId: string | null | undefined): Promise<'user' | 'app'>;
+export declare function activeGrant(grantId: string): Promise<ActiveGrant | null>;
+export declare function grantFor(grantee: string, sub: string): Promise<ActiveGrant | null>;
+/** The app's own active grant on this machine. Null for a mirror-only grant: an
+ *  unsandboxed machine runs no app, so a fanned-out hosted grant is never "the
+ *  app's grant" for a local app caller, sandbox or install. */
+export declare function activeGrantForApp(grantee: string): Promise<ActiveGrant | null>;
+/** Where a run's notice goes: its grant's registered `run_notice_url`, with the grant's `sub` and `grantee`. Null when the run has no active grant or the grantee registered no URL. */
+export declare function runNoticeTarget(grantId: string): Promise<{
+    url: string;
+    sub: string;
+    grantee: string;
+} | null>;
+/** `person`'s (`user:<id>`) active `app:terminal` grant on this runtime, or null. A runtime serves many people on the fleet, so the person is always
+ *  named: it is the request's person, or the `sub` of the node the call is about. Throws only when that one person holds two. */
+export declare function terminalGrant(person: string): Promise<ActiveGrant | null>;
+/** Where the grant mirror came from: `'local'` for an unjoined runtime's own grant, the directory issuer once joined, null before any install. */
+export declare function grantsSource(): Promise<string | null>;
+export declare function hasSyncedGrants(source: string): Promise<boolean>;
+/** OWN-11 for a joined runtime: the unjoined runtime's local mirror grants
+ *  the install's person full local scopes and is not the directory's. Delete it so no
+ *  grant exists until grant sync installs the directory's mirror. */
+export declare function dropLocalGrantMirror(db: CanvasDb): Promise<number>;
+/** Mark rows a build older than C-D2 wrote as computed for their revision. That build computed every column locally in the same
+ *  write but never set `computed_rev`, so its rows are complete; left NULL they read as no grant until the next successful
+ *  sync rewrites them, and the terminal grant then refuses every launch (NL-550). A directory-written row with lagging
+ *  columns has NULL scopes, so it is never matched. Returns the rows changed. */
+export declare function backfillComputedRev(): Promise<number>;
+/** The directory response is complete; commit it or keep the prior snapshot intact. */
+/** A directory team the runtime's owner belongs to: `team` is `team:<id>`, `members` are `user:<id>`. */
+export interface TeamRecord {
+    team: string;
+    members: string[];
+}
+/** The `teams` a grant sync answer carried; absent (an unjoined install, an older directory) reads as none. */
+export declare function teamsOf(value: unknown): TeamRecord[];
+/** Replace the mirror with `grants` and the `written_by = 'directory'` team `member` facts with `teams`, in one transaction. The
+ *  ledger's `grant:<id>` limit rows follow from the `grants` trigger `crtr_grant_limit` (schema delta 002). */
+export declare function replaceGrants(grants: readonly GrantRecord[], syncedAt: string, source: string, teams?: readonly TeamRecord[]): Promise<void>;
+/** Bumped by every `replaceGrants`. A launch compiled against one generation
+ *  and started under another may hold mounts the new mirror no longer grants. */
+export declare function grantsGeneration(): Promise<number>;