@north-light/api 0.3.579 → 0.3.587

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

@@ -0,0 +1,90 @@
+import { type ObjectRow, type Privacy } from '../graph/types.js';
+import { type CustomEvents } from '../graph/custom.js';
+import type { ObjectDTO } from '../../api/dto/objects.js';
+import type { Envelope } from './envelope.js';
+import type { CanvasDb } from '../canvas/db.js';
+/** The part of an envelope a stub stores: who the remote watcher is, never what it may do. */
+export interface StubIdentity {
+    sub: string;
+    /** `null` for a person. */
+    app: string | null;
+    node: string | null;
+    node_scopes: string[] | null;
+    place: {
+        run: string;
+        isolated: boolean;
+    } | null;
+}
+/** An owner as the sending machine names it, so the receiver can map it onto its own owner object. */
+export interface OwnerRef {
+    id: string;
+    type: 'person' | 'app' | 'repo' | 'profile';
+    scheme: string | null;
+    external_id: string | null;
+    handle: string;
+}
+/** A custom kind as the home machine declares it: carried so the receiver can hold a stub of an instance. It grants nothing (no `read` leaf). */
+export interface KindDeclaration {
+    name: string;
+    description: string;
+    events: CustomEvents;
+    owner: OwnerRef;
+}
+/** An object as it crosses the wire: identity only, never content. */
+export interface ObjectRef {
+    id: string;
+    type: string;
+    kind: string | null;
+    name: string;
+    preview?: string;
+    owner: OwnerRef | null;
+    /** The declaration of a custom `type`; absent for a built-in. */
+    kind_decl?: KindDeclaration;
+    /** The home object's privacy; a stub is never more readable than it. Absent: `public`. */
+    privacy?: Privacy;
+}
+export interface StubRecord {
+    object: ObjectRow;
+    home_machine: string;
+    /** Absent on a stub that only stands for a watched object. */
+    identity: StubIdentity | null;
+}
+export declare const identityOfEnvelope: (envelope: Envelope) => StubIdentity;
+export declare function stubOf(db: CanvasDb, object: ObjectRow | string): Promise<StubRecord | null>;
+export declare const isStub: (db: CanvasDb, object: ObjectRow) => Promise<boolean>;
+/** The local object for an app or person the other machine names as an event's actor, or null for any other type. An app or person is an
+ *  owner, not a thing that lives on one machine: it is the same object here as there, so it is never given a stub (a stub would collide
+ *  with the local owner object of the same handle, as with an installed plugin's app). */
+export declare function localOwnerActor(db: CanvasDb, ref: ObjectRef): Promise<ObjectRow | null>;
+/** Lock every key in `keys` in one global order (family rank, then lock hash), so no two transactions that lock overlapping sets can wait on
+ *  each other. Locks are held to the end of the transaction, and taking one again is free. */
+export declare function lockInOrder(db: CanvasDb, keys: readonly string[]): Promise<void>;
+/** Every advisory lock `ensureStub` takes for this object: the stub, the custom kind its reference declares, and each owner it may create.
+ *  A caller that touches several stubs locks the union with `lockInOrder` first, so the order never depends on which stub comes first. */
+export declare function stubLockKeys(db: CanvasDb, id: string, type: string, identity: StubIdentity | null, ref: ObjectRef | undefined): Promise<string[]>;
+/** The advisory locks `actorFor` takes for an event's actor. */
+export declare function actorLockKeys(db: CanvasDb, ref: ObjectRef): Promise<string[]>;
+/**
+ * The stub of the object `id` that lives on `machine`, created on first sight. Idempotent: a second
+ * call returns the same row and, given an `envelope`, replaces the identity it stores. Refuses
+ * (`conflict`) an id that is a real local object or a stub of another machine. The owner is the
+ * local app (or person) object of the remote owner, so the stub sits in a space the access rules
+ * understand. No `nodes` row is written.
+ */
+export declare function ensureStub(db: CanvasDb, id: string, type: string, machine: string, envelope?: Envelope, ref?: ObjectRef): Promise<ObjectRow>;
+/**
+ * The stub of the node `nodeId` that lives on `machine`, as a watcher: created on first sight with no envelope
+ * identity, owned by the local person, and marked `reception = 2` so `publish` considers it and the node
+ * kind's receiver sends its events through the `peer` outbox. A later forwarded call by that node fills in the
+ * identity on the same row (`ensureStub` with an envelope). Refuses (`conflict`) an id that is a real local
+ * object or a stub of another machine. Writes no `nodes` row.
+ */
+export declare function ensureNodeStub(db: CanvasDb, nodeId: string, machine: string): Promise<ObjectRow>;
+/** The object moved: the machine that answered for it is now its home. A no-op for a local object or a stub already homed there. */
+export declare function rehomeStub(db: CanvasDb, id: string, machine: string): Promise<void>;
+/** How `o` is described to another machine. */
+export declare function describeObject(db: CanvasDb, o: ObjectRow): Promise<ObjectRef>;
+/** The declaration of the custom kind `type`, or null for a built-in (no `object_kinds` row). Carries no `read` leaf. */
+export declare function kindDeclarationOf(db: CanvasDb, type: string): Promise<KindDeclaration | null>;
+/** `dto` with the declaration of its object's kind, when the kind is custom. */
+export declare function withKindDecl(db: CanvasDb, row: ObjectRow, dto: ObjectDTO): Promise<ObjectDTO>;

package/dist/core/peer/stubs.js

@@ -0,0 +1,208 @@
+// Stubs (first crossing C4): a remote object's local representative.
+//
+// A stub is an `objects` row of the remote object's type with `home_machine` set, a `peer_stubs`
+// row, and no `nodes` row, body or directory. It exists so the local graph can hold an edge to
+// something that lives on another machine: a watch from a local node to a remote node (the stub is
+// the watched object), and a watch from a remote node's stub to a local object (the stub is the
+// watcher). A stub never launches a broker and is never listed or counted as a node.
+//
+// A stub that watches carries the envelope identity it acts under (app, node, node_scopes, place).
+// That identity names who the remote watcher is; it is never authority. What the stub may read is
+// recomputed from the current mirrored grant every time an event is published (`readerForObject`).
+import { createObject, getById, ownerForGrantee, ownerLockKey } from '../graph/objects.js';
+import { readLegacyPrivacy } from '../graph/types.js';
+import { upsertKind } from '../graph/custom.js';
+import { CrtrError } from '../errors.js';
+import { ExitCode } from '../../types.js';
+import { normalizeMachineId } from './names.js';
+import { personId, personIdAsync } from '../canvas/person.js';
+import { writeActsFor } from '../permissions/facts.js';
+const PRIVACY = ['public', 'private'];
+export const identityOfEnvelope = (envelope) => {
+    const inner = envelope.act.act;
+    return inner === undefined
+        ? { sub: envelope.sub, app: null, node: null, node_scopes: null, place: null }
+        : { sub: envelope.sub, app: inner.sub, node: inner.node, node_scopes: inner.node_scopes, place: inner.place };
+};
+export async function stubOf(db, object) {
+    const row = typeof object === 'string' ? await getById(db, object) : object;
+    if (row === null)
+        return null;
+    const stub = await db.prepare('SELECT home_machine, envelope_json FROM peer_stubs WHERE object = ?').get(row.id);
+    if (!stub)
+        return null;
+    return { object: row, home_machine: stub.home_machine, identity: stub.envelope_json === null ? null : JSON.parse(stub.envelope_json) };
+}
+export const isStub = async (db, object) => await db.prepare('SELECT 1 FROM peer_stubs WHERE object = ?').get(object.id) !== undefined;
+async function localPerson(db) {
+    return await ownerForGrantee(db, personId());
+}
+async function localApp(db, grantee) {
+    return await ownerForGrantee(db, grantee);
+}
+/** The local object for an app or person the other machine names as an event's actor, or null for any other type. An app or person is an
+ *  owner, not a thing that lives on one machine: it is the same object here as there, so it is never given a stub (a stub would collide
+ *  with the local owner object of the same handle, as with an installed plugin's app). */
+export async function localOwnerActor(db, ref) {
+    if (ref.type === 'app')
+        return await localApp(db, `app:${ref.name}`);
+    if (ref.type === 'person')
+        return await localPerson(db);
+    return null;
+}
+/** The grantee of the local owner standing for the owner the other machine reported. */
+function ownerGrantee(identity, owner) {
+    if (identity !== null)
+        return identity.app === null ? personId() : identity.app;
+    return owner?.type === 'app' ? owner.external_id ?? `app:${owner.handle}` : personId();
+}
+/** The local owner object standing for the owner the other machine reported. */
+async function ownerFor(db, identity, ref) {
+    return await ownerForGrantee(db, ownerGrantee(identity, ref?.owner));
+}
+/** Where each advisory lock family sits in the one order peer code takes them in. Every other path that nests two of them already
+ *  takes the owner before the kind (`package-kinds`, `holdKind`), and a stub before either, so this order never crosses theirs. */
+const LOCK_RANK = ['ingest:', 'stub:', 'owner:', 'kind:'];
+const rankOf = (key) => {
+    const rank = LOCK_RANK.findIndex((prefix) => key.startsWith(prefix));
+    if (rank < 0)
+        throw new Error(`lockInOrder: ${JSON.stringify(key)} is not a known lock key`);
+    return rank;
+};
+/** Lock every key in `keys` in one global order (family rank, then lock hash), so no two transactions that lock overlapping sets can wait on
+ *  each other. Locks are held to the end of the transaction, and taking one again is free. */
+export async function lockInOrder(db, keys) {
+    const unique = [...new Set(keys)];
+    if (unique.length === 0)
+        return;
+    const hashes = await db.prepareUncached(unique.map((_, i) => `SELECT ${i} AS i, hashtext(?) AS h`).join(' UNION ALL ')).all(...unique);
+    const ordered = hashes.map((row) => ({ key: unique[Number(row.i)], hash: Number(row.h) }))
+        .sort((l, r) => rankOf(l.key) - rankOf(r.key) || l.hash - r.hash);
+    for (const { key } of ordered)
+        await db.prepare('SELECT pg_advisory_xact_lock(hashtext(?))').get(key);
+}
+/** The lock key to create the owner `grantee` names, or none when it exists (`ensureOwner` locks only a first sighting). */
+async function missingOwnerKey(db, grantee) {
+    const [scheme, externalId] = grantee.startsWith('app:') ? ['app', grantee] : ['user', grantee];
+    return await db.prepare('SELECT 1 FROM identities WHERE scheme = ? AND external_id = ?').get(scheme, externalId) === undefined ? [ownerLockKey(scheme, externalId)] : [];
+}
+/** Every advisory lock `ensureStub` takes for this object: the stub, the custom kind its reference declares, and each owner it may create.
+ *  A caller that touches several stubs locks the union with `lockInOrder` first, so the order never depends on which stub comes first. */
+export async function stubLockKeys(db, id, type, identity, ref) {
+    const keys = [`stub:${id}`];
+    const decl = ref?.kind_decl;
+    if (decl !== undefined && decl.name === type)
+        keys.push(`kind:${type}`, ...await missingOwnerKey(db, ownerGrantee(null, decl.owner)));
+    if (await getById(db, id) === null)
+        keys.push(...await missingOwnerKey(db, ownerGrantee(identity, ref?.owner)));
+    return keys;
+}
+/** The advisory locks `actorFor` takes for an event's actor. */
+export async function actorLockKeys(db, ref) {
+    if (ref.type === 'app')
+        return await missingOwnerKey(db, `app:${ref.name}`);
+    if (ref.type === 'person')
+        return await missingOwnerKey(db, personId());
+    return await stubLockKeys(db, ref.id, ref.type, null, ref);
+}
+/**
+ * The stub of the object `id` that lives on `machine`, created on first sight. Idempotent: a second
+ * call returns the same row and, given an `envelope`, replaces the identity it stores. Refuses
+ * (`conflict`) an id that is a real local object or a stub of another machine. The owner is the
+ * local app (or person) object of the remote owner, so the stub sits in a space the access rules
+ * understand. No `nodes` row is written.
+ */
+export async function ensureStub(db, id, type, machine, envelope, ref) {
+    const identity = envelope === undefined ? null : identityOfEnvelope(envelope);
+    const privacy = readLegacyPrivacy(ref?.privacy ?? 'public');
+    if (!PRIVACY.includes(privacy))
+        throw new CrtrError('invalid_event', `invalid privacy ${JSON.stringify(privacy)}`, ExitCode.GENERAL, { id });
+    // Concurrent ingests for one new object take turns: the later waits for the earlier commit, then finds the stub instead of failing on `objects_pkey`.
+    // The stub, its kind and its owner are locked together in one order (`lockInOrder`), never one after the other.
+    await lockInOrder(db, await stubLockKeys(db, id, type, identity, ref));
+    const existing = await getById(db, id);
+    if (existing !== null) {
+        const stub = await stubOf(db, existing);
+        if (stub === null)
+            throw new CrtrError('conflict', `${id} is a local ${existing.type}, not a stub of ${machine}`, ExitCode.GENERAL, { id });
+        if (stub.home_machine !== machine) {
+            throw new CrtrError('conflict', `${id} is already a stub of ${stub.home_machine}, not ${machine}`, ExitCode.GENERAL, { id, home_machine: stub.home_machine });
+        }
+        if (identity !== null) {
+            await db.prepare('UPDATE peer_stubs SET envelope_json = ? WHERE object = ?').run(JSON.stringify(identity), existing.id);
+            await db.prepare('UPDATE objects SET reception = 2 WHERE id = ?').run(existing.id);
+        }
+        if (ref !== undefined) {
+            await holdKind(db, type, ref);
+            if (ref.privacy !== undefined && existing.privacy !== privacy) {
+                await db.prepare('UPDATE objects SET privacy = ? WHERE id = ?').run(privacy, existing.id);
+                return (await getById(db, existing.id));
+            }
+        }
+        return existing;
+    }
+    const owner = await ownerFor(db, identity, ref);
+    await holdKind(db, type, ref);
+    const created = await createObject(db, { id, type, kind: ref?.kind ?? null, owner: owner.id, privacy, name: ref?.name ?? id, preview: ref?.preview ?? '', home_machine: machine });
+    await db.prepare('INSERT INTO peer_stubs (object, home_machine, envelope_json, created_at) VALUES (?, ?, ?, ?)')
+        .run(created.id, machine, identity === null ? null : JSON.stringify(identity), new Date().toISOString());
+    // An object directly under an app is read through an `acts_for` fact; a stub under the person inherits the person's. The stub stands for
+    // the install's person, so a local watcher of it reads it exactly as it read the stub before the evaluator.
+    if (owner.type === 'app')
+        await writeActsFor(db, created.id, await personIdAsync());
+    // A stub that stands for a remote watcher receives events exactly as the node would.
+    if (identity !== null)
+        await db.prepare('UPDATE objects SET reception = 2 WHERE id = ?').run(created.id);
+    return (await getById(db, created.id));
+}
+/** Hold the kind declaration `ref` carries for `type` as a `peer` row, so the stub's type is a declared kind. A `manifest` or `register`
+ *  row is never overwritten (`upsertKind`). A declaration that names another kind is ignored. */
+async function holdKind(db, type, ref) {
+    const decl = ref?.kind_decl;
+    if (decl === undefined || decl.name !== type)
+        return;
+    await upsertKind(db, { name: decl.name, owner: await ownerFor(db, null, { ...ref, owner: decl.owner }), description: decl.description, events: decl.events, read: null, source: 'peer' });
+}
+/**
+ * The stub of the node `nodeId` that lives on `machine`, as a watcher: created on first sight with no envelope
+ * identity, owned by the local person, and marked `reception = 2` so `publish` considers it and the node
+ * kind's receiver sends its events through the `peer` outbox. A later forwarded call by that node fills in the
+ * identity on the same row (`ensureStub` with an envelope). Refuses (`conflict`) an id that is a real local
+ * object or a stub of another machine. Writes no `nodes` row.
+ */
+export async function ensureNodeStub(db, nodeId, machine) {
+    const stub = await ensureStub(db, nodeId, 'node', normalizeMachineId(machine));
+    await db.prepare('UPDATE objects SET reception = 2 WHERE id = ?').run(stub.id);
+    return (await getById(db, stub.id));
+}
+/** The object moved: the machine that answered for it is now its home. A no-op for a local object or a stub already homed there. */
+export async function rehomeStub(db, id, machine) {
+    const stub = await stubOf(db, id);
+    if (stub === null || stub.home_machine === machine)
+        return;
+    await db.prepare('UPDATE peer_stubs SET home_machine = ? WHERE object = ?').run(machine, stub.object.id);
+    await db.prepare('UPDATE objects SET home_machine = ? WHERE id = ?').run(machine, stub.object.id);
+}
+/** How `o` is described to another machine. */
+export async function describeObject(db, o) {
+    const ownerRef = await ownerRefOf(db, o.owner === null ? null : await getById(db, o.owner));
+    const decl = await kindDeclarationOf(db, o.type);
+    return { id: o.id, type: o.type, kind: o.kind, name: o.name, preview: o.preview, owner: ownerRef, privacy: o.privacy, ...(decl === null ? {} : { kind_decl: decl }) };
+}
+async function ownerRefOf(db, owner) {
+    if (owner === null || (owner.type !== 'person' && owner.type !== 'app' && owner.type !== 'repo' && owner.type !== 'profile'))
+        return null;
+    const identity = await db.prepare('SELECT scheme, external_id FROM identities WHERE object = ?').get(owner.id);
+    return { id: owner.id, type: owner.type, scheme: identity?.scheme ?? null, external_id: identity?.external_id ?? null, handle: owner.name };
+}
+/** The declaration of the custom kind `type`, or null for a built-in (no `object_kinds` row). Carries no `read` leaf. */
+export async function kindDeclarationOf(db, type) {
+    const row = await db.prepare('SELECT owner, description, events_json FROM object_kinds WHERE name = ?').get(type);
+    const owner = row === undefined ? null : await ownerRefOf(db, await getById(db, row.owner));
+    return row === undefined || owner === null ? null : { name: type, description: row.description, events: JSON.parse(row.events_json), owner };
+}
+/** `dto` with the declaration of its object's kind, when the kind is custom. */
+export async function withKindDecl(db, row, dto) {
+    const decl = await kindDeclarationOf(db, row.type);
+    return decl === null ? dto : { ...dto, kind_decl: decl };
+}

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

@@ -0,0 +1,13 @@
+import { type DirectoryToken } from '../grants/sync.js';
+export declare const REFRESH_BEFORE_EXPIRY_MS = 30000;
+export type Mint = (issuer: string, audience?: string) => Promise<DirectoryToken>;
+export interface TokenCache {
+    /** A token for `audience` (a peer machine URL or the relay origin), or for the directory's own `/v1` when omitted. */
+    get(issuer: string, audience?: string): Promise<string>;
+    /** Forget a token the far side refused (revoked key, clock skew); the next `get` mints a new one. */
+    drop(issuer: string, audience?: string): void;
+    clear(): void;
+}
+export declare function createTokenCache(mint?: Mint, now?: () => number): TokenCache;
+/** The daemon's process-wide cache. */
+export declare const peerTokens: TokenCache;

package/dist/core/peer/token.js

@@ -0,0 +1,29 @@
+// Peer tokens, kept in memory only (never written to disk). One token per
+// audience, reused until `REFRESH_BEFORE_EXPIRY_MS` before its `exp`. The same
+// cache holds the runtime's directory `/v1` token (audience undefined).
+import { mintDirectoryToken } from '../grants/sync.js';
+export const REFRESH_BEFORE_EXPIRY_MS = 30_000;
+export function createTokenCache(mint = mintDirectoryToken, now = Date.now) {
+    const live = new Map();
+    const pending = new Map();
+    const keyOf = (issuer, audience) => `${issuer.replace(/\/$/, '')}\n${audience ?? ''}`;
+    return {
+        async get(issuer, audience) {
+            const key = keyOf(issuer, audience);
+            const held = live.get(key);
+            if (held && held.expires_at - REFRESH_BEFORE_EXPIRY_MS > now())
+                return held.access_token;
+            let flight = pending.get(key);
+            if (!flight) {
+                flight = mint(issuer, audience).then((token) => { live.set(key, token); return token; })
+                    .finally(() => { pending.delete(key); });
+                pending.set(key, flight);
+            }
+            return (await flight).access_token;
+        },
+        drop(issuer, audience) { live.delete(keyOf(issuer, audience)); },
+        clear() { live.clear(); pending.clear(); },
+    };
+}
+/** The daemon's process-wide cache. */
+export const peerTokens = createTokenCache();

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

@@ -0,0 +1,16 @@
+/** Request header naming the sending machine's crtr release. */
+export declare const PEER_VERSION_HEADER = "Crtr-Version";
+/** The oldest crtr release that speaks the peer protocol. 0.3.487 is the first release whose app listener verifies peer tokens with `verifyCallToken` (peer authority), so it can take tokens without `machine_id`/`grantee`. */
+export declare const PEER_VERSION_FLOOR = "0.3.487";
+export interface PeerVersionRefusal {
+    status: 426;
+    code: 'peer_version_too_old';
+    message: string;
+    details: {
+        peer_version: string | null;
+        floor: string;
+        receiver_version: string;
+    };
+}
+/** The refusal for a peer announcing `peerVersion` (the `Crtr-Version` header, or a reach answer's `crtr_version`), or null when it is at or above the floor. */
+export declare function peerVersionRefusal(peerVersion: string | null | undefined, floor?: string, own?: string): PeerVersionRefusal | null;

package/dist/core/peer/version.js

@@ -0,0 +1,23 @@
+// Peer version gate (spec-machines §15.10). Every peer request carries
+// `Crtr-Version`; a receiver below its floor refuses with `426 peer_version_too_old`
+// naming both versions, and a sender that already knows a peer is too old (from the
+// directory's reach answer) refuses before sending with the same error.
+import { compareReleaseVersions } from '../../api/runtime-version.js';
+import { crtrVersion } from '../../shared/crtr-version.js';
+/** Request header naming the sending machine's crtr release. */
+export const PEER_VERSION_HEADER = 'Crtr-Version';
+/** The oldest crtr release that speaks the peer protocol. 0.3.487 is the first release whose app listener verifies peer tokens with `verifyCallToken` (peer authority), so it can take tokens without `machine_id`/`grantee`. */
+export const PEER_VERSION_FLOOR = '0.3.487';
+/** The refusal for a peer announcing `peerVersion` (the `Crtr-Version` header, or a reach answer's `crtr_version`), or null when it is at or above the floor. */
+export function peerVersionRefusal(peerVersion, floor = PEER_VERSION_FLOOR, own = crtrVersion()) {
+    const named = peerVersion?.trim() ? peerVersion.trim() : null;
+    if (named !== null && compareReleaseVersions(named, floor) >= 0)
+        return null;
+    return {
+        status: 426, code: 'peer_version_too_old',
+        message: named === null
+            ? `The peer did not name its crtr version; machines below ${floor} cannot take part (this machine is ${own}). Update it with \`crtr sys update\`.`
+            : `The peer runs crtr ${named}; machines below ${floor} cannot take part (this machine is ${own}). Update it with \`crtr sys update\`.`,
+        details: { peer_version: named, floor, receiver_version: own },
+    };
+}

package/dist/core/permissions/builtin.d.ts

@@ -0,0 +1,8 @@
+import { type Definition } from './schema-parser.js';
+/** The built-in definitions: every object's `crtr/object` rules, teams, and the subject types. `crtr` is a reserved namespace. */
+export declare const BUILTIN_SOURCE = "\ndefinition user {}\ndefinition app {}\ndefinition crtr/group {\n  relation member: user | crtr/group#member\n}\ndefinition crtr/object {\n  relation parent: crtr/object\n  relation acts_for: user\n  relation reader: user | user:* | crtr/group#member\n  relation editor: user | crtr/group#member\n  relation messenger: user | crtr/group#member\n  relation user_of: user | crtr/group#member\n  permission read = reader + editor + messenger + user_of + acts_for + parent->read\n  permission edit = editor + acts_for + parent->edit\n  permission message = messenger + acts_for + parent->message\n  permission use = user_of + acts_for + parent->use\n  permission share = acts_for + parent->share\n}\n";
+export declare const BUILTIN_DEFINITIONS: Definition[];
+export declare const OBJECT_TYPE = "crtr/object";
+export declare const GROUP_TYPE = "crtr/group";
+/** Verb on the CLI → relation on `crtr/object`. */
+export declare const VERB_RELATION: Record<string, string>;

package/dist/core/permissions/builtin.js

@@ -0,0 +1,27 @@
+import { parseSchema } from './schema-parser.js';
+/** The built-in definitions: every object's `crtr/object` rules, teams, and the subject types. `crtr` is a reserved namespace. */
+export const BUILTIN_SOURCE = `
+definition user {}
+definition app {}
+definition crtr/group {
+  relation member: user | crtr/group#member
+}
+definition crtr/object {
+  relation parent: crtr/object
+  relation acts_for: user
+  relation reader: user | user:* | crtr/group#member
+  relation editor: user | crtr/group#member
+  relation messenger: user | crtr/group#member
+  relation user_of: user | crtr/group#member
+  permission read = reader + editor + messenger + user_of + acts_for + parent->read
+  permission edit = editor + acts_for + parent->edit
+  permission message = messenger + acts_for + parent->message
+  permission use = user_of + acts_for + parent->use
+  permission share = acts_for + parent->share
+}
+`;
+export const BUILTIN_DEFINITIONS = parseSchema(BUILTIN_SOURCE);
+export const OBJECT_TYPE = 'crtr/object';
+export const GROUP_TYPE = 'crtr/group';
+/** Verb on the CLI → relation on `crtr/object`. */
+export const VERB_RELATION = { read: 'reader', edit: 'editor', message: 'messenger', use: 'user_of' };

package/dist/core/permissions/ceiling.d.ts

@@ -0,0 +1,57 @@
+import type { CanvasDb } from '../canvas/db.js';
+import type { Reader } from '../graph/types.js';
+import { type Frag } from './sql.js';
+/** How a candidate must sit under a root to pass through it. `depth` is the distance from the candidate up to the root (0 = the root itself). */
+export type Match = 'any' | 'below' | 'direct-doc' | 'no-node' | 'node-tree' | 'objects-app' | 'node-report' | 'run-node' | 'custom' | 'shipped' | 'non-document' | 'run-report' | 'self' | `authored:${string}`;
+export interface CeilingRoot {
+    id: string;
+    private: boolean;
+    match: Match;
+}
+export interface Ceiling {
+    /** The reader's own app object: run confinement applies to every object below it, whichever alternative lets the object through. */
+    ownApp: string;
+    roots: CeilingRoot[];
+    /** Schema namespaces the reader's app owns: a document whose `schema_type` is in one passes the ceiling anywhere, at any privacy. */
+    namespaces: string[];
+    /** The reader's run place; null for the app's server and for readers outside a run. */
+    place: {
+        run: string;
+        isolated: boolean;
+    } | null;
+    predicates: {
+        /** `crtr:objects:<verb>:node`: every public node passes. */
+        allNodes: boolean;
+        /** The space objects themselves (apps, persons, repos with no owner) pass: a granted reader sees that they exist. */
+        spaces: boolean;
+    };
+    /** App object ids for the `authored:` match (first-revision author rule): the caller's app and every first-party app, one whose grant holds
+     *  `crtr:memory:manage:user` always. A revoked first-party grant still counts: revocation stops its calls, not who wrote the document. */
+    authorApps: string[];
+}
+export type Access = 'read' | 'write' | 'message';
+export interface CeilingOptions {
+    verb?: 'watch' | 'link';
+}
+/** Every live local person object. The ceiling reaches a person's tree through the scope the reader holds; which person's documents the reader's user may
+ *  actually read is the schema's decision (`acts_for` on the reader's own person, a share on anyone else's), so a document shared with the reader is in reach. */
+export declare function personObjectIds(db: CanvasDb): Promise<string[]>;
+/** Whether `scopes` hold a provider-group scope `<provider>:<group>` of the app whose external id is `appExt`: what lets a run read that app's private objects. */
+export declare function holdsProviderGroup(scopes: readonly string[], appExt: string): boolean;
+/** The ceiling of `reader` for `access`; null for a person reader (no ceiling). */
+export declare function resolveCeiling(db: CanvasDb, reader: Reader, access: Access, options?: CeilingOptions): Promise<Ceiling | null>;
+export interface RunPlace {
+    run: string;
+    isolated: boolean;
+}
+/** A node's run and whether it is isolated (its own flag: isolation is sticky). A deleted node of an isolated run keeps its run in `deleted_isolated_nodes`. */
+export declare function nodePlace(db: CanvasDb, nodeId: string): Promise<RunPlace | null>;
+/** Record, before a node's row is deleted, the run of a node of an isolated run. */
+export declare function rememberDeletedIsolated(nodeId: string, db: CanvasDb): Promise<void>;
+/** The reader with its launched list lifted, for the runtime's own writes inside a narrowed run (a `crtr push` report, a promoted node's scaffolded roadmap). */
+export declare function asRuntimeWriter<R extends Reader>(reader: R): R;
+/** The own-app memory scope a narrowed run lacks to `read` or `rw` the document `objectId` (or a document about to be created under `objectId` when `creating`), or null.
+ *  A run with no launched list, the app's server and a person are never narrowed. Only documents are gated. */
+export declare function missingMemoryScope(db: CanvasDb, reader: Reader, objectId: string, access: 'read' | 'rw', creating?: boolean): Promise<string | null>;
+/** The ceiling as a condition on the candidate `o` (an alias of `objects`). */
+export declare function ceilingFrag(c: Ceiling, o: string): Frag;