@north-light/cli 0.0.0 → 0.3.414

package/dist/core/graph/documents.js

@@ -0,0 +1,10 @@
+var te=Object.defineProperty;var a=(t,n)=>te(t,"name",{value:n,configurable:!0});import{prepared as c}from"../sqlite-statements.js";import{randomUUID as ne}from"node:crypto";import{CrtrError as k,notFound as R,usage as l}from"../errors.js";import{ExitCode as A}from"../../types.js";import{canChange as L,canRead as F,ownerChain as re}from"./access.js";import{bodyOf as oe,get as ie,put as J}from"./bodies.js";import{recordActedOn as N,setLinks as se}from"./edges.js";import{publish as O}from"./events.js";import{resolveName as ae}from"./names.js";import{createObject as ue,getById as ce,getByRowid as f}from"./objects.js";import{replaceRules as B,setRulesOwner as le}from"./rules.js";import{recordWatch as $}from"./watches.js";function _(t){return t.class==="node"?t.node:t.class==="app"?t.app:t.class==="object"?t.object:t.person}a(_,"actorOf");let me=0;function E(t,n){const e=`graph_doc_${++me}`;t.exec(`SAVEPOINT ${e}`);try{const o=n();return t.exec(`RELEASE ${e}`),o}catch(o){throw t.exec(`ROLLBACK TO ${e}`),t.exec(`RELEASE ${e}`),o}}a(E,"atomic");function de(t,n){return new k("conflict",t,A.GENERAL,n)}a(de,"conflict");function y(t){if(t.type!=="document")throw l(`${t.type} ${t.id} is not a document`)}a(y,"assertDocument");function P(t,n){const e=re(t,n);return(e.length?e[e.length-1]:n).type}a(P,"spaceType");function I(t,n,e){if(e!=="public"&&P(t,n)==="repo")throw l(`a repo owns only public documents; ${n.name} cannot own a ${e} one`,{rule:"repo-public-only",next:"Write it as public, or give it another owner (your own documents can carry `if: {repo: <handle>}`)."})}a(I,"assertPublicInRepo");function K(t,n,e,o){if(e.trim()===""||e!==e.trim())throw l(`invalid document name ${JSON.stringify(e)}`);const r=c(t,"SELECT id FROM objects WHERE (type = 'document' OR instr(type, '.') > 0) AND owner = ? AND name = ? AND deleted_at IS NULL").get(n.rowid,e);if(r&&r.id!==o?.id)throw de(`${n.name} already has a document named ${e}`,{name:e,holder:r.id})}a(K,"assertNameFree");function H(t,n,e){if(!F(t,n,e))throw R(`no document ${e.id}`)}a(H,"readable");function D(t,n,e){if(H(t,n,e),!L(t,n,e))throw new k("forbidden",`you cannot change ${e.name}`,A.GENERAL,{id:e.id})}a(D,"changeable");function G(t,n){const e=c(t,`SELECT p.rev_id FROM revision_parents rp JOIN revisions p ON p.rowid = rp.parent
+    WHERE rp.child = ? ORDER BY p.rev_id`).all(n.rowid);return{rowid:n.rowid,rev_id:n.rev_id,number:n.number,body_hash:n.body_hash,author:n.author===null?null:f(t,n.author)?.id??null,rationale:n.rationale,verbatim:n.verbatim===1,created_at:n.created_at,parents:e.map(o=>o.rev_id)}}a(G,"toRevision");function C(t,n){return c(t,`SELECT * FROM revisions r WHERE r.document = ?
+    AND NOT EXISTS (SELECT 1 FROM revision_parents p WHERE p.parent = r.rowid) ORDER BY r.number DESC, r.rev_id`).all(n.rowid).map(o=>G(t,o))}a(C,"heads");function pe(t){return t.map(n=>n.rev_id).sort().join(",")}a(pe,"headsKeyOf");function x(t,n){const e=c(t,"SELECT * FROM documents WHERE object = ?").get(n.rowid);if(!e)throw R(`no document record for ${n.id}`);return{summary:e.summary,heads_key:e.heads_key,revision:e.revision,why_it_exists:e.why_it_exists,unlisted:e.unlisted===1,lint_ignore:e.lint_ignore_json===null?null:JSON.parse(e.lint_ignore_json),extensions:e.extensions_json===null?null:JSON.parse(e.extensions_json),source_path:e.source_path}}a(x,"documentRecord");function T(t,n,e){const o=c(t,`INSERT INTO revisions (document, rev_id, number, body_hash, author, rationale, verbatim, created_at)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?) RETURNING *`).get(n.rowid,e.rev_id??ne(),e.number,e.body_hash,e.author?.rowid??null,e.rationale,e.verbatim?1:0,e.created_at??new Date().toISOString()),r=c(t,"INSERT INTO revision_parents (child, parent) VALUES (?, ?)");for(const i of e.parents)r.run(o.rowid,i);return o}a(T,"insertRevision");function we(t){const n=new Set;for(const e of t.matchAll(/\[\[([^[\]\n]+?)\]\]/g))n.add(e[1].trim());return[...n]}a(we,"linksIn");function V(t,n,e,o){const r=[],i=[];for(const u of we(o)){const s=ae(t,n,u);"object"in s?r.push({written_as:u,dst:s.object}):"deleted"in s?r.push({written_as:u,dst:s.deleted}):"remote"in s||i.push(u)}return Z(t,se(t,e,r)),i}a(V,"setRevisionLinks");function fe(t,n,e){return n.type==="node"?n.id:c(t,`SELECT 1 FROM objects o JOIN objects d ON d.owner = o.rowid
+    WHERE o.name = ? AND o.type <> ? AND o.type IN ('person','app','repo','profile')
+      AND d.type = 'document' AND d.name = ? AND d.deleted_at IS NULL LIMIT 1`).get(n.name,n.type,e)?`${n.type}:${n.name}`:n.name}a(fe,"ownerPrefix");function Y(t,n,e){const o=c(t,`SELECT e.written_as, o.* FROM edges e JOIN objects o ON o.rowid = e.dst
+    WHERE e.type = 'links-to' AND e.src = ? AND e.written_as IS NOT NULL`).all(n.rowid);if(o.length===0)return e;const r=new Map;for(const i of o){if(i.deleted_at||i.written_as===i.id)continue;const u=!i.written_as.includes("/");if(u&&i.name===i.written_as)continue;const s=i.owner===null?null:f(t,i.owner),m=s?`${fe(t,s,i.name)}/${i.name}`:i.name,d=u&&i.owner===n.owner?i.name:m;d!==i.written_as&&r.set(i.written_as,d)}return r.size===0?e:e.replace(/\[\[([^[\]\n]+?)\]\]/g,(i,u)=>{const s=r.get(u.trim());return s===void 0?i:`[[${s}]]`})}a(Y,"withCurrentNames");function W(t,n,e){if(e.preview!==void 0){if(e.preview.trim()==="")throw l("a document needs a preview",{field:"preview"});c(t,"UPDATE objects SET preview = ? WHERE rowid = ?").run(e.preview,n.rowid)}e.privacy!==void 0&&(I(t,f(t,n.owner),e.privacy),c(t,"UPDATE objects SET privacy = ? WHERE rowid = ?").run(e.privacy,n.rowid));const o=a((i,u)=>t.prepare(`UPDATE documents SET ${i} = ? WHERE object = ?`).run(u,n.rowid),"set");e.summary!==void 0&&o("summary",e.summary),e.whyItExists!==void 0&&o("why_it_exists",e.whyItExists),e.unlisted!==void 0&&o("unlisted",e.unlisted?1:0),e.lintIgnore!==void 0&&o("lint_ignore_json",e.lintIgnore===null?null:JSON.stringify(e.lintIgnore)),e.extensions!==void 0&&o("extensions_json",e.extensions===null?null:JSON.stringify(e.extensions));const r=f(t,n.rowid);return e.rules!==void 0&&B(t,r,e.rules),r}a(W,"applyDocumentFields");function X(t,n){if(n.owner.deleted_at)throw l(`${n.owner.name} is deleted`);if(n.preview.trim()==="")throw l("a document needs a preview",{field:"preview"});I(t,n.owner,n.privacy),K(t,n.owner,n.name);const e=ue(t,{...n.id?{id:n.id}:{},type:"document",kind:n.kind,owner:n.owner.rowid,privacy:n.privacy,name:n.name,preview:n.preview});return c(t,"INSERT INTO documents (object, heads_key, revision) VALUES (?, '', 0)").run(e.rowid),W(t,e,{...n,preview:void 0,privacy:void 0,rules:n.rules??[]})}a(X,"createDocument");function M(t,n){const e=C(t,n),o=pe(e),r=Math.max(0,...e.map(i=>i.number));return c(t,"UPDATE documents SET heads_key = ?, revision = ? WHERE object = ?").run(o,r,n.rowid),{heads_key:o,revision:r,headCount:e.length}}a(M,"setHeads");function Ae(t,n,e,o,r){const i=J(o);return E(t,()=>{const u=_(n),s=X(t,e),m=T(t,s,{number:1,body_hash:i,author:u,rationale:null,parents:[]}),{heads_key:d}=M(t,s);if(!L(t,n,s))throw R(`no owner ${e.owner.name} you can write to`);const w=V(t,n,s,o);return N(t,u,s),$(t,u,s,"write",{readHeadsKey:d}),O(t,{event:"created",object:s,actor:u,attrs:{revision:1},pointer:m.rev_id},r),{object:s,revision:1,unresolved:w}})}a(Ae,"writeDocument");function Le(t,n,e){return c(t,"SELECT read_heads_key FROM watches WHERE watcher = ? AND object = ?").get(_(n).rowid,e.rowid)?.read_heads_key??null}a(Le,"readBase");function he(t,n){let e=t;for(const[o,{old:r,new:i}]of n.entries()){if(r==="")throw l(`block ${o+1}: a replacement needs non-empty old text`,{field:"replace"});const u=e.indexOf(r);if(u<0)throw l(`block ${o+1}: old text not found: ${JSON.stringify(r.slice(0,120))}`,{field:"replace",old:r});if(e.indexOf(r,u+1)>=0)throw l(`block ${o+1}: old text occurs more than once: ${JSON.stringify(r.slice(0,120))}`,{field:"replace",old:r});e=e.slice(0,u)+i+e.slice(u+r.length)}return e}a(he,"applyReplacements");function $e(t,n,e,o,r,i,u={},s){if(y(e),D(t,n,e),e.deleted_at)throw l(`${e.name} is deleted`);if(i===null)throw new k("read_first",`read ${e.name} before editing it`,A.GENERAL,{id:e.id});if(r.trim()==="")throw l("an edit needs a rationale",{field:"rationale"});const m=x(t,e);if(m.heads_key!==i)return{stale:{heads_key:m.heads_key,revision:m.revision}};const d=C(t,e);let w;if("body"in o)w=o.body;else{if(d.length!==1)throw l(`${e.name} has ${d.length} heads and needs a merge; pass the whole merged body`,{heads:d.length});w=he(Y(t,e,ie(d[0].body_hash)),o.replace)}const p=J(w);try{return E(t,()=>{const h=_(n),g=1+Math.max(0,...d.map(v=>v.number)),U=T(t,e,{number:g,body_hash:p,author:h,rationale:r,verbatim:o.verbatim===!0,parents:d.map(v=>v.rowid)}),j=U.rev_id,b=c(t,"UPDATE documents SET heads_key = ?, revision = ? WHERE object = ? AND heads_key = ?").run(j,g,e.rowid,i);if(Number(b.changes)===0){const v=x(t,e);throw new q(v.heads_key,v.revision)}const S=W(t,e,u),ee=V(t,n,S,w);return N(t,h,S),$(t,h,S,"write",{readHeadsKey:j}),O(t,{event:"edited",object:S,actor:h,pointer:U.rev_id,attrs:{revision:g,from_revision:m.revision,rationale:r}},s),{revision:g,heads_key:j,unresolved:ee}})}catch(h){if(h instanceof q)return{stale:{heads_key:h.heads_key,revision:h.revision}};throw h}}a($e,"editDocument");class q extends Error{static{a(this,"StaleEdit")}heads_key;revision;constructor(n,e){super("stale"),this.heads_key=n,this.revision=e}}function Ie(t,n,e,o){return y(e),n&&D(t,n,e),E(t,()=>{const r=W(t,e,o);return n&&N(t,_(n),r),r})}a(Ie,"setDocumentRecord");function Ee(t,n,e,o){const r=_(n),{heads_key:i}=x(t,e);$(t,r,e,"read",{readHeadsKey:i}),O(t,{event:"read",object:e,actor:r,attrs:{}},o)}a(Ee,"recordRead");function He(t,n,e,o){return y(e),H(t,n,e),E(t,()=>{const r=x(t,e),i=C(t,e).map(s=>({...s,body:Y(t,e,oe(s.body_hash,r.source_path))})),u=c(t,"SELECT dst, written_as FROM edges WHERE type = 'links-to' AND src = ? ORDER BY written_as").all(e.rowid).map(s=>({written_as:s.written_as??"",object:f(t,s.dst)})).filter(s=>s.object&&F(t,n,s.object)).map(s=>({...s,deleted:s.object.deleted_at!==null}));return e.deleted_at||Ee(t,n,e,o),{object:e,record:r,heads:i,needsMerge:i.length>1,links:u}})}a(He,"readDocument");function Ce(t,n,e){return y(e),H(t,n,e),c(t,"SELECT * FROM revisions WHERE document = ? ORDER BY number DESC, created_at DESC, rowid DESC").all(e.rowid).map(r=>G(t,r))}a(Ce,"history");function We(t,n,e,o){if(y(e),e.deleted_at)throw l(`${e.name} is deleted`);return n&&D(t,n,e),E(t,()=>{const r=o.owner??f(t,e.owner),i=o.name??e.name;K(t,r,i,e),I(t,r,e.privacy),c(t,"UPDATE objects SET name = ?, owner = ? WHERE rowid = ?").run(i,r.rowid,e.rowid);const u=f(t,e.rowid);if(r.rowid!==e.owner&&(le(t,u),n&&!L(t,n,u)))throw R(`no owner ${r.name} you can move documents to`);return n&&N(t,_(n),u),u})}a(We,"moveDocument");function Me(t,n,e,o){return y(e),e.deleted_at?e:(n&&D(t,n,e),E(t,()=>{const r=z(t,n,e,o);return Z(t,Q(t,e.rowid),o),r}))}a(Me,"deleteDocument");function z(t,n,e,o){c(t,"UPDATE objects SET deleted_at = ? WHERE rowid = ?").run(new Date().toISOString(),e.rowid);const r=f(t,e.rowid),i=n?_(n):null;return i&&N(t,i,r),O(t,{event:"deleted",object:r,actor:i,attrs:{}},o),c(t,"DELETE FROM watches WHERE object = ?").run(e.rowid),B(t,r,[]),r}a(z,"markDeleted");function Q(t,n){return c(t,"SELECT dst FROM edges WHERE type = 'links-to' AND src = ?").all(n).map(({dst:e})=>e)}a(Q,"linkTargets");function Z(t,n,e){const o=c(t,`SELECT 1 FROM objects d JOIN objects w ON w.rowid = d.owner
+    WHERE d.rowid = ? AND d.type = 'document' AND d.deleted_at IS NULL AND w.deleted_at IS NOT NULL
+      AND NOT EXISTS (SELECT 1 FROM edges e JOIN objects s ON s.rowid = e.src
+        WHERE e.type = 'links-to' AND e.dst = d.rowid AND e.src != d.rowid AND s.deleted_at IS NULL)`),r=[...n];for(;r.length>0;){const i=r.pop();o.get(i)!==void 0&&(z(t,null,f(t,i),e),r.push(...Q(t,i)))}}a(Z,"collectUnlinked");function Ue(t,n){if(n.revisions.length===0)throw l(`import of ${n.name}: no revisions`);return E(t,()=>{const e=X(t,n);c(t,"UPDATE objects SET created_at = ? WHERE rowid = ?").run(n.revisions[0].created_at,e.rowid);let o=null;return n.revisions.forEach((r,i)=>{o=T(t,e,{...r,number:i+1,parents:o===null?[]:[o]}).rowid}),M(t,e),f(t,e.rowid)})}a(Ue,"importDocument");function Fe(t,n,e){if(y(n),n.privacy!=="public"&&P(t,n)==="repo")throw l(`a repo owns only public documents; refusing revisions of ${n.name}`);return E(t,()=>{const o=c(t,"SELECT rowid, number, document FROM revisions WHERE rev_id = ?");let r=e.filter(s=>!o.get(s.rev_id));for(;r.length>0;){const s=[];for(const m of r){const d=m.parents.map(p=>o.get(p));if(d.some(p=>p===void 0)){s.push(m);continue}const w=d;if(w.some(p=>p.document!==n.rowid))throw l(`revision ${m.rev_id} names a parent of another document`);T(t,n,{...m,author:null,number:1+Math.max(0,...w.map(p=>p.number)),parents:w.map(p=>p.rowid)})}if(s.length===r.length)throw l(`revisions of ${n.name} name unknown parents: ${s.map(m=>m.rev_id).join(", ")}`);r=s}const{heads_key:i,headCount:u}=M(t,n);return{heads_key:i,headCount:u}})}a(Fe,"insertImportedRevisions");function Je(t,n){const e=ce(t,n);if(!e||e.type!=="document")throw R(`no document ${n}`);return e}a(Je,"documentById");export{_ as actorOf,W as applyDocumentFields,he as applyReplacements,Z as collectUnlinked,Me as deleteDocument,Je as documentById,x as documentRecord,$e as editDocument,C as heads,Ce as history,Ue as importDocument,Fe as insertImportedRevisions,we as linksIn,We as moveDocument,Le as readBase,He as readDocument,Ee as recordRead,Ie as setDocumentRecord,V as setRevisionLinks,Y as withCurrentNames,Ae as writeDocument};

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

@@ -0,0 +1,25 @@
+/** `acted-on` and `links-to` edges. An edge is visible only to a reader who may read both ends. */
+import type { DatabaseSync } from 'node:sqlite';
+import type { ObjectRow, Reader } from './types.js';
+export type EdgeType = 'acted-on' | 'links-to';
+export interface Edge {
+    type: EdgeType;
+    src: ObjectRow;
+    dst: ObjectRow;
+    written_as: string | null;
+    created_at: string;
+}
+/** One row per actor and object however many times the actor acts. */
+export declare function recordActedOn(db: DatabaseSync, actor: ObjectRow, object: ObjectRow): void;
+/** Replace the document's `links-to` edges with the links of its current revision. Answers the
+ *  rowids it no longer links to, so the caller can collect a kept document that lost its last link. */
+export declare function setLinks(db: DatabaseSync, doc: ObjectRow, links: ReadonlyArray<{
+    written_as: string;
+    dst: ObjectRow;
+}>): number[];
+/** Documents whose body links to `object`. */
+export declare function backlinks(db: DatabaseSync, reader: Reader, object: ObjectRow): Edge[];
+export declare function edgesOf(db: DatabaseSync, reader: Reader, object: ObjectRow, opts?: {
+    type?: EdgeType;
+    direction?: 'out' | 'in' | 'both';
+}): Edge[];

package/dist/core/graph/edges.js

@@ -0,0 +1 @@
+var O=Object.defineProperty;var d=(t,r)=>O(t,"name",{value:r,configurable:!0});import{prepared as o}from"../sqlite-statements.js";import{canRead as R}from"./access.js";import{getByRowid as l}from"./objects.js";function L(t,r,e){o(t,"INSERT OR IGNORE INTO edges (type, src, dst, written_as, created_at) VALUES ('acted-on', ?, ?, NULL, ?)").run(r.rowid,e.rowid,new Date().toISOString())}d(L,"recordActedOn");function _(t,r,e){const i=o(t,"SELECT dst FROM edges WHERE type = 'links-to' AND src = ?").all(r.rowid).map(({dst:s})=>s);o(t,"DELETE FROM edges WHERE type = 'links-to' AND src = ?").run(r.rowid);const a=o(t,"INSERT OR IGNORE INTO edges (type, src, dst, written_as, created_at) VALUES ('links-to', ?, ?, ?, ?)"),w=new Date().toISOString();for(const s of e)a.run(r.rowid,s.dst.rowid,s.written_as,w);const c=new Set(e.map(s=>s.dst.rowid));return i.filter(s=>!c.has(s))}d(_,"setLinks");function h(t,r,e){return S(t,r,e,{type:"links-to",direction:"in"})}d(h,"backlinks");function S(t,r,e,i={}){if(!R(t,r,e))return[];const a=i.direction??"both",w=i.type?[i.type]:["acted-on","links-to"],c=[];for(const n of w)a!=="in"&&c.push(...o(t,"SELECT * FROM edges WHERE type = ? AND src = ?").all(n,e.rowid)),a!=="out"&&c.push(...o(t,"SELECT * FROM edges WHERE type = ? AND dst = ?").all(n,e.rowid));const s=new Set,f=[];for(const n of c){const u=`${n.type}|${n.src}|${n.dst}`;if(s.has(u))continue;s.add(u);const p=n.src===e.rowid?e:l(t,n.src),E=n.dst===e.rowid?e:l(t,n.dst);if(!p||!E)continue;const y=p===e?E:p;y!==e&&!R(t,r,y)||f.push({type:n.type,src:p,dst:E,written_as:n.written_as,created_at:n.created_at})}return f}d(S,"edgesOf");export{h as backlinks,S as edgesOf,L as recordActedOn,_ as setLinks};

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

@@ -0,0 +1,50 @@
+/** The event catalog, subject matching, listening-config resolution and `publish`: the one
+ *  path by which an event on an object reaches its watchers' inboxes. */
+import type { DatabaseSync } from 'node:sqlite';
+import { type ReposFn } from './reader.js';
+import { type Subscription } from './watches.js';
+import { CrtrError } from '../errors.js';
+import type { EventSpec } from './kinds/kind.js';
+import { type CanvasEvent, type Level, type ListenConfig, type ListenDelivery, type ObjectRow } from './types.js';
+/** The level `ev` publishes at: the declared level when none is supplied; a supplied level
+ *  must equal it or be one of the event's declared `levels`. Throws `unknown_event` for an
+ *  event the object's kind does not declare, `invalid_level` for any other level. */
+export declare function resolveLevel(ev: Pick<CanvasEvent, 'event' | 'object' | 'level'>, spec: EventSpec): Level;
+/** NATS-style match over dot-separated event names: `*` is one part, `>` the rest (at least one part). */
+export declare function matchSubject(pattern: string, event: string): boolean;
+/** Per config, the delivery of the highest threshold the level reaches; across configs, the
+ *  strongest. Null when the level is below every threshold of every config. */
+export declare function resolveDelivery(configs: readonly ListenConfig[], level: Level): ListenDelivery | null;
+/** A subscription's own config, else the watcher's `objects.listen_json`, else the global default. */
+export declare function listenConfigFor(db: DatabaseSync, subscription: Pick<Subscription, 'config'>, watcher: ObjectRow): ListenConfig;
+/** Supersede (`spec.supersedes`): each destination's pending deliveries of the same
+ *  event on the same object are deleted. A receiver kind may fence its claimed delivery if
+ *  that in-flight execution is replaceable. The replacement carries `spec.merge(prior, ev)` —
+ *  prior being the attrs of the latest superseded message, null when there is none — or, with no
+ *  merge, the newer event's attrs. Destinations are grouped by the message they superseded, so
+ *  each group shares one replacement message. Messages left with no delivery are deleted.
+ *  The core selects matches by delivery destination and the message's event and object.
+ *  An event that does not supersede is one group with its own attrs. */
+export declare function supersede<D>(db: DatabaseSync, ev: CanvasEvent, spec: EventSpec, destinations: readonly D[], idOf: (d: D) => string): Array<{
+    attrs: Record<string, unknown>;
+    destinations: D[];
+}>;
+/**
+ * Validate the event against its object's kind (`resolveLevel`), then push it to every watcher of
+ * the object itself whose subscriptions receive it — a watch on an owner hears that owner's own
+ * events, not those of the objects it owns — inside the caller's write transaction. Candidates are
+ * the watchers whose `objects.reception` admits the event: a `durable` event reaches reception ≥ 1
+ * (a done node too), any other only reception 2. The actor is never pushed its own act, and access
+ * is re-checked per watcher. Writes one `messages` row, only when a delivery results, and hands
+ * each receiver (`receivers.ts`) its destinations. `reposFn` resolves a watcher's repos when the
+ * object lives in a repo space.
+ */
+export declare const HOP_LIMIT = 8;
+export declare class HopLimitError extends CrtrError {
+    constructor(depth: number);
+}
+export declare function publish(db: DatabaseSync, input: CanvasEvent, reposFn?: ReposFn): {
+    delivered: number;
+    message_id: string | null;
+    depth: number;
+};

package/dist/core/graph/events.js

@@ -0,0 +1,11 @@
+var k=Object.defineProperty;var c=(n,e)=>k(n,"name",{value:e,configurable:!0});import{prepared as m}from"../sqlite-statements.js";import{evalCondition as x}from"../predicate.js";import{finalizeNodeMail as W,insertMessage as $}from"../feed/messages.js";import{ownerChain as B,readCheck as J}from"./access.js";import{publishLookups as U,readerForObject as G}from"./reader.js";import{configFromJson as T}from"./watches.js";import{CrtrError as L}from"../errors.js";import{ExitCode as A}from"../../types.js";import{eventSpec as K,kindOf as C}from"./kinds/registry.js";import{RECEIVERS as D}from"./receivers.js";import{DEFAULT_LISTEN as F}from"./types.js";function q(n,e){if(n.level===void 0||n.level===e.level||e.levels?.includes(n.level))return n.level??e.level;const o=[e.level,...e.levels??[]].filter((s,t,d)=>d.indexOf(s)===t).sort((s,t)=>s-t);throw new L("invalid_level",`${n.object.type} ${n.event} publishes at level ${o.join(", ")}, not ${n.level}`,A.USAGE,{kind:n.object.type,event:n.event,level:n.level,allowed:o})}c(q,"resolveLevel");function X(n,e){const o=n.split("."),s=e.split(".");for(let t=0;t<o.length;t++){if(o[t]===">")return t===o.length-1&&s.length>t;if(t>=s.length||o[t]!=="*"&&o[t]!==s[t])return!1}return o.length===s.length}c(X,"matchSubject");const H={"next-turn":1,"after-turn":2,steer:3,interrupt:4};function Y(n,e){let o=null;for(const s of n){let t=null;for(const d of s)d.threshold<=e&&(!t||d.threshold>t.threshold)&&(t=d);t&&(!o||H[t.delivery]>H[o])&&(o=t.delivery)}return o}c(Y,"resolveDelivery");function fe(n,e,o){if(e.config)return e.config;const s=m(n,"SELECT listen_json FROM objects WHERE rowid = ?").get(o.rowid);return s?.listen_json?T(s.listen_json):F}c(fe,"listenConfigFor");function z(n,e){return e.inboxKind??(n.level>=7?"urgent":"update")}c(z,"inboxKind");function P(n,e){return e.type==="node"?e.id:m(n,`SELECT 1 FROM objects WHERE type IN ('person','app','repo','profile')
+    AND name = ? AND rowid != ? LIMIT 1`).get(e.name,e.rowid)?`${e.type}:${e.name}`:e.name}c(P,"ownerHandleOf");function V(n,e,o){const s=e.object.owner===null?null:m(n,"SELECT * FROM objects WHERE rowid = ?").get(e.object.owner),t=s?.id??null,d=s?P(n,s):null;return{event:e.event,level:e.level,object:{id:e.object.id,type:e.object.type,kind:e.object.kind,owner:t,owner_handle:d,name:e.object.name},actor:e.actor?.id??null,attrs:o,...e.pointer===void 0?{}:{pointer:e.pointer}}}c(V,"pushFields");function Q(n,e,o,s){const t=V(n,e,s),d=e.messageBody!==void 0&&o.carriesBody===!0,E=d?typeof e.messageBody=="object"&&e.messageBody!==null&&!Array.isArray(e.messageBody)?{...e.messageBody,push:t}:{body:e.messageBody,push:t}:{push:t},a=d?e.messageBody:null,l=a?.bodyRef===void 0?null:a;return{kind:z(e,o),label:l?.label??(e.object.type.includes(".")&&typeof e.messageBody?.summary=="string"?e.messageBody.summary.split(`
+`)[0]:`${e.event} ${e.object.type} ${e.object.name}`),...l?.bodyRef===void 0?{}:{bodyRef:l.bodyRef},...l?.disposition===void 0?{}:{disposition:l.disposition},senderNodeId:e.actor?.type==="node"?e.actor.id:null,senderName:e.actor?.name??null,bodyJson:E}}c(Q,"messageInput");function Z(n,e,o,s,t){if(!o.supersedes)return[{attrs:e.attrs,destinations:[...s]}];const d=m(n,`SELECT d.delivery_id, d.message_id, d.state, m.body_json FROM deliveries d
+    JOIN messages m ON m.message_id = d.message_id
+    WHERE d.destination_id = ? AND d.state IN ('pending', 'handed_off')
+      AND d.canceled_at IS NULL AND m.event = ? AND m.object_id = ?
+    ORDER BY m.seq`),E=m(n,"DELETE FROM deliveries WHERE delivery_id = ?"),a=m(n,"SELECT * FROM objects WHERE id = ?"),l=new Map,j=new Set;for(const p of s){const w=t(p),R=a.get(w),S=R===void 0?void 0:C(n,R.type),N=d.all(w,e.event,e.object.id),v=new Set;for(const r of N)r.state==="handed_off"?S?.supersedeClaimed?.(n,r.delivery_id)&&v.add(r.delivery_id):(E.run(r.delivery_id),j.add(r.message_id));const g=N.filter(r=>r.state==="pending"||v.has(r.delivery_id)).at(-1),b=g?.message_id??null,i=l.get(b)??{prior:g?.body_json?JSON.parse(g.body_json).push?.attrs??null:null,destinations:[]};i.destinations.push(p),l.set(b,i)}const _=m(n,"DELETE FROM messages WHERE message_id = ? AND NOT EXISTS (SELECT 1 FROM deliveries WHERE message_id = ?)");for(const p of j)_.run(p,p);return[...l.values()].map(p=>({attrs:o.merge?o.merge(p.prior,e):e.attrs,destinations:p.destinations}))}c(Z,"supersede");const M=8;class ee extends L{static{c(this,"HopLimitError")}constructor(e){super("hop_limit",`event depth ${e} exceeds ${M}`,A.GENERAL,{depth:e,limit:M})}}function me(n,e,o=()=>[]){const s=K(n,e.object.type,e.event),t={...e,level:q(e,s)},d=e.cause??null,E=d===null?null:m(n,`SELECT depth FROM messages WHERE message_id = ?
+    UNION ALL SELECT depth FROM message_causes WHERE message_id = ? LIMIT 1`).get(d,d);if(d!==null&&E===void 0)throw new L("unknown_cause",`no message ${d}`,A.USAGE,{cause:d});const a=E===null?0:E.depth+1;if(a>M)throw new ee(a);const l=B(n,t.object),j=`w.watcher, o.id AS watcher_id, o.type AS watcher_type, o.reception, s.pattern, s.filter_json,
+    COALESCE(s.config_json, o.listen_json) AS config_json`,_=n.prepare(s.durable?`SELECT ${j} FROM watches w JOIN watch_subscriptions s ON s.watch = w.rowid
+        JOIN objects o ON o.rowid = w.watcher WHERE w.object = ? AND w.watcher != ? AND o.reception >= 1`:`SELECT ${j} FROM objects o INDEXED BY objects_receiving CROSS JOIN watches w CROSS JOIN watch_subscriptions s
+        WHERE o.reception = 2 AND w.watcher = o.rowid AND s.watch = w.rowid AND w.object = ? AND w.watcher != ?`).all(t.object.rowid,t.actor?.rowid??-1);if(_.length===0)return{delivered:0,message_id:null,depth:a};const p={event:t.event,level:t.level,id:t.object.id,type:t.object.type,kind:t.object.kind,actor:t.actor?.id??null,...t.attrs},w=new Map;for(const i of _){if(!X(i.pattern,t.event)||i.filter_json!==null&&!x(JSON.parse(i.filter_json),p))continue;const r=w.get(i.watcher)??{id:i.watcher_id,type:i.watcher_type,reception:i.reception,configs:[]};r.configs.push(i.config_json?T(i.config_json):F),w.set(i.watcher,r)}const R=(l.length?l[l.length-1]:t.object).type==="repo",S=c(()=>[],"noRepos"),N=J(n,t.object),v=U(n),g=[];for(const i of w.values()){const r=m(n,"SELECT * FROM objects WHERE id = ?").get(i.id),u=C(n,r.type),O=u.receiverFor?u.receiverFor(n,r):u.receiver;if(O===void 0)continue;const y=Y(i.configs,t.level);if(y===null)continue;const h=G(n,r,R?o:S,v);h.scopes===null&&(h.class==="node"||h.owner.type!=="person")||N(h)&&g.push({id:i.id,reception:i.reception,delivery:y,receiver:O})}if(g.length===0)return{delivered:0,message_id:null,depth:a};let b=null;for(const i of Z(n,t,s,g,r=>r.id)){const r=new Map;for(const f of i.destinations)r.set(f.receiver,[...r.get(f.receiver)??[],f]);const u=Q(n,t,s,i.attrs),O=[...r].map(([f,I])=>D[f].bodyOwner(I)).find(f=>f!==null)??null,y=W({...u,urgency:"normal"},O),h=$(n,{operationId:y.operationId,createdAt:y.createdAt,senderNodeId:u.senderNodeId,senderName:u.senderName,kind:u.kind,label:u.label,bodyRef:y.bodyRef,bodyJson:y.bodyJson,disposition:u.disposition??null,event:{event:t.event,objectId:t.object.id,level:t.level,actorId:t.actor?.id??null},causeMessageId:d,depth:a});b??=h;for(const[f,I]of r)D[f].enqueue(n,{messageId:h,event:t.event,level:t.level,senderNodeId:u.senderNodeId,elevatesTier:s.elevatesTier===!0},I)}return{delivered:g.length,message_id:b,depth:a}}c(me,"publish");export{M as HOP_LIMIT,ee as HopLimitError,fe as listenConfigFor,X as matchSubject,me as publish,Y as resolveDelivery,q as resolveLevel,Z as supersede};

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

@@ -0,0 +1,53 @@
+/** The exposure ledger: what each node's loaded context already holds, per
+ *  channel (`system` = rebuilt system prompt, `transcript` = conversation), in
+ *  `exposures` and `context_sessions`. Rows cascade with the node. Callers
+ *  load, mutate in memory, and `saveLedger` inside their own transaction. */
+import type { DatabaseSync } from 'node:sqlite';
+import type { RuleSpec } from './types.js';
+export type ExposureLevel = RuleSpec['deliver'];
+export type Channel = 'system' | 'transcript';
+export interface Held {
+    system?: ExposureLevel;
+    transcript?: ExposureLevel;
+    headsKey: string | null;
+    contentHash: string | null;
+}
+export type Listed = {
+    system?: ExposureLevel;
+    transcript?: ExposureLevel;
+};
+export interface Ledger {
+    node: number;
+    preferenceSnapshot: string | null;
+    objects: Map<number, Held>;
+    /** key = `<owner object id>/<prefix>` */
+    listed: Map<string, Listed>;
+}
+export interface Exposed {
+    object: number;
+    headsKey: string | null;
+    contentHash: string | null;
+}
+export declare function loadLedger(db: DatabaseSync, node: number): Ledger;
+/** Write what changed since `loadLedger` (a ledger never loaded is written whole). */
+export declare function saveLedger(db: DatabaseSync, ledger: Ledger): void;
+/** Whether the node has a ledger at all (a context session or any exposure). */
+export declare function hasLedger(db: DatabaseSync, node: number): boolean;
+/** End the node's context session: nothing is held any more. */
+export declare function clearLedger(db: DatabaseSync, node: number): void;
+/** Seed a fork with what the source's transcript holds; the fork builds its own
+ *  system prompt, so system rows and the preference snapshot are not copied. */
+export declare function forkLedger(db: DatabaseSync, source: number, fork: number): void;
+/** Held at `level` or above: this object, or any held object with the same body
+ *  (content hash). The object itself counts at content level only for the same revision. */
+export declare function heldAtOrAbove(ledger: Ledger, exposed: Exposed, level: ExposureLevel, channel?: Channel): boolean;
+/** Record that `channel` now holds the object at `level`; never lowers a level of the same revision. */
+export declare function hold(ledger: Ledger, channel: Channel, exposed: Exposed, level: ExposureLevel): void;
+export declare function listedAtOrAbove(ledger: Ledger, key: string, level: ExposureLevel, channel?: Channel): boolean;
+export declare function holdListing(ledger: Ledger, channel: Channel, key: string, level: ExposureLevel): void;
+/** Forget the transcript's copy of the object and of every held object with the
+ *  same body (compaction dropped it); system holdings stay. */
+export declare function demoteTranscript(ledger: Ledger, object: number): void;
+/** The byte-stable preference block: the first render is kept for the session. */
+export declare function freezePreferences(ledger: Ledger, rendered: string): string;
+export declare function hasTranscript(ledger: Ledger): boolean;

package/dist/core/graph/exposures.js

@@ -0,0 +1,4 @@
+var O=Object.defineProperty;var i=(n,e)=>O(n,"name",{value:e,configurable:!0});import{prepared as a}from"../sqlite-statements.js";const f={name:1,preview:2,content:3},b=["system","transcript"],l=new WeakMap;function _(n){return{node:n.node,preferenceSnapshot:n.preferenceSnapshot,objects:new Map([...n.objects].map(([e,t])=>[e,{...t}])),listed:new Map([...n.listed].map(([e,t])=>[e,{...t}]))}}i(_,"cloneLedger");function S(n){return{node:n,preferenceSnapshot:null,objects:new Map,listed:new Map}}i(S,"emptyLedger");function T(n,e){const t=S(e),s=a(n,"SELECT preference_snapshot, listed_json FROM context_sessions WHERE node = ?").get(e);if(s!==void 0){t.preferenceSnapshot=s.preference_snapshot;for(const[o,r]of Object.entries(JSON.parse(s.listed_json)))t.listed.set(o,r)}const c=a(n,"SELECT object, channel, level, heads_key, content_hash FROM exposures WHERE node = ?").all(e);for(const o of c){const r=t.objects.get(o.object)??{headsKey:o.heads_key,contentHash:o.content_hash};r[o.channel]=o.level,t.objects.set(o.object,r)}return l.set(t,_(t)),t}i(T,"loadLedger");function x(n,e){const t=l.get(e)??S(e.node),s=JSON.stringify(Object.fromEntries(e.listed));(e.preferenceSnapshot!==t.preferenceSnapshot||s!==JSON.stringify(Object.fromEntries(t.listed)))&&a(n,`INSERT INTO context_sessions (node, preference_snapshot, listed_json) VALUES (?, ?, ?)
+      ON CONFLICT(node) DO UPDATE SET preference_snapshot = excluded.preference_snapshot, listed_json = excluded.listed_json`).run(e.node,e.preferenceSnapshot,s);const c=a(n,`INSERT INTO exposures (node, object, channel, level, heads_key, content_hash) VALUES (?, ?, ?, ?, ?, ?)
+    ON CONFLICT(node, object, channel) DO UPDATE SET level = excluded.level, heads_key = excluded.heads_key, content_hash = excluded.content_hash`),o=a(n,"DELETE FROM exposures WHERE node = ? AND object = ? AND channel = ?"),r=new Set([...t.objects.keys(),...e.objects.keys()]);for(const d of r){const u=e.objects.get(d),p=t.objects.get(d);for(const h of b){const E=u?.[h];E===void 0?p?.[h]!==void 0&&o.run(e.node,d,h):(E!==p?.[h]||u.headsKey!==p?.headsKey||u.contentHash!==p?.contentHash)&&c.run(e.node,d,h,E,u.headsKey,u.contentHash)}}l.set(e,_(e))}i(x,"saveLedger");function H(n,e){return a(n,"SELECT 1 FROM context_sessions WHERE node = ? UNION ALL SELECT 1 FROM exposures WHERE node = ? LIMIT 1").get(e,e)!==void 0}i(H,"hasLedger");function L(n,e){a(n,"DELETE FROM exposures WHERE node = ?").run(e),a(n,"DELETE FROM context_sessions WHERE node = ?").run(e)}i(L,"clearLedger");function R(n,e,t){L(n,t),a(n,`INSERT INTO exposures (node, object, channel, level, heads_key, content_hash)
+    SELECT ?, object, channel, level, heads_key, content_hash FROM exposures WHERE node = ? AND channel = 'transcript'`).run(t,e);const s=a(n,"SELECT listed_json FROM context_sessions WHERE node = ?").get(e);if(s===void 0)return;const c={};for(const[o,r]of Object.entries(JSON.parse(s.listed_json)))r.transcript!==void 0&&(c[o]={transcript:r.transcript});a(n,"INSERT INTO context_sessions (node, preference_snapshot, listed_json) VALUES (?, NULL, ?)").run(t,JSON.stringify(c))}i(R,"forkLedger");function j(n,e){if(n===void 0)return 0;const t=i(s=>n[s]!==void 0?f[n[s]]:0,"of");return e!==void 0?t(e):Math.max(t("system"),t("transcript"))}i(j,"rankIn");function m(n,e,t,s){const c=f[t],o=n.objects.get(e.object);if(o!==void 0&&j(o,s)>=c&&(t!=="content"||o.headsKey===e.headsKey))return!0;if(e.contentHash===null)return!1;for(const r of n.objects.values())if(r.contentHash===e.contentHash&&j(r,s)>=c)return!0;return!1}i(m,"heldAtOrAbove");function M(n,e,t,s){const c=n.objects.get(t.object),o=c!==void 0&&c.headsKey===t.headsKey&&c.contentHash===t.contentHash,r=o?{...c}:{headsKey:t.headsKey,contentHash:t.contentHash},d=o?c[e]:void 0;r[e]=d!==void 0&&f[d]>=f[s]?d:s,n.objects.set(t.object,r)}i(M,"hold");function A(n,e,t,s){return j(n.listed.get(e),s)>=f[t]}i(A,"listedAtOrAbove");function v(n,e,t,s){const c=n.listed.get(t)??{},o=c[e];o!==void 0&&f[o]>=f[s]||n.listed.set(t,{...c,[e]:s})}i(v,"holdListing");function I(n,e){const t=n.objects.get(e);if(t!==void 0)for(const[s,c]of n.objects){if(s!==e&&(t.contentHash===null||c.contentHash!==t.contentHash))continue;const{transcript:o,...r}=c;r.system===void 0?n.objects.delete(s):n.objects.set(s,r)}}i(I,"demoteTranscript");function w(n,e){return n.preferenceSnapshot===null&&(n.preferenceSnapshot=e),n.preferenceSnapshot}i(w,"freezePreferences");function k(n){return[...n.objects.values()].some(e=>e.transcript!==void 0)||[...n.listed.values()].some(e=>e.transcript!==void 0)}i(k,"hasTranscript");export{L as clearLedger,I as demoteTranscript,R as forkLedger,w as freezePreferences,H as hasLedger,k as hasTranscript,m as heldAtOrAbove,M as hold,v as holdListing,A as listedAtOrAbove,T as loadLedger,x as saveLedger};

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

@@ -0,0 +1,31 @@
+/** Jobs: a backgrounded bash command as an object the node that started it owns, with its
+ *  `jobs` row and the events of its start and end. Runs in the caller's transaction. */
+import type { DatabaseSync } from 'node:sqlite';
+import type { ObjectRow } from './types.js';
+export type JobStatus = 'running' | 'exited' | 'killed';
+export interface JobRow {
+    object: number;
+    command: string;
+    status: JobStatus;
+    exit_code: number | null;
+    job_dir: string;
+    log_path: string;
+}
+export declare function jobRow(db: DatabaseSync, job: ObjectRow): JobRow | null;
+/** Create the job object (`id` keeps the job id the runner already uses), its `running` row,
+ *  the node's acted-on edge and `job-start` watch, and publish `created`. */
+export declare function startJob(db: DatabaseSync, node: ObjectRow, spec: {
+    id?: string;
+    command: string;
+    jobDir: string;
+    logPath: string;
+}): ObjectRow;
+/** End a running job: `exited` with its exit code, or `killed` with the killer as actor (null
+ *  when the runtime killed it, e.g. at its deadline; `reason` then names why). The event carries
+ *  the exit code and log path, never output. A job already ended is left as is. */
+export declare function finishJob(db: DatabaseSync, job: ObjectRow, end: {
+    exitCode: number;
+} | {
+    killedBy: ObjectRow | null;
+    reason?: string;
+}): ObjectRow;

package/dist/core/graph/jobs.js

@@ -0,0 +1,2 @@
+var w=Object.defineProperty;var n=(t,o)=>w(t,"name",{value:o,configurable:!0});import{prepared as a}from"../sqlite-statements.js";import{recordActedOn as u}from"./edges.js";import{publish as d}from"./events.js";import{createObject as h,getByRowid as E}from"./objects.js";import{recordWatch as b}from"./watches.js";function m(t){return t.split(`
+`,1)[0].trim()}n(m,"firstLine");function f(t,o){return`${m(t)} (${o})`}n(f,"previewOf");function j(t,o){return a(t,"SELECT * FROM jobs WHERE object = ?").get(o.rowid)??null}n(j,"jobRow");function v(t,o,r){if(o.type!=="node")throw new Error(`startJob: ${o.id} is a ${o.type}, not a node`);const i=h(t,{...r.id===void 0?{}:{id:r.id},type:"job",kind:"bash",owner:o.rowid,privacy:"public",name:m(r.command)||"bash",preview:f(r.command,"running")});return a(t,"INSERT INTO jobs (object, command, status, exit_code, job_dir, log_path) VALUES (?, ?, 'running', NULL, ?, ?)").run(i.rowid,r.command,r.jobDir,r.logPath),u(t,o,i),b(t,o,i,"job-start"),d(t,{event:"created",object:i,actor:o,attrs:{}}),i}n(v,"startJob");function S(t,o,r){const i=j(t,o);if(i===null)throw new Error(`finishJob: ${o.id} has no jobs row`);if(i.status!=="running")return o;const e="killedBy"in r,s=e?"killed":"exited",l=e?null:r.exitCode;a(t,"UPDATE jobs SET status = ?, exit_code = ? WHERE object = ?").run(s,l,o.rowid);const p=e?"killed":`exited ${l}`;a(t,"UPDATE objects SET preview = ? WHERE rowid = ?").run(f(i.command,p),o.rowid);const c=E(t,o.rowid);return e&&r.killedBy!==null&&u(t,r.killedBy,c),d(t,{event:s,object:c,actor:e?r.killedBy:null,attrs:e?{"log-path":i.log_path,...r.reason===void 0?{}:{reason:r.reason}}:{"exit-code":l,"log-path":i.log_path}}),c}n(S,"finishJob");export{S as finishJob,j as jobRow,v as startJob};

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

@@ -0,0 +1,3 @@
+import type { ObjectKind } from './kind.js';
+/** An action is a receiver, not a publisher. Its source is the node it watches. */
+export declare const actionKind: ObjectKind;

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

@@ -0,0 +1 @@
+import{receiverForObject as o}from"../receivers.js";import{withBase as d}from"./kind.js";import{header as c}from"./render.js";import{objectDTO as n}from"./dto.js";const b={name:"action",addressable:"id",events:d({}),receiverFor:o,supersedeClaimed(r,t){const e=Date.now();return Number(r.prepare("UPDATE deliveries SET canceled_at = ?, updated_at = ? WHERE delivery_id = ? AND state = 'handed_off' AND canceled_at IS NULL").run(e,e,t).changes)===1},read(r,t,e){const a={object:n(r,e)};return{data:a,text:c("object",a.object)}}};export{b as actionKind};

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

@@ -0,0 +1,7 @@
+import type { ObjectKind } from './kind.js';
+import type { Level } from '../types.js';
+/** A catalog is frozen into the kind; receiver choice belongs to each object. */
+export declare function customKind(name: string, declared: Record<string, {
+    level: Level;
+    supersedes?: boolean;
+}>): ObjectKind;

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

@@ -0,0 +1,7 @@
+var l=Object.defineProperty;var d=(s,n)=>l(s,"name",{value:n,configurable:!0});import{prepared as m}from"../../sqlite-statements.js";import{recordLiveRead as u}from"./kind.js";import{header as v}from"./render.js";import{objectDTO as j}from"./dto.js";import{receiverForObject as b}from"../receivers.js";function S(s,n){const a=Object.fromEntries(Object.entries(n).map(([t,i])=>[`${s}.${t}`,{...i,carriesBody:!0}]));return{name:s,events:{created:{level:4},read:{level:1},watched:{level:1},deleted:{level:5},configured:{level:1},...a},addressable:"name",receiverFor:b,read(t,i,c,p){u(t,i,c,p.reposFn);const e=m(t,"SELECT description, summary, state_json, published_at, receiver_json, dropped FROM custom_objects WHERE object = ?").get(c.rowid),o=e?.receiver_json==null?null:JSON.parse(e.receiver_json),r={object:j(t,c),description:e?.description??"",summary:e?.summary??null,state:e?.state_json==null?null:JSON.parse(e.state_json),published_at:e?.published_at??null,receiver:typeof o=="string"?o:o&&typeof o=="object"?Object.keys(o)[0]:null,dropped:e?.dropped??0};return{data:r,text:`${v("object",r.object)}
+Description: ${r.description}
+Summary: ${r.summary??""}
+State: ${JSON.stringify(r.state)}
+Published: ${r.published_at??"never"}
+Receiver: ${r.receiver??"none"}
+Dropped: ${r.dropped}`}}}}d(S,"customKind");export{S as customKind};

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

@@ -0,0 +1,19 @@
+import type { DocFieldsDTO, ObjectDTO } from '../../../api/dto/objects.js';
+import { type ObjectKind } from './kind.js';
+export interface DocumentReadData {
+    summary: string | null;
+    revision: number;
+    heads: Array<{
+        rev_id: string;
+        number: number;
+        author_id: string | null;
+        created_at: string;
+    }>;
+    /** One body per head, in `heads` order. */
+    bodies: string[];
+    needs_merge: boolean;
+    listing?: ObjectDTO[];
+    attachments?: string;
+    fields?: DocFieldsDTO;
+}
+export declare const documentKind: ObjectKind;

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

@@ -0,0 +1,5 @@
+var y=Object.defineProperty;var m=(e,t)=>y(e,"name",{value:t,configurable:!0});import{prepared as v}from"../../sqlite-statements.js";import{recordMemoryReadsIn as _}from"../../canvas/memory-reads.js";import{deliveryDocOf as x,nodeSubject as $,ownerHandle as R}from"../../substrate/delivery/corpus.js";import{recordContentDelivery as S}from"../../substrate/delivery/deliver.js";import{renderExplicitRead as D}from"../../substrate/delivery/render-event.js";import{canRead as j}from"../access.js";import{documentRecord as k,readDocument as E}from"../documents.js";import{loadLedger as N,saveLedger as O}from"../exposures.js";import{getByRowid as A}from"../objects.js";import{rulesOf as p}from"../rules.js";import{objectDTO as d}from"./dto.js";import{withBase as M}from"./kind.js";import{attr as l,header as I,section as L}from"./render.js";function b(e,t,n){const r=`${n.name}/`;return v(e,`SELECT * FROM objects WHERE type = 'document' AND deleted_at IS NULL AND owner IS ?
+    AND substr(name, 1, ?) = ? ORDER BY name`).all(n.owner,r.length,r).filter(s=>!s.name.slice(r.length).includes("/")&&j(e,t,s)).map(s=>d(e,s))}m(b,"listingOf");function B(e,t,n){const r=t.class==="node",o=r?N(e,t.node.rowid):{node:0,preferenceSnapshot:null,objects:new Map,listed:new Map},s={db:e,reader:t,subject:r?$(e,t):null,ledger:o,channel:"transcript"},a=D(s,x(e,t,n));return r&&(S(e,t,a.delivered),O(e,o)),{attachments:a.attachments,linked:a.linked.map(u=>u.object)}}m(B,"explicitReadAttachments");function T(e,t,n){if(t.class!=="node"||n.kind!=="knowledge"&&n.kind!=="preference"||n.owner===null)return;const r=A(e,n.owner);r!==null&&_(e,t.node.id,[{name:n.name,scope:R(r),at:new Date().toISOString(),type:"read"}])}m(T,"recordExplicitMemoryRead");function W(e,t){const n=[];if(t.attachments&&n.push(t.attachments,""),n.push(I("object",e,l("privacy",e.privacy)+l("revision",t.revision))),n.push(`Preview: ${e.preview}`),t.summary&&n.push(`Summary: ${t.summary}`),t.fields!==void 0&&n.push(`<fields>
+${JSON.stringify(t.fields,null,2)}
+</fields>`),t.needs_merge?(t.heads.forEach((r,o)=>{n.push(`<head${l("rev",r.rev_id)}${l("number",r.number)}${l("author",r.author_id)}>`,t.bodies[o]??"","</head>")}),n.push(`This document has ${t.heads.length} heads. Your next \`crtr doc edit\` writes the merged body and joins them into one revision.`)):n.push("",t.bodies[0]??""),t.listing&&t.listing.length>0){const r=t.listing.some(a=>a.owner?.id===e.owner?.id&&a.name.startsWith(`${e.name}/`)),o=t.listing.some(a=>a.owner?.id!==e.owner?.id||!a.name.startsWith(`${e.name}/`)),s=r&&o?`Names under ${e.name}/ and documents it links to`:r?`Names under ${e.name}/`:"Documents it links to";n.push("",...L(s,t.listing))}return n.join(`
+`)}m(W,"render");function C(e){const t=e.attrs.revision,n=e.attrs.from_revision??(typeof t=="number"?t-1:null),r=e.attrs.rationale;return{...e.attrs,from_revision:n,revision:t,authors:e.actor?[e.actor.id]:[],rationales:typeof r=="string"?[r]:[]}}m(C,"editAttrs");const H=m((e,t)=>{const n=C(t);if(e===null)return n;const r=e.authors??[];return{...n,from_revision:e.from_revision??null,authors:[...r,...n.authors.filter(o=>!r.includes(o))],rationales:[...e.rationales??[],...n.rationales]}},"mergeEdits"),te={name:"document",addressable:"name",events:M({edited:{level:8,supersedes:!0,merge:H},deleted:{level:8}}),listItem(e,t){return{summary:k(e,t).summary??null,rules:p(e,t).length}},read(e,t,n,r){const o=E(e,t,n,r.reposFn);T(e,t,n);const s=o.record,a=b(e,t,n),{attachments:u,linked:h}=B(e,t,n),g=new Set(a.map(i=>i.id)),f=[...a,...h.filter(i=>!g.has(i.id)).map(i=>d(e,i))],c={summary:s.summary??null,revision:s.revision,heads:o.heads.map(i=>({rev_id:i.rev_id,number:i.number,author_id:i.author,created_at:i.created_at})),bodies:o.heads.map(i=>i.body),needs_merge:o.needsMerge,...f.length>0?{listing:f}:{},...u===""?{}:{attachments:u}};return r.fields&&(c.fields={why_it_exists:s.why_it_exists??null,unlisted:s.unlisted,lint_ignore:s.lint_ignore??[],extensions:s.extensions??{},rules:p(e,n).map(({matchFrontmatter:i,...w})=>({...w,...i===void 0?{}:{match_frontmatter:i}}))}),{data:c,text:W(d(e,n),c)}}};export{te as documentKind};

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

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

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

@@ -0,0 +1 @@
+var i=Object.defineProperty;var d=(n,e)=>i(n,"name",{value:e,configurable:!0});import{getByRowid as a}from"../objects.js";function c(n,e){const t=e.owner===null?null:a(n,e.owner),r=t?{id:t.id,type:t.type,handle:t.type==="node"?t.id:t.name}:null;return{id:e.id,type:e.type,kind:e.kind,owner:r,privacy:e.privacy,name:e.name,preview:e.preview??"",created_at:e.created_at,deleted_at:e.deleted_at}}d(c,"objectDTO");export{c as objectDTO};

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

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

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

@@ -0,0 +1,2 @@
+import{jobRow as m}from"../jobs.js";import{objectDTO as c}from"./dto.js";import{recordLiveRead as l,withBase as p}from"./kind.js";import{attr as a,header as h}from"./render.js";const f={name:"job",addressable:"id",events:p({exited:{level:7},killed:{level:7}}),read(r,s,e,d){const o=m(r,e);if(!o)throw new Error(`job object ${e.id} has no jobs row`);l(r,s,e,d.reposFn);const n=c(r,e),t={command:o.command,status:o.status,exit_code:o.exit_code,log_path:o.log_path},i=[h("object",n,a("status",t.status)+a("exit_code",t.exit_code)),`Command: ${t.command}`,`Log: ${t.log_path}`].join(`
+`);return{data:t,text:i}}};export{f as jobKind};

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

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

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

@@ -0,0 +1 @@
+var l=Object.defineProperty;var d=(e,r)=>l(e,"name",{value:r,configurable:!0});import{actorOf as a}from"../documents.js";import{publish as c}from"../events.js";import{recordWatch as n}from"../watches.js";const f={created:{level:4},read:{level:1},watched:{level:1},deleted:{level:5},configured:{level:1}};function s(e={}){return{...f,...e}}d(s,"withBase");function h(e,r,t,i){const o=a(r);o.rowid!==t.rowid&&(n(e,o,t,"read"),c(e,{event:"read",object:t,actor:o,attrs:{}},i))}d(h,"recordLiveRead");export{f as BASE_EVENTS,h as recordLiveRead,s as withBase};

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

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

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

@@ -0,0 +1,5 @@
+var T=Object.defineProperty;var u=(r,t)=>T(r,"name",{value:t,configurable:!0});import{prepared as p}from"../../sqlite-statements.js";import{cancelCronsOnWake as I}from"../../canvas/crons.js";import{settleMatchingControllerWait as N}from"../../canvas/waits.js";import{effectiveTier as R,listenDeliveryTier as b,newId as y}from"../../feed/messages.js";import{readGoal as S}from"../../runtime/kickoff.js";import{canRead as h}from"../access.js";import{objectDTO as _}from"./dto.js";import{recordLiveRead as D,withBase as L}from"./kind.js";import{attr as O,header as g,section as f}from"./render.js";const m=[3,5,7];function j(r){return r?.split(`
+`).map(t=>t.trim()).find(t=>t!=="")??""}u(j,"firstLine");const $={bodyOwner:u(r=>r[0]?.id??null,"bodyOwner"),enqueue(r,t,o){const d=Date.now(),s=t.senderNodeId,i=o.map(e=>e.id),l=`(${i.map(()=>"?").join(",")})`,c=s===null?new Set:new Set(r.prepare(`SELECT DISTINCT node_id FROM waits WHERE kind = 'controller' AND target_id = ? AND satisfied_at IS NULL AND node_id IN ${l}`).all(s,...i).map(e=>e.node_id)),n=new Set(r.prepare(`SELECT DISTINCT anchor_node FROM crons WHERE cancel_on_wake = 1 AND anchor_node IN ${l}`).all(...i).map(e=>e.anchor_node)),v=p(r,`INSERT INTO deliveries (delivery_id, message_id, destination_id, urgency, wake, state, created_at, updated_at)
+       VALUES (?, ?, ?, ?, ?, 'pending', ?, ?)`);for(const e of o){const a=b(e.delivery),E=e.reception===2?a.wake:0,w=t.elevatesTier?R(e.id,a.urgency):a.urgency;v.run(y(),t.messageId,e.id,w,E,d,d),c.has(e.id)&&N(e.id,s,d,r),E===1&&w!=="deferred"&&n.has(e.id)&&I(e.id)}}},K={name:"node",addressable:"id",receiver:"inbox",events:L({configured:{level:1,durable:!0},messaged:{level:2,durable:!0},sent:{level:1,durable:!0},"report.update":{level:5,levels:m,durable:!0,carriesBody:!0,elevatesTier:!0},"report.final":{level:7,durable:!0,carriesBody:!0,elevatesTier:!0,inboxKind:"final"},outcome:{level:1,durable:!0,supersedes:!0,carriesBody:!0},"report.result":{level:5,durable:!0,carriesBody:!0,elevatesTier:!0,inboxKind:"completed"},"notice.crash":{level:5,levels:m,durable:!0,carriesBody:!0,elevatesTier:!0},"notice.deadline":{level:5,levels:m,durable:!0,carriesBody:!0,elevatesTier:!0},"notice.close":{level:5,levels:m,durable:!0,carriesBody:!0,elevatesTier:!0}}),read(r,t,o,d){const s=p(r,"SELECT status FROM nodes WHERE node_id = ?").get(o.id),i=u(e=>e.filter(a=>h(r,t,a)).map(a=>_(r,a)),"visible"),l=p(r,`SELECT o.* FROM nodes n JOIN objects o ON o.id = n.node_id
+      WHERE n.parent = ? AND o.deleted_at IS NULL ORDER BY o.rowid`).all(o.id),c=p(r,"SELECT * FROM objects WHERE owner = ? AND deleted_at IS NULL ORDER BY rowid").all(o.rowid);D(r,t,o,d.reposFn);const n={status:s?.status??"deleted",mandate_first_line:j(S(o.id)),children:i(l),owned:i(c.filter(e=>e.type!=="job")),jobs:i(c.filter(e=>e.type==="job"))},v=[g("object",_(r,o),O("status",n.status)),`Mandate: ${n.mandate_first_line}`,...f("Children",n.children),...f("Owns",n.owned),...f("Jobs",n.jobs)].join(`
+`);return{data:n,text:v}}};export{$ as nodeInbox,K as nodeKind};

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

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

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

@@ -0,0 +1,2 @@
+var p=Object.defineProperty;var d=(a,t)=>p(a,"name",{value:t,configurable:!0});import{prepared as c}from"../../sqlite-statements.js";import{objectDTO as l}from"./dto.js";import{recordLiveRead as h,withBase as y}from"./kind.js";import{header as f}from"./render.js";function n(a){return{name:a,addressable:"handle",events:y(),read(t,o,e,s){const r=c(t,"SELECT scheme, external_id FROM identities WHERE object = ?").get(e.rowid);h(t,o,e,s.reposFn);const i={handle:e.name,display_name:e.preview||e.name,identity:{scheme:r?.scheme??"",external_id:r?.external_id??""}},m=[f("object",l(t,e)),`Handle: ${i.handle}`,`Display name: ${i.display_name}`,`Identity: ${i.identity.scheme}:${i.identity.external_id}`].join(`
+`);return{data:i,text:m}}}}d(n,"ownerKind");const u=[n("person"),n("app"),n("repo"),n("profile")];export{u as ownerKinds};

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

@@ -0,0 +1,13 @@
+/** The kind registry: kind name → its `ObjectKind`, and each kind's declared events.
+ *  `createObject` and `publish` go through it, so an undeclared kind cannot be written and an
+ *  undeclared event cannot be published. It decides no access, fan-out or delivery. */
+import type { DatabaseSync } from 'node:sqlite';
+import type { EventSpec, ObjectKind } from './kind.js';
+/** A registration write invalidates the in-process copy before its next lookup. */
+export declare function invalidateCustomKind(db: DatabaseSync, name: string): void;
+export declare function kindNames(db: DatabaseSync): string[];
+export declare function isKind(db: DatabaseSync, name: string): boolean;
+/** The kind named `name`, or throws `unknown_kind`. */
+export declare function kindOf(db: DatabaseSync, name: string): ObjectKind;
+/** The declared spec of `event` on `kind`, or throws `unknown_event` naming the declared events. */
+export declare function eventSpec(db: DatabaseSync, kind: string, event: string): EventSpec;

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

@@ -0,0 +1 @@
+var l=Object.defineProperty;var o=(e,n)=>l(e,"name",{value:n,configurable:!0});import{prepared as u}from"../../sqlite-statements.js";import{CrtrError as f}from"../../errors.js";import{ExitCode as m}from"../../../types.js";import{documentKind as k}from"./document.js";import{jobKind as w}from"./job.js";import{nodeKind as O}from"./node.js";import{actionKind as j}from"./action.js";import{ownerKinds as E}from"./owner.js";import{customKind as S}from"./custom.js";let a=null;function s(){return a??=new Map([k,O,j,w,...E].map(e=>[e.name,e])),a}o(s,"kinds");const c=new WeakMap;function N(e,n){c.get(e)?.delete(n)}o(N,"invalidateCustomKind");function g(e){return[...s().keys(),...u(e,"SELECT name FROM object_kinds ORDER BY name").all().map(n=>n.name)]}o(g,"kindNames");function J(e,n){return s().has(n)||p(e,n)!==null}o(J,"isKind");function p(e,n){let t=c.get(e);t||(t=new Map,c.set(e,t));const r=t.get(n);if(r)return r;const i=u(e,"SELECT events_json FROM object_kinds WHERE name = ?").get(n);if(!i)return null;const d=S(n,JSON.parse(i.events_json));return t.set(n,d),d}o(p,"kindOfCustom");function h(e,n){const t=s().get(n)??p(e,n);if(t==null)throw new f("unknown_kind",`no object kind named ${JSON.stringify(n)}; the kinds are ${g(e).join(", ")}`,m.USAGE,{kind:n});return t}o(h,"kindOf");function A(e,n,t){const r=h(e,n).events,i=Object.hasOwn(r,t)?r[t]:void 0;if(i===void 0)throw new f("unknown_event",`${n} declares no event ${JSON.stringify(t)}; it declares ${Object.keys(r).join(", ")}`,m.USAGE,{kind:n,event:t,declared:Object.keys(r)});return i}o(A,"eventSpec");export{A as eventSpec,N as invalidateCustomKind,J as isKind,g as kindNames,h as kindOf};

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

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

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

@@ -0,0 +1 @@
+var i=Object.defineProperty;var t=(e,n)=>i(e,"name",{value:n,configurable:!0});function r(e,n){return n==null||n===""?"":` ${e}="${String(n).replace(/"/g,"&quot;")}"`}t(r,"attr");function p(e){const n=e.kind?`${e.type}/${e.kind}`:e.type,d=e.owner?` owner=${e.owner.handle}`:"",$=e.deleted_at?" (deleted)":"";return`- ${e.id} [[${e.name}]] ${n}${d}${$} \u2014 ${e.preview}`}t(p,"objectRow");function u(e,n,d=""){return`<${e}${r("type",n.type)}${r("kind",n.kind)}${r("id",n.id)}${r("name",n.name)}${r("owner",n.owner?.handle)}${d}>`}t(u,"header");function a(e,n){return n.length===0?[]:[`${e}:`,...n.map(p)]}t(a,"section");export{r as attr,u as header,p as objectRow,a as section};

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

@@ -0,0 +1,35 @@
+import type { DatabaseSync } from 'node:sqlite';
+import type { ObjectRow, Reader } from './types.js';
+export type Resolution = {
+    object: ObjectRow;
+} | {
+    deleted: ObjectRow;
+} | {
+    remote: string;
+} | {
+    ambiguous: ObjectRow[];
+} | {
+    missing: true;
+};
+/** The owners a bare name is looked up under, in order: own node, repos nearest
+ *  first, profile, app, you, then the apps whose tools the run may use (installed
+ *  plugins) with `crtr` last. */
+export declare function viewOf(db: DatabaseSync, reader: Reader): ObjectRow[];
+/** The owner types that carry a handle; `<type>:<handle>/<name>` names one exactly. */
+export declare const HANDLE_TYPES: readonly ["person", "app", "repo", "profile"];
+/** Every owner a handle names: a node by id, and each handle-carrying owner type
+ *  holding that handle (handles are unique per type, not across types). Any owner
+ *  also answers to its object id, so `<owner object id>/<name>` names a document
+ *  whatever its owner's type. */
+export declare function ownersByHandle(db: DatabaseSync, handle: string, type?: string): ObjectRow[];
+/** `name` may be wrapped in `[[ ]]`, a raw object id, a bare document name,
+ *  `<owner handle>/<name>`, or `<type>:<owner handle>/<name>`. Under a handle
+ *  several owner types share, owners in the reader's view come first in view
+ *  order; otherwise exactly one holder wins and more are `ambiguous`. Anything
+ *  the reader cannot read answers `missing`. */
+/** Precomputed for one reader across many resolutions (a corpus names every document). */
+export interface ResolveContext {
+    view: ObjectRow[];
+    readable: (o: ObjectRow) => boolean;
+}
+export declare function resolveName(db: DatabaseSync, reader: Reader, raw: string, context?: ResolveContext): Resolution;

package/dist/core/graph/names.js

@@ -0,0 +1,3 @@
+var A=Object.defineProperty;var u=(t,e)=>A(t,"name",{value:e,configurable:!0});import{prepared as w}from"../sqlite-statements.js";import{isSafeNodeId as L}from"../canvas/paths.js";import{canRead as I,toolApps as T}from"./access.js";import{getById as x}from"./objects.js";function H(t,e){const s=w(t,"SELECT * FROM objects WHERE type = 'person' AND name = 'user'").get(),l=T(t,e),o=e.class==="node"?[e.node,...e.repos,e.profile,e.app]:e.class==="app"?[e.app]:e.class==="object"?[e.owner,...e.repos,e.app]:[],a=new Set;return[...o,s,...l].filter(r=>!!r&&!a.has(r.rowid)&&!!a.add(r.rowid))}u(H,"viewOf");function E(t,e,s,l){return t.prepare(`SELECT * FROM objects WHERE (type = 'document' OR instr(type, '.') > 0) AND owner = ? AND name = ?
+    AND deleted_at IS ${l?"NOT NULL ORDER BY deleted_at DESC":"NULL"}`).all(e.rowid,s)}u(E,"namedObjects");const b=["person","app","repo","profile"],y=/^(person|app|repo|profile|node):([^/]+)\/(.+)$/;function M(t,e,s){return s==="node"?w(t,"SELECT * FROM objects WHERE type = 'node' AND id = ?").all(e):s?w(t,"SELECT * FROM objects WHERE type = ? AND (name = ? OR id = ?)").all(s,e,e):w(t,`SELECT * FROM objects WHERE (type = 'node' AND id = ?)
+    OR (type IN ('person','app','repo','profile') AND (name = ? OR id = ?))`).all(e,e,e)}u(M,"ownersByHandle");function v(t,e,s,l){let o=s.trim().replace(/^\[\[(.*)\]\]$/,"$1").trim();const a=/^([^:/]+):reports\/(.+?)(?:\.md)?$/.exec(o);a&&!y.test(o)&&(o=`${a[1]}/reports/${a[2]}`);const r=l?.readable??(p=>I(t,e,p)),d=x(t,o);if(d&&r(d))return d.deleted_at?{deleted:d}:{object:d};const N=l?.view??H(t,e);for(const p of N){const i=E(t,p,o,!1).find(r);if(i)return{object:i}}const c=y.exec(o),O=o.indexOf("/");if(c||O>0){const p=c?c[2]:o.slice(0,O),i=c?c[3]:o.slice(O+1),m=M(t,p,c?.[1]),D=u(n=>{const f=N.findIndex(g=>g.rowid===n.rowid);return f<0?1/0:f},"rank"),S=m.filter(n=>D(n)<1/0).sort((n,f)=>D(n)-D(f));for(const n of S){const f=E(t,n,i,!1).find(r);if(f)return{object:f}}const R=m.flatMap(n=>E(t,n,i,!1)).filter(r);if(R.length===1)return{object:R[0]};if(R.length>1)return{ambiguous:R};const j=m.flatMap(n=>E(t,n,i,!0)).find(r);return j?{deleted:j}:!c&&m.length===0&&L(p)?{remote:o}:{missing:!0}}for(const p of N){const i=E(t,p,o,!0).find(r);if(i)return{deleted:i}}return{missing:!0}}u(v,"resolveName");export{b as HANDLE_TYPES,M as ownersByHandle,v as resolveName,H as viewOf};

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

@@ -0,0 +1,62 @@
+import type { DatabaseSync } from 'node:sqlite';
+import type { ObjectRow, Privacy, Reader } from './types.js';
+export type OwnerType = 'person' | 'app' | 'repo' | 'profile';
+export declare function getById(db: DatabaseSync, id: string): ObjectRow | null;
+export declare function getByRowid(db: DatabaseSync, rowid: number): ObjectRow | null;
+export declare function createObject(db: DatabaseSync, spec: {
+    id?: string;
+    type: string;
+    kind: string | null;
+    owner: number | null;
+    privacy: Privacy;
+    name: string;
+    preview: string;
+}): ObjectRow;
+/** 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: DatabaseSync, type: OwnerType, scheme: string, externalId: string, handle: string, owner?: ObjectRow): 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: DatabaseSync, profileId: string, handle: string): boolean;
+/** The owner object of a node grantee: `user:local` → person `user`; `app:<x>` → app `<x>`. */
+export declare function ownerForGrantee(db: DatabaseSync, grantee: string): ObjectRow;
+/** The owner's live document named `name`, or null. */
+export declare function liveDocumentNamed(db: DatabaseSync, owner: number, name: string): ObjectRow | null;
+export declare function nodeObject(db: DatabaseSync, nodeId: string): ObjectRow;
+export declare function setObjectName(db: DatabaseSync, object: ObjectRow, name: string): void;
+export declare function setObjectKind(db: DatabaseSync, object: ObjectRow, kind: string | null): void;
+export interface ObjectFilter {
+    type?: string;
+    kind?: string;
+    owner?: ObjectRow;
+    privacy?: Privacy;
+    name?: string;
+    deleted?: boolean;
+}
+export interface Page {
+    limit?: number;
+    after_rowid?: number;
+}
+/** Objects the reader can read, in rowid order. Records nothing. `limit` ≤ 100. */
+export declare function listObjects(db: DatabaseSync, reader: Reader, filter: ObjectFilter, page?: Page): ObjectRow[];
+export interface SearchQuery {
+    text: string;
+    body?: boolean;
+    grep?: boolean;
+}
+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: DatabaseSync, reader: Reader, query: SearchQuery): SearchHit[];