@north-light/cli 0.0.0-stage → 0.3.413

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

@@ -0,0 +1,76 @@
+import type { DatabaseSync } from 'node:sqlite';
+import { type Scope } from '@north-light/identity';
+import type { ProviderDependency } from '../../api/dto/grants.js';
+export interface GrantScope {
+    scope: string;
+    mode: 'always' | 'ask';
+}
+export type GrantDependencies = Record<string, ProviderDependency>;
+export interface GrantRecord {
+    id: string;
+    runtime: string;
+    sub: string;
+    grantee: string;
+    rev: number;
+    scopes: GrantScope[];
+    resolved_scopes: GrantScope[];
+    spend_cap: number | null;
+    expires_at: string | null;
+    status: 'active' | 'revoked' | 'removed';
+    revoked_at: string | null;
+    approved_at: string | null;
+    payer: 'user' | 'app' | null;
+    /** The directory's setup entry (`{ state, message?, next }`) per provider the grantee requires. Absent (an older directory) reads as `{}`. */
+    dependencies?: GrantDependencies;
+    /** The grantee's registered run-notice endpoint (https), or null: runs of this grant send no notice. */
+    run_notice_url?: string | null;
+    synced_at: string;
+}
+export interface ActiveGrant extends GrantRecord {
+    resolved: Scope[];
+}
+/** The `dependencies` a grant sync answer carried. Advisory data, so a missing or
+ *  malformed value never fails the sync (which also carries every grant's
+ *  authorization): absent or non-object reads as `{}`, and a malformed entry
+ *  (see `dependencyOf`) is dropped. A directory older than the Context stage sends none. */
+export declare function dependenciesOf(value: unknown): GrantDependencies;
+/** Every mirrored grant, whatever its status. */
+export declare function allGrants(): GrantRecord[];
+/** The active form of a grant record read earlier, or null when it is not active or unparsable. */
+export declare function activeRecord(grant: GrantRecord): ActiveGrant | null;
+/** `grant.get`'s `version`: an opaque string that changes exactly when what an app
+ *  reads from its grant changes — `rev`, `resolved_scopes` (order kept), `spend_cap`,
+ *  `payer`, `dependencies`. `synced_at` and the token's claims are left out, so a
+ *  periodic sync with the same content (or a daemon restart) keeps it. */
+export declare function grantVersion(grant: Pick<GrantRecord, 'rev' | 'resolved_scopes' | 'spend_cap' | 'payer' | 'dependencies'>): string;
+export declare function hasGrant(grantId: string): boolean;
+/** The grant state the freshness ordering reads (contract 1 "Grant sync"):
+ *  the mirrored grant's revision and status, whatever its status. */
+export interface GrantSyncState {
+    rev: number;
+    status: GrantRecord['status'];
+}
+/** The mirrored state of grant `grantId`, or null when the mirror lacks it. */
+export declare function grantSyncState(grantId: string): GrantSyncState | null;
+/** The mirrored state of the grant `sub` gave `grantee`, whatever its status, or null when the mirror lacks it. */
+export declare function grantSyncStateFor(grantee: string, sub: string): GrantSyncState | null;
+export declare function activeGrant(grantId: string): ActiveGrant | null;
+export declare function grantFor(grantee: string, sub: string): ActiveGrant | null;
+export declare function activeGrantForApp(grantee: string): ActiveGrant | null;
+/** Where a run's notice goes: its grant's registered `run_notice_url`, with the grant's `sub` and `grantee`. Null when the run has no active grant or the grantee registered no URL. */
+export declare function runNoticeTarget(grantId: string): {
+    url: string;
+    sub: string;
+    grantee: string;
+} | null;
+export declare function terminalGrant(): ActiveGrant | null;
+export declare function hasSyncedGrants(source: string): boolean;
+/** OWN-11 for a joined runtime: the unjoined runtime's local mirror grants
+ *  `user:local` full local scopes and is not the directory's. Delete it so no
+ *  grant exists until grant sync installs the directory's mirror. */
+export declare function dropLocalGrantMirror(db: DatabaseSync): number;
+/** The directory response is complete; commit it or keep the prior snapshot intact. */
+export declare function replaceGrants(grants: readonly GrantRecord[], syncedAt: string, source: string): void;
+/** Bumped by every `replaceGrants`. A launch compiled against one generation
+ *  and started under another may hold mounts the new mirror no longer grants. */
+export declare function grantsGeneration(): number;

package/dist/core/grants/mirror.js

@@ -0,0 +1,4 @@
+var g=Object.defineProperty;var r=(e,t)=>g(e,"name",{value:t,configurable:!0});import{createHash as _}from"node:crypto";import{prepared as s}from"../sqlite-statements.js";import{parseScope as y}from"@north-light/identity";import{openDb as i,withCanvasWrite as S}from"../canvas/db.js";const v=["not_started","pending","ready","failed"];function c(e){if(!Array.isArray(e))throw new TypeError("grant scopes must be a list");return e.map(t=>{if(!t||typeof t!="object"||typeof t.scope!="string"||!["always","ask"].includes(t.mode))throw new TypeError("invalid grant scope entry");return{scope:t.scope,mode:t.mode}})}r(c,"entries");function T(e){if(!e||typeof e!="object"||Array.isArray(e))return null;const{state:t,message:o,next:u}=e;return typeof t!="string"||!v.includes(t)||o!==void 0&&typeof o!="string"||typeof u!="string"||!u?null:{state:t,...o===void 0?{}:{message:o},next:u}}r(T,"dependencyOf");function l(e){if(!e||typeof e!="object"||Array.isArray(e))return{};const t={};for(const[o,u]of Object.entries(e)){const n=T(u);n&&(t[o]=n)}return t}r(l,"dependenciesOf");function E(e){return{id:e.id,runtime:e.runtime,sub:e.sub,grantee:e.grantee,rev:e.rev,scopes:c(JSON.parse(e.scopes_json)),resolved_scopes:c(JSON.parse(e.resolved_scopes_json)),spend_cap:e.spend_cap,expires_at:e.expires_at,status:e.status,revoked_at:e.revoked_at,approved_at:e.approved_at,payer:e.payer,dependencies:l(JSON.parse(e.dependencies_json)),run_notice_url:e.run_notice_url??null,synced_at:e.synced_at}}r(E,"record");function p(e){if(!e||e.status!=="active")return null;try{return m(E(e))}catch(t){if(t instanceof TypeError||t instanceof SyntaxError)return null;throw t}}r(p,"active");function h(){return s(i(),"SELECT * FROM grants").all().flatMap(e=>{try{return[E(e)]}catch(t){if(t instanceof TypeError||t instanceof SyntaxError)return[];throw t}})}r(h,"allGrants");function m(e){if(e.status!=="active")return null;try{const t=e.resolved_scopes.map(({scope:o})=>y(o));return{...e,resolved:e.resolved_scopes.flatMap(({mode:o},u)=>o==="always"?[t[u]]:[])}}catch(t){if(t instanceof TypeError||t instanceof SyntaxError)return null;throw t}}r(m,"activeRecord");function d(e){return Array.isArray(e)?`[${e.map(d).join(",")}]`:e&&typeof e=="object"?`{${Object.keys(e).sort().filter(t=>e[t]!==void 0).map(t=>`${JSON.stringify(t)}:${d(e[t])}`).join(",")}}`:JSON.stringify(e)??"null"}r(d,"canonicalJson");function L(e){const t={rev:e.rev,resolved_scopes:e.resolved_scopes,spend_cap:e.spend_cap,payer:e.payer,dependencies:e.dependencies??{}};return _("sha256").update(d(t)).digest("base64url").slice(0,22)}r(L,"grantVersion");function F(e){return!!s(i(),"SELECT 1 FROM grants WHERE id = ?").get(e)}r(F,"hasGrant");function C(e){return s(i(),"SELECT rev, status FROM grants WHERE id = ?").get(e)??null}r(C,"grantSyncState");function M(e,t){return s(i(),"SELECT rev, status FROM grants WHERE grantee = ? AND sub = ?").get(e,t)??null}r(M,"grantSyncStateFor");function b(e){return p(s(i(),"SELECT * FROM grants WHERE id = ?").get(e))}r(b,"activeGrant");function j(e,t){return p(s(i(),"SELECT * FROM grants WHERE grantee = ? AND sub = ?").get(e,t))}r(j,"grantFor");function k(e){const t=s(i(),"SELECT * FROM grants WHERE grantee = ? AND status = 'active'").all(e);if(t.length>1)throw new Error(`multiple active grants for ${e}`);return p(t[0])}r(k,"activeGrantForApp");function D(e){const t=s(i(),"SELECT run_notice_url AS url, sub, grantee FROM grants WHERE id = ? AND status = 'active'").get(e);return t&&t.url?{url:t.url,sub:t.sub,grantee:t.grantee}:null}r(D,"runNoticeTarget");function H(){const e=s(i(),"SELECT * FROM grants WHERE grantee = 'app:terminal' AND status = 'active'").all();if(e.length>1)throw new Error("multiple active terminal grants");return p(e[0])}r(H,"terminalGrant");function W(e){return s(i(),"SELECT value FROM runtime_state WHERE key = 'grants_source'").get()?.value===e}r(W,"hasSyncedGrants");function G(e){return s(e,"SELECT value FROM runtime_state WHERE key = 'grants_source'").get()?.value!=="local"?0:(s(e,"DELETE FROM runtime_state WHERE key = 'grants_source'").run(),Number(s(e,"DELETE FROM grants").run().changes))}r(G,"dropLocalGrantMirror");function I(e,t,o){const u=new Set;for(const n of e){if(u.has(n.id)||!n.id||!n.runtime||!n.sub||!n.grantee||!Number.isInteger(n.rev)||!["active","revoked","removed"].includes(n.status))throw new TypeError("invalid grant sync response");u.add(n.id),c(n.scopes),c(n.resolved_scopes)}S(n=>{n.exec("DELETE FROM grants");const f=s(n,`INSERT INTO grants
+      (id, runtime, sub, grantee, rev, scopes_json, resolved_scopes_json, spend_cap, expires_at,
+       status, revoked_at, approved_at, payer, dependencies_json, run_notice_url, synced_at)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`);for(const a of e)f.run(a.id,a.runtime,a.sub,a.grantee,a.rev,JSON.stringify(a.scopes),JSON.stringify(a.resolved_scopes),a.spend_cap,a.expires_at,a.status,a.revoked_at,a.approved_at,a.payer,JSON.stringify(l(a.dependencies)),a.run_notice_url??null,a.synced_at);s(n,"INSERT INTO runtime_state (key, value) VALUES ('grants_source', ?) ON CONFLICT(key) DO UPDATE SET value = excluded.value").run(o),s(n,"INSERT INTO runtime_state (key, value) VALUES ('grants_generation', '1') ON CONFLICT(key) DO UPDATE SET value = CAST(CAST(value AS INTEGER) + 1 AS TEXT)").run()})}r(I,"replaceGrants");function J(){const e=s(i(),"SELECT value FROM runtime_state WHERE key = 'grants_generation'").get();return e?Number(e.value):0}r(J,"grantsGeneration");export{b as activeGrant,k as activeGrantForApp,m as activeRecord,h as allGrants,l as dependenciesOf,G as dropLocalGrantMirror,j as grantFor,C as grantSyncState,M as grantSyncStateFor,L as grantVersion,J as grantsGeneration,F as hasGrant,W as hasSyncedGrants,I as replaceGrants,D as runNoticeTarget,H as terminalGrant};

package/dist/core/grants/on-sync.d.ts

@@ -0,0 +1,22 @@
+import type { SandboxRecord } from '../../launcher/spec.js';
+import { type GrantRecord } from './mirror.js';
+/** Work that outlives the sync that started it; the daemon keeps ownership of it during shutdown. */
+export type Detach = (work: Promise<void>) => void;
+/** Why a sandbox must stop under the current mirror, or null when every
+ *  granted mount it was launched with is still granted. */
+export declare function exceeds(sandbox: Pick<SandboxRecord, 'uid' | 'nodeId' | 'mounts'>, owners?: ReadonlyMap<number, {
+    app: string;
+    status: string;
+}>): string | null;
+/** R26 from current state (runtime spec §15 "Ending revoked file access"):
+ *  compare every live launcher sandbox's launched mounts with what the current
+ *  mirror grants, and stop each one that holds more. Runs after every sync and
+ *  once at daemon start, so a stop an earlier daemon never confirmed is retried.
+ *  Resolves once every stop has been started; `completion` settles when they end. */
+export declare function sweepSandboxes(): Promise<{
+    completion: Promise<void>;
+}>;
+/** R26 and R27 after a sync replaced the grant mirror (runtime spec §15).
+ *  Resolves once streams are closed and the sweep's stops have started; stop
+ *  completion and removal cascades continue as detached work. */
+export declare function onGrantSync(before: readonly GrantRecord[], detach?: Detach): Promise<void>;

package/dist/core/grants/on-sync.js

@@ -0,0 +1 @@
+var b=Object.defineProperty;var p=(o,r)=>b(o,"name",{value:r,configurable:!0});import{prepared as m}from"../sqlite-statements.js";import{relative as h,sep as v}from"node:path";import{activeBackgroundBashJobs as x,readJobPgid as S}from"../bash-jobs.js";import{appSpace as y}from"../layout.js";import{getNode as f,recordSettledTurn as k}from"../canvas/index.js";import{transition as E}from"../runtime/lifecycle.js";import{openDb as _}from"../canvas/db.js";import{contextDir as R}from"../canvas/node-agent-paths.js";import{emitEvent as c}from"../events/emit.js";import{closeGrantStreams as G}from"../runs/events.js";import{grantedMounts as P,isGrantedSource as C,mountAllowed as T}from"../spaces/mounts.js";import{permissionsForRun as g}from"../spaces/permissions.js";import{stopNodeSandboxes as M}from"../spaces/stop.js";import{discardChangedGrantTokens as O}from"../providers/token-cache.js";import{activeGrantForApp as A,allGrants as D}from"./mirror.js";import{runRemovalCascades as N}from"./remove.js";import{notifyGrantChanges as F}from"./watch.js";import{launcherPresent as I,listSandboxes as W,stopSandboxPid as j}from"./sandboxes.js";function w(){return new Map(m(_(),"SELECT uid, app, status FROM app_users").all().map(o=>[o.uid,{app:o.app,status:o.status}]))}p(w,"appUserOwners");function B(o,r=w()){const e=r.get(o.uid);if(!e||e.app==="app:terminal")return null;if(e.status!=="active")return"app_removed";const s=f(o.nodeId);try{let t;if(s&&s.grantee===e.app)t=g(e.app,s.sub??"user:local",s.grant_id??null,s.scopes??null);else{const i=A(e.app);if(!i)return"permission_revoked";t=g(e.app,i.sub,i.id,null)}const n=P(t),a=y(e.app).root;return o.mounts.every(i=>{const l=h(a,i.source);return l===""||l!==".."&&!l.startsWith(`..${v}`)&&!l.startsWith(v)||!C(e.app,i.source)||T(i,n)})?null:"permission_revoked"}catch{return"permission_revoked"}}p(B,"exceeds");async function J(o){const r=f(o);if(!r)return;(r.status==="active"||r.status==="idle")&&E(o,"release");const e=new Date().toISOString();k(o,e),r.run_id&&r.run_id!==o&&m(_(),"UPDATE nodes SET last_settled_at = COALESCE(last_settled_at, ?) WHERE node_id = ?").run(e,r.run_id)}p(J,"afterRevocationStop");function L(o){const r=new Set,e=f(o);e?.pi_pid!=null&&r.add(e.pi_pid);try{const s=R(o,e?.grantee);for(const t of x(s,!0)){const n=S(s,t.jobId);n!==void 0&&r.add(n)}}catch{}return r}p(L,"nodePids");async function U(){if(!I())return{completion:Promise.resolve()};const o=await W(),r=w(),e=o.flatMap(n=>{const a=B(n,r);return a?[{sandbox:n,reason:a}]:[]}),s=[],t=new Map;for(const n of e){c({level:"info",event:"daemon.grants.sandbox_stop",fields:{sandbox_node:n.sandbox.nodeId,pid:n.sandbox.pid,grantee:r.get(n.sandbox.uid).app,reason:n.reason}});const a=t.get(n.sandbox.nodeId)??[];a.push(n),t.set(n.sandbox.nodeId,a)}for(const[n,a]of t){const i=f(n),l=i?L(n):new Set,u=i!==null&&a.some(({sandbox:d})=>l.has(d.pid));s.push((async()=>{if(u){const d=await M(n,"permission_revoked",{holdRecovery:!0,after:p(()=>J(n),"after")});if(!d.confirmed)throw d.error??new Error(`stop of ${n} was not confirmed`)}for(const{sandbox:d}of a)(!u||!l.has(d.pid))&&await j(d.pid)})().catch(d=>{c({level:"error",event:"daemon.grants.sandbox_stop_failed",...i?{node_id:n}:{fields:{sandbox_node:n}},error:d})}))}return{completion:Promise.all(s).then(()=>{})}}p(U,"sweepSandboxes");function $(o,r){try{const{pairs:e,tokens:s}=O(o,r);e&&c({level:"info",event:"daemon.grants.outbound_tokens_discarded",fields:{grants:e,tokens:s}})}catch(e){c({level:"error",event:"daemon.grants.outbound_tokens_discard_failed",error:e})}}p($,"discardOutboundTokens");async function ce(o,r=e=>{}){const e=D();try{F(o,e)}catch(t){c({level:"error",event:"daemon.grants.notify_failed",error:t})}$(o,e);for(const t of o){if(t.status!=="active"||e.find(i=>i.id===t.id)?.status==="active")continue;const a=G(t.id);a&&c({level:"info",event:"daemon.grants.streams_closed",fields:{grant:t.id,grantee:t.grantee,streams:a}})}try{const{completion:t}=await U();r(t)}catch(t){c({level:"error",event:"daemon.grants.sweep_failed",error:t})}const s=new Set(e.filter(t=>t.status==="removed"&&o.find(n=>n.id===t.id)?.status!=="removed").map(t=>t.grantee));r(N(s).catch(()=>{})),r(import("../providers/bundles.js").then(({syncProviderBundles:t})=>t()).catch(t=>{c({level:"error",event:"daemon.providers.bundle_sync_failed",error:t})}))}p(ce,"onGrantSync");export{B as exceeds,ce as onGrantSync,U as sweepSandboxes};

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

@@ -0,0 +1,7 @@
+/** Run the removal cascade for every `removed` grant whose app still has an
+ *  active OS-user row, and once for each app in `transitions` (its grant became
+ *  `removed` at this sync) even with no row. Serialized; each cascade is
+ *  idempotent and marks the row `removed` last, so an interrupted one resumes. */
+export declare function runRemovalCascades(transitions?: ReadonlySet<string>): Promise<void>;
+/** Runtime spec §15 "On removal" (design flow 10). Audit and usage rows stay. */
+export declare function removeApp(app: string): Promise<void>;

package/dist/core/grants/remove.js

@@ -0,0 +1 @@
+var S=Object.defineProperty;var m=(r,i)=>S(r,"name",{value:i,configurable:!0});import{prepared as d}from"../sqlite-statements.js";import{rmSync as h}from"node:fs";import{join as w}from"node:path";import{deleteNodes as O}from"../canvas/canvas.js";import{openDb as c,withCanvasWrite as E}from"../canvas/db.js";import{cancelCron as T}from"../canvas/crons.js";import{emitEvent as l}from"../events/emit.js";import{appSpace as C,appsRoot as u,secretsDir as D}from"../layout.js";import{notifyRunDeleted as L}from"../runs/events.js";import{cancelOpenQuestions as W}from"../runs/questions.js";import{removeTreeBeneath as F}from"../spaces/open-beneath.js";import{markGranteeUploadsDeletePending as H,releaseRunUploads as N,turnSharesOffFor as M}from"../storage/tables.js";import{stopNodeSandboxes as b}from"../spaces/stop.js";import{activeAppUser as p,markAppUserRemoved as I}from"../spaces/users.js";import{launcherRequest as y}from"../../launcher/client.js";import{LaunchRefused as A}from"../../launcher/spec.js";import{allGrants as P}from"./mirror.js";import{launcherPresent as g,listSandboxes as U,stopSandboxPid as $}from"./sandboxes.js";let v=Promise.resolve();function ae(r=new Set){const i=v.then(async()=>{const t=P(),o=new Set(t.filter(n=>n.status==="removed").map(n=>n.grantee));for(const n of o)if(!t.some(a=>a.grantee===n&&a.status==="active")&&!(p(n)===null&&!r.has(n)))try{await x(n)}catch(a){l({level:"error",event:"daemon.grants.removal_failed",error:a,fields:{grantee:n}})}});return v=i.catch(()=>{}),i}m(ae,"runRemovalCascades");async function x(r){if(r==="app:terminal")throw new Error("app:terminal cannot be removed");const i=C(r),t=p(r);l({level:"info",event:"daemon.grants.removal_started",fields:{grantee:r,uid:t?.uid??null}}),await W({grantee:r},"the app was removed");const o=E(e=>(d(e,"UPDATE nodes SET deleting_at = COALESCE(deleting_at, ?) WHERE node_id IN (SELECT node_id FROM node_rows WHERE grantee = ?)").run(new Date().toISOString(),r),d(e,"SELECT node_id FROM node_rows WHERE grantee = ? ORDER BY created DESC").all(r).map(s=>s.node_id)));for(const{cron_id:e}of d(c(),"SELECT cron_id FROM crons WHERE grantee = ?").all(r))T(e);const a=(await Promise.all(o.map(e=>b(e,"app_removed",{deleting:!0})))).filter(e=>!e.confirmed);if(a.length)throw new Error(`sandbox teardown could not be confirmed for ${a.length} node(s) of ${r}`);if(t&&g())for(const e of await U())e.uid===t.uid&&await $(e.pid);const R=o.filter(e=>d(c(),"SELECT run_id FROM nodes WHERE node_id = ?").get(e)?.run_id===e);E(e=>{if(M(r,e),N(o,e),H(r,e),!o.length)return;const s=o.map(()=>"?").join(","),_=e.prepare(`SELECT message_id FROM messages WHERE sender_node_id IN (${s}) UNION SELECT message_id FROM deliveries WHERE destination_id IN (${s})`).all(...o,...o);e.prepare(`DELETE FROM deliveries WHERE destination_id IN (${s})`).run(...o);for(const{message_id:f}of _)d(e,"DELETE FROM messages WHERE message_id = ? AND NOT EXISTS (SELECT 1 FROM deliveries WHERE message_id = ?)").run(f,f)}),O(o);for(const e of R)L(e);if(h(w(D(),"env",i.root.slice(u().length+1)),{recursive:!0,force:!0}),F(u(),i.root),t&&g())try{await y({operation:"user.delete",uid:t.uid})}catch(e){if(!(e instanceof A&&e.refusal==="invalid_uid"))throw e}t&&I(t.uid),l({level:"info",event:"daemon.grants.removal_completed",fields:{grantee:r,uid:t?.uid??null,nodes:o.length}})}m(x,"removeApp");export{x as removeApp,ae as runRemovalCascades};

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

@@ -0,0 +1,7 @@
+import { type SandboxRecord } from '../../launcher/spec.js';
+/** App sandboxes exist only where the root launcher runs (Linux). */
+export declare function launcherPresent(): boolean;
+/** Every live launcher sandbox with the mounts it was launched with. */
+export declare function listSandboxes(): Promise<SandboxRecord[]>;
+/** Kill one launcher sandbox. A pid the launcher no longer knows has already exited. */
+export declare function stopSandboxPid(pid: number): Promise<void>;

package/dist/core/grants/sandboxes.js

@@ -0,0 +1 @@
+var e=Object.defineProperty;var r=(n,o)=>e(n,"name",{value:o,configurable:!0});import{existsSync as s}from"node:fs";import{launcherRequest as t}from"../../launcher/client.js";import{LAUNCHER_SOCKET as i,LaunchRefused as a}from"../../launcher/spec.js";function l(){return process.platform==="linux"&&s(i)}r(l,"launcherPresent");async function d(){const n=await t({operation:"list"});if(!("sandboxes"in n))throw new Error("launcher did not list sandboxes");return n.sandboxes}r(d,"listSandboxes");async function x(n){try{await t({operation:"stop",pid:n,signal:"SIGKILL"})}catch(o){if(!(o instanceof a&&o.refusal==="invalid_spec"))throw o}}r(x,"stopSandboxPid");export{l as launcherPresent,d as listSandboxes,x as stopSandboxPid};

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

@@ -0,0 +1,40 @@
+import { type JsonWebKey } from 'node:crypto';
+import { type Detach } from './on-sync.js';
+export declare const GRANT_SYNC_INTERVAL_S = 300;
+export interface RuntimeClient {
+    jwk: JsonWebKey & {
+        kid: string;
+    };
+    kid: string;
+    alg: 'ES256';
+    client_id: string;
+    runtime: string;
+}
+/** A `private_key_jwt` client assertion for `endpoint` (the directory's token endpoint), signed by the runtime client key. */
+export declare function assertion(client: RuntimeClient, endpoint: string): string;
+export declare function runtimeClient(): RuntimeClient;
+/** The runtime's id as storage names it: the directory principal id without `runtime:`. */
+export declare function runtimeId(client?: RuntimeClient): string;
+export interface DirectoryToken {
+    access_token: string;
+    expires_at: number;
+}
+/** A `client_credentials` token for the runtime client. With `audience`, the
+ *  directory issues it for that audience (the storage service); without, for
+ *  the directory's own `/v1`. `expires_at` is epoch ms. */
+export declare function mintDirectoryToken(issuer: string, audience?: string): Promise<DirectoryToken>;
+export type GrantSync = (options?: {
+    fresh?: boolean;
+}) => Promise<void>;
+/** Ask the daemon's grant sync (the latest `createGrantSync`) for a pull; a
+ *  no-op where none exists (v0, a process that is not the daemon). */
+export declare function requestGrantSync(options?: {
+    fresh?: boolean;
+}): Promise<void>;
+/** Calls share one in-flight pull, including the start, periodic, and
+ *  unknown-grant triggers. A `fresh` call (a directory sync notice) needs a pull
+ *  that started after it arrived: while one is in flight it queues exactly one
+ *  more, which every later fresh call shares. A pull resolves once the mirror is
+ *  committed and the R26 stops have started; stop completion and removal
+ *  cascades run as `detach`ed work. */
+export declare function createGrantSync(issuer: string, detach?: Detach): GrantSync;

package/dist/core/grants/sync.js

@@ -0,0 +1 @@
+var k=Object.defineProperty;var o=(t,r)=>k(t,"name",{value:r,configurable:!0});import{createPrivateKey as w,randomUUID as h,sign as v}from"node:crypto";import{readFileSync as S}from"node:fs";import{join as b}from"node:path";import{crtrHome as E}from"../canvas/paths.js";import{emitEvent as l}from"../events/emit.js";import{allGrants as j,dependenciesOf as x,replaceGrants as A}from"./mirror.js";import{onGrantSync as $}from"./on-sync.js";const U=300;function T(t,r){const e=Math.floor(Date.now()/1e3),i=Buffer.from(JSON.stringify({alg:"ES256",typ:"JWT",kid:t.kid})).toString("base64url"),a=Buffer.from(JSON.stringify({iss:t.client_id,sub:t.client_id,aud:r,iat:e,exp:e+300,jti:h()})).toString("base64url"),n=`${i}.${a}`,s=v("sha256",Buffer.from(n),{key:w({key:t.jwk,format:"jwk"}),dsaEncoding:"ieee-p1363"});return`${n}.${s.toString("base64url")}`}o(T,"assertion");function y(){const t=JSON.parse(S(b(E(),"secrets","runtime-client.json"),"utf8"));if(!t.jwk||t.alg!=="ES256"||!t.kid||!t.client_id||!t.runtime||t.jwk.kid!==t.kid||t.jwk.kty!=="EC"||t.jwk.crv!=="P-256"||!t.jwk.d)throw new TypeError("invalid runtime client key");return t}o(y,"runtimeClient");function W(t=y()){return t.runtime.startsWith("runtime:")?t.runtime.slice(8):t.runtime}o(W,"runtimeId");async function N(t,r){const e=y(),i=`${t.replace(/\/$/,"")}/token`,a=new URLSearchParams({grant_type:"client_credentials",client_id:e.client_id,client_assertion_type:"urn:ietf:params:oauth:client-assertion-type:jwt-bearer",client_assertion:T(e,i),...r===void 0?{}:{audience:r}}),n=await fetch(i,{method:"POST",body:a,signal:AbortSignal.timeout(1e4)});if(!n.ok)throw new Error(`directory token request failed: ${n.status}`);const s=await n.json();if(typeof s.access_token!="string")throw new TypeError("directory token response has no access_token");return{access_token:s.access_token,expires_at:G(s.access_token,s.expires_in)}}o(N,"mintDirectoryToken");function G(t,r){if(typeof r=="number"&&Number.isFinite(r)&&r>0)return Date.now()+r*1e3;try{const e=JSON.parse(Buffer.from(t.split(".")[1]??"","base64url").toString("utf8"));if(typeof e.exp=="number")return e.exp*1e3}catch{}return Date.now()+3e5}o(G,"tokenExpiry");function O(t,r){if(!t||typeof t!="object")throw new TypeError("invalid grant sync response");const e=t;if(e.runtime!==(r.runtime.startsWith("runtime:")?r.runtime:`runtime:${r.runtime}`)||typeof e.id!="string"||typeof e.sub!="string"||typeof e.grantee!="string"||!Number.isInteger(e.rev)||!Array.isArray(e.scopes)||!Array.isArray(e.resolved_scopes)||!["active","revoked","removed"].includes(e.status??"")||typeof e.synced_at!="string")throw new TypeError("invalid grant sync response");const a=t.revisions?.find(n=>n.rev===e.rev)?.approved_at;if(typeof a!="string")throw new TypeError("grant revision has no approval time");return{...e,spend_cap:e.spend_cap??null,expires_at:e.expires_at??null,revoked_at:e.revoked_at??null,approved_at:a,payer:"user",dependencies:x(e.dependencies),run_notice_url:typeof e.run_notice_url=="string"&&e.run_notice_url!==""?e.run_notice_url:null}}o(O,"responseGrant");let m;function L(t){return m?m(t):Promise.resolve()}o(L,"requestGrantSync");function z(t,r=e=>{}){let e;const i=t.replace(/\/$/,""),a=o(async()=>{const c=y(),p=await N(i),f=await fetch(`${i}/v1/runtime/grants`,{headers:{Authorization:`Bearer ${p.access_token}`},signal:AbortSignal.timeout(1e4)});if(!f.ok)throw new Error(`directory grant sync failed: ${f.status}`);const u=await f.json();if(!Array.isArray(u.grants)||typeof u.synced_at!="string")throw new TypeError("invalid grant sync response");const g=j();A(u.grants.map(d=>O(d,c)),u.synced_at,i),l({level:"info",event:"daemon.grants.synced",fields:{grants:u.grants.length,synced_at:u.synced_at}});try{await $(g,r)}catch(d){l({level:"error",event:"daemon.grants.on_sync_failed",error:d})}},"run");let n;const s=o(()=>{const c=a().catch(p=>{throw l({level:"error",event:"daemon.grants.sync_failed",error:p}),p}).finally(()=>{e===c&&(e=void 0)});return e=c,c},"start"),_=o((c={})=>e?c.fresh?(n??=e.catch(()=>{}).then(()=>(n=void 0,e??s())),n):e:s(),"sync");return m=_,_}o(z,"createGrantSync");export{U as GRANT_SYNC_INTERVAL_S,T as assertion,z as createGrantSync,N as mintDirectoryToken,L as requestGrantSync,y as runtimeClient,W as runtimeId};

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

@@ -0,0 +1,14 @@
+import { type GrantRecord } from './mirror.js';
+/** Resolve when grant `grantId` is notified, or after `seconds`. Register it in the
+ *  same synchronous block that read the mirror, so no notify falls between the read
+ *  and the registration. The timer is unref'd: a held request never keeps the
+ *  process alive. */
+export declare function waitGrantChange(grantId: string, seconds: number): Promise<void>;
+/** Wake the long-polls of every grant whose `grant.get` answer this sync changed:
+ *  it left (or reached) `active`, or its version differs. Never triggers a sync. */
+export declare function notifyGrantChanges(before: readonly GrantRecord[], after: readonly GrantRecord[]): void;
+/** The app listener is closing: drop every held long-poll and its timer. Its
+ *  socket is being destroyed, so nothing is answered. */
+export declare function releaseGrantWaiters(): void;
+/** Held long-polls, for tests. */
+export declare function grantWaiterCount(): number;

package/dist/core/grants/watch.js

@@ -0,0 +1 @@
+var u=Object.defineProperty;var s=(e,t)=>u(e,"name",{value:t,configurable:!0});import{grantVersion as c}from"./mirror.js";const o=new Map;function f(e,t){const i=o.get(e);i&&(i.delete(t),i.size||o.delete(e))}s(f,"release");function m(e,t){return new Promise(i=>{const r={wake:s(()=>{clearTimeout(n),f(e,r),i()},"wake"),cancel:s(()=>{clearTimeout(n),f(e,r)},"cancel")},n=setTimeout(r.wake,t*1e3);n.unref();let a=o.get(e);a||o.set(e,a=new Set),a.add(r)})}s(m,"waitGrantChange");function l(e,t){const i=e?.status==="active",r=t?.status==="active";return i!==r?!0:r?c(e)!==c(t):!1}s(l,"changed");function v(e,t){if(!o.size)return;const i=new Map(e.map(n=>[n.id,n])),r=new Map(t.map(n=>[n.id,n]));for(const n of[...o.keys()])if(l(i.get(n),r.get(n)))for(const a of[...o.get(n)??[]])a.wake()}s(v,"notifyGrantChanges");function d(){for(const e of[...o.values()])for(const t of[...e])t.cancel();o.clear()}s(d,"releaseGrantWaiters");function g(){let e=0;for(const t of o.values())e+=t.size;return e}s(g,"grantWaiterCount");export{g as grantWaiterCount,v as notifyGrantChanges,d as releaseGrantWaiters,m as waitGrantChange};

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

@@ -0,0 +1,28 @@
+import type { DatabaseSync } from 'node:sqlite';
+import type { ObjectRow, Reader } from './types.js';
+/** The object's owners, nearest first, ending at its space; empty when the object is a space.
+ *  CROSS JOIN pins the chain as the outer loop: left to the planner, it scans every
+ *  object and probes the chain, which made each read check cost milliseconds. */
+export declare function ownerChain(db: DatabaseSync, object: ObjectRow): ObjectRow[];
+export declare function spaceOf(db: DatabaseSync, object: ObjectRow): ObjectRow;
+/** A shipped document: one a package reconciler owns, read from its package file
+ *  (`documents.source_path` is set). Only the reconciler writes it. */
+export declare function isShipped(db: DatabaseSync, object: ObjectRow): boolean;
+/** The apps whose tools a run may use, `crtr` last. On a local runtime (v0) every
+ *  installed, enabled plugin's tools are usable by every run, and an installed
+ *  plugin is exactly an app holding live shipped documents. Hosted grants narrow
+ *  this per reader later; `mayUseTools` is the one question both ask. */
+export declare function toolApps(db: DatabaseSync, reader: Reader): ObjectRow[];
+/** May `reader` use any of `app`'s tool groups? v0: every run may use every installed plugin's tools. */
+export declare function mayUseTools(_db: DatabaseSync, _reader: Reader, app: ObjectRow): boolean;
+/** Whether this reader may register, publish or watch as an object owned by `owner`. */
+export declare function mayActAs(db: DatabaseSync, reader: Reader, owner: ObjectRow): boolean;
+/** Callers turn `false` into `not_found`. A person reader reads everything. An app's
+ *  shipped documents are read by any run that may use that app's tools. */
+export declare function canRead(db: DatabaseSync, reader: Reader, object: ObjectRow): boolean;
+/** `canRead` for many readers of one object: the owner chain is walked once. */
+export declare function readCheck(db: DatabaseSync, object: ObjectRow): (reader: Reader) => boolean;
+/** Always asked of the space, also for a person: a repo never owns a non-public
+ *  document, whoever asks. A shipped document is changed by nobody, its own app
+ *  included — only the package reconciler writes it, and it asks no reader. */
+export declare function canChange(db: DatabaseSync, reader: Reader, object: ObjectRow): boolean;

package/dist/core/graph/access.js

@@ -0,0 +1,8 @@
+var l=Object.defineProperty;var n=(o,t)=>l(o,"name",{value:t,configurable:!0});import{prepared as a}from"../sqlite-statements.js";import{SPACES as d}from"./spaces/index.js";import{insideRepo as E}from"./spaces/repo.js";function f(o,t){return a(o,`WITH RECURSIVE chain(rowid, depth) AS (
+      SELECT owner, 1 FROM objects WHERE rowid = ? AND owner IS NOT NULL
+      UNION ALL
+      SELECT o.owner, c.depth + 1 FROM objects o JOIN chain c ON o.rowid = c.rowid WHERE o.owner IS NOT NULL
+    ) SELECT o.* FROM chain c CROSS JOIN objects o WHERE o.rowid = c.rowid ORDER BY c.depth`).all(t.rowid)}n(f,"ownerChain");function O(o,t){return c(o,t).space}n(O,"spaceOf");function c(o,t){const e=f(o,t),r=e.length?e[e.length-1]:t,p=d[r.type];if(!p)throw new Error(`${t.type} ${t.id} has no space: its owner chain ends at ${r.type} ${r.id}`);const i=e.length?[...e.slice(0,-1).reverse(),t]:[];return{space:r,path:i,impl:p}}n(c,"locate");function s(o,t){return t.type!=="document"?!1:a(o,"SELECT source_path FROM documents WHERE object = ?").get(t.rowid)?.source_path!=null}n(s,"isShipped");function m(o,t){return a(o,`SELECT a.* FROM objects a WHERE a.type = 'app' AND a.deleted_at IS NULL AND EXISTS (
+      SELECT 1 FROM objects o JOIN documents d ON d.object = o.rowid
+      WHERE o.owner = a.rowid AND o.type = 'document' AND o.deleted_at IS NULL AND d.source_path IS NOT NULL)
+    ORDER BY a.name = 'crtr', a.name`).all().filter(r=>u(o,t,r))}n(m,"toolApps");function u(o,t,e){return e.type==="app"}n(u,"mayUseTools");function L(o,t,e){return t.class==="person"?!0:t.class==="object"?t.owner.rowid===e.rowid:t.class==="app"?t.app.rowid===e.rowid||e.type==="profile"&&e.owner===t.app.rowid:t.app.rowid===e.rowid||e.type==="profile"&&t.profile?.rowid===e.rowid||e.type==="repo"&&E(o,t,e,"rw")}n(L,"mayActAs");function y(o,t,e){return h(o,e)(t)}n(y,"canRead");function h(o,t){let e=null,r=null;return p=>p.class==="person"||(e??=c(o,t),e.space.type==="app"&&e.path.length>0&&(r??=s(o,t),r&&u(o,p,e.space)))?!0:e.impl.canRead(o,p,e.space,e.path,t)}n(h,"readCheck");function C(o,t,e){if(s(o,e))return!1;const{space:r,path:p,impl:i}=c(o,e);return i.canChange(o,t,r,p,e)}n(C,"canChange");export{C as canChange,y as canRead,s as isShipped,L as mayActAs,u as mayUseTools,f as ownerChain,h as readCheck,O as spaceOf,m as toolApps};

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

@@ -0,0 +1,6 @@
+/** Store a body durably (temp + fsync + rename); call before the transaction that references it. */
+export declare function put(body: string): string;
+export declare function get(hash: string): string;
+/** A revision's body: a package document's (one with a `source_path`) is its file's body after
+ *  the frontmatter; every other document's comes from the body store. */
+export declare function bodyOf(hash: string, sourcePath: string | null): string;

package/dist/core/graph/bodies.js

@@ -0,0 +1 @@
+var m=Object.defineProperty;var o=(r,t)=>m(r,"name",{value:t,configurable:!0});import{createHash as p}from"node:crypto";import{closeSync as y,existsSync as s,fsyncSync as d,mkdirSync as a,openSync as l,readFileSync as c,renameSync as S,writeSync as w}from"node:fs";import{join as f}from"node:path";import{notFound as b}from"../errors.js";import{crtrHome as x}from"../canvas/paths.js";import{parseFrontmatterGeneric as $}from"../frontmatter.js";function u(r){if(!/^[0-9a-f]{64}$/.test(r))throw new Error(`invalid body hash: ${r}`);return f(x(),"bodies",r.slice(0,2),r)}o(u,"bodyPath");function j(r){const t=p("sha256").update(r,"utf8").digest("hex"),n=u(t);if(s(n))return t;a(f(n,".."),{recursive:!0});const i=`${n}.tmp-${process.pid}`,e=l(i,"w");try{w(e,r,null,"utf8"),d(e)}finally{y(e)}return S(i,n),t}o(j,"put");function h(r){try{return c(u(r),"utf8")}catch(t){throw t.code==="ENOENT"?b(`no body ${r}`):t}}o(h,"get");function k(r,t){return t===null?h(r):$(c(t,"utf8")).body}o(k,"bodyOf");export{k as bodyOf,h as get,j as put};

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

@@ -0,0 +1,74 @@
+import type { DatabaseSync } from 'node:sqlite';
+import type { Level, ObjectRow, Reader } from './types.js';
+import { mayActAs } from './access.js';
+import { onQueueSignal } from './receivers.js';
+export { mayActAs, onQueueSignal };
+export type CustomReceiver = 'queue' | {
+    url: string;
+} | {
+    argv: string[];
+    cwd: string;
+};
+export type CustomEvents = Record<string, {
+    level: Level;
+    supersedes?: boolean;
+}>;
+export interface QueueLine {
+    delivery_id: string;
+    message_id: string;
+    seq: number;
+    event: string;
+    level: number;
+    object: {
+        id: string;
+        type: string;
+        name: string;
+        owner: string | null;
+    };
+    actor: string | null;
+    attrs: Record<string, unknown>;
+    summary?: string;
+    state?: unknown;
+    pointer?: string;
+    depth: number;
+    created_at: string;
+}
+/** Register a kind and a named instance in the caller's write transaction. */
+export declare function registerCustomObject(db: DatabaseSync, reader: Reader, input: {
+    kind: string;
+    name: string;
+    owner: ObjectRow;
+    description: string;
+    events: CustomEvents;
+    receiver?: CustomReceiver | null;
+    rotateToken?: boolean;
+}): {
+    object: ObjectRow;
+    token?: string;
+    created: boolean;
+    changed: string[];
+};
+export declare function publishCustom(db: DatabaseSync, object: ObjectRow, actor: ObjectRow | null, input: {
+    event: string;
+    summary: string;
+    state?: unknown;
+    cause?: string;
+}): {
+    message_id: string | null;
+    delivered: number;
+    depth: number;
+};
+export declare function unregisterCustomObject(db: DatabaseSync, object: ObjectRow, actor: ObjectRow | null): void;
+export declare function pendingFor(db: DatabaseSync, object: ObjectRow, afterSeq?: number): QueueLine[];
+/** A claimed push delivery has the identical document as a pending queue delivery. */
+export declare function pushLineFor(db: DatabaseSync, deliveryId: string): QueueLine | null;
+export declare function acknowledge(db: DatabaseSync, object: ObjectRow, deliveryIds: string[]): {
+    acknowledged: number;
+    unknown?: string[];
+};
+export declare function verifyPublishToken(db: DatabaseSync, object: ObjectRow, token: string): boolean;
+/** Run confinement for a node acting on a custom object of its app (Silas, 2026-09-30):
+ *  a node reaches an object registered in its own run, or when neither run is isolated.
+ *  An object the person or the app's server registered is reached by nodes outside
+ *  isolation only. Any other reader is unchanged. */
+export declare function customReachable(db: DatabaseSync, reader: Reader, object: ObjectRow): boolean;

package/dist/core/graph/custom.js

@@ -0,0 +1,11 @@
+var $=Object.defineProperty;var u=(e,t)=>$(e,"name",{value:t,configurable:!0});import{prepared as a}from"../sqlite-statements.js";import{objectPlace as C,runPlace as x,runsSeeEachOther as P}from"../runs/confinement.js";import{createHash as J,randomBytes as q,timingSafeEqual as F}from"node:crypto";import{CrtrError as S,usage as g}from"../errors.js";import{ExitCode as O}from"../../types.js";import{createObject as M,liveDocumentNamed as B}from"./objects.js";import{invalidateCustomKind as z}from"./kinds/registry.js";import{mayActAs as L}from"./access.js";import{publish as b,HOP_LIMIT as K,HopLimitError as G}from"./events.js";import{checkoutsForCwd as N}from"./repo-sync/repos.js";import{onQueueSignal as Q,signalQueue as R}from"./receivers.js";import{receiverEndpoint as V,isPublicReceiverAddress as Y}from"./receiver-url.js";import{isIP as X}from"node:net";const Z=/^[a-z][a-z0-9-]*\.[a-z][a-z0-9-]*$/,k=/^[a-z][a-z0-9-]*$/;function h(e,t){throw new S(e,t,O.GENERAL)}u(h,"conflict");function D(e){return J("sha256").update(e).digest("hex")}u(D,"hash");function H(){return`crtr_pub_${q(32).toString("base64url")}`}u(H,"issueToken");function ee(e){if(e==null)return null;if(e==="queue")return JSON.stringify(e);if(typeof e!="object"||Array.isArray(e))throw g("invalid custom receiver; expected queue, an https url, or argv and absolute cwd");if("url"in e&&typeof e.url=="string")try{const s=V(e.url).hostname.replace(/^\[|\]$/g,"");if(X(s)&&!Y(s))throw new Error("non-public IP address");return JSON.stringify({url:e.url})}catch(t){throw g(`invalid custom receiver: ${String(t)}`)}if("argv"in e&&Array.isArray(e.argv)&&e.argv.length>0&&e.argv.every(t=>typeof t=="string")&&typeof e.cwd=="string"&&e.cwd.startsWith("/"))return JSON.stringify(e);throw g("invalid custom receiver; url must be https and argv requires a command and absolute cwd")}u(ee,"receiverJson");function _e(e,t,s){const{kind:n,name:i,owner:o,description:r,events:l,receiver:m,rotateToken:w}=s;if(L(e,t,o)||h("forbidden",`cannot act as ${o.id}`),!Z.test(n)||["report","notice","node","job","document","person","app","repo","profile","action"].includes(n.split(".")[0]))throw g(`invalid or reserved kind ${n}`);if(!i.trim()||i!==i.trim()||i.includes("\0"))throw g(`invalid object name ${JSON.stringify(i)}`);const f=ee(m);if(m!=="queue"&&m!==null&&m!==void 0&&"argv"in m&&t.class!=="person"&&t.class!=="node"&&h("argv_forbidden","argv receiver requires a person or node principal"),Object.keys(l).length>64||Object.entries(l).some(([c,_])=>!k.test(c)||!Number.isInteger(_?.level)||_.level<1||_.level>10||_.supersedes!==void 0&&typeof _.supersedes!="boolean"))throw g("invalid custom event catalog");const d=B(e,o.rowid,i);if(d&&!te(e,t,d)&&h("forbidden",`cannot act as ${o.id}`),d&&t.class!=="person"&&t.class!=="node"){const c=a(e,"SELECT receiver_json FROM custom_objects WHERE object = ?").get(d.rowid)?.receiver_json;c&&typeof JSON.parse(c)=="object"&&"argv"in JSON.parse(c)&&h("argv_forbidden","argv receiver requires a person or node principal")}d&&d.type!==n&&h("name_taken",`${o.name}/${i} is already held by ${d.id}`);const p=a(e,"SELECT owner, description, events_json FROM object_kinds WHERE name = ?").get(n);p&&p.owner!==o.rowid&&h("kind_owned",`${n} belongs to another owner`);const T=new Date().toISOString(),v=U(l),A=p===void 0?null:U(JSON.parse(p.events_json));if(p?(p.description!==r||A!==v)&&a(e,"UPDATE object_kinds SET description = ?, events_json = ?, updated_at = ? WHERE name = ?").run(r,v,T,n):a(e,"INSERT INTO object_kinds VALUES (?, ?, ?, ?, ?, ?)").run(n,o.rowid,r,v,T,T),(!p||A!==v)&&z(e,n),!d){const c=M(e,{type:n,kind:null,owner:o.rowid,privacy:"public",name:i,preview:""}),_=H();return a(e,`INSERT INTO custom_objects (object, description, receiver_json, token_hash)
+      VALUES (?, ?, ?, ?)`).run(c.rowid,r,f,D(_)),t.class==="node"&&a(e,"UPDATE custom_objects SET registered_by = ? WHERE object = ?").run(t.node.id,c.rowid),f!==null&&a(e,"UPDATE objects SET reception = 2 WHERE rowid = ?").run(c.rowid),b(e,{event:"created",object:c,actor:t.class==="object"?t.object:t.class==="person"?t.person:t.class==="app"?t.app:t.node,attrs:{}},I=>N(e,I)),{object:c,token:_,created:!0,changed:[]}}const y=a(e,"SELECT description, receiver_json FROM custom_objects WHERE object = ?").get(d.rowid);y||h("name_taken",`${o.name}/${i} is not a custom object`);const E=[];if(y.description!==r&&E.push("description"),y.receiver_json!==f&&E.push("receiver"),p&&A!==v&&E.push("events"),p&&p.description!==r&&!E.includes("description")&&E.push("description"),w&&E.push("token"),E.length===0)return{object:d,created:!1,changed:E};const j=w?H():void 0;if(a(e,"UPDATE custom_objects SET description = ?, receiver_json = ?, token_hash = COALESCE(?, token_hash) WHERE object = ?").run(r,f,j===void 0?null:D(j),d.rowid),a(e,"UPDATE objects SET reception = ? WHERE rowid = ?").run(f===null?0:2,d.rowid),y.receiver_json!==f){const c=Date.now();if(f===null){const _=a(e,`UPDATE deliveries SET canceled_at = ?, updated_at = ?
+        WHERE destination_id = ? AND state = 'pending' AND canceled_at IS NULL`).run(c,c,d.id);a(e,"UPDATE custom_objects SET dropped = dropped + ? WHERE object = ?").run(_.changes,d.rowid)}else a(e,`UPDATE deliveries SET next_attempt_at = ?, updated_at = ?
+        WHERE destination_id = ? AND state = 'pending' AND canceled_at IS NULL`).run(f==='"queue"'?null:c,c,d.id);R(d.id)}return w&&R(d.id),b(e,{event:"configured",object:d,actor:t.class==="object"?t.object:t.class==="person"?t.person:t.class==="app"?t.app:t.node,attrs:{changed:E.join(",")}},c=>N(e,c)),{object:d,...j===void 0?{}:{token:j},created:!1,changed:E}}u(_e,"registerCustomObject");function ge(e,t,s,n){const i=a(e,"SELECT events_json FROM object_kinds WHERE name = ?").get(t.type);if(!i||t.deleted_at!==null)throw g(`${t.id} is not a live custom object`);const o=JSON.parse(i.events_json);if(!k.test(n.event)||!Object.hasOwn(o,n.event))throw new S("unknown_event",`${t.type} declares ${Object.keys(o).join(", ")}, not ${n.event}`,O.USAGE,{declared:Object.keys(o),event:n.event});if(typeof n.summary!="string")throw g("summary must be text");const r=n.state===void 0?null:JSON.stringify(n.state);if(n.state!==void 0&&r===void 0)throw g("state must be JSON-serializable");if(Buffer.byteLength(JSON.stringify({summary:n.summary,...n.state===void 0?{}:{state:n.state}}))>64*1024)throw new S("body_too_large","custom event summary and state exceed 64 KiB",O.USAGE);if(r!==null&&Buffer.byteLength(r)>64*1024)throw g("state exceeds 64 KiB");const l=n.cause??null,m=l===null?null:a(e,`SELECT depth FROM messages WHERE message_id = ?
+    UNION ALL SELECT depth FROM message_causes WHERE message_id = ? LIMIT 1`).get(l,l);if(l!==null&&m===void 0)throw new S("unknown_cause",`no message ${l}`,O.USAGE);if(m&&m.depth>=K)throw new G(m.depth+1);const w=new Date().toISOString();return a(e,"UPDATE custom_objects SET summary = ?, state_json = ?, published_at = ? WHERE object = ?").run(n.summary,r,w,t.rowid),a(e,"UPDATE objects SET preview = ? WHERE rowid = ?").run(n.summary.split(`
+`)[0],t.rowid),b(e,{event:`${t.type}.${n.event}`,object:t,actor:s,attrs:{},messageBody:{summary:n.summary,...n.state===void 0?{}:{state:n.state}},...n.cause===void 0?{}:{cause:n.cause}},f=>N(e,f))}u(ge,"publishCustom");function he(e,t,s){if(t.deleted_at!==null)return;b(e,{event:"deleted",object:t,actor:s,attrs:{}},i=>N(e,i));const n=new Date().toISOString();a(e,"UPDATE objects SET deleted_at = ?, reception = 0 WHERE rowid = ?").run(n,t.rowid),a(e,"UPDATE deliveries SET canceled_at = ?, updated_at = ? WHERE destination_id = ? AND state = 'pending' AND canceled_at IS NULL").run(Date.now(),Date.now(),t.id),R(t.id)}u(he,"unregisterCustomObject");function U(e){return JSON.stringify(Object.fromEntries(Object.entries(e).sort(([t],[s])=>t.localeCompare(s)).map(([t,s])=>[t,{level:s.level,...s.supersedes===void 0?{}:{supersedes:s.supersedes}}])))}u(U,"canonicalEvents");function we(e,t,s=0){return W(e,t.id,s,"pending")}u(we,"pendingFor");function ve(e,t){const s=a(e,"SELECT destination_id FROM deliveries WHERE delivery_id = ?").get(t);return s?W(e,s.destination_id,-1,"handed_off").find(n=>n.delivery_id===t)??null:null}u(ve,"pushLineFor");function W(e,t,s,n){return a(e,`SELECT d.delivery_id, m.message_id, m.seq, m.event, m.level, m.object_id, m.actor_id, m.body_json, m.body_ref, m.depth, m.created_at,
+    o.type, o.name, owner.id AS owner_id
+    FROM deliveries d JOIN messages m ON m.message_id = d.message_id JOIN objects o ON o.id = m.object_id
+    LEFT JOIN objects owner ON owner.rowid = o.owner
+    WHERE d.destination_id = ? AND d.state = ? AND d.canceled_at IS NULL AND m.seq > ? ORDER BY m.seq`).all(t,n,s).map(o=>{const r=o.body_json?JSON.parse(o.body_json):{};return{delivery_id:o.delivery_id,message_id:o.message_id,seq:o.seq,event:o.event,level:o.level,object:{id:o.object_id,type:o.type,name:o.name,owner:o.owner_id},actor:o.actor_id,attrs:r.push?.attrs??{},...r.summary===void 0?{}:{summary:r.summary},...r.state===void 0?{}:{state:r.state},...r.push?.pointer===void 0?{}:{pointer:r.push.pointer},depth:o.depth,created_at:o.created_at}})}u(W,"queueLines");function ye(e,t,s){const n=Date.now(),i=[];let o=0;for(const r of s){const l=a(e,`UPDATE deliveries SET state = 'acknowledged', acknowledged_at = ?, updated_at = ?
+      WHERE delivery_id = ? AND destination_id = ? AND state = 'pending' AND canceled_at IS NULL`).run(n,n,r,t.id);Number(l.changes)?o++:i.push(r)}return{acknowledged:o,...i.length?{unknown:i}:{}}}u(ye,"acknowledge");function je(e,t,s){const n=a(e,"SELECT token_hash FROM custom_objects WHERE object = ?").get(t.rowid),i=Buffer.from(n?.token_hash??"".padEnd(64,"0"),"hex"),o=Buffer.from(D(s),"hex");return s.startsWith("crtr_pub_")&&t.deleted_at===null&&i.length===o.length&&F(i,o)&&n?.token_hash!=null}u(je,"verifyPublishToken");function te(e,t,s){if(t.class!=="node")return!0;const n=x(t.node.id,e);if(n===null)return!0;const i=C(s.rowid,e);return i===null?!n.isolated:P(n,i)}u(te,"customReachable");export{ye as acknowledge,te as customReachable,L as mayActAs,Q as onQueueSignal,we as pendingFor,ge as publishCustom,ve as pushLineFor,_e as registerCustomObject,he as unregisterCustomObject,je as verifyPublishToken};

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

@@ -0,0 +1,17 @@
+/** Deleting a node with what it owns (spec §6 "Deletion follows the owner", A9). Rows are kept
+ *  with `deleted_at` so every pointer resolves to "deleted" with the last preview. A document a
+ *  live document outside the deletion links to is kept: it stays owned by the deleted node, under
+ *  its name and rules, and is collected when its last link goes (`collectUnlinked`). */
+import type { DatabaseSync } from 'node:sqlite';
+import type { ObjectRow } from './types.js';
+/** Mark the node and everything it owns deleted except kept documents, which stay owned by the
+ *  deleted node; drop the node's watches (both ends) and its `nodes` row. One savepoint, so it runs as one
+ *  transaction or inside the caller's. Refuses a node whose managed worktree is unreconciled. */
+export declare function deleteNodeWithOwned(db: DatabaseSync, node: ObjectRow): void;
+/** Delete a profile object with what it owns, in the same flow as the profile's own deletion
+ *  (`crtr profile delete`): its documents follow the node rule — deleted, except one a live document
+ *  outside the deletion links to, which stays owned by the deleted profile until its last link goes.
+ *  The object row stays with `deleted_at` (kept documents still name it); its handle is released so
+ *  a new profile can take the name, and its identity row stays so a kept document's permission
+ *  string still names the profile id. Returns whether a profile object existed for `profileId`. */
+export declare function deleteProfileWithOwned(db: DatabaseSync, profileId: string): boolean;

package/dist/core/graph/deletion.js

@@ -0,0 +1,6 @@
+var R=Object.defineProperty;var E=(e,t)=>R(e,"name",{value:t,configurable:!0});import{prepared as n}from"../sqlite-statements.js";import{hasUnreconciledWorktree as f}from"../canvas/worktrees.js";import{deleteDocument as p}from"./documents.js";import{publish as d}from"./events.js";import{getByRowid as w}from"./objects.js";import{rememberDeletedIsolated as h}from"../runs/confinement.js";let a=0;function W(e,t){if(t.type!=="node")throw new Error(`deleteNodeWithOwned: ${t.id} is a ${t.type}, not a node`);if(f(t.id))throw new Error(`refusing to delete node ${t.id}: its managed worktree is not reconciled`);const o=`graph_delete_${++a}`;e.exec(`SAVEPOINT ${o}`);try{S(e,t),e.exec(`RELEASE ${o}`)}catch(i){throw e.exec(`ROLLBACK TO ${o}`),e.exec(`RELEASE ${o}`),i}}E(W,"deleteNodeWithOwned");function j(e,t){const o=n(e,`SELECT o.* FROM identities i JOIN objects o ON o.rowid = i.object
+    WHERE i.scheme = 'profile' AND i.external_id = ? AND o.type = 'profile' AND o.deleted_at IS NULL`).get(t);if(!o)return!1;const i=`graph_delete_${++a}`;e.exec(`SAVEPOINT ${i}`);try{u(e,o),n(e,"UPDATE objects SET deleted_at = ?, name = ? WHERE rowid = ?").run(new Date().toISOString(),`${o.name}.deleted-${o.rowid}`,o.rowid),d(e,{event:"deleted",object:w(e,o.rowid),actor:null,attrs:{}}),n(e,"DELETE FROM watches WHERE object = ? OR watcher = ?").run(o.rowid,o.rowid),e.exec(`RELEASE ${i}`)}catch(s){throw e.exec(`ROLLBACK TO ${i}`),e.exec(`RELEASE ${i}`),s}return!0}E(j,"deleteProfileWithOwned");function S(e,t){const o=u(e,t);n(e,"UPDATE objects SET deleted_at = ? WHERE rowid = ?").run(o,t.rowid),d(e,{event:"deleted",object:w(e,t.rowid),actor:null,attrs:{}}),n(e,"DELETE FROM watches WHERE object = ? OR watcher = ?").run(t.rowid,t.rowid),h(t.id,e),n(e,"DELETE FROM nodes WHERE node_id = ?").run(t.id)}E(S,"deleteInside");function u(e,t){const o=n(e,`WITH RECURSIVE sub(rowid) AS (
+      SELECT rowid FROM objects WHERE owner = ?
+      UNION SELECT o.rowid FROM objects o JOIN sub ON o.owner = sub.rowid)
+    SELECT o.* FROM objects o JOIN sub ON sub.rowid = o.rowid WHERE o.deleted_at IS NULL`).all(t.rowid),i=new Set(o.map(r=>r.rowid)),s=n(e,`SELECT e.src FROM edges e JOIN objects s ON s.rowid = e.src
+    WHERE e.type = 'links-to' AND e.dst = ? AND s.deleted_at IS NULL`);for(let r=!0;r;){r=!1;for(const c of o)c.type!=="document"||!i.has(c.rowid)||s.all(c.rowid).some(({src:O})=>!i.has(O))&&(i.delete(c.rowid),r=!0)}const l=new Date().toISOString();for(const r of o)if(i.has(r.rowid)){if(r.type==="document"){p(e,null,r);continue}n(e,"UPDATE objects SET deleted_at = ? WHERE rowid = ?").run(l,r.rowid),d(e,{event:"deleted",object:w(e,r.rowid),actor:null,attrs:{}}),n(e,"DELETE FROM watches WHERE object = ? OR watcher = ?").run(r.rowid,r.rowid)}return l}E(u,"deleteOwned");export{W as deleteNodeWithOwned,j as deleteProfileWithOwned};

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

@@ -0,0 +1,4 @@
+/** Unified diff between two document texts, computed at read time. Dependency
+ *  free (an LCS over lines) — documents are small, so the
+ *  quadratic table is never a cost. */
+export declare function unifiedDiff(before: string, after: string, context?: number): string;

package/dist/core/graph/diff.js

@@ -0,0 +1,4 @@
+var b=Object.defineProperty;var m=(n,f)=>b(n,"name",{value:f,configurable:!0});function W(n,f,o=3){const{lines:l,terminated:c}=w(n),{lines:a,terminated:e}=w(f),t=K(M(l,c),M(a,e)),s=[];for(let i=0;i<t.length;i+=1){if(t[i].tag===" ")continue;const p=Math.max(0,i-o),d=Math.min(t.length,i+o+1),u=s[s.length-1];u!==void 0&&p<=u.to?u.to=Math.max(u.to,d):s.push({from:p,to:d})}if(s.length===0)return"";const r=[],N=[];let A=0,E=0;for(const i of t)r.push(A),N.push(E),i.tag!=="+"&&(A+=1),i.tag!=="-"&&(E+=1);const x=[];for(const{from:i,to:p}of s){const d=t.slice(i,p),u=d.filter(h=>h.tag!=="+").length,L=d.filter(h=>h.tag!=="-").length;x.push(`@@ -${u===0?0:r[i]+1},${u} +${L===0?0:N[i]+1},${L} @@`);for(let h=i;h<p;h+=1){const g=t[h];x.push(g.tag+(g.tag==="+"?a[g.index]:l[g.index]));const _=g.tag!=="+"&&!c&&r[h]===l.length-1,$=g.tag!=="-"&&!e&&N[h]===a.length-1;(_||$)&&x.push(j)}}return x.join(`
+`)}m(W,"unifiedDiff");const j="\",y="\0no-newline-at-eof";function M(n,f){return f||n.length===0?n:n.map((o,l)=>l===n.length-1?o+y:o)}m(M,"diffKeys");function w(n){if(n==="")return{lines:[],terminated:!0};const f=n.endsWith(`
+`),o=n.split(`
+`);return f&&o.pop(),{lines:o,terminated:f}}m(w,"toLines");function K(n,f){const o=n.length,l=f.length,c=Array.from({length:o+1},()=>new Array(l+1).fill(0));for(let s=o-1;s>=0;s-=1)for(let r=l-1;r>=0;r-=1)c[s][r]=n[s]===f[r]?c[s+1][r+1]+1:Math.max(c[s+1][r],c[s][r+1]);const a=[];let e=0,t=0;for(;e<o&&t<l;)n[e]===f[t]?(a.push({tag:" ",index:e}),e+=1,t+=1):c[e+1][t]>=c[e][t+1]?(a.push({tag:"-",index:e}),e+=1):(a.push({tag:"+",index:t}),t+=1);for(;e<o;e+=1)a.push({tag:"-",index:e});for(;t<l;t+=1)a.push({tag:"+",index:t});return a}m(K,"diffOps");export{W as unifiedDiff};

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

@@ -0,0 +1,167 @@
+/** Documents: write, CAS edit, revisions and heads, links per revision, record fields, move,
+ *  delete, history, read, and the two import paths (migration, repo sync). Every act records
+ *  its actor's `acted-on` edge and watch and publishes its event in the caller's transaction. */
+import type { DatabaseSync } from 'node:sqlite';
+import type { ReposFn } from './reader.js';
+import type { ObjectRow, Privacy, Reader, Revision, RuleSpec } from './types.js';
+export interface DocumentFields {
+    preview?: string;
+    summary?: string | null;
+    privacy?: Privacy;
+    rules?: readonly RuleSpec[];
+    whyItExists?: string | null;
+    unlisted?: boolean;
+    lintIgnore?: readonly string[] | null;
+    extensions?: Record<string, Record<string, unknown>> | null;
+}
+export interface WriteSpec extends DocumentFields {
+    owner: ObjectRow;
+    name: string;
+    kind: string;
+    preview: string;
+    privacy: Privacy;
+}
+export type DocumentChange = {
+    body: string;
+    verbatim?: boolean;
+} | {
+    replace: ReadonlyArray<{
+        old: string;
+        new: string;
+    }>;
+    verbatim?: boolean;
+};
+export interface DocumentRecord {
+    summary: string | null;
+    heads_key: string;
+    revision: number;
+    why_it_exists: string | null;
+    unlisted: boolean;
+    lint_ignore: string[] | null;
+    extensions: Record<string, Record<string, unknown>> | null;
+    source_path: string | null;
+}
+export interface Head extends Revision {
+    body: string;
+}
+export interface RenderedLink {
+    written_as: string;
+    object: ObjectRow;
+    deleted: boolean;
+}
+export interface DocumentRead {
+    object: ObjectRow;
+    record: DocumentRecord;
+    heads: Head[];
+    needsMerge: boolean;
+    links: RenderedLink[];
+}
+/** The object a reader acts as: its node, its app, or the person. */
+export declare function actorOf(reader: Reader): ObjectRow;
+/** Head revisions (no child), highest number first. More than one means the document needs a merge. */
+export declare function heads(db: DatabaseSync, doc: ObjectRow): Revision[];
+export declare function documentRecord(db: DatabaseSync, doc: ObjectRow): DocumentRecord;
+/** The `[[name]]` links a body names, in order, each once. */
+export declare function linksIn(body: string): string[];
+/** Derive the document's `links-to` edges from `body`, resolving each name in the writer's
+ *  view. A name that resolves to nothing or to several objects stays text and is returned;
+ *  one that may live on another runtime is neither linked nor reported. */
+export declare function setRevisionLinks(db: DatabaseSync, reader: Reader, doc: ObjectRow, body: string): string[];
+/** `body` with each `[[link]]` the document's `links-to` edges resolved shown under its target's
+ *  current name, so a rename rewrites no stored body yet every read shows the new name (spec §4).
+ *  A link written as the target's id, or to a deleted target, stays as written. */
+export declare function withCurrentNames(db: DatabaseSync, doc: ObjectRow, body: string): string;
+/** Write the record fields that are present; `null` clears a nullable one. Rules are
+ *  replaced when given. Does not publish; callers publish the act the fields belong to. */
+export declare function applyDocumentFields(db: DatabaseSync, doc: ObjectRow, fields: DocumentFields): ObjectRow;
+/** Create a document with its first revision. The actor becomes a watcher whose read base is
+ *  the new revision; `created` is published. Returns the names that stayed text. */
+export declare function writeDocument(db: DatabaseSync, reader: Reader, spec: WriteSpec, body: string, reposFn?: ReposFn): {
+    object: ObjectRow;
+    revision: number;
+    unresolved: string[];
+};
+/** The base of the reader's next edit: the heads it last read or wrote, or null when it never has. */
+export declare function readBase(db: DatabaseSync, reader: Reader, doc: ObjectRow): string | null;
+/** Apply exact-text replacements to one head's body; each `old` must occur exactly once. */
+export declare function applyReplacements(body: string, replace: ReadonlyArray<{
+    old: string;
+    new: string;
+}>): string;
+/**
+ * Commit a new revision made from `base` — the editor's read heads captured when it computed
+ * the change. No base → `read_first`. The commit is CAS on `documents.heads_key`: a base that is
+ * no longer current returns `{stale}` and writes nothing. The new revision's parents are every
+ * head, so an edit from a read that showed several heads merges them. `fields` are record
+ * changes applied with the edit.
+ */
+export declare function editDocument(db: DatabaseSync, reader: Reader, doc: ObjectRow, change: DocumentChange, rationale: string, base: string | null, fields?: DocumentFields, reposFn?: ReposFn): {
+    revision: number;
+    heads_key: string;
+    unresolved: string[];
+} | {
+    stale: {
+        heads_key: string;
+        revision: number;
+    };
+};
+/** Change record fields (preview, summary, privacy, rules, …) without a new revision. A null
+ *  reader is repo sync, which carries no reader and checks no access. */
+export declare function setDocumentRecord(db: DatabaseSync, reader: Reader | null, doc: ObjectRow, fields: DocumentFields): ObjectRow;
+/** Record that the reader holds the document's current heads: a `read` watch with that read
+ *  base, and a `read` push. Delivery's content load calls this without reading the body. */
+export declare function recordRead(db: DatabaseSync, reader: Reader, doc: ObjectRow, reposFn?: ReposFn): void;
+/** The document's record, each head with its body (several = needs merge) and its links under
+ *  their current names; records the read. */
+export declare function readDocument(db: DatabaseSync, reader: Reader, doc: ObjectRow, reposFn?: ReposFn): DocumentRead;
+/** Every revision, newest first, with authors, rationales and parents. Records nothing. */
+export declare function history(db: DatabaseSync, reader: Reader, doc: ObjectRow): Revision[];
+/** Rename and/or re-own a document. Only `objects` changes: links point at the id, so no body is
+ *  rewritten. A null actor is repo sync, which carries no reader and checks no access. */
+export declare function moveDocument(db: DatabaseSync, reader: Reader | null, doc: ObjectRow, to: {
+    name?: string;
+    owner?: ObjectRow;
+}): ObjectRow;
+/** Mark the document deleted; the row stays with its last preview. Publishes `deleted`
+ *  (level 8), then ends the watches on it and drops its rules. A null actor is repo sync or
+ *  node deletion. What it linked to is re-checked by {@link collectUnlinked}. */
+export declare function deleteDocument(db: DatabaseSync, reader: Reader | null, doc: ObjectRow, reposFn?: ReposFn): ObjectRow;
+/** Delete each of `targets` that is a kept document nothing links to any more: a live document
+ *  whose owner is deleted (node deletion kept it because a live document linked to it) and that
+ *  no other live document links to. Each one deleted re-checks what it linked to, so chains of
+ *  kept documents collapse; a cycle of kept documents keeps itself. Call it after a document
+ *  stops linking to `targets` — it was deleted, or an edit dropped the links. */
+export declare function collectUnlinked(db: DatabaseSync, targets: Iterable<number>, reposFn?: ReposFn): void;
+export interface ImportedRevision {
+    rev_id?: string;
+    body_hash: string;
+    author: ObjectRow | null;
+    rationale: string | null;
+    created_at: string;
+    verbatim?: boolean;
+}
+export interface ImportSpec extends WriteSpec {
+    id?: string;
+    revisions: readonly ImportedRevision[];
+}
+/** Migration: a document with its linear history (oldest first; bodies already in the body
+ *  store). Explicit authors and times; records no edge or watch and publishes nothing — the
+ *  caller adds links (`setRevisionLinks`), acted-on edges and watches. */
+export declare function importDocument(db: DatabaseSync, spec: ImportSpec): ObjectRow;
+export interface SyncedRevision {
+    rev_id: string;
+    parents: readonly string[];
+    body_hash: string;
+    rationale: string | null;
+    created_at: string;
+    verbatim?: boolean;
+}
+/** Repo sync: add revisions that arrived from another runtime, skipping known `rev_id`s. No
+ *  CAS, author NULL, publishes nothing; the caller publishes `edited` (with `needs_merge`
+ *  when `headCount > 1`) and re-derives links from the head it trusts. */
+export declare function insertImportedRevisions(db: DatabaseSync, doc: ObjectRow, revs: readonly SyncedRevision[]): {
+    heads_key: string;
+    headCount: number;
+};
+/** Look up a live document by id (convenience for handlers and importers). */
+export declare function documentById(db: DatabaseSync, id: string): ObjectRow;