@north-light/api 0.3.580 → 0.3.588

package/dist/core/graph/package-docs.js

@@ -0,0 +1,198 @@
+/** Package documents: builtin (`crtr`) and plugin documents stay files in their package; this
+ *  converges their `objects`/`documents` rows, their one revision and their rules onto those
+ *  files (contract §6.6). The parsed text goes into the `bodies` table with the revision that names it, so every reader
+ *  gets it from the database; `documents.source_path` is provenance and the shipped marker, and no reader opens it.
+ *  A plugin is an app: its documents belong to the app `<plugin>` (identity `app:<plugin>`,
+ *  the one `ownerForGrantee` gives), and a document with a `source_path` is shipped. */
+import { randomUUID } from 'node:crypto';
+import { CrtrError } from '../errors.js';
+import { emitEvent } from '../events/emit.js';
+import { quarantineBrokenPlugins } from '../plugin-quarantine.js';
+import { listInstalledPlugins } from '../resolver.js';
+import { builtinMemoryRoot, pluginMemoryDir } from '../scope.js';
+import { documentFields } from '../../migrations/004-canvas-documents/fields.js';
+import { put as putBody } from './bodies.js';
+import { applyDocumentFields, deleteDocument, documentRecord, heads, importDocument, linksIn, moveDocument } from './documents.js';
+import { deleteShippedReader, writeShippedReader } from '../permissions/facts.js';
+import { setLinks } from './edges.js';
+import { publish } from './events.js';
+import { resolveName } from './names.js';
+import { packageFiles } from './package-files.js';
+import { ensureOwner, getById, setObjectKind } from './objects.js';
+import { checkoutsForCwd } from './repo-sync/repos.js';
+import { rulesOf } from './rules.js';
+/** The builtin corpus (app `crtr`), then every enabled user-scope plugin's `memory/` folder. */
+export function packageSources() {
+    return [
+        { plugin: 'crtr', dir: builtinMemoryRoot() },
+        ...listInstalledPlugins('user').filter((p) => p.enabled).map((p) => ({ plugin: p.name, dir: pluginMemoryDir(p) })),
+    ];
+}
+/** 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 async function reconcilePackageDocuments(db, explicitSources) {
+    const report = { created: 0, updated: 0, deleted: 0, conflicts: [], invalid: [], quarantined: [] };
+    // One damaged plugin directory (a 0-byte manifest from an interrupted write) is set aside, never fatal.
+    // Only the real installed set is swept; a caller passing its own sources has no plugins directory here.
+    if (explicitSources === undefined) {
+        report.quarantined = quarantineBrokenPlugins();
+        for (const q of report.quarantined) {
+            emitEvent({ level: 'error', event: 'daemon.plugins.quarantined', fields: { plugin: q.name, file: q.file, reason: q.reason, ...(q.movedTo !== undefined ? { moved_to: q.movedTo } : {}) } });
+        }
+    }
+    const sources = explicitSources ?? packageSources();
+    const reposFn = async (cwd) => await checkoutsForCwd(db, cwd);
+    const reconciled = new Set();
+    const converged = [];
+    const names = new Set();
+    for (const source of sources) {
+        let owner;
+        try {
+            if (names.has(source.plugin))
+                throw new CrtrError('conflict', `plugin "${source.plugin}" is already provided by another package`);
+            names.add(source.plugin);
+            owner = await ensureOwner(db, 'app', 'app', `app:${source.plugin}`, source.plugin);
+        }
+        catch (error) {
+            if (!(error instanceof CrtrError) || error.code !== 'conflict')
+                throw error;
+            report.conflicts.push({ plugin: source.plugin, message: error.message });
+            continue;
+        }
+        reconciled.add(owner.id);
+        const { files, invalid } = packageFiles(source.dir);
+        report.invalid.push(...invalid);
+        const seen = new Set();
+        for (const file of files) {
+            const id = await convergeFile(db, owner, file, report, reposFn);
+            seen.add(id);
+            converged.push({ owner, id, body: file.body });
+        }
+        await deleteMissing(db, owner, seen, report, reposFn);
+    }
+    // A plugin no longer installed (or disabled) keeps its app and the app's other objects;
+    // only its shipped documents are deleted.
+    const stale = await db.prepare(`SELECT DISTINCT o.owner AS id FROM objects o JOIN documents d ON d.object = o.id
+    WHERE o.type = 'document' AND o.deleted_at IS NULL AND d.source_path IS NOT NULL`).all();
+    for (const { id } of stale) {
+        if (!reconciled.has(id))
+            await deleteMissing(db, (await getById(db, id)), new Set(), report, reposFn);
+    }
+    // Links resolve only after every package's documents are in place, so a link to a document
+    // another package ships, or one reconciled later in this pass, still attaches.
+    for (const { owner, id, body } of converged)
+        await deriveLinks(db, owner, (await getById(db, id)), body);
+    return report;
+}
+/** 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 async function deriveLinks(db, owner, doc, body) {
+    if (doc.deleted_at !== null)
+        return;
+    const reader = { class: 'app', app: owner, scopes: [] };
+    const links = [];
+    for (const name of linksIn(body)) {
+        const hit = await resolveName(db, reader, name);
+        if ('object' in hit && hit.object.id !== doc.id && await shippedDocument(db, hit.object.id))
+            links.push({ written_as: name, dst: hit.object });
+    }
+    const key = (rows) => JSON.stringify(rows.map((r) => [r.dst, r.written_as]).sort());
+    const current = await db.prepare(`SELECT dst, written_as FROM edges WHERE type = 'links-to' AND src = ?`)
+        .all(doc.id);
+    if (key(current) === key(links.map((l) => ({ dst: l.dst.id, written_as: l.written_as }))))
+        return;
+    await setLinks(db, doc, links);
+}
+/** Whether the object is a live shipped document (its `documents.source_path` is set). */
+async function shippedDocument(db, id) {
+    return await db.prepare('SELECT 1 FROM documents WHERE object = ? AND source_path IS NOT NULL').get(id) !== undefined;
+}
+export async function convergeFile(db, owner, file, report, reposFn) {
+    const f = documentFields(file.frontmatter, file.body, { missingPrivacy: 'public' });
+    const fields = {
+        preview: f.preview.trim() === '' ? file.name : f.preview, summary: f.summary, whyItExists: f.whyItExists,
+        unlisted: f.unlisted, rules: f.rules,
+        lintIgnore: Array.isArray(f.lintIgnore) ? f.lintIgnore.filter((x) => typeof x === 'string') : null,
+        extensions: f.extensions !== null && typeof f.extensions === 'object' && !Array.isArray(f.extensions)
+            ? f.extensions : null,
+    };
+    // Also for a document whose text is unchanged: a row missing from `bodies` (a database that never had it) heals here.
+    const hash = await putBody(db, file.body);
+    // Identity is (owner app, name), so a package whose files moved (a new runtime generation, a pod's own disk) keeps its documents.
+    // Only a document the file's name no longer reaches (renamed in its frontmatter) is found by its `source_path`.
+    let existing = await db.prepare(`SELECT o.* FROM objects o JOIN documents d ON d.object = o.id
+    WHERE o.type = 'document' AND o.owner = ? AND o.deleted_at IS NULL AND o.name = ? AND d.source_path IS NOT NULL`)
+        .get(owner.id, file.name);
+    if (!existing) {
+        existing = await db.prepare(`SELECT o.* FROM objects o JOIN documents d ON d.object = o.id
+      WHERE o.type = 'document' AND o.owner = ? AND o.deleted_at IS NULL AND d.source_path = ?`)
+            .get(owner.id, file.path);
+    }
+    else {
+        await db.prepare('UPDATE documents SET source_path = ? WHERE object = ? AND source_path IS DISTINCT FROM ?').run(file.path, existing.id, file.path);
+    }
+    if (!existing) {
+        const doc = await importDocument(db, {
+            owner, name: file.name, kind: f.kind, privacy: 'public', ...fields,
+            revisions: [{ body_hash: hash, author: owner, rationale: null, created_at: new Date().toISOString() }],
+        });
+        await db.prepare('UPDATE documents SET source_path = ? WHERE object = ?').run(file.path, doc.id);
+        await writeShippedReader(db, doc.id);
+        report.created += 1;
+        return doc.id;
+    }
+    const renamed = existing.name !== file.name || existing.kind !== f.kind;
+    if (existing.name !== file.name)
+        existing = await moveDocument(db, null, existing, { name: file.name });
+    if (existing.kind !== f.kind) {
+        await setObjectKind(db, existing, f.kind);
+        existing = (await getById(db, existing.id));
+    }
+    const record = await documentRecord(db, existing);
+    const [head] = await heads(db, existing);
+    const bodyChanged = head?.body_hash !== hash;
+    const fieldsChanged = existing.preview !== fields.preview || record.summary !== fields.summary
+        || record.why_it_exists !== fields.whyItExists || record.unlisted !== fields.unlisted
+        || JSON.stringify(record.lint_ignore) !== JSON.stringify(fields.lintIgnore)
+        || JSON.stringify(record.extensions) !== JSON.stringify(fields.extensions)
+        || JSON.stringify((await rulesOf(db, existing)).map(ruleKey)) !== JSON.stringify(fields.rules.map(ruleKey));
+    if (!bodyChanged && !fieldsChanged && !renamed)
+        return existing.id;
+    const doc = await applyDocumentFields(db, existing, fields);
+    if (bodyChanged && head) {
+        const revId = randomUUID();
+        const number = head.number + 1;
+        // `rev_id` is the key `revision_parents` references, so the head is replaced by a new row that takes over its parents.
+        await db.prepare(`INSERT INTO revisions (rev_id, document, number, body_hash, author, rationale, verbatim, created_at)
+      SELECT ?, document, ?, ?, author, rationale, verbatim, ? FROM revisions WHERE rev_id = ?`)
+            .run(revId, number, hash, new Date().toISOString(), head.rev_id);
+        await db.prepare('INSERT INTO revision_parents (child, parent) SELECT ?, parent FROM revision_parents WHERE child = ?').run(revId, head.rev_id);
+        await db.prepare('DELETE FROM revisions WHERE rev_id = ?').run(head.rev_id);
+        await db.prepare('UPDATE documents SET heads_key = ?, revision = ? WHERE object = ?').run(revId, number, doc.id);
+        await publish(db, { event: 'edited', object: doc, actor: owner, pointer: revId,
+            attrs: { revision: number, from_revision: head.number, rationale: 'package file changed' } }, reposFn);
+    }
+    report.updated += 1;
+    return doc.id;
+}
+/** A rule in a fixed key order, for change detection. */
+function ruleKey(rule) {
+    return [rule.on, rule.deliver, rule.match ?? null, rule.matchFrontmatter ?? null, rule.if ?? null];
+}
+export async function deleteMissing(db, owner, keep, report, reposFn) {
+    const live = await db.prepare(`SELECT o.* FROM objects o JOIN documents d ON d.object = o.id
+    WHERE o.type = 'document' AND o.owner = ? AND o.deleted_at IS NULL AND d.source_path IS NOT NULL`).all(owner.id);
+    for (const doc of live) {
+        if (keep.has(doc.id))
+            continue;
+        await deleteDocument(db, null, doc, reposFn);
+        await deleteShippedReader(db, doc.id);
+        report.deleted += 1;
+    }
+}

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

@@ -0,0 +1,20 @@
+/** One markdown file of a package's `memory/` folder. */
+export interface PackageFile {
+    /** owner-local document name; a package root `INDEX.md` is `index` */
+    name: string;
+    path: string;
+    frontmatter: Record<string, unknown> | null;
+    body: string;
+}
+/** The documents of one package folder, sorted by name. A file whose frontmatter does not parse,
+ *  or whose name another file already holds, is returned in `invalid` and is not a document. */
+export declare function packageFiles(dir: string): {
+    files: PackageFile[];
+    invalid: Array<{
+        path: string;
+        error: string;
+    }>;
+};
+/** Strict frontmatter check a plugin package's documents must pass before the
+ *  package installs. */
+export declare function lintPackageFrontmatter(fm: Record<string, unknown> | null): string | null;

package/dist/core/graph/package-files.js

@@ -0,0 +1,146 @@
+/** The documents of a package's `memory/` folder, read from its files. Filesystem only — CLI
+ *  listings (`pkg plugin inspect`, the plugin browser) and the daemon's reconcile share it. */
+import { readFileSync } from 'node:fs';
+import { relative, sep } from 'node:path';
+import { parseFrontmatterGeneric } from '../frontmatter.js';
+import { pathExists, walkFiles } from '../fs-utils.js';
+import { readLegacyPrivacy } from './types.js';
+import { explicitLocalName, isDocKind, localNameFromPath, representationForPath } from '../substrate/schema.js';
+/** The documents of one package folder, sorted by name. A file whose frontmatter does not parse,
+ *  or whose name another file already holds, is returned in `invalid` and is not a document. */
+export function packageFiles(dir) {
+    const invalid = [];
+    if (!pathExists(dir))
+        return { files: [], invalid };
+    const byName = new Map();
+    for (const path of walkFiles(dir, (n) => n.endsWith('.md') && n !== 'SKILL.md', (d) => d === '.crouter' || d.startsWith('.')).sort()) {
+        const rel = relative(dir, path).split(sep).join('/');
+        let parsed;
+        try {
+            parsed = parseFrontmatterGeneric(readFileSync(path, 'utf8'));
+        }
+        catch (error) {
+            invalid.push({ path, error: `invalid frontmatter: ${(error instanceof Error ? error.message : String(error)).split('\n')[0]}` });
+            continue;
+        }
+        const local = localNameFromPath(rel) === '' ? '' : explicitLocalName(parsed.data) ?? localNameFromPath(rel);
+        const name = local === '' ? 'index' : local;
+        const file = { name, path, frontmatter: parsed.data, body: parsed.body, index: representationForPath(rel) === 'directory-index' };
+        const held = byName.get(name);
+        if (held && (held.index || !file.index)) {
+            invalid.push({ path, error: `name ${name} is already held by ${held.path}` });
+            continue;
+        }
+        if (held)
+            invalid.push({ path: held.path, error: `name ${name} is already held by ${path}` });
+        byName.set(name, file);
+    }
+    const files = [...byName.values()].map(({ index: _index, ...f }) => f).sort((a, b) => a.name.localeCompare(b.name));
+    return { files, invalid };
+}
+// Package preflight — the frontmatter a package document must carry.
+const PRIVACY_LEVELS = ['public', 'private'];
+const SURFACE_EVENTS = ['boot', 'workspace-open', 'read', 'memory-read', 'command', 'pre-command'];
+const SURFACE_RUNGS = ['name', 'preview', 'content'];
+const RETIRED_FIELDS = ['system-prompt-visibility', 'file-read-visibility', 'applies-to', 'read-when'];
+const SURFACE_ENTRY_KEYS = ['on', 'match', 'match-frontmatter', 'gate', 'at'];
+const SUPPRESSIBLE_RULES = ['length', 'broad-memory-read', 'orphan'];
+/** Strict validation of one raw routing entry. Package preflight refuses
+ * what import would silently drop. */
+function lintPackageSurfaces(value) {
+    if (value === undefined)
+        return null;
+    if (!Array.isArray(value))
+        return `invalid surfaces: ${JSON.stringify(value)} (expected a list of {on, at, match?, match-frontmatter?, gate?} entries)`;
+    for (const raw of value) {
+        if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) {
+            return `invalid surfaces entry: ${JSON.stringify(raw)} (expected an {on, at, match?, match-frontmatter?, gate?} object)`;
+        }
+        const entry = raw;
+        for (const key of Object.keys(entry)) {
+            if (!SURFACE_ENTRY_KEYS.includes(key)) {
+                return `invalid surfaces entry: unknown key \`${key}\` (an entry carries only on, match, match-frontmatter, gate, at)`;
+            }
+        }
+        const on = entry['on'];
+        if (typeof on !== 'string' || !SURFACE_EVENTS.includes(on)) {
+            return `invalid surfaces entry \`on\`: ${JSON.stringify(on)} (expected ${SURFACE_EVENTS.join('|')})`;
+        }
+        const at = entry['at'];
+        if (typeof at !== 'string' || !SURFACE_RUNGS.includes(at)) {
+            return `invalid surfaces entry \`at\`: ${JSON.stringify(at)} (expected ${SURFACE_RUNGS.join('|')})`;
+        }
+        let hasMatch = false;
+        if (entry['match'] !== undefined) {
+            if (on === 'boot' || on === 'workspace-open') {
+                return `invalid surfaces entry: \`match\` is meaningless on \`${on}\` — the entry's presence is the match; drop it`;
+            }
+            const match = entry['match'];
+            const globs = typeof match === 'string' ? [match] : Array.isArray(match) && match.every((glob) => typeof glob === 'string') ? match : null;
+            if (globs === null || globs.length === 0 || globs.some((glob) => glob.trim() === '')) {
+                return `invalid surfaces entry \`match\`: ${JSON.stringify(match)} (expected a non-empty glob or non-empty glob list)`;
+            }
+            hasMatch = true;
+        }
+        const matchFrontmatter = entry['match-frontmatter'];
+        if (matchFrontmatter !== undefined) {
+            if (on !== 'read')
+                return 'invalid surfaces entry: `match-frontmatter` is a `read`-event predicate only';
+            if (matchFrontmatter === null || typeof matchFrontmatter !== 'object' || Array.isArray(matchFrontmatter)) {
+                return `invalid surfaces entry \`match-frontmatter\`: ${JSON.stringify(matchFrontmatter)} (expected a field→matcher object)`;
+            }
+        }
+        if ((on === 'read' || on === 'memory-read' || on === 'command' || on === 'pre-command') && !hasMatch && matchFrontmatter === undefined) {
+            return `invalid surfaces entry: a \`${on}\` entry requires \`match\`${on === 'read' ? ' or `match-frontmatter`' : ''}`;
+        }
+        const gate = entry['gate'];
+        if (gate !== undefined && (gate === null || typeof gate !== 'object' || Array.isArray(gate))) {
+            return `invalid surfaces entry \`gate\`: ${JSON.stringify(gate)} (expected a field→matcher object)`;
+        }
+    }
+    return null;
+}
+/** Strict frontmatter check a plugin package's documents must pass before the
+ *  package installs. */
+export function lintPackageFrontmatter(fm) {
+    if (fm === null)
+        return 'missing frontmatter: a package document requires `kind: knowledge|preference`';
+    if (!isDocKind(fm.kind))
+        return `invalid kind: ${JSON.stringify(fm.kind)} (expected knowledge|preference)`;
+    if ('when' in fm || 'why' in fm) {
+        return 'retired `when`/`why` keys: merge them into one `when-and-why-to-read` line — "When <circumstance>, this <kind> should be read because <broader downstream payoff>." WHY is the benefit unlocked by reading, not the document summary, rule, or obedience rationale.';
+    }
+    if (typeof fm['when-and-why-to-read'] !== 'string' || fm['when-and-why-to-read'].trim() === '') {
+        return 'missing `when-and-why-to-read`: one routing line — "When <circumstance>, this <kind> should be read because <broader downstream payoff>." WHY is the benefit unlocked by reading, not the document summary, rule, or obedience rationale.';
+    }
+    for (const field of RETIRED_FIELDS) {
+        if (field in fm) {
+            return `retired \`${field}\` key: a package document no longer carries it; delete it and, to load the document on its own, route it with a \`surfaces\` list of {on: ${SURFACE_EVENTS.join('|')}, at: ${SURFACE_RUNGS.join('|')}, match?, match-frontmatter?, gate?} entries (omit \`surfaces\` for a package document delivered by no rule — read only when pointed at, listed, or searched)`;
+        }
+    }
+    if ('privacy' in fm && !PRIVACY_LEVELS.includes(readLegacyPrivacy(fm['privacy']))) {
+        return `invalid privacy: ${JSON.stringify(fm['privacy'])} (expected ${PRIVACY_LEVELS.join('|')})`;
+    }
+    if (fm['unlisted'] !== undefined && typeof fm['unlisted'] !== 'boolean') {
+        return `invalid unlisted: ${JSON.stringify(fm['unlisted'])} (expected a boolean)`;
+    }
+    const surfacesError = lintPackageSurfaces(fm['surfaces']);
+    if (surfacesError !== null)
+        return surfacesError;
+    if (fm.gate !== undefined && (fm.gate === null || typeof fm.gate !== 'object' || Array.isArray(fm.gate))) {
+        return `invalid gate: ${JSON.stringify(fm.gate)} (expected a field→matcher object)`;
+    }
+    if (fm.slash !== undefined && typeof fm.slash !== 'boolean') {
+        return `invalid slash: ${JSON.stringify(fm.slash)} (expected a boolean)`;
+    }
+    if (fm.rationale !== undefined && typeof fm.rationale !== 'string') {
+        return `invalid rationale: ${JSON.stringify(fm.rationale)} (expected a string)`;
+    }
+    if (fm['lint-ignore'] !== undefined) {
+        const rules = Array.isArray(fm['lint-ignore']) ? fm['lint-ignore'] : [fm['lint-ignore']];
+        if (rules.length === 0 || !rules.every((rule) => typeof rule === 'string' && SUPPRESSIBLE_RULES.includes(rule))) {
+            return `invalid lint-ignore: ${JSON.stringify(fm['lint-ignore'])} (suppressible rules: ${SUPPRESSIBLE_RULES.map((rule) => `\`${rule}\``).join(', ')})`;
+        }
+    }
+    return null;
+}

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

@@ -0,0 +1,22 @@
+import type { CanvasDb } from '../canvas/db.js';
+export interface KindsReport {
+    /** every kind a valid plugin declares that now has its row, and what upserting it did */
+    applied: Array<{
+        plugin: string;
+        kind: string;
+        outcome: 'inserted' | 'updated' | 'unchanged';
+    }>;
+    /** kinds another owner holds; the plugin's other kinds still applied */
+    refused: Array<{
+        plugin: string;
+        kind: string;
+        code: 'kind_owned';
+        message: string;
+    }>;
+    /** enabled plugins whose manifest or commands are invalid (no kind update, no token); a provider bundle's kinds reconcile without a token, and plugins whose app handle another owner holds */
+    invalid: Array<{
+        plugin: string;
+        error: string;
+    }>;
+}
+export declare function reconcilePackageKinds(db: CanvasDb): Promise<KindsReport>;

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

@@ -0,0 +1,49 @@
+/** Installed plugins' `object_kinds` blocks → `object_kinds` rows. Runs in the caller's write transaction.
+ *  A kind is never deleted and its catalog is never altered when undeclared: only `declared` flips, so the
+ *  instances of a dropped kind go inert instead of vanishing. */
+import { CrtrError } from '../errors.js';
+import { invalidAppPlugins, kindPlugins } from '../plugin-app.js';
+import { upsertKind } from './custom.js';
+import { ensureOwner } from './objects.js';
+export async function reconcilePackageKinds(db) {
+    const report = { applied: [], refused: [], invalid: invalidAppPlugins().map((i) => ({ plugin: i.plugin.name, error: i.error })) };
+    const declared = new Set();
+    for (const plugin of kindPlugins()) {
+        const kinds = Object.entries(plugin.manifest.object_kinds ?? {});
+        if (kinds.length === 0)
+            continue;
+        let owner;
+        try {
+            owner = await ensureOwner(db, 'app', 'app', `app:${plugin.name}`, plugin.name);
+        }
+        catch (error) {
+            if (!(error instanceof CrtrError) || error.code !== 'conflict')
+                throw error;
+            report.invalid.push({ plugin: plugin.name, error: error.message });
+            continue;
+        }
+        for (const [kind, decl] of kinds) {
+            try {
+                const result = await upsertKind(db, {
+                    name: kind, owner, description: decl.description, events: decl.events,
+                    read: decl.read === undefined ? null : { command: decl.read.command }, source: 'manifest',
+                });
+                if (result.outcome === 'skipped')
+                    continue;
+                declared.add(kind);
+                report.applied.push({ plugin: plugin.name, kind, outcome: result.outcome });
+            }
+            catch (error) {
+                if (!(error instanceof CrtrError) || error.code !== 'kind_owned')
+                    throw error;
+                report.refused.push({ plugin: plugin.name, kind, code: 'kind_owned', message: error.message });
+            }
+        }
+    }
+    const rows = await db.prepare("SELECT name FROM object_kinds WHERE source = 'manifest' AND declared = 1").all();
+    for (const { name } of rows) {
+        if (!declared.has(name))
+            await db.prepare('UPDATE object_kinds SET declared = 0 WHERE name = ?').run(name);
+    }
+    return report;
+}

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

@@ -0,0 +1,17 @@
+import { type KindsReport } from './package-kinds.js';
+import { type PackageReconcileReport } from './package-docs.js';
+import type { CanvasDb } from '../canvas/db.js';
+export interface TokensReport {
+    /** plugins holding a `crtr_app_` token, with the manifest scopes it carries */
+    granted: Array<{
+        plugin: string;
+        scopes: string[];
+    }>;
+    /** plugins whose `crtr_app_` token was removed because they no longer qualify */
+    revoked: string[];
+}
+export interface PackagesReport extends PackageReconcileReport {
+    kinds: KindsReport;
+    tokens: TokensReport;
+}
+export declare function reconcilePackages(db: CanvasDb): Promise<PackagesReport>;

package/dist/core/graph/package-reconcile.js

@@ -0,0 +1,31 @@
+/** The one package reconcile pass: documents, then kinds, then plugin app tokens. Runs in the caller's write
+ *  transaction. The token writes go to the secrets store and are idempotent, so a rolled-back pass re-converges
+ *  on the next one. */
+import { appPlugins } from '../plugin-app.js';
+import { ensurePluginAppToken, listScopedApiTokens, revokePluginAppTokens } from '../secrets.js';
+import { reconcilePackageKinds } from './package-kinds.js';
+import { reconcilePackageDocuments } from './package-docs.js';
+export async function reconcilePackages(db) {
+    const documents = await reconcilePackageDocuments(db);
+    const kinds = await reconcilePackageKinds(db);
+    const tokens = { granted: [], revoked: [] };
+    const holders = new Set();
+    for (const plugin of appPlugins()) {
+        const scopes = plugin.manifest.scopes ?? [];
+        ensurePluginAppToken(plugin.name, scopes);
+        holders.add(plugin.name);
+        tokens.granted.push({ plugin: plugin.name, scopes: [...scopes] });
+    }
+    const stale = new Set();
+    for (const entry of listScopedApiTokens('user')) {
+        if (!entry.token.startsWith('crtr_app_') || !entry.grantee.startsWith('app:'))
+            continue;
+        const plugin = entry.grantee.slice('app:'.length);
+        if (!holders.has(plugin))
+            stale.add(plugin);
+    }
+    for (const plugin of stale)
+        if (revokePluginAppTokens(plugin))
+            tokens.revoked.push(plugin);
+    return { ...documents, kinds, tokens };
+}

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

@@ -0,0 +1,45 @@
+import type { RequestPrincipal } from '../../daemon/api/router.js';
+import { type ActiveGrant } from '../grants/mirror.js';
+import { type CanvasDb } from '../canvas/db.js';
+import type { Checkout, ObjectRow, Reader } from './types.js';
+/** The repos enclosing a directory, with their checkout roots, nearest first. */
+export type ReposFn = (cwd: string) => Promise<Checkout[]>;
+/** A node's view of repos: the ones enclosing its cwd, then those of each project path of its profile
+ *  (manifest order), each repo once. A project path that no longer exists, is not in a repo, or has no
+ *  work tree (a bare repository) contributes nothing. */
+export declare function viewRepos(cwd: string, profileId: string | null, reposFn: ReposFn, lookups: Pick<ReaderLookups, 'projectPaths'>): Promise<Pick<Extract<Reader, {
+    class: 'node';
+}>, 'repos' | 'checkouts' | 'projectRepos' | 'projectCheckouts'>>;
+/** Run the git lookups a node's reader needs (its cwd and its profile's project paths) now, before a canvas write opens, so
+ *  `viewRepos` inside the write hits the identity cache instead of spawning git while the write holds a pooled connection. */
+export declare function warmNodeRepos(db: CanvasDb, nodeId: string): Promise<void>;
+export declare function readerFor(db: CanvasDb, principal: RequestPrincipal, reposFn: ReposFn): Promise<Exclude<Reader, {
+    class: 'object';
+}>>;
+export declare function readerForNode(db: CanvasDb, nodeId: string, reposFn: ReposFn, lookups?: ReaderLookups, allowRevoked?: boolean): Promise<Extract<Reader, {
+    class: 'node';
+}>>;
+/** A receiving object reads using its owner's app grant, not its registering caller's rights. */
+export declare function readerForObject(db: CanvasDb, watcher: ObjectRow, reposFn?: ReposFn, lookups?: ReaderLookups): Promise<Extract<Reader, {
+    class: 'node' | 'object';
+}>>;
+/** The scopes `app` (an app object) holds now: its one active grant's always-scopes, or a local plugin's `crtr_app_` token scopes when it has no
+ *  grant; null for several grants or none that applies. The same rule as an app-owned object's reader (`readerForObject`). */
+export declare function appScopesNow(db: CanvasDb, app: ObjectRow, lookups: ReaderLookups): Promise<readonly string[] | null>;
+/** What building a node reader looks up besides the node's own row. `liveLookups` reads each
+ *  one per call; `publishLookups` memoizes them for one publish inside its transaction, so the
+ *  readers of one event share a single config read and one lookup per grant, owner and
+ *  profile. Never keep a memoized one past that transaction. */
+export interface ReaderLookups {
+    grantById(grantId: string): Promise<ActiveGrant | null>;
+    grantFor(app: string, sub: string): Promise<ActiveGrant | null>;
+    /** The scopes of the `crtr_app_` token a local plugin's app (`app:<plugin>`) holds, or null when it holds none. */
+    pluginScopes(grantee: string): readonly string[] | null;
+    object(id: string): Promise<ObjectRow | null>;
+    profile(profileId: string, app: ObjectRow): Promise<ObjectRow>;
+    /** The profile's project paths in manifest order; none in a sandboxed node, whose profile store is unreadable. */
+    projectPaths(profileId: string): readonly string[];
+}
+export declare function liveLookups(db: CanvasDb): ReaderLookups;
+export declare function publishLookups(db: CanvasDb): ReaderLookups;
+export declare function profileObject(db: CanvasDb, profileId: string, app: ObjectRow): Promise<ObjectRow>;