@north-light/api 0.3.579 → 0.3.587

package/dist/core/graph/names.js

@@ -0,0 +1,183 @@
+import { isSafeNodeId } from '../canvas/paths.js';
+import { OBJECT_TYPE } from '../permissions/builtin.js';
+import { ceilingFrag, resolveCeiling } from '../permissions/ceiling.js';
+import { compilePermission } from '../permissions/compile.js';
+import { permits, readerUser, resolveReader } from '../permissions/evaluator.js';
+import { loadDefinitions } from '../permissions/schemas.js';
+import { and, or, raw } from '../permissions/sql.js';
+import { getById } from './objects.js';
+import { flatMapAsync } from '../async-array.js';
+/** 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 async function viewOf(db, reader) {
+    const user = await readerUser(db, reader);
+    const person = user === null ? undefined : await db.prepare(`SELECT o.* FROM objects o JOIN identities i ON i.object = o.id AND i.scheme = 'user'
+    WHERE o.type = 'person' AND o.home_machine IS NULL AND regexp_replace(i.external_id, '^user:', '') = ?`).get(user);
+    // The apps that ship documents (installed plugins), `crtr` last: ranking only; what a reader may read is decided in each query.
+    const tools = await db.prepare(`SELECT a.* FROM objects a WHERE a.type = 'app' AND a.deleted_at IS NULL AND EXISTS (
+      SELECT 1 FROM objects o JOIN documents d ON d.object = o.id
+      WHERE o.owner = a.id AND o.type = 'document' AND o.deleted_at IS NULL AND d.source_path IS NOT NULL)
+    ORDER BY a.name = 'crtr', a.name`).all();
+    const head = reader.class === 'node' ? [reader.node, ...reader.repos, ...reader.projectRepos, reader.profile, reader.app]
+        : reader.class === 'app' ? [reader.app]
+            : reader.class === 'object' ? [reader.owner, ...reader.repos, reader.app]
+                : [];
+    const seen = new Set();
+    return [...head, person, ...tools].filter((o) => !!o && !seen.has(o.id) && !!seen.add(o.id));
+}
+/** 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 async function readableOrDeleted(db, ev, alias) {
+    const live = await permits(db, ev, 'read', alias);
+    const ceiling = await resolveCeiling(db, ev.reader, 'read');
+    const grants = compilePermission(await loadDefinitions(db), ev.subjects, OBJECT_TYPE, 'read', raw('gr.id'));
+    const chain = { sql: `EXISTS (WITH RECURSIVE up(id, depth) AS (
+      SELECT ${alias}.id, 0
+      UNION ALL SELECT p.owner, up.depth + 1 FROM up JOIN objects p ON p.id = up.id WHERE p.owner IS NOT NULL AND up.depth < 12)
+    SELECT 1 FROM up gr WHERE ${grants.sql})`, params: grants.params };
+    const deleted = and([raw(`${alias}.deleted_at IS NOT NULL AND ${alias}.schema_type IS NULL`), ...(ceiling === null ? [] : [ceilingFrag(ceiling, alias)]), chain]);
+    return or([live, deleted]);
+}
+// A resolution asks for `readableOrDeleted(ev, 'o')` once per owner in the reader's view, and a corpus resolves every name with one `ev`: each
+// ask recompiled the schema and re-resolved the ceiling (several queries apiece). The fragment depends only on `ev`, which lives for one
+// resolution or one corpus, so compute it once per `ev`.
+const readFrags = new WeakMap();
+function readableFrag(db, ev) {
+    let frag = readFrags.get(ev);
+    if (frag === undefined) {
+        frag = readableOrDeleted(db, ev, 'o');
+        frag.catch(() => readFrags.delete(ev));
+        readFrags.set(ev, frag);
+    }
+    return frag;
+}
+/** Whether the reader may read the object `id`, live or deleted. */
+export async function canReadOrDeleted(db, ev, id) {
+    const p = await readableFrag(db, ev);
+    const row = await db.prepareUncached(`SELECT ${p.sql} AS ok FROM objects o WHERE o.id = ?`).get(...p.params, id);
+    return row?.ok === true;
+}
+/** The documents and custom objects named `name` under `owner` that the reader may read. */
+async function namedObjects(db, ev, owner, name, deleted, stubs = false) {
+    const read = await readableFrag(db, ev);
+    return await db.prepareUncached(`SELECT o.* FROM objects o WHERE (o.type = 'document' OR strpos(o.type, '.') > 0) AND o.owner = ? AND o.name = ? AND o.home_machine IS ${stubs ? 'NOT NULL' : 'NULL'}
+    AND o.deleted_at IS ${deleted ? 'NOT NULL' : 'NULL'} AND ${read.sql}${deleted ? ' ORDER BY o.deleted_at DESC' : ''}`).all(owner.id, name, ...read.params);
+}
+/** The owner types that carry a handle; `<type>:<handle>/<name>` names one exactly. */
+export const HANDLE_TYPES = ['person', 'app', 'repo', 'profile'];
+const TYPED = /^(person|app|repo|profile|node):([^/]+)\/(.+)$/;
+/** A ref without its `[[ ]]` wrapper. */
+export const unwrapRef = (raw) => raw.trim().replace(/^\[\[(.*)\]\]$/, '$1').trim();
+/** `<type>:<owner handle>/<name>` or `<owner handle>/<name>` split into its parts; null for a bare name. */
+function splitOwnerRef(name) {
+    const typed = TYPED.exec(name);
+    if (typed)
+        return { type: typed[1], handle: typed[2], rest: typed[3] };
+    const slash = name.indexOf('/');
+    return slash > 0 ? { handle: name.slice(0, slash), rest: name.slice(slash + 1) } : null;
+}
+/** 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 async function ownersByHandle(db, handle, type) {
+    if (type === 'node')
+        return await db.prepare("SELECT * FROM objects WHERE type = 'node' AND id = ?").all(handle);
+    if (type)
+        return await db.prepare('SELECT * FROM objects WHERE type = ? AND (name = ? OR id = ?) AND home_machine IS NULL').all(type, handle, handle);
+    return await db.prepare(`SELECT * FROM objects WHERE (type = 'node' AND id = ?)
+    OR (type IN ('person','app','repo','profile') AND (name = ? OR id = ?) AND home_machine IS NULL)`).all(handle, handle, handle);
+}
+const OLD_REPORT = /^([^:/]+):reports\/(.+?)(?:\.md)?$/;
+/** 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 async function viewResolutions(db, context, names) {
+    const plain = [...new Set(names.filter((n) => unwrapRef(n) === n && !OLD_REPORT.test(n)))];
+    const hits = new Map();
+    if (plain.length === 0 || context.view.length === 0)
+        return hits;
+    const ids = new Set((await db.prepare('SELECT id FROM objects WHERE id = ANY(?::text[])').all(plain)).map((r) => r.id));
+    const settled = plain.filter((n) => !ids.has(n));
+    for (const n of settled)
+        hits.set(n, null);
+    const read = await readableFrag(db, context.ev);
+    const rows = await db.prepareUncached(`SELECT o.id, o.owner, o.name FROM objects o WHERE (o.type = 'document' OR strpos(o.type, '.') > 0)
+    AND o.owner = ANY(?::text[]) AND o.name = ANY(?::text[]) AND o.home_machine IS NULL AND o.deleted_at IS NULL AND ${read.sql}`)
+        .all(context.view.map((o) => o.id), settled, ...read.params);
+    const rank = new Map(context.view.map((o, i) => [o.id, i]));
+    const best = new Map();
+    for (const r of rows) {
+        const at = rank.get(r.owner);
+        if (at < (best.get(r.name) ?? Infinity)) {
+            best.set(r.name, at);
+            hits.set(r.name, r.id);
+        }
+    }
+    return hits;
+}
+export async function resolveName(db, reader, raw, context) {
+    let name = unwrapRef(raw);
+    const oldReport = OLD_REPORT.exec(name);
+    if (oldReport && !TYPED.test(name))
+        name = `${oldReport[1]}/reports/${oldReport[2]}`;
+    const ev = context?.ev ?? await resolveReader(db, reader);
+    const byId = await getById(db, name);
+    if (byId && await canReadOrDeleted(db, ev, byId.id))
+        return byId.deleted_at ? { deleted: byId } : { object: byId };
+    const view = context?.view ?? await viewOf(db, reader);
+    for (const owner of view) {
+        const hit = (await namedObjects(db, ev, owner, name, false))[0];
+        if (hit)
+            return { object: hit };
+    }
+    const split = splitOwnerRef(name);
+    if (split) {
+        const { type, handle, rest } = split;
+        const typed = type !== undefined;
+        const owners = await ownersByHandle(db, handle, type);
+        const rank = (o) => { const i = view.findIndex((v) => v.id === o.id); return i < 0 ? Infinity : i; };
+        const inView = owners.filter((o) => rank(o) < Infinity).sort((a, b) => rank(a) - rank(b));
+        for (const owner of inView) {
+            const hit = (await namedObjects(db, ev, owner, rest, false))[0];
+            if (hit)
+                return { object: hit };
+        }
+        const hits = await flatMapAsync(owners, async (owner) => await namedObjects(db, ev, owner, rest, false));
+        if (hits.length === 1)
+            return { object: hits[0] };
+        if (hits.length > 1)
+            return { ambiguous: hits };
+        const gone = (await flatMapAsync(owners, async (owner) => await namedObjects(db, ev, owner, rest, true)))[0];
+        if (gone)
+            return { deleted: gone };
+        if (!typed && owners.length === 0 && isSafeNodeId(handle))
+            return { remote: name };
+        return { missing: true };
+    }
+    for (const owner of view) {
+        const gone = (await namedObjects(db, ev, owner, name, true))[0];
+        if (gone)
+            return { deleted: gone };
+    }
+    return { missing: true };
+}
+/** 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 async function stubsNamed(db, reader, raw) {
+    const name = unwrapRef(raw);
+    const ev = await resolveReader(db, reader);
+    const found = async (owners, rest) => await flatMapAsync(owners, async (owner) => await namedObjects(db, ev, owner, rest, false, true));
+    const inView = await found(await viewOf(db, reader), name);
+    if (inView.length)
+        return inView;
+    const split = splitOwnerRef(name);
+    return split ? await found(await ownersByHandle(db, split.handle, split.type), split.rest) : [];
+}

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

@@ -0,0 +1,88 @@
+import type { ObjectRow, Privacy, Reader } from './types.js';
+import type { CanvasDb } from '../canvas/db.js';
+export type OwnerType = 'person' | 'app' | 'repo' | 'profile';
+export declare function getById(db: CanvasDb, id: string): Promise<ObjectRow | null>;
+export declare function createObject(db: CanvasDb, spec: {
+    id?: string;
+    type: string;
+    kind: string | null;
+    owner: string | null;
+    privacy: Privacy;
+    name: string;
+    preview: string;
+    /** Set for a stub, in the insert itself: the name indexes cover only rows without it. */
+    home_machine?: string;
+    /** The permission schema type the object is evaluated under (`firstlight/memory`); omitted = `crtr/object`. */
+    schema_type?: string;
+}): Promise<ObjectRow>;
+/** The advisory lock key `ensureOwner` takes for a first sighting of an identity. */
+export declare const ownerLockKey: (scheme: string, externalId: string) => string;
+/** The owner object for an identity, created on first sight. Idempotent on
+ *  (scheme, externalId). Handles are unique per owner type: a handle already held
+ *  by a different identity of the same type throws `conflict` naming both; it is
+ *  never renamed silently. */
+export declare function ensureOwner(db: CanvasDb, type: OwnerType, scheme: string, externalId: string, handle: string, owner?: ObjectRow): Promise<ObjectRow>;
+/** Give the live profile object of `profileId` the handle `handle`, so `[[handle/x]]` links,
+ *  `owner=` listings and `--owner profile:<handle>` follow a profile rename. Refuses with
+ *  `conflict` — before changing anything — when another live profile object holds the handle.
+ *  A profile with no object yet has nothing to rename (its object is created from the manifest name
+ *  on first use). Returns whether an object was renamed. Links are edges to ids, so they keep resolving. */
+export declare function renameProfileObject(db: CanvasDb, profileId: string, handle: string): Promise<boolean>;
+/** The handle a profile's object carries. Handles are unique per owner type in the one database, and on a cloud role many people each hold
+ *  a profile of the same name (every person's default `app-<app>`, or a `work`): the profile id is unique, so it is the handle there. A Mac keeps the name. */
+export declare function profileHandle(profileId: string, name: string): string;
+/** The owner object of a principal: `app:<x>` → app `<x>`; `user:<id>` → person (handle `user` for this install's person, else the id).
+ *  A cloud role serves many people and `personId()` is the request's person, so every person there gets the id as its handle: the one
+ *  `user` handle would otherwise go to whichever person was created first and refuse every other person with a `conflict`. */
+export declare function ownerForGrantee(db: CanvasDb, grantee: string): Promise<ObjectRow>;
+/** The owner's live document named `name`, or null. */
+export declare function liveDocumentNamed(db: CanvasDb, owner: string, name: string): Promise<ObjectRow | null>;
+export declare function nodeObject(db: CanvasDb, nodeId: string): Promise<ObjectRow>;
+export declare function setObjectName(db: CanvasDb, object: ObjectRow, name: string): Promise<void>;
+export declare function setObjectKind(db: CanvasDb, object: ObjectRow, kind: string | null): Promise<void>;
+export interface ExtensionsFilter {
+    /** Documents whose `extensions` contain this (JSON containment: `{ 'firstlight': { workspace: 'w1' } }`). */
+    extensions?: Record<string, Record<string, unknown>>;
+    /** Objects whose permission schema type is exactly this. */
+    schemaType?: string;
+}
+export interface ObjectFilter extends ExtensionsFilter {
+    type?: string;
+    kind?: string;
+    owner?: ObjectRow;
+    privacy?: Privacy;
+    name?: string;
+    deleted?: boolean;
+    /** Objects whose name starts with this text (matched literally). */
+    namePrefix?: string;
+    /** Only objects the reader reaches through a share and not through its own tree: a `reader`/`editor`/`messenger`/`user_of` fact (not a package's) names the
+     *  reader's user, `user:*` or a team it belongs to, on the object or an ancestor, and no `acts_for` fact names the reader's user on the object or an ancestor.
+     *  Applies to objects governed by `crtr/object` (no `schema_type`). */
+    shared?: boolean;
+}
+/** `after_seq` is the `seq` of the last object on the previous page (the `/v1` cursor, a decimal number). */
+export interface Page {
+    limit?: number;
+    after_seq?: number;
+}
+/** Objects the reader can read, in `seq` (insertion) order. Records nothing. `limit` ≤ 100. */
+export declare function listObjects(db: CanvasDb, reader: Reader, filter: ObjectFilter, page?: Page): Promise<ObjectRow[]>;
+export interface SearchQuery extends ExtensionsFilter {
+    text: string;
+    body?: boolean;
+    grep?: boolean;
+    type?: string;
+    kind?: string;
+    owner?: ObjectRow;
+}
+export interface SearchHit {
+    object: ObjectRow;
+    field: 'name' | 'preview' | 'summary' | 'body';
+    line?: number;
+    text?: string;
+}
+/** Up to 100 hits over live objects the reader can read. Records nothing. `text`
+ *  matches name, preview and document summary as a substring; `body` also scans
+ *  each document's head bodies for the substring, and `grep` scans them for `text`
+ *  as a regular expression. Body search reads every readable body: linear, no index. */
+export declare function searchObjects(db: CanvasDb, reader: Reader, query: SearchQuery): Promise<SearchHit[]>;

package/dist/core/graph/objects.js

@@ -0,0 +1,273 @@
+import { CrtrError, notFound } from '../errors.js';
+import { ExitCode } from '../../types.js';
+import { newNodeId } from '../runtime/nodes.js';
+import { kindOf } from './kinds/registry.js';
+import { findMany as findBodies } from './bodies.js';
+import { isCloudRole, personId, personIdAsync } from '../canvas/person.js';
+import { check, permits, resolveReader } from '../permissions/evaluator.js';
+import { userSubject, writeActsFor } from '../permissions/facts.js';
+const OWNER_TYPES = new Set(['person', 'app', 'repo', 'profile']);
+function rowFrom(raw) {
+    return raw ? raw : null;
+}
+export async function getById(db, id) {
+    return rowFrom(await db.prepare('SELECT * FROM objects WHERE id = ?').get(id));
+}
+export async function createObject(db, spec) {
+    await kindOf(db, spec.type); // an undeclared kind cannot be written
+    const row = await db.prepare(`INSERT INTO objects (id, type, kind, owner, privacy, name, preview, created_at, home_machine, schema_type)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?) RETURNING *`).get(spec.id ?? await newNodeId(), spec.type, spec.kind, spec.owner, spec.privacy, spec.name, spec.preview, new Date().toISOString(), spec.home_machine ?? null, spec.schema_type ?? null);
+    return row;
+}
+/** The advisory lock key `ensureOwner` takes for a first sighting of an identity. */
+export const ownerLockKey = (scheme, externalId) => `owner:${scheme}:${externalId}`;
+/** The owner object for an identity, created on first sight. Idempotent on
+ *  (scheme, externalId). Handles are unique per owner type: a handle already held
+ *  by a different identity of the same type throws `conflict` naming both; it is
+ *  never renamed silently. */
+export async function ensureOwner(db, type, scheme, externalId, handle, owner) {
+    if (!OWNER_TYPES.has(type))
+        throw new Error(`ensureOwner: ${type} is not an owner type`);
+    // An owner that exists needs no lock: taking one here would acquire it outside the order a peer ingest locked its keys in.
+    const find = async () => await db.prepare(`SELECT o.* FROM identities i JOIN objects o ON o.id = i.object
+    WHERE i.scheme = ? AND i.external_id = ?`).get(scheme, externalId);
+    const found = await find();
+    if (found)
+        return found;
+    // Concurrent first sightings of one identity take turns: the later waits for the earlier commit, then finds the owner instead of creating a second.
+    await db.prepare('SELECT pg_advisory_xact_lock(hashtext(?))').get(ownerLockKey(scheme, externalId));
+    const existing = await find();
+    if (existing)
+        return existing;
+    const holder = await db.prepare(`SELECT o.id, o.type, i.scheme, i.external_id FROM objects o
+    LEFT JOIN identities i ON i.object = o.id
+    WHERE o.name = ? AND o.type = ? AND o.home_machine IS NULL`).get(handle, type);
+    if (holder) {
+        throw new CrtrError('conflict', `handle "${handle}" is held by ${holder.type} ${holder.id} (${holder.scheme}:${holder.external_id}); cannot give it to ${type} ${scheme}:${externalId}`, ExitCode.GENERAL, { handle, holder: holder.id });
+    }
+    const created = await createObject(db, {
+        type, kind: null, owner: type === 'profile' ? (owner?.id ?? null) : null,
+        privacy: 'public', name: handle, preview: '',
+    });
+    await db.prepare('INSERT INTO identities (object, scheme, external_id) VALUES (?, ?, ?)').run(created.id, scheme, externalId);
+    // The person object is kept for its own user; a profile or repo object for the install's person (boot's seed does the same for existing rows).
+    if (type === 'person' && scheme === 'user')
+        await writeActsFor(db, created.id, userSubject(externalId).id);
+    else if (type === 'profile' || type === 'repo')
+        await writeActsFor(db, created.id, userSubject(await personIdAsync()).id);
+    return created;
+}
+/** Give the live profile object of `profileId` the handle `handle`, so `[[handle/x]]` links,
+ *  `owner=` listings and `--owner profile:<handle>` follow a profile rename. Refuses with
+ *  `conflict` — before changing anything — when another live profile object holds the handle.
+ *  A profile with no object yet has nothing to rename (its object is created from the manifest name
+ *  on first use). Returns whether an object was renamed. Links are edges to ids, so they keep resolving. */
+export async function renameProfileObject(db, profileId, handle) {
+    if (isCloudRole())
+        return false; // a cloud role's handle is the profile id, which a rename does not change
+    const own = await db.prepare(`SELECT o.* FROM identities i JOIN objects o ON o.id = i.object
+    WHERE i.scheme = 'profile' AND i.external_id = ? AND o.type = 'profile' AND o.deleted_at IS NULL`)
+        .get(profileId);
+    const holder = await db.prepare(`SELECT o.id FROM objects o
+    WHERE o.name = ? AND o.type = 'profile' AND o.deleted_at IS NULL AND o.home_machine IS NULL AND o.id <> ?`)
+        .get(handle, own ? own.id : '');
+    if (holder) {
+        throw new CrtrError('conflict', `handle "${handle}" is already held by profile object ${holder.id}; cannot rename profile ${profileId} to it`, ExitCode.GENERAL, { handle, holder: holder.id });
+    }
+    if (!own)
+        return false;
+    const row = own;
+    if (row.name === handle)
+        return false;
+    await setObjectName(db, row, handle);
+    return true;
+}
+/** The handle a profile's object carries. Handles are unique per owner type in the one database, and on a cloud role many people each hold
+ *  a profile of the same name (every person's default `app-<app>`, or a `work`): the profile id is unique, so it is the handle there. A Mac keeps the name. */
+export function profileHandle(profileId, name) {
+    return isCloudRole() ? profileId : name;
+}
+/** The owner object of a principal: `app:<x>` → app `<x>`; `user:<id>` → person (handle `user` for this install's person, else the id).
+ *  A cloud role serves many people and `personId()` is the request's person, so every person there gets the id as its handle: the one
+ *  `user` handle would otherwise go to whichever person was created first and refuse every other person with a `conflict`. */
+export async function ownerForGrantee(db, grantee) {
+    if (/^app:[a-z0-9][a-z0-9._-]*$/.test(grantee))
+        return await ensureOwner(db, 'app', 'app', grantee, grantee.slice(4));
+    if (/^user:[a-z0-9][a-z0-9._-]*$/.test(grantee))
+        return await ensureOwner(db, 'person', 'user', grantee, !isCloudRole() && grantee === personId() ? 'user' : grantee.slice(5));
+    throw new Error(`principal ${JSON.stringify(grantee)} is neither app:<name> nor user:<id>`);
+}
+/** The owner's live document named `name`, or null. */
+export async function liveDocumentNamed(db, owner, name) {
+    return rowFrom(await db.prepare(`SELECT * FROM objects WHERE (type = 'document' OR strpos(type, '.') > 0) AND owner = ? AND name = ? AND deleted_at IS NULL AND home_machine IS NULL`)
+        .get(owner, name));
+}
+export async function nodeObject(db, nodeId) {
+    const row = await getById(db, nodeId);
+    if (!row || row.type !== 'node')
+        throw notFound(`no node object ${nodeId}`);
+    return row;
+}
+export async function setObjectName(db, object, name) {
+    await db.prepare('UPDATE objects SET name = ? WHERE id = ?').run(name, object.id);
+}
+export async function setObjectKind(db, object, kind) {
+    await db.prepare('UPDATE objects SET kind = ? WHERE id = ?').run(kind, object.id);
+}
+/** WHERE clauses (on `objects` aliased `o`) for the schema type and extensions filters, pushing their parameters in order. */
+function narrowing(filter, args) {
+    const where = [];
+    if (filter.type !== undefined) {
+        where.push('o.type = ?');
+        args.push(filter.type);
+    }
+    if (filter.kind !== undefined) {
+        where.push('o.kind = ?');
+        args.push(filter.kind);
+    }
+    if (filter.owner !== undefined) {
+        where.push('o.owner = ?');
+        args.push(filter.owner.id);
+    }
+    if (filter.namePrefix !== undefined) {
+        where.push("o.name LIKE ? ESCAPE '\\'");
+        args.push(`${filter.namePrefix.replace(/[\\%_]/g, (c) => `\\${c}`)}%`);
+    }
+    if (filter.schemaType !== undefined) {
+        where.push('o.schema_type = ?');
+        args.push(filter.schemaType);
+    }
+    if (filter.extensions !== undefined) {
+        where.push('EXISTS (SELECT 1 FROM documents x WHERE x.object = o.id AND x.extensions_json::jsonb @> ?::jsonb)');
+        args.push(JSON.stringify(filter.extensions));
+    }
+    return where;
+}
+/** WHERE clauses (on `o`) for `ObjectFilter.shared`, pushing their parameters in order. */
+function sharedOnly(ev, args) {
+    const ancestors = `WITH RECURSIVE sa(id, owner, depth) AS (SELECT o.id, o.owner, 0 UNION ALL SELECT p.id, p.owner, sa.depth + 1 FROM sa JOIN objects p ON p.id = sa.owner WHERE sa.depth < 12)`;
+    args.push(ev.subjects.userIds, ev.subjects.groupIds);
+    const shared = ['o.schema_type IS NULL',
+        `EXISTS (${ancestors} SELECT 1 FROM sa JOIN relations r ON r.resource_type = 'crtr/object' AND r.resource_id = sa.id
+      AND r.relation IN ('reader', 'editor', 'messenger', 'user_of') AND r.written_by <> 'package'
+      AND ((r.subject_type = 'user' AND r.subject_id = ANY(?::text[])) OR (r.subject_type = 'crtr/group' AND r.subject_relation = 'member' AND r.subject_id = ANY(?::text[]))))`];
+    // A reader that acts for no person has nothing kept for it, so nothing to leave out.
+    if (ev.userId === null)
+        return shared;
+    args.push(ev.userId);
+    return [...shared,
+        `NOT EXISTS (${ancestors} SELECT 1 FROM sa JOIN relations r ON r.resource_type = 'crtr/object' AND r.resource_id = sa.id
+      AND r.relation = 'acts_for' AND r.subject_type = 'user' AND r.subject_id = ?)`];
+}
+/** Objects the reader can read, in `seq` (insertion) order. Records nothing. `limit` ≤ 100. */
+export async function listObjects(db, reader, filter, page = {}) {
+    const where = ['o.seq > ?'];
+    const args = [page.after_seq ?? 0];
+    if (filter.privacy !== undefined) {
+        where.push('o.privacy = ?');
+        args.push(filter.privacy);
+    }
+    if (filter.name !== undefined) {
+        where.push('o.name = ?');
+        args.push(filter.name);
+    }
+    where.push('o.home_machine IS NULL'); // a stub stands for an object another machine homes; that machine lists it
+    where.push(filter.deleted ? 'o.deleted_at IS NOT NULL' : 'o.deleted_at IS NULL');
+    where.push(...narrowing(filter, args));
+    const ev = await resolveReader(db, reader);
+    if (filter.shared)
+        where.push(...sharedOnly(ev, args));
+    const read = await permits(db, ev, 'read', 'o');
+    const limit = Math.min(page.limit ?? 100, 100);
+    return await db.prepareUncached(`SELECT o.* FROM objects o WHERE ${where.join(' AND ')} AND (${read.sql}) ORDER BY o.seq LIMIT ${limit}`)
+        .all(...args, ...read.params);
+}
+/** Up to 100 hits over live objects the reader can read. Records nothing. `text`
+ *  matches name, preview and document summary as a substring; `body` also scans
+ *  each document's head bodies for the substring, and `grep` scans them for `text`
+ *  as a regular expression. Body search reads every readable body: linear, no index. */
+export async function searchObjects(db, reader, query) {
+    const limit = 100;
+    const hits = [];
+    const like = `%${query.text.replace(/[\\%_]/g, (c) => `\\${c}`)}%`;
+    const ev = await resolveReader(db, reader);
+    if (!query.grep) {
+        const args = [like];
+        const narrow = narrowing(query, args).map((c) => ` AND ${c}`).join('');
+        const read = await permits(db, ev, 'read', 'o');
+        const rows = await db.prepareUncached(`SELECT o.*, (SELECT d.summary FROM documents d WHERE d.object = o.id) AS _summary FROM objects o
+      WHERE o.deleted_at IS NULL AND o.home_machine IS NULL AND (o.name ILIKE ?1 ESCAPE '\\' OR o.preview ILIKE ?1 ESCAPE '\\'
+        OR EXISTS (SELECT 1 FROM documents d WHERE d.object = o.id AND d.summary ILIKE ?1 ESCAPE '\\'))${narrow}
+      AND (${read.sql}) ORDER BY o.seq LIMIT ${limit}`).all(...args, ...read.params);
+        const needle = query.text.toLowerCase();
+        for (const raw of rows) {
+            const { _summary, ...rest } = raw;
+            const object = rest;
+            const field = object.name.toLowerCase().includes(needle) ? 'name' : object.preview.toLowerCase().includes(needle) ? 'preview' : 'summary';
+            hits.push({ object, field, ...(field === 'summary' ? { text: String(_summary) } : {}) });
+        }
+        if (hits.length >= limit)
+            return hits;
+    }
+    if (!query.body && !query.grep)
+        return hits;
+    const found = new Set(hits.map((h) => h.object.id));
+    const test = query.grep ? ((re) => (line) => re.test(line))(new RegExp(query.text)) : (line) => line.includes(query.text);
+    const docArgs = [];
+    const docNarrow = narrowing(query, docArgs).map((c) => ` AND ${c}`).join('');
+    // The text match comes first: the only way to test a body is to read it, and the permission check (an ancestor walk per
+    // candidate) then runs on the matches alone, in chunks that keep `seq` order and stop at the limit. Reading a body the reader may not see
+    // discloses nothing: only matches that pass `read` are returned.
+    const candidates = await db.prepareUncached(`SELECT o.id, r.body_hash AS body_hash FROM objects o
+      JOIN documents d ON d.object = o.id JOIN revisions r ON r.document = o.id
+      WHERE o.type = 'document' AND o.deleted_at IS NULL AND NOT EXISTS (SELECT 1 FROM revision_parents p WHERE p.parent = r.rev_id)${docNarrow}
+      ORDER BY o.seq, r.number`).all(...docArgs);
+    const read = await permits(db, ev, 'read', 'o');
+    const CHUNK = 200;
+    let pending = [];
+    const flush = async () => {
+        if (pending.length === 0)
+            return false;
+        const rows = await db.prepareUncached(`SELECT o.* FROM objects o WHERE o.id = ANY(?::text[]) AND (${read.sql})`)
+            .all(pending.map((m) => m.id), ...read.params);
+        const readable = new Map(rows.map((row) => [row.id, row]));
+        for (const m of pending) {
+            const object = readable.get(m.id);
+            if (object === undefined)
+                continue;
+            hits.push({ object, field: 'body', line: m.line, text: m.text });
+            if (hits.length >= limit)
+                return true;
+        }
+        pending = [];
+        return false;
+    };
+    const BODY_BATCH = 100;
+    for (let from = 0; from < candidates.length; from += BODY_BATCH) {
+        const batch = candidates.slice(from, from + BODY_BATCH).filter((c) => !found.has(c.id));
+        const texts = await findBodies(db, batch.map((c) => c.body_hash));
+        for (const c of batch) {
+            if (found.has(c.id))
+                continue;
+            const body = texts.get(c.body_hash);
+            if (body === undefined) {
+                // A missing body fails the search only for a document the reader can read, as before the match came first.
+                if (await check(db, ev, 'read', c.id))
+                    throw notFound(`no body ${c.body_hash}`);
+                continue;
+            }
+            if (!query.grep && !body.includes(query.text))
+                continue; // a literal needle: skip splitting a body that cannot match
+            const lines = body.split('\n');
+            const index = lines.findIndex(test);
+            if (index < 0)
+                continue;
+            found.add(c.id);
+            pending.push({ id: c.id, line: index + 1, text: lines[index] });
+            if (pending.length >= CHUNK && await flush())
+                return hits;
+        }
+    }
+    await flush();
+    return hits;
+}

package/dist/core/graph/package-docs.d.ts

@@ -0,0 +1,41 @@
+import { type QuarantinedPlugin } from '../plugin-quarantine.js';
+import { type PackageFile } from './package-files.js';
+import type { ReposFn } from './reader.js';
+import type { ObjectRow } from './types.js';
+import type { CanvasDb } from '../canvas/db.js';
+export interface PackageSource {
+    plugin: string;
+    dir: string;
+}
+/** The builtin corpus (app `crtr`), then every enabled user-scope plugin's `memory/` folder. */
+export declare function packageSources(): PackageSource[];
+export interface PackageReconcileReport {
+    created: number;
+    updated: number;
+    deleted: number;
+    /** plugins provided by more than one package; only the first is reconciled */
+    conflicts: Array<{
+        plugin: string;
+        message: string;
+    }>;
+    invalid: Array<{
+        path: string;
+        error: string;
+    }>;
+    /** plugin directories with an unreadable manifest or command file, moved aside before reconciling */
+    quarantined: QuarantinedPlugin[];
+}
+/** Converge every package's documents onto its files. Run inside the caller's transaction.
+ *  Idempotent: a second run over unchanged files changes no document, revision or rule (it re-derives
+ *  each document's link edges, which land the same). A changed body replaces the
+ *  document's single revision and publishes `edited`; a vanished file (or plugin) marks its
+ *  document deleted and publishes `deleted`. */
+export declare function reconcilePackageDocuments(db: CanvasDb, explicitSources?: readonly PackageSource[]): Promise<PackageReconcileReport>;
+/** Record a package document's `links-to` edges the way a runtime document gets them, so delivery
+ *  attaches the link previews. Each `[[name]]` resolves in its own app's view and links only when it
+ *  names another shipped document (builtin or plugin): a package never links to a user's or a
+ *  runtime document that happens to share a bare name. A name that resolves to nothing stays text.
+ *  Edges are rewritten only when they differ, so an unchanged pass writes nothing. */
+export declare function deriveLinks(db: CanvasDb, owner: ObjectRow, doc: ObjectRow, body: string): Promise<void>;
+export declare function convergeFile(db: CanvasDb, owner: ObjectRow, file: PackageFile, report: PackageReconcileReport, reposFn: ReposFn): Promise<string>;
+export declare function deleteMissing(db: CanvasDb, owner: ObjectRow, keep: ReadonlySet<string>, report: PackageReconcileReport, reposFn: ReposFn): Promise<void>;