@graview/core 0.1.0

package/dist/cli/index.js

@@ -0,0 +1,281 @@
+#!/usr/bin/env node
+import { existsSync, mkdirSync, readFileSync, realpathSync, writeFileSync } from "node:fs";
+import { mkdir, writeFile } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { checkApp, formatFindings } from "./check.js";
+import { create, CREATE_USAGE } from "./create.js";
+import { describeApp } from "./describe.js";
+import { generateAgentsMd, generateLlmsTxt } from "./docs.js";
+import { figureBrief, figureFaults, FIGURE_NAMES, FIGURES } from "../schema/figures.js";
+import { scaffoldLens, validateLensOptions } from "../scaffold/lens.js";
+export const USAGE = `graview — start a product, check its declaration, write its agent docs
+
+${CREATE_USAGE}
+
+  graview check <entry> [--views <module>] [--json]
+      Loads <entry> (a module whose default export, or \`app\` export, is a
+      GraviewApp) and reports schema problems. Exits 1 on any error.
+
+  graview docs <entry> [--out <dir>] [--views <module>]
+      Writes llms.txt and agents.md next to the entry, or into <dir>.
+
+  graview describe <entry> [--as <role>] [--views <module>]
+      Reads the app out: what a blank installation meets and in what order,
+      what is drawn and what falls back, the hues, what a seat may do, how a
+      model is reached, what is judged. The rung between check and a browser
+      — "run it and look" for something that cannot see.
+
+  graview lens <name> --roles a,b,c [--binds fields|entities] [--dir <dir>]
+      Writes a lens that compiles: the role check that fails loudly, the
+      createXLens factory, three fidelities, pick targets — and beside it a
+      REUSE TEST in a domain the app is not about, red until you make the
+      claim true. If you cannot make it pass, you wrote a view, and a view
+      is a legitimate thing to have written.
+
+  graview figure <entry> --kind <kind> [--name <shipped>]
+                         [--from "<what the thing is>"] [--judge <file|->]
+      Prints the figure line to paste into defineNode. With --name it is one
+      of the shipped drawings; with neither, it suggests the nearest one by
+      name and says so. --from prints the brief to hand a model — the rules,
+      the angle and a shipped figure as the style — and --judge reads the
+      answer back, holds it to the rules graview check holds a figure to, and
+      prints the line. Nine shipped figures is a vocabulary to start from,
+      not a vocabulary to finish in.
+`;
+export async function loadApp(entry) {
+    const path = resolve(process.cwd(), entry);
+    const module = (await import(pathToFileURL(path).href));
+    const app = (module["default"] ?? module["app"]);
+    if (!app || typeof app !== "object" || !("schema" in app)) {
+        throw new Error(`${entry} does not export a GraviewApp. Export it as default, or as \`app\`.`);
+    }
+    return app;
+}
+/**
+ * The shipped figure whose NAME is closest to a kind's — never a guess
+ * about what a thing is. A cleat is not a box, and the framework has never
+ * met this domain.
+ */
+function nearest(kind) {
+    const said = kind.toLowerCase();
+    if (FIGURES[said])
+        return said;
+    return FIGURE_NAMES.find((name) => said.includes(name) || name.includes(said)) ?? "note";
+}
+/**
+ * THE PICTURES, FROM WHERE THEY LIVE (F-042).
+ *
+ * A view registry is React, and the declaration is the domain tier, which
+ * must not import React — so no app can pass `defineApp({ views })`, and
+ * everything outside a browser went quiet about what is drawn. The
+ * pictures are still a module: `--views ./dist/ui/views.js` names it, and
+ * this reads the registry — `places()`, `kindsWithViews()`, `all()` —
+ * without rendering anything. The module exports `views` (a registry, or
+ * a function that builds one), or the registry as its default export.
+ */
+export function withViews(app, module, name) {
+    const candidate = module["views"] ?? module["default"] ?? module["registry"];
+    const registry = typeof candidate === "function" ? candidate() : candidate;
+    const looksLikeOne = typeof registry === "object" &&
+        registry !== null &&
+        typeof registry.kindsWithViews === "function" &&
+        typeof registry.places === "function";
+    if (!looksLikeOne) {
+        throw new Error(`${name} does not export a view registry. Export \`views\` — the registry, or a function that builds it — or the registry as default.`);
+    }
+    return { ...app, views: registry };
+}
+async function loadViews(app, entry) {
+    if (!entry)
+        return app;
+    const path = resolve(process.cwd(), entry);
+    const module = (await import(pathToFileURL(path).href));
+    return withViews(app, module, entry);
+}
+function flag(argv, name) {
+    const index = argv.indexOf(name);
+    if (index === -1)
+        return undefined;
+    return argv[index + 1] ?? "";
+}
+export async function main(argv) {
+    const [command, entry] = argv;
+    if (!command || command === "--help" || command === "-h") {
+        process.stdout.write(USAGE);
+        return 0;
+    }
+    if (command === "create")
+        return create(argv.slice(1));
+    if (command === "lens") {
+        /*
+         * A LENS, STARTED. The rules in `graview-lens` are the kind that are
+         * easy to agree with and easy to forget at line 300, so they arrive in
+         * the file already — and the reuse test arrives RED, which is the only
+         * way an instruction nothing can enforce ever gets followed.
+         */
+        const name = argv[1];
+        if (!name || name.startsWith("--")) {
+            process.stderr.write(`graview lens: a name is required\n\n${USAGE}`);
+            return 2;
+        }
+        const roles = (flag(argv, "--roles") ?? "").split(",").map((role) => role.trim()).filter(Boolean);
+        const bindsFlag = flag(argv, "--binds");
+        const dir = flag(argv, "--dir");
+        const options = {
+            name,
+            roles,
+            ...(bindsFlag === "entities" || bindsFlag === "fields" ? { binds: bindsFlag } : {}),
+            ...(dir ? { dir } : {}),
+        };
+        const problems = validateLensOptions(options);
+        if (problems.length > 0) {
+            process.stderr.write(`graview lens: ${problems.join("\ngraview lens: ")}\n`);
+            return 2;
+        }
+        const files = scaffoldLens(options);
+        for (const file of files) {
+            const path = resolve(process.cwd(), file.path);
+            if (existsSync(path)) {
+                process.stderr.write(`graview lens: ${file.path} already exists — nothing was written.\n`);
+                return 1;
+            }
+        }
+        for (const file of files) {
+            const path = resolve(process.cwd(), file.path);
+            mkdirSync(dirname(path), { recursive: true });
+            writeFileSync(path, file.contents, "utf8");
+        }
+        process.stdout.write(`${files.map((file) => `  ${file.path}\n`).join("")}` +
+            `\nThe reuse test is RED on purpose: bind the roles to a domain this app is not\n` +
+            `about and make it pass, or say plainly that you wrote a view.\n`);
+        return 0;
+    }
+    if (!entry) {
+        process.stderr.write(`graview ${command}: an entry module is required\n\n${USAGE}`);
+        return 2;
+    }
+    switch (command) {
+        case "check": {
+            const app = await loadViews(await loadApp(entry), flag(argv, "--views"));
+            const result = checkApp(app);
+            if (argv.includes("--json")) {
+                process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+            }
+            else {
+                process.stdout.write(`${formatFindings(result)}\n`);
+            }
+            return result.ok ? 0 : 1;
+        }
+        case "docs": {
+            const app = await loadViews(await loadApp(entry), flag(argv, "--views"));
+            const outDir = resolve(process.cwd(), flag(argv, "--out") || dirname(resolve(process.cwd(), entry)));
+            await mkdir(outDir, { recursive: true });
+            await writeFile(`${outDir}/llms.txt`, generateLlmsTxt(app), "utf8");
+            await writeFile(`${outDir}/agents.md`, generateAgentsMd(app), "utf8");
+            process.stdout.write(`graview docs: wrote llms.txt and agents.md to ${outDir}\n`);
+            return 0;
+        }
+        case "describe": {
+            /*
+             * The one instruction an agent cannot follow is the one every skill
+             * ends on. It can declare, and it cannot see — so the derivations say
+             * what they would do, in words.
+             */
+            const app = await loadViews(await loadApp(entry), flag(argv, "--views"));
+            const role = flag(argv, "--as");
+            process.stdout.write(`${describeApp(app, role ? { as: { kind: "human", id: role, roles: [role] } } : {})}\n`);
+            return 0;
+        }
+        case "figure": {
+            /*
+             * A DRAWING YOU CAN PASTE, judged before it is printed.
+             *
+             * No model here: reaching a vendor is `@graview/tools`' job and the
+             * CLI has no key, no seam and no business holding one. What this
+             * does is the other half — name a figure, judge it against the rules
+             * `graview check` will judge it against, and print the line. An
+             * agent that HAS a model calls `drawFigure` and lands here anyway,
+             * because the judging is the same judging.
+             */
+            const app = await loadApp(entry);
+            const kind = flag(argv, "--kind");
+            if (!kind) {
+                process.stderr.write(`graview figure: --kind <kind> is required\n\n${USAGE}`);
+                return 2;
+            }
+            if (!app.schema.kinds.includes(kind)) {
+                process.stderr.write(`graview figure: "${kind}" is not a kind of ${app.name}. It declares: ${app.schema.kinds.join(", ")}\n`);
+                return 1;
+            }
+            /*
+             * THE AUTHORING LOOP, through the door every app has: a prompt to
+             * copy and an answer to paste. The CLI still holds no key and reaches
+             * no vendor — that is `@graview/tools`' job — and it does the half it
+             * is actually good at, which is saying what a figure must be and then
+             * judging what came back.
+             */
+            const from = flag(argv, "--from");
+            if (from) {
+                process.stdout.write(`${figureBrief(kind, from)}\n`);
+                return 0;
+            }
+            const judge = flag(argv, "--judge");
+            if (judge) {
+                const drawn = judge === "-" ? readFileSync(0, "utf8") : readFileSync(resolve(process.cwd(), judge), "utf8");
+                const trimmed = drawn.trim();
+                const faults = figureFaults(trimmed);
+                if (faults.length > 0) {
+                    process.stderr.write(`graview figure: that drawing cannot be kept —\n${faults.map((fault) => `  ${fault}\n`).join("")}` +
+                        `Ask again with the fault quoted; the brief is graview figure ${entry} --kind ${kind} --from "…".\n`);
+                    return 1;
+                }
+                process.stdout.write(`  figure:\n    ${JSON.stringify(trimmed)},\n` +
+                    `Paste it into defineNode(${JSON.stringify(kind)}, { ... }), then look at it at twenty pixels.\n`);
+                return 0;
+            }
+            const named = flag(argv, "--name");
+            const figure = named || nearest(kind);
+            const faults = figureFaults(figure);
+            if (faults.length > 0) {
+                process.stderr.write(`graview figure: that figure cannot be drawn — ${faults.join(" ")}\n`);
+                return 1;
+            }
+            process.stdout.write(`${named ? "" : `graview figure: nothing was asked to draw one, so this is the nearest shipped figure by name.\n`}` +
+                `  figure: ${JSON.stringify(figure)},\n` +
+                `Paste it into defineNode("${kind}", { ... }). The shipped set: ${FIGURE_NAMES.join(", ")}.\n`);
+            return 0;
+        }
+        default:
+            process.stderr.write(`graview: unknown command "${command}"\n\n${USAGE}`);
+            return 2;
+    }
+}
+/*
+ * Whether this module is the program, not an import. Compared by REAL path:
+ * a project's `node_modules/.bin/graview` is a symlink to this file, and
+ * comparing the unresolved path made `npx graview check` exit 0 having done
+ * nothing — the quietest possible way for a check to pass.
+ */
+function invokedAs(argv1) {
+    if (argv1 === undefined)
+        return false;
+    try {
+        return realpathSync(argv1) === realpathSync(fileURLToPath(import.meta.url));
+    }
+    catch {
+        return import.meta.url === pathToFileURL(argv1).href;
+    }
+}
+const invokedDirectly = invokedAs(process.argv[1]);
+if (invokedDirectly) {
+    main(process.argv.slice(2))
+        .then((code) => {
+        process.exitCode = code;
+    })
+        .catch((error) => {
+        process.stderr.write(`graview: ${error instanceof Error ? error.message : String(error)}\n`);
+        process.exitCode = 1;
+    });
+}
+//# sourceMappingURL=index.js.map

package/dist/cli/index.js.map

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

package/dist/extend.d.ts

@@ -0,0 +1,23 @@
+import { type AnySchema } from "./schema/schema.js";
+import type { AnyMutationDefinition } from "./mutations/types.js";
+import type { InvariantDefinition } from "./invariants/types.js";
+/**
+ * Carries declarations written against a base schema over to a schema that
+ * EXTENDS it.
+ *
+ * Adding a node kind should not mean rewriting the mutations and invariants
+ * that never mentioned it — but a mutation typed for seven kinds is not
+ * automatically typed for eight, because the reader it is handed is
+ * contravariant in the node union. That is a real typing fact, not a bug, and
+ * pretending otherwise with a bare cast would hide the moment it stops being
+ * true.
+ *
+ * So this is a checked crossing rather than an assertion: every kind the
+ * declarations name must exist in the wider schema, and anything that does
+ * not is reported by name. The cast that follows is then sound, and the
+ * reason it is sound has been verified rather than asserted.
+ */
+export declare function extendMutations<Wide extends AnySchema>(schema: Wide, mutations: readonly AnyMutationDefinition<never>[]): AnyMutationDefinition<Wide>[];
+/** The same checked crossing, for invariants. */
+export declare function extendInvariants<Wide extends AnySchema>(schema: Wide, invariants: readonly InvariantDefinition<never>[]): InvariantDefinition<Wide>[];
+//# sourceMappingURL=extend.d.ts.map

package/dist/extend.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"extend.d.ts","sourceRoot":"","sources":["../src/extend.ts"],"names":[],"mappings":"AAAA,OAAO,EAAe,KAAK,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAEjE,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAClE,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAEjE;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,eAAe,CAAC,IAAI,SAAS,SAAS,EACpD,MAAM,EAAE,IAAI,EACZ,SAAS,EAAE,SAAS,qBAAqB,CAAC,KAAK,CAAC,EAAE,GACjD,qBAAqB,CAAC,IAAI,CAAC,EAAE,CAsB/B;AAED,iDAAiD;AACjD,wBAAgB,gBAAgB,CAAC,IAAI,SAAS,SAAS,EACrD,MAAM,EAAE,IAAI,EACZ,UAAU,EAAE,SAAS,mBAAmB,CAAC,KAAK,CAAC,EAAE,GAChD,mBAAmB,CAAC,IAAI,CAAC,EAAE,CAY7B"}

package/dist/extend.js

@@ -0,0 +1,53 @@
+import { SchemaError } from "./schema/schema.js";
+import { nodeRefArgs } from "./mutations/node-ref.js";
+/**
+ * Carries declarations written against a base schema over to a schema that
+ * EXTENDS it.
+ *
+ * Adding a node kind should not mean rewriting the mutations and invariants
+ * that never mentioned it — but a mutation typed for seven kinds is not
+ * automatically typed for eight, because the reader it is handed is
+ * contravariant in the node union. That is a real typing fact, not a bug, and
+ * pretending otherwise with a bare cast would hide the moment it stops being
+ * true.
+ *
+ * So this is a checked crossing rather than an assertion: every kind the
+ * declarations name must exist in the wider schema, and anything that does
+ * not is reported by name. The cast that follows is then sound, and the
+ * reason it is sound has been verified rather than asserted.
+ */
+export function extendMutations(schema, mutations) {
+    const kinds = new Set(schema.kinds);
+    for (const mutation of mutations) {
+        const named = new Set();
+        const subject = mutation.subject;
+        if (subject && subject.kinds !== "*") {
+            for (const kind of subject.kinds)
+                named.add(kind);
+        }
+        for (const ref of nodeRefArgs(mutation.input)) {
+            for (const kind of ref.kinds) {
+                if (kind !== "*")
+                    named.add(kind);
+            }
+        }
+        const missing = [...named].filter((kind) => !kinds.has(kind));
+        if (missing.length > 0) {
+            throw new SchemaError(`Mutation "${mutation.name}" names node kinds the extended schema does not declare: ${missing.join(", ")}`, `Declared kinds: ${[...kinds].join(", ")}`);
+        }
+    }
+    return mutations;
+}
+/** The same checked crossing, for invariants. */
+export function extendInvariants(schema, invariants) {
+    const kinds = new Set(schema.kinds);
+    for (const invariant of invariants) {
+        if (invariant.scope === "graph")
+            continue;
+        if (!kinds.has(invariant.scope.kind)) {
+            throw new SchemaError(`Invariant "${invariant.name}" is scoped to "${invariant.scope.kind}", which the extended schema does not declare`, `Declared kinds: ${[...kinds].join(", ")}`);
+        }
+    }
+    return invariants;
+}
+//# sourceMappingURL=extend.js.map

package/dist/extend.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"extend.js","sourceRoot":"","sources":["../src/extend.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAkB,MAAM,oBAAoB,CAAC;AACjE,OAAO,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAItD;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,eAAe,CAC7B,MAAY,EACZ,SAAkD;IAElD,MAAM,KAAK,GAAG,IAAI,GAAG,CAAS,MAAM,CAAC,KAA0B,CAAC,CAAC;IACjE,KAAK,MAAM,QAAQ,IAAI,SAAS,EAAE,CAAC;QACjC,MAAM,KAAK,GAAG,IAAI,GAAG,EAAU,CAAC;QAChC,MAAM,OAAO,GAAG,QAAQ,CAAC,OAAO,CAAC;QACjC,IAAI,OAAO,IAAI,OAAO,CAAC,KAAK,KAAK,GAAG,EAAE,CAAC;YACrC,KAAK,MAAM,IAAI,IAAI,OAAO,CAAC,KAA0B;gBAAE,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QACzE,CAAC;QACD,KAAK,MAAM,GAAG,IAAI,WAAW,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;YAC9C,KAAK,MAAM,IAAI,IAAI,GAAG,CAAC,KAAK,EAAE,CAAC;gBAC7B,IAAI,IAAI,KAAK,GAAG;oBAAE,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;YACpC,CAAC;QACH,CAAC;QACD,MAAM,OAAO,GAAG,CAAC,GAAG,KAAK,CAAC,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC;QAC9D,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACvB,MAAM,IAAI,WAAW,CACnB,aAAa,QAAQ,CAAC,IAAI,4DAA4D,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,EAC1G,mBAAmB,CAAC,GAAG,KAAK,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAC3C,CAAC;QACJ,CAAC;IACH,CAAC;IACD,OAAO,SAAqD,CAAC;AAC/D,CAAC;AAED,iDAAiD;AACjD,MAAM,UAAU,gBAAgB,CAC9B,MAAY,EACZ,UAAiD;IAEjD,MAAM,KAAK,GAAG,IAAI,GAAG,CAAS,MAAM,CAAC,KAA0B,CAAC,CAAC;IACjE,KAAK,MAAM,SAAS,IAAI,UAAU,EAAE,CAAC;QACnC,IAAI,SAAS,CAAC,KAAK,KAAK,OAAO;YAAE,SAAS;QAC1C,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;YACrC,MAAM,IAAI,WAAW,CACnB,cAAc,SAAS,CAAC,IAAI,mBAAmB,SAAS,CAAC,KAAK,CAAC,IAAI,+CAA+C,EAClH,mBAAmB,CAAC,GAAG,KAAK,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAC3C,CAAC;QACJ,CAAC;IACH,CAAC;IACD,OAAO,UAAyC,CAAC;AACnD,CAAC"}

package/dist/graph/diff.d.ts

@@ -0,0 +1,31 @@
+import type { AnyGraphNode, GraphEdge, GraphNodeBase } from "./types.js";
+export interface NodeChange<N extends GraphNodeBase = AnyGraphNode> {
+    readonly before: N;
+    readonly after: N;
+    /** Field names whose values differ. */
+    readonly fields: readonly string[];
+}
+export interface GraphDiff<N extends GraphNodeBase = AnyGraphNode> {
+    readonly addedNodes: readonly N[];
+    readonly removedNodes: readonly N[];
+    readonly changedNodes: readonly NodeChange<N>[];
+    readonly addedEdges: readonly GraphEdge[];
+    readonly removedEdges: readonly GraphEdge[];
+    /** Every node id implicated, so a renderer can highlight across planes. */
+    readonly touched: readonly string[];
+}
+export declare const EMPTY_DIFF: GraphDiff;
+export declare function isEmptyDiff(diff: GraphDiff<never>): boolean;
+/**
+ * Pure structural diff of two snapshots. Used for previewing a mutation (or
+ * an undo) before it applies — a human edit and an agent edit produce the
+ * same diff shape, which is why watching an agent needs no bespoke layer.
+ */
+export declare function diffSnapshots<N extends GraphNodeBase>(before: {
+    nodes: readonly N[];
+    edges: readonly GraphEdge[];
+}, after: {
+    nodes: readonly N[];
+    edges: readonly GraphEdge[];
+}): GraphDiff<N>;
+//# sourceMappingURL=diff.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"diff.d.ts","sourceRoot":"","sources":["../../src/graph/diff.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAGzE,MAAM,WAAW,UAAU,CAAC,CAAC,SAAS,aAAa,GAAG,YAAY;IAChE,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAC;IACnB,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAC;IAClB,uCAAuC;IACvC,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;CACpC;AAED,MAAM,WAAW,SAAS,CAAC,CAAC,SAAS,aAAa,GAAG,YAAY;IAC/D,QAAQ,CAAC,UAAU,EAAE,SAAS,CAAC,EAAE,CAAC;IAClC,QAAQ,CAAC,YAAY,EAAE,SAAS,CAAC,EAAE,CAAC;IACpC,QAAQ,CAAC,YAAY,EAAE,SAAS,UAAU,CAAC,CAAC,CAAC,EAAE,CAAC;IAChD,QAAQ,CAAC,UAAU,EAAE,SAAS,SAAS,EAAE,CAAC;IAC1C,QAAQ,CAAC,YAAY,EAAE,SAAS,SAAS,EAAE,CAAC;IAC5C,2EAA2E;IAC3E,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;CACrC;AAED,eAAO,MAAM,UAAU,EAAE,SAOxB,CAAC;AAEF,wBAAgB,WAAW,CAAC,IAAI,EAAE,SAAS,CAAC,KAAK,CAAC,GAAG,OAAO,CAQ3D;AAaD;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,CAAC,SAAS,aAAa,EACnD,MAAM,EAAE;IAAE,KAAK,EAAE,SAAS,CAAC,EAAE,CAAC;IAAC,KAAK,EAAE,SAAS,SAAS,EAAE,CAAA;CAAE,EAC5D,KAAK,EAAE;IAAE,KAAK,EAAE,SAAS,CAAC,EAAE,CAAC;IAAC,KAAK,EAAE,SAAS,SAAS,EAAE,CAAA;CAAE,GAC1D,SAAS,CAAC,CAAC,CAAC,CAoCd"}

package/dist/graph/diff.js

@@ -0,0 +1,71 @@
+import { edgeId } from "./types.js";
+export const EMPTY_DIFF = {
+    addedNodes: [],
+    removedNodes: [],
+    changedNodes: [],
+    addedEdges: [],
+    removedEdges: [],
+    touched: [],
+};
+export function isEmptyDiff(diff) {
+    return (diff.addedNodes.length === 0 &&
+        diff.removedNodes.length === 0 &&
+        diff.changedNodes.length === 0 &&
+        diff.addedEdges.length === 0 &&
+        diff.removedEdges.length === 0);
+}
+function changedFields(before, after) {
+    const keys = new Set([...Object.keys(before), ...Object.keys(after)]);
+    const fields = [];
+    for (const key of keys) {
+        const a = before[key];
+        const b = after[key];
+        if (JSON.stringify(a) !== JSON.stringify(b))
+            fields.push(key);
+    }
+    return fields.sort();
+}
+/**
+ * Pure structural diff of two snapshots. Used for previewing a mutation (or
+ * an undo) before it applies — a human edit and an agent edit produce the
+ * same diff shape, which is why watching an agent needs no bespoke layer.
+ */
+export function diffSnapshots(before, after) {
+    const beforeNodes = new Map(before.nodes.map((n) => [n.id, n]));
+    const afterNodes = new Map(after.nodes.map((n) => [n.id, n]));
+    const addedNodes = after.nodes.filter((n) => !beforeNodes.has(n.id));
+    const removedNodes = before.nodes.filter((n) => !afterNodes.has(n.id));
+    const changedNodes = [];
+    for (const prev of before.nodes) {
+        const next = afterNodes.get(prev.id);
+        if (!next)
+            continue;
+        const fields = changedFields(prev, next);
+        if (fields.length > 0)
+            changedNodes.push({ before: prev, after: next, fields });
+    }
+    const beforeEdges = new Map(before.edges.map((e) => [edgeId(e), e]));
+    const afterEdges = new Map(after.edges.map((e) => [edgeId(e), e]));
+    const addedEdges = after.edges.filter((e) => !beforeEdges.has(edgeId(e)));
+    const removedEdges = before.edges.filter((e) => !afterEdges.has(edgeId(e)));
+    const touched = new Set();
+    for (const n of addedNodes)
+        touched.add(n.id);
+    for (const n of removedNodes)
+        touched.add(n.id);
+    for (const c of changedNodes)
+        touched.add(c.after.id);
+    for (const e of [...addedEdges, ...removedEdges]) {
+        touched.add(e.from);
+        touched.add(e.to);
+    }
+    return {
+        addedNodes,
+        removedNodes,
+        changedNodes,
+        addedEdges,
+        removedEdges,
+        touched: [...touched].sort(),
+    };
+}
+//# sourceMappingURL=diff.js.map

package/dist/graph/diff.js.map

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

package/dist/graph/graph.d.ts

@@ -0,0 +1,69 @@
+import type { AnySchema, NodeOfSchema } from "../schema/schema.js";
+import { type GraphDiff } from "./diff.js";
+import { type Primitive } from "./primitives.js";
+import { type GraphEdge, type GraphReader, type GraphSnapshot } from "./types.js";
+export interface GraphOptions {
+    /** Validate every node against its declared fields on the way in. */
+    readonly validate?: boolean;
+}
+export type GraphListener<S extends AnySchema> = (diff: GraphDiff<NodeOfSchema<S>>) => void;
+export declare class GraphError extends Error {
+    readonly hint?: string | undefined;
+    constructor(message: string, hint?: string | undefined);
+}
+/**
+ * The framework owns the reactive in-memory graph. Owning it — rather than
+ * reading someone else's store — is what makes invariants enforceable and
+ * agent attribution free; persistence is a pluggable adapter underneath.
+ */
+export declare class Graph<S extends AnySchema> implements GraphReader<NodeOfSchema<S>> {
+    readonly schema: S;
+    private readonly nodes;
+    private readonly edges;
+    private readonly outIndex;
+    private readonly inIndex;
+    private readonly listeners;
+    private readonly validate;
+    constructor(schema: S, options?: GraphOptions);
+    static from<S extends AnySchema>(schema: S, snapshot: GraphSnapshot<NodeOfSchema<S>>, options?: GraphOptions): Graph<S>;
+    /** Replaces the whole graph without emitting a per-node diff storm. */
+    load(snapshot: GraphSnapshot<NodeOfSchema<S>>): GraphDiff<NodeOfSchema<S>>;
+    getNode(id: string): NodeOfSchema<S> | undefined;
+    has(id: string): boolean;
+    allNodes(): NodeOfSchema<S>[];
+    allEdges(): GraphEdge[];
+    nodesOfKind<K extends NodeOfSchema<S>["kind"]>(kind: K): Extract<NodeOfSchema<S>, {
+        kind: K;
+    }>[];
+    edgesOfKind(kind: string): GraphEdge[];
+    out(id: string, kind?: string): NodeOfSchema<S>[];
+    in(id: string, kind?: string): NodeOfSchema<S>[];
+    neighbors(id: string): NodeOfSchema<S>[];
+    /** Edges leaving `id`, optionally of one kind. */
+    outEdges(id: string, kind?: string): GraphEdge[];
+    /** Edges arriving at `id`, optionally of one kind. */
+    inEdges(id: string, kind?: string): GraphEdge[];
+    snapshot(): GraphSnapshot<NodeOfSchema<S>>;
+    get size(): {
+        nodes: number;
+        edges: number;
+    };
+    /**
+     * Applies primitives as one batch and emits a single diff. Nothing outside
+     * the op log should call this directly — attribution lives in the log.
+     */
+    applyPrimitives(primitives: readonly Primitive[]): GraphDiff<NodeOfSchema<S>>;
+    /** Applies primitives to a throwaway copy — used for previewing a diff. */
+    preview(primitives: readonly Primitive[]): GraphDiff<NodeOfSchema<S>>;
+    subscribe(listener: GraphListener<S>): () => void;
+    private emit;
+    private applyOne;
+    private check;
+    private insertNode;
+    private insertEdge;
+    private deleteEdge;
+    private index;
+    private edgesFrom;
+    private resolve;
+}
+//# sourceMappingURL=graph.d.ts.map

package/dist/graph/graph.d.ts.map

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