@graview/core 0.1.0 → 0.1.3

package/dist/persistence/sql.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sql.js","sourceRoot":"","sources":["../../src/persistence/sql.ts"],"names":[],"mappings":"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"}

package/dist/persistence/sqlite.d.ts

@@ -1,10 +1,15 @@
+import { type SqlExec } from "./sql.js";
 import type { PersistenceAdapter } from "./types.js";
+export { createSqlAdapter } from "./sql.js";
+export type { SqlAdapterOptions, SqlExec } from "./sql.js";
 /**
  * The slice of better-sqlite3 this adapter needs. Typed structurally so the
  * package never has to import the native module, and so a Drizzle app can
  * hand over its underlying client (`db.$client`) with no wrapper.
  */
 export interface SqliteStatement {
+    /** Whether the statement returns rows; better-sqlite3 says, and a statement that does not is `run`. */
+    readonly reader?: boolean;
     all(...params: unknown[]): unknown[];
     run(...params: unknown[]): unknown;
 }
@@ -51,9 +56,18 @@ export declare const SQLITE_TABLE_SHAPE: {
 };
 /**
  * Reads and writes an app's existing `graph_nodes` / `graph_edges` tables —
- * the shape the household example already stores. `data` is schemaless JSON on disk and
- * becomes a typed node on the way in, validated by the schema registry when
- * the snapshot is loaded into a Graph.
+ * the shape the household example already stores — through better-sqlite3.
+ * The SQL adapter over `sqlFromDatabase(database)`: one implementation, so
+ * what holds here holds over a Durable Object's storage too (FR-09).
  */
 export declare function createSqliteAdapter(options: SqliteAdapterOptions): PersistenceAdapter<string>;
+/**
+ * better-sqlite3 as the SQL adapter's `exec`, with its own transaction.
+ * Each statement is prepared once and kept, and a statement that reads
+ * nothing is `run` rather than asked for rows (better-sqlite3 refuses that).
+ */
+export declare function sqlFromDatabase(database: SqliteDatabase): {
+    readonly sql: SqlExec;
+    readonly transaction: <T>(fn: () => T) => T;
+};
 //# sourceMappingURL=sqlite.d.ts.map

package/dist/persistence/sqlite.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sqlite.d.ts","sourceRoot":"","sources":["../../src/persistence/sqlite.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAErD;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B,GAAG,CAAC,GAAG,MAAM,EAAE,OAAO,EAAE,GAAG,OAAO,EAAE,CAAC;IACrC,GAAG,CAAC,GAAG,MAAM,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC;CACpC;AACD,MAAM,WAAW,cAAc;IAC7B,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,eAAe,CAAC;IACtC,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;IAC3B,WAAW,CAAC,CAAC,SAAS,CAAC,GAAG,IAAI,EAAE,KAAK,EAAE,KAAK,OAAO,EAAE,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC;CAChE;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,QAAQ,EAAE,cAAc,CAAC;IAClC,sEAAsE;IACtE,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,4EAA4E;IAC5E,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,mFAAmF;IACnF,QAAQ,CAAC,YAAY,CAAC,EAAE,OAAO,CAAC;CACjC;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,kBAAkB;;;CAGrB,CAAC;AAEX;;;;;GAKG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,oBAAoB,GAC5B,kBAAkB,CAAC,MAAM,CAAC,CAmH5B"}
+{"version":3,"file":"sqlite.d.ts","sourceRoot":"","sources":["../../src/persistence/sqlite.ts"],"names":[],"mappings":"AAAA,OAAO,EAAoB,KAAK,OAAO,EAAE,MAAM,UAAU,CAAC;AAC1D,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAErD,OAAO,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAC;AAC5C,YAAY,EAAE,iBAAiB,EAAE,OAAO,EAAE,MAAM,UAAU,CAAC;AAE3D;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B,uGAAuG;IACvG,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC;IAC1B,GAAG,CAAC,GAAG,MAAM,EAAE,OAAO,EAAE,GAAG,OAAO,EAAE,CAAC;IACrC,GAAG,CAAC,GAAG,MAAM,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC;CACpC;AACD,MAAM,WAAW,cAAc;IAC7B,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,eAAe,CAAC;IACtC,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;IAC3B,WAAW,CAAC,CAAC,SAAS,CAAC,GAAG,IAAI,EAAE,KAAK,EAAE,KAAK,OAAO,EAAE,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC;CAChE;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,QAAQ,EAAE,cAAc,CAAC;IAClC,sEAAsE;IACtE,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,4EAA4E;IAC5E,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,mFAAmF;IACnF,QAAQ,CAAC,YAAY,CAAC,EAAE,OAAO,CAAC;CACjC;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,kBAAkB;;;CAGrB,CAAC;AAEX;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,oBAAoB,GAAG,kBAAkB,CAAC,MAAM,CAAC,CAG7F;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,cAAc,GAAG;IAAE,QAAQ,CAAC,GAAG,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,WAAW,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,CAAC,KAAK,CAAC,CAAA;CAAE,CAsBhI"}

package/dist/persistence/sqlite.js

@@ -1,3 +1,5 @@
+import { createSqlAdapter } from "./sql.js";
+export { createSqlAdapter } from "./sql.js";
 /**
  * The Drizzle/SQLite table shapes this adapter reads and writes, for an app
  * that wants to declare them in its own Drizzle schema:
@@ -25,107 +27,41 @@ export const SQLITE_TABLE_SHAPE = {
 };
 /**
  * Reads and writes an app's existing `graph_nodes` / `graph_edges` tables —
- * the shape the household example already stores. `data` is schemaless JSON on disk and
- * becomes a typed node on the way in, validated by the schema registry when
- * the snapshot is loaded into a Graph.
+ * the shape the household example already stores — through better-sqlite3.
+ * The SQL adapter over `sqlFromDatabase(database)`: one implementation, so
+ * what holds here holds over a Durable Object's storage too (FR-09).
  */
 export function createSqliteAdapter(options) {
-    const db = options.database;
-    const nodeTable = options.nodeTable ?? "graph_nodes";
-    const edgeTable = options.edgeTable ?? "graph_edges";
-    const opTable = options.opTable ?? "graview_ops";
-    const scope = options.scopeColumn ?? "household_id";
-    if (options.createTables) {
-        db.exec(`
-      CREATE TABLE IF NOT EXISTS ${nodeTable} (
-        ${scope} TEXT NOT NULL, id TEXT NOT NULL,
-        kind TEXT NOT NULL, data TEXT NOT NULL,
-        PRIMARY KEY (${scope}, id)
-      );
-      CREATE TABLE IF NOT EXISTS ${edgeTable} (
-        ${scope} TEXT NOT NULL, position INTEGER NOT NULL,
-        kind TEXT NOT NULL, from_id TEXT NOT NULL, to_id TEXT NOT NULL,
-        PRIMARY KEY (${scope}, position)
-      );
-      CREATE TABLE IF NOT EXISTS ${opTable} (
-        ${scope} TEXT NOT NULL, seq INTEGER NOT NULL, data TEXT NOT NULL,
-        PRIMARY KEY (${scope}, seq)
-      );
-    `);
-    }
-    const selectNodes = db.prepare(`SELECT id, kind, data FROM ${nodeTable} WHERE ${scope} = ?`);
-    const selectEdges = db.prepare(`SELECT kind, from_id, to_id FROM ${edgeTable} WHERE ${scope} = ? ORDER BY position ASC`);
-    const deleteNodes = db.prepare(`DELETE FROM ${nodeTable} WHERE ${scope} = ?`);
-    const deleteEdges = db.prepare(`DELETE FROM ${edgeTable} WHERE ${scope} = ?`);
-    const insertNode = db.prepare(`INSERT INTO ${nodeTable} (${scope}, id, kind, data) VALUES (?, ?, ?, ?)`);
-    const insertEdge = db.prepare(`INSERT INTO ${edgeTable} (${scope}, position, kind, from_id, to_id) VALUES (?, ?, ?, ?, ?)`);
-    /**
-     * The op table is the framework's own, not the app's, so it is created on
-     * demand. The node and edge tables are the app's and are never touched
-     * unless `createTables` explicitly asks for them.
-     */
-    let opTableReady = false;
-    function ensureOpTable() {
-        if (opTableReady)
-            return;
-        db.exec(`CREATE TABLE IF NOT EXISTS ${opTable} (
-         ${scope} TEXT NOT NULL, seq INTEGER NOT NULL, data TEXT NOT NULL,
-         PRIMARY KEY (${scope}, seq)
-       )`);
-        opTableReady = true;
-    }
-    const write = db.transaction(((key, snapshot) => {
-        deleteEdges.run(key);
-        deleteNodes.run(key);
-        for (const node of snapshot.nodes) {
-            insertNode.run(key, node.id, node.kind, JSON.stringify(node));
+    const { database, ...tables } = options;
+    return createSqlAdapter({ ...sqlFromDatabase(database), ...tables });
+}
+/**
+ * better-sqlite3 as the SQL adapter's `exec`, with its own transaction.
+ * Each statement is prepared once and kept, and a statement that reads
+ * nothing is `run` rather than asked for rows (better-sqlite3 refuses that).
+ */
+export function sqlFromDatabase(database) {
+    const prepared = new Map();
+    const statement = (sql) => {
+        let found = prepared.get(sql);
+        if (!found) {
+            found = database.prepare(sql);
+            prepared.set(sql, found);
         }
-        snapshot.edges.forEach((edge, position) => {
-            insertEdge.run(key, position, edge.kind, edge.from, edge.to);
-        });
-    }));
+        return found;
+    };
     return {
-        name: "sqlite",
-        async load(key) {
-            const nodeRows = selectNodes.all(key);
-            if (nodeRows.length === 0)
-                return null;
-            const edgeRows = selectEdges.all(key);
-            const nodes = nodeRows.map((row) => {
-                const parsed = JSON.parse(row.data);
-                // `id` and `kind` live in columns as well as the JSON blob; the
-                // columns win so a row is never internally inconsistent.
-                return { ...parsed, id: row.id, kind: row.kind };
-            });
-            const edges = edgeRows.map((row) => ({
-                kind: row.kind,
-                from: row.from_id,
-                to: row.to_id,
-            }));
-            return { nodes, edges };
-        },
-        async save(key, snapshot) {
-            write(key, snapshot);
-        },
-        async delete(key) {
-            deleteEdges.run(key);
-            deleteNodes.run(key);
-        },
-        async loadLog(key) {
-            ensureOpTable();
-            const rows = db
-                .prepare(`SELECT data FROM ${opTable} WHERE ${scope} = ? ORDER BY seq ASC`)
-                .all(key);
-            return rows.map((row) => JSON.parse(row.data));
-        },
-        async appendOps(key, ops) {
-            if (ops.length === 0)
-                return;
-            ensureOpTable();
-            const insert = db.prepare(`INSERT OR REPLACE INTO ${opTable} (${scope}, seq, data) VALUES (?, ?, ?)`);
-            for (const op of ops)
-                insert.run(key, op.seq, JSON.stringify(op));
+        sql: {
+            exec(sql, ...params) {
+                const prepared = statement(sql);
+                const reads = prepared.reader ?? /^\s*(SELECT|WITH|PRAGMA|VALUES)\b/i.test(sql);
+                if (reads)
+                    return prepared.all(...params);
+                prepared.run(...params);
+                return [];
+            },
         },
+        transaction: (fn) => database.transaction(fn)(),
     };
 }
 //# sourceMappingURL=sqlite.js.map

package/dist/persistence/sqlite.js.map

@@ -1 +1 @@
-{"version":3,"file":"sqlite.js","sourceRoot":"","sources":["../../src/persistence/sqlite.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"sqlite.js","sourceRoot":"","sources":["../../src/persistence/sqlite.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAgB,MAAM,UAAU,CAAC;AAG1D,OAAO,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAC;AAgC5C;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG;IAChC,KAAK,EAAE,CAAC,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC;IACtC,KAAK,EAAE,CAAC,OAAO,EAAE,UAAU,EAAE,MAAM,EAAE,SAAS,EAAE,OAAO,CAAC;CAChD,CAAC;AAEX;;;;;GAKG;AACH,MAAM,UAAU,mBAAmB,CAAC,OAA6B;IAC/D,MAAM,EAAE,QAAQ,EAAE,GAAG,MAAM,EAAE,GAAG,OAAO,CAAC;IACxC,OAAO,gBAAgB,CAAC,EAAE,GAAG,eAAe,CAAC,QAAQ,CAAC,EAAE,GAAG,MAAM,EAAE,CAAC,CAAC;AACvE,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,eAAe,CAAC,QAAwB;IACtD,MAAM,QAAQ,GAAG,IAAI,GAAG,EAA2B,CAAC;IACpD,MAAM,SAAS,GAAG,CAAC,GAAW,EAAmB,EAAE;QACjD,IAAI,KAAK,GAAG,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QAC9B,IAAI,CAAC,KAAK,EAAE,CAAC;YACX,KAAK,GAAG,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;YAC9B,QAAQ,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;QAC3B,CAAC;QACD,OAAO,KAAK,CAAC;IACf,CAAC,CAAC;IACF,OAAO;QACL,GAAG,EAAE;YACH,IAAI,CAAC,GAAG,EAAE,GAAG,MAAM;gBACjB,MAAM,QAAQ,GAAG,SAAS,CAAC,GAAG,CAAC,CAAC;gBAChC,MAAM,KAAK,GAAG,QAAQ,CAAC,MAAM,IAAI,oCAAoC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;gBAChF,IAAI,KAAK;oBAAE,OAAO,QAAQ,CAAC,GAAG,CAAC,GAAG,MAAM,CAAC,CAAC;gBAC1C,QAAQ,CAAC,GAAG,CAAC,GAAG,MAAM,CAAC,CAAC;gBACxB,OAAO,EAAE,CAAC;YACZ,CAAC;SACF;QACD,WAAW,EAAE,CAAI,EAAW,EAAK,EAAE,CAAC,QAAQ,CAAC,WAAW,CAAC,EAAa,CAAC,EAAO;KAC/E,CAAC;AACJ,CAAC"}

package/dist/persistence/types.d.ts

@@ -1,4 +1,5 @@
 import type { GraphSnapshot } from "../graph/types.js";
+import type { Epoch, LogArchive } from "../ops/log.js";
 import type { Operation } from "../ops/types.js";
 /**
  * The framework owns the reactive graph, invariants, diff and undo;
@@ -18,5 +19,23 @@ export interface PersistenceAdapter<Scope = string> {
     /** Optional: adapters that keep history append the log too. */
     loadLog?(scope: Scope): Promise<Operation[]>;
     appendOps?(scope: Scope, ops: readonly Operation[]): Promise<void>;
+    /**
+     * Optional: the epochs the log folds from (FR-27), kept beside it. An
+     * adapter without them reopens a store with none recorded, and ship has
+     * it adopt what it holds as its first epoch on each open.
+     */
+    loadEpochs?(scope: Scope): Promise<Epoch[]>;
+    saveEpochs?(scope: Scope, epochs: readonly Epoch[]): Promise<void>;
+    /**
+     * Optional (FR-23): compaction behind an undo horizon. Moves the ops
+     * before `checkpoint.seq`, and the epochs before it, into the archive,
+     * and makes `checkpoint` the first epoch. From then on `loadLog` returns
+     * the ops from its seq on and `loadEpochs` the checkpoint and what came
+     * after it, so a normal open loads nothing older; `loadArchive` returns
+     * what was moved, oldest first, for a full export. Nothing is deleted.
+     * An adapter that keeps no epochs keeps no checkpoint, and has neither.
+     */
+    compact?(scope: Scope, checkpoint: Epoch): Promise<void>;
+    loadArchive?(scope: Scope): Promise<LogArchive>;
 }
 //# sourceMappingURL=types.d.ts.map

package/dist/persistence/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/persistence/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AACvD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAEjD;;;;GAIG;AACH,MAAM,WAAW,kBAAkB,CAAC,KAAK,GAAG,MAAM;IAChD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;;;;OAIG;IACH,IAAI,CAAC,KAAK,EAAE,KAAK,GAAG,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC,CAAC;IAClD,IAAI,CAAC,KAAK,EAAE,KAAK,EAAE,QAAQ,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3D,MAAM,CAAC,KAAK,EAAE,KAAK,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACpC,+DAA+D;IAC/D,OAAO,CAAC,CAAC,KAAK,EAAE,KAAK,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC,CAAC;IAC7C,SAAS,CAAC,CAAC,KAAK,EAAE,KAAK,EAAE,GAAG,EAAE,SAAS,SAAS,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACpE"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/persistence/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AACvD,OAAO,KAAK,EAAE,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AACvD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAEjD;;;;GAIG;AACH,MAAM,WAAW,kBAAkB,CAAC,KAAK,GAAG,MAAM;IAChD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;;;;OAIG;IACH,IAAI,CAAC,KAAK,EAAE,KAAK,GAAG,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC,CAAC;IAClD,IAAI,CAAC,KAAK,EAAE,KAAK,EAAE,QAAQ,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3D,MAAM,CAAC,KAAK,EAAE,KAAK,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACpC,+DAA+D;IAC/D,OAAO,CAAC,CAAC,KAAK,EAAE,KAAK,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC,CAAC;IAC7C,SAAS,CAAC,CAAC,KAAK,EAAE,KAAK,EAAE,GAAG,EAAE,SAAS,SAAS,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACnE;;;;OAIG;IACH,UAAU,CAAC,CAAC,KAAK,EAAE,KAAK,GAAG,OAAO,CAAC,KAAK,EAAE,CAAC,CAAC;IAC5C,UAAU,CAAC,CAAC,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,SAAS,KAAK,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACnE;;;;;;;;OAQG;IACH,OAAO,CAAC,CAAC,KAAK,EAAE,KAAK,EAAE,UAAU,EAAE,KAAK,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACzD,WAAW,CAAC,CAAC,KAAK,EAAE,KAAK,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;CACjD"}

package/dist/presence.d.ts

@@ -6,8 +6,14 @@ export interface PresenceRobot {
 export interface Presence {
     /** `kind:id:session` — the op log's own reading of an author, so a figure and its edits agree. */
     readonly participant: string;
+    /** What they are: a person, an agent, a rule, a system. A server says it from the seat (FR-47); absent from an older word, read the key. */
+    readonly kind?: Participant["kind"];
     /** What to call them. Absent for an anonymous viewer, who is counted rather than drawn. */
     readonly name?: string;
+    /** The id of the person an agent acts for (FR-47), from its seat — never from what a client claims. */
+    readonly onBehalfOf?: string;
+    /** What to call that person: "Claude, for Ada". Withheld with `onBehalfOf` from a seat that may not see them. */
+    readonly onBehalfOfName?: string;
     readonly hue: number;
     /** Where they are: `toUrl(view)`, the complete answer. */
     readonly stop: string;
@@ -17,6 +23,12 @@ export interface Presence {
     readonly robot?: PresenceRobot;
     /** When they last said so, ISO. */
     readonly at: string;
+    /**
+     * When an ANNOUNCED visitor goes, ISO (FR-47): an agent acting over MCP or
+     * an RPC, a polling tab — somebody without a socket, stamped by a host.
+     * Until then they stand without a heartbeat; after it, they are gone.
+     */
+    readonly until?: string;
 }
 export interface PresenceChannel {
     /** Say where you are. Called on every change and on every heartbeat. */
@@ -28,6 +40,50 @@ export interface PresenceChannel {
 }
 /** How long a presence stands after its last word: three missed heartbeats at the poll's own pace. */
 export declare const PRESENCE_TTL_MS = 2500;
+/**
+ * HOW LONG A PRESENCE FROM SOMEWHERE ELSE STANDS (FR-13). A list that came
+ * over a wire was stamped by a server's clock and read by a browser's, and
+ * it arrives at the poll's pace rather than the heartbeat's, so it is given
+ * four times a tab's own grace. Past it a participant is gone whether or
+ * not the channel ever said so: a host's channel that forgets to drop
+ * somebody does not keep them on the map.
+ */
+export declare const REMOTE_PRESENCE_TTL_MS: number;
+/**
+ * HOW LONG AN ANNOUNCED VISITOR STANDS (FR-47) when a host does not say:
+ * an agent between two calls is thinking, not gone.
+ */
+export declare const VISITOR_PRESENCE_TTL_MS = 30000;
+/**
+ * WHAT TO CALL THEM, in a room: "Claude, for Ada" for an agent whose
+ * person may be named, the name alone otherwise, and "" for an anonymous
+ * viewer, who is counted rather than drawn.
+ */
+export declare function presenceName(presence: Presence): string;
+/** Whether a presence still stands at `now`: until its announced time, or within the TTL of its last word. */
+export declare function presenceStands(presence: Presence, now: number, ttlMs?: number): boolean;
+/** The parts of a participant key: who, and which tab of theirs. */
+export interface Participant {
+    readonly kind: "human" | "agent" | "rule" | "system";
+    readonly id?: string;
+    readonly session?: string;
+}
+/**
+ * THE ONE DIALECT. A participant is `kind:id:session`: the op log's own
+ * reading of an author (`Author.kind`, `.id`, `.session`), a figure's key on
+ * the map, and what the wire's presence routes carry, so a figure and its
+ * edits are the same person by construction. A host that says who is here
+ * from its own server writes this, and only this.
+ */
+export declare function participantKey(participant: Participant): string;
+/**
+ * A participant key read back. The kind is everything before the first
+ * colon and the session everything after the last, so an id that holds a
+ * colon (`mcp:claude`) survives. Null for anything that is not a key.
+ */
+export declare function parseParticipant(key: string): (Participant & {
+    readonly session: string;
+}) | null;
 /**
  * The others as they are now: what arrived, minus what has gone quiet, minus
  * yourself. Pure, so a test can ask what a viewer sees without a channel.

package/dist/presence.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"presence.d.ts","sourceRoot":"","sources":["../src/presence.ts"],"names":[],"mappings":"AAaA,MAAM,WAAW,aAAa;IAC5B,gFAAgF;IAChF,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,QAAQ;IACvB,kGAAkG;IAClG,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,2FAA2F;IAC3F,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,0DAA0D;IAC1D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,iEAAiE;IACjE,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,sDAAsD;IACtD,QAAQ,CAAC,KAAK,CAAC,EAAE,aAAa,CAAC;IAC/B,mCAAmC;IACnC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,eAAe;IAC9B,wEAAwE;IACxE,IAAI,CAAC,QAAQ,EAAE,QAAQ,GAAG,IAAI,CAAC;IAC/B,yFAAyF;IACzF,KAAK,CAAC,QAAQ,EAAE,CAAC,GAAG,EAAE,SAAS,QAAQ,EAAE,KAAK,IAAI,GAAG,MAAM,IAAI,CAAC;IAChE,mCAAmC;IACnC,KAAK,IAAI,IAAI,CAAC;CACf;AAED,sGAAsG;AACtG,eAAO,MAAM,eAAe,OAAO,CAAC;AAEpC;;;GAGG;AACH,wBAAgB,YAAY,CAC1B,KAAK,EAAE,WAAW,CAAC,MAAM,EAAE,QAAQ,CAAC,EACpC,OAAO,EAAE,SAAS,QAAQ,EAAE,EAC5B,GAAG,EAAE,MAAM,EACX,KAAK,GAAE,MAAwB,EAC/B,IAAI,CAAC,EAAE,MAAM,GACZ,GAAG,CAAC,MAAM,EAAE,QAAQ,CAAC,CAevB;AAED,uEAAuE;AACvE,wBAAgB,YAAY,CAAC,CAAC,EAAE,QAAQ,GAAG,SAAS,EAAE,CAAC,EAAE,QAAQ,GAAG,SAAS,GAAG,OAAO,CAWtF"}
+{"version":3,"file":"presence.d.ts","sourceRoot":"","sources":["../src/presence.ts"],"names":[],"mappings":"AAaA,MAAM,WAAW,aAAa;IAC5B,gFAAgF;IAChF,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,QAAQ;IACvB,kGAAkG;IAClG,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,4IAA4I;IAC5I,QAAQ,CAAC,IAAI,CAAC,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IACpC,2FAA2F;IAC3F,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,uGAAuG;IACvG,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,iHAAiH;IACjH,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,0DAA0D;IAC1D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,iEAAiE;IACjE,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,sDAAsD;IACtD,QAAQ,CAAC,KAAK,CAAC,EAAE,aAAa,CAAC;IAC/B,mCAAmC;IACnC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB;;;;OAIG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,eAAe;IAC9B,wEAAwE;IACxE,IAAI,CAAC,QAAQ,EAAE,QAAQ,GAAG,IAAI,CAAC;IAC/B,yFAAyF;IACzF,KAAK,CAAC,QAAQ,EAAE,CAAC,GAAG,EAAE,SAAS,QAAQ,EAAE,KAAK,IAAI,GAAG,MAAM,IAAI,CAAC;IAChE,mCAAmC;IACnC,KAAK,IAAI,IAAI,CAAC;CACf;AAED,sGAAsG;AACtG,eAAO,MAAM,eAAe,OAAO,CAAC;AAEpC;;;;;;;GAOG;AACH,eAAO,MAAM,sBAAsB,QAAsB,CAAC;AAE1D;;;GAGG;AACH,eAAO,MAAM,uBAAuB,QAAS,CAAC;AAE9C;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,QAAQ,GAAG,MAAM,CAGvD;AAED,8GAA8G;AAC9G,wBAAgB,cAAc,CAAC,QAAQ,EAAE,QAAQ,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,GAAE,MAAwB,GAAG,OAAO,CAGxG;AAED,oEAAoE;AACpE,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,GAAG,MAAM,GAAG,QAAQ,CAAC;IACrD,QAAQ,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC3B;AAID;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,WAAW,EAAE,WAAW,GAAG,MAAM,CAE/D;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,CAAC,WAAW,GAAG;IAAE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC,GAAG,IAAI,CAQjG;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAC1B,KAAK,EAAE,WAAW,CAAC,MAAM,EAAE,QAAQ,CAAC,EACpC,OAAO,EAAE,SAAS,QAAQ,EAAE,EAC5B,GAAG,EAAE,MAAM,EACX,KAAK,GAAE,MAAwB,EAC/B,IAAI,CAAC,EAAE,MAAM,GACZ,GAAG,CAAC,MAAM,EAAE,QAAQ,CAAC,CAevB;AAED,uEAAuE;AACvE,wBAAgB,YAAY,CAAC,CAAC,EAAE,QAAQ,GAAG,SAAS,EAAE,CAAC,EAAE,QAAQ,GAAG,SAAS,GAAG,OAAO,CAetF"}

package/dist/presence.js

@@ -12,6 +12,62 @@
  */
 /** How long a presence stands after its last word: three missed heartbeats at the poll's own pace. */
 export const PRESENCE_TTL_MS = 2500;
+/**
+ * HOW LONG A PRESENCE FROM SOMEWHERE ELSE STANDS (FR-13). A list that came
+ * over a wire was stamped by a server's clock and read by a browser's, and
+ * it arrives at the poll's pace rather than the heartbeat's, so it is given
+ * four times a tab's own grace. Past it a participant is gone whether or
+ * not the channel ever said so: a host's channel that forgets to drop
+ * somebody does not keep them on the map.
+ */
+export const REMOTE_PRESENCE_TTL_MS = PRESENCE_TTL_MS * 4;
+/**
+ * HOW LONG AN ANNOUNCED VISITOR STANDS (FR-47) when a host does not say:
+ * an agent between two calls is thinking, not gone.
+ */
+export const VISITOR_PRESENCE_TTL_MS = 30_000;
+/**
+ * WHAT TO CALL THEM, in a room: "Claude, for Ada" for an agent whose
+ * person may be named, the name alone otherwise, and "" for an anonymous
+ * viewer, who is counted rather than drawn.
+ */
+export function presenceName(presence) {
+    const name = presence.name ?? "";
+    return name && presence.onBehalfOfName ? `${name}, for ${presence.onBehalfOfName}` : name;
+}
+/** Whether a presence still stands at `now`: until its announced time, or within the TTL of its last word. */
+export function presenceStands(presence, now, ttlMs = PRESENCE_TTL_MS) {
+    if (presence.until !== undefined)
+        return now < Date.parse(presence.until);
+    return now - Date.parse(presence.at) < ttlMs;
+}
+const PARTICIPANT_KINDS = new Set(["human", "agent", "rule", "system"]);
+/**
+ * THE ONE DIALECT. A participant is `kind:id:session`: the op log's own
+ * reading of an author (`Author.kind`, `.id`, `.session`), a figure's key on
+ * the map, and what the wire's presence routes carry, so a figure and its
+ * edits are the same person by construction. A host that says who is here
+ * from its own server writes this, and only this.
+ */
+export function participantKey(participant) {
+    return `${participant.kind}:${participant.id ?? ""}:${participant.session ?? ""}`;
+}
+/**
+ * A participant key read back. The kind is everything before the first
+ * colon and the session everything after the last, so an id that holds a
+ * colon (`mcp:claude`) survives. Null for anything that is not a key.
+ */
+export function parseParticipant(key) {
+    const first = key.indexOf(":");
+    const last = key.lastIndexOf(":");
+    if (first < 0 || last === first)
+        return null;
+    const kind = key.slice(0, first);
+    if (!PARTICIPANT_KINDS.has(kind))
+        return null;
+    const id = key.slice(first + 1, last);
+    return { kind: kind, ...(id ? { id } : {}), session: key.slice(last + 1) };
+}
 /**
  * The others as they are now: what arrived, minus what has gone quiet, minus
  * yourself. Pure, so a test can ask what a viewer sees without a channel.
@@ -19,11 +75,11 @@ export const PRESENCE_TTL_MS = 2500;
 export function foldPresence(known, arrived, now, ttlMs = PRESENCE_TTL_MS, self) {
     const next = new Map();
     for (const [participant, presence] of known) {
-        if (now - Date.parse(presence.at) < ttlMs)
+        if (presenceStands(presence, now, ttlMs))
             next.set(participant, presence);
     }
     for (const presence of arrived) {
-        if (now - Date.parse(presence.at) >= ttlMs) {
+        if (!presenceStands(presence, now, ttlMs)) {
             next.delete(presence.participant);
             continue;
         }
@@ -40,7 +96,11 @@ export function samePresence(a, b) {
     if (!a || !b)
         return a === b;
     return (a.participant === b.participant &&
+        a.kind === b.kind &&
         a.name === b.name &&
+        a.onBehalfOf === b.onBehalfOf &&
+        a.onBehalfOfName === b.onBehalfOfName &&
+        a.until === b.until &&
         a.hue === b.hue &&
         a.stop === b.stop &&
         (a.over ?? null) === (b.over ?? null) &&

package/dist/presence.js.map

@@ -1 +1 @@
-{"version":3,"file":"presence.js","sourceRoot":"","sources":["../src/presence.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAiCH,sGAAsG;AACtG,MAAM,CAAC,MAAM,eAAe,GAAG,IAAI,CAAC;AAEpC;;;GAGG;AACH,MAAM,UAAU,YAAY,CAC1B,KAAoC,EACpC,OAA4B,EAC5B,GAAW,EACX,QAAgB,eAAe,EAC/B,IAAa;IAEb,MAAM,IAAI,GAAG,IAAI,GAAG,EAAoB,CAAC;IACzC,KAAK,MAAM,CAAC,WAAW,EAAE,QAAQ,CAAC,IAAI,KAAK,EAAE,CAAC;QAC5C,IAAI,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,EAAE,CAAC,GAAG,KAAK;YAAE,IAAI,CAAC,GAAG,CAAC,WAAW,EAAE,QAAQ,CAAC,CAAC;IAC7E,CAAC;IACD,KAAK,MAAM,QAAQ,IAAI,OAAO,EAAE,CAAC;QAC/B,IAAI,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,EAAE,CAAC,IAAI,KAAK,EAAE,CAAC;YAC3C,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAC;YAClC,SAAS;QACX,CAAC;QACD,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAC;QAC5C,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,EAAE,CAAC;YAAE,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,WAAW,EAAE,QAAQ,CAAC,CAAC;IACxG,CAAC;IACD,IAAI,IAAI,KAAK,SAAS;QAAE,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IAC1C,OAAO,IAAI,CAAC;AACd,CAAC;AAED,uEAAuE;AACvE,MAAM,UAAU,YAAY,CAAC,CAAuB,EAAE,CAAuB;IAC3E,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC;QAAE,OAAO,CAAC,KAAK,CAAC,CAAC;IAC7B,OAAO,CACL,CAAC,CAAC,WAAW,KAAK,CAAC,CAAC,WAAW;QAC/B,CAAC,CAAC,IAAI,KAAK,CAAC,CAAC,IAAI;QACjB,CAAC,CAAC,GAAG,KAAK,CAAC,CAAC,GAAG;QACf,CAAC,CAAC,IAAI,KAAK,CAAC,CAAC,IAAI;QACjB,CAAC,CAAC,CAAC,IAAI,IAAI,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,IAAI,IAAI,CAAC;QACrC,CAAC,CAAC,CAAC,KAAK,EAAE,EAAE,IAAI,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,EAAE,EAAE,IAAI,IAAI,CAAC;QAC/C,CAAC,CAAC,CAAC,KAAK,EAAE,IAAI,IAAI,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,EAAE,IAAI,IAAI,IAAI,CAAC,CACpD,CAAC;AACJ,CAAC"}
+{"version":3,"file":"presence.js","sourceRoot":"","sources":["../src/presence.ts"],"names":[],"mappings":"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"}

package/dist/refusal.d.ts

@@ -0,0 +1,34 @@
+/**
+ * WHY A CHANGE WAS REFUSED, AS A CODE A PROGRAM CAN BRANCH ON (FR-46).
+ *
+ * A refusal reached a client as a sentence and nothing else, so an MCP tool
+ * and an interface told "you may not" from "it is gone" by matching words.
+ * The set is closed and on the stability surface (docs/stability.md): a
+ * code never changes meaning, and a new one is a new protocol.
+ *
+ *   forbidden  the seat may not: the policy, a sight, an agent's `may`, a module turned off
+ *   missing    what the call names is not there: a record, or a batch to take back
+ *   invalid    the call as asked does not fit: its arguments, the kind, a rule, the order things happened in
+ *   limit      the host's hard cap: the call can never succeed as asked, however long the caller waits
+ *
+ * `limit` is the host's to say; nothing in the store says it. It is not
+ * `busy`: busy is "not now", and the client keeps the change and sends it
+ * again (FR-45). A refusal of any reason is final, and the change is taken
+ * back.
+ */
+export declare const REFUSAL_REASONS: readonly ["forbidden", "missing", "invalid", "limit"];
+export type RefusalReason = (typeof REFUSAL_REASONS)[number];
+/** A refusal as the wire carries it: the code, the sentence a person reads, and who could. */
+export interface WireRefusal {
+    readonly reason: RefusalReason;
+    readonly sentence: string;
+    /** The roles that would be allowed, when the policy knows them. Absent when it names none. */
+    readonly wouldNeed?: readonly string[];
+}
+/**
+ * THE STORE'S OWN ERRORS, READ INTO A REASON. Anything that is not one of
+ * the store's refusals — a mutation's own throw, an invariant, an id that
+ * is taken — is `invalid`, in its own words.
+ */
+export declare function refusalOf(error: unknown): WireRefusal;
+//# sourceMappingURL=refusal.d.ts.map

package/dist/refusal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"refusal.d.ts","sourceRoot":"","sources":["../src/refusal.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,eAAe,uDAAwD,CAAC;AAErF,MAAM,MAAM,aAAa,GAAG,CAAC,OAAO,eAAe,CAAC,CAAC,MAAM,CAAC,CAAC;AAE7D,8FAA8F;AAC9F,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;IAC/B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,8FAA8F;IAC9F,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACxC;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,OAAO,GAAG,WAAW,CASrD"}

package/dist/refusal.js

@@ -0,0 +1,40 @@
+import { MissingRecordError } from "./graph/graph.js";
+import { UndoBlockedError } from "./ops/undo.js";
+import { PermissionDeniedError } from "./permissions/types.js";
+/**
+ * WHY A CHANGE WAS REFUSED, AS A CODE A PROGRAM CAN BRANCH ON (FR-46).
+ *
+ * A refusal reached a client as a sentence and nothing else, so an MCP tool
+ * and an interface told "you may not" from "it is gone" by matching words.
+ * The set is closed and on the stability surface (docs/stability.md): a
+ * code never changes meaning, and a new one is a new protocol.
+ *
+ *   forbidden  the seat may not: the policy, a sight, an agent's `may`, a module turned off
+ *   missing    what the call names is not there: a record, or a batch to take back
+ *   invalid    the call as asked does not fit: its arguments, the kind, a rule, the order things happened in
+ *   limit      the host's hard cap: the call can never succeed as asked, however long the caller waits
+ *
+ * `limit` is the host's to say; nothing in the store says it. It is not
+ * `busy`: busy is "not now", and the client keeps the change and sends it
+ * again (FR-45). A refusal of any reason is final, and the change is taken
+ * back.
+ */
+export const REFUSAL_REASONS = ["forbidden", "missing", "invalid", "limit"];
+/**
+ * THE STORE'S OWN ERRORS, READ INTO A REASON. Anything that is not one of
+ * the store's refusals — a mutation's own throw, an invariant, an id that
+ * is taken — is `invalid`, in its own words.
+ */
+export function refusalOf(error) {
+    const sentence = error instanceof Error ? error.message : String(error);
+    if (error instanceof PermissionDeniedError) {
+        const roles = error.refusal.wouldNeed;
+        return { reason: "forbidden", sentence, ...(roles.length > 0 ? { wouldNeed: [...roles] } : {}) };
+    }
+    if (error instanceof MissingRecordError)
+        return { reason: "missing", sentence };
+    if (error instanceof UndoBlockedError)
+        return { reason: error.check.reason ?? "invalid", sentence };
+    return { reason: "invalid", sentence };
+}
+//# sourceMappingURL=refusal.js.map

package/dist/refusal.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"refusal.js","sourceRoot":"","sources":["../src/refusal.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AACtD,OAAO,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AACjD,OAAO,EAAE,qBAAqB,EAAE,MAAM,wBAAwB,CAAC;AAE/D;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,WAAW,EAAE,SAAS,EAAE,SAAS,EAAE,OAAO,CAAU,CAAC;AAYrF;;;;GAIG;AACH,MAAM,UAAU,SAAS,CAAC,KAAc;IACtC,MAAM,QAAQ,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IACxE,IAAI,KAAK,YAAY,qBAAqB,EAAE,CAAC;QAC3C,MAAM,KAAK,GAAG,KAAK,CAAC,OAAO,CAAC,SAAS,CAAC;QACtC,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,QAAQ,EAAE,GAAG,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,CAAC,GAAG,KAAK,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC;IACnG,CAAC;IACD,IAAI,KAAK,YAAY,kBAAkB;QAAE,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,QAAQ,EAAE,CAAC;IAChF,IAAI,KAAK,YAAY,gBAAgB;QAAE,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,KAAK,CAAC,MAAM,IAAI,SAAS,EAAE,QAAQ,EAAE,CAAC;IACpG,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,QAAQ,EAAE,CAAC;AACzC,CAAC"}

package/dist/scaffold/from-template.d.ts

@@ -0,0 +1,16 @@
+import type { GraviewTemplate } from "../document/graview-template.js";
+import { type Ids } from "./names.js";
+/** The kind a project's UI leads with, and the act its seat is gated on: the first kind something creates. */
+export declare function templateKind(template: GraviewTemplate): {
+    readonly kind: string;
+    readonly plural: string;
+    readonly gate: string;
+};
+export declare function documentJson(template: GraviewTemplate): string;
+export declare function templateJson(template: GraviewTemplate): string;
+export declare function documentAppTs(ids: Ids): string;
+export declare function documentSchemaTs(ids: Ids): string;
+export declare function documentBrandTs(ids: Ids): string;
+export declare function documentTest(ids: Ids): string;
+export declare function documentReadmeLayout(ids: Ids, run: string): string;
+//# sourceMappingURL=from-template.d.ts.map

package/dist/scaffold/from-template.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"from-template.d.ts","sourceRoot":"","sources":["../../src/scaffold/from-template.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,iCAAiC,CAAC;AACvE,OAAO,EAAE,KAAK,GAAG,EAAyB,MAAM,YAAY,CAAC;AAmB7D,8GAA8G;AAC9G,wBAAgB,YAAY,CAAC,QAAQ,EAAE,eAAe,GAAG;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAQjI;AAED,wBAAgB,YAAY,CAAC,QAAQ,EAAE,eAAe,GAAG,MAAM,CAE9D;AAED,wBAAgB,YAAY,CAAC,QAAQ,EAAE,eAAe,GAAG,MAAM,CAE9D;AAED,wBAAgB,aAAa,CAAC,GAAG,EAAE,GAAG,GAAG,MAAM,CAkC9C;AAED,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,GAAG,GAAG,MAAM,CAOjD;AAED,wBAAgB,eAAe,CAAC,GAAG,EAAE,GAAG,GAAG,MAAM,CAiBhD;AAED,wBAAgB,YAAY,CAAC,GAAG,EAAE,GAAG,GAAG,MAAM,CA+C7C;AAED,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAalE"}