@graview/core 0.1.0

package/dist/schema/json-schema.js

@@ -0,0 +1,74 @@
+import { z } from "zod";
+import { takesAnId } from "../mutations/define-mutation.js";
+import { nodeRefArgs } from "../mutations/node-ref.js";
+/**
+ * One source, three outputs: the same Zod declaration produces runtime
+ * validation, TypeScript inference, and the JSON Schema an agent tool
+ * definition needs. Nothing is written twice, so nothing drifts.
+ */
+export function toJsonSchema(schema) {
+    const convert = z
+        .toJSONSchema;
+    if (typeof convert !== "function") {
+        throw new Error("This Zod build has no toJSONSchema(). Upgrade to zod >= 3.25 / 4.x, " +
+            "or pass a JSON Schema explicitly.");
+    }
+    return convert(schema, { io: "input", unrepresentable: "any" });
+}
+/** JSON Schema for one node kind, including its id and kind discriminator. */
+export function nodeJsonSchema(definition) {
+    return toJsonSchema(definition.fields.extend({
+        id: z.string().min(1),
+        kind: z.literal(definition.kind),
+    }));
+}
+/**
+ * Derives an agent-facing tool schema from a mutation declaration. The
+ * `nodeRefs` metadata travels alongside so a caller can resolve "a person"
+ * to real ids without the agent guessing.
+ */
+export function mutationToolSchema(mutation) {
+    const refs = nodeRefArgs(mutation.input);
+    const base = toJsonSchema(mutation.input);
+    const properties = (base["properties"] ?? {});
+    /*
+     * THE ID A CALLER MAY BRING. An act that creates takes it beside its own
+     * arguments (`compileMutation` lifts it before the input parses), so the
+     * tool says so — an agent that will name the node in its next call, or a
+     * seed being synced, asks for the id it needs rather than reading one back.
+     */
+    if (takesAnId(mutation)) {
+        const made = mutation.creates.join(" | ");
+        properties["id"] = {
+            type: "string",
+            minLength: 1,
+            description: `Optional: the id for the ${made} this makes. Refused if the graph already has it; left out, one is minted from the label.`,
+        };
+        base["properties"] = properties;
+    }
+    for (const ref of refs) {
+        const property = properties[ref.name];
+        if (!property)
+            continue;
+        const kinds = ref.kinds.includes("*") ? "any node kind" : ref.kinds.join(" | ");
+        property["description"] = [property["description"], `Id of a node (${kinds}).`]
+            .filter(Boolean)
+            .join(" ");
+    }
+    return {
+        name: mutation.name,
+        ...(mutation.title === undefined ? {} : { title: mutation.title }),
+        description: mutation.description ?? mutation.title ?? mutation.name,
+        inputSchema: base,
+        nodeRefs: refs,
+    };
+}
+/** Every node kind's JSON Schema, keyed by kind. */
+export function schemaJson(schema) {
+    const out = {};
+    for (const definition of schema.definitions) {
+        out[definition.kind] = nodeJsonSchema(definition);
+    }
+    return out;
+}
+//# sourceMappingURL=json-schema.js.map

package/dist/schema/json-schema.js.map

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

package/dist/schema/schema.d.ts

@@ -0,0 +1,43 @@
+import type { AnyNodeDefinition, NodeOf, ValidateEdgeTargets } from "./types.js";
+export interface EdgeKindInfo {
+    readonly kind: string;
+    /** Node kinds this edge may leave. */
+    readonly from: readonly string[];
+    /** Node kinds this edge may point at, or `"*"`. */
+    readonly to: readonly string[] | "*";
+    readonly cardinality: "one" | "many";
+    readonly description?: string;
+}
+export interface Schema<Defs extends readonly AnyNodeDefinition[] = readonly AnyNodeDefinition[]> {
+    readonly definitions: Defs;
+    readonly kinds: readonly Defs[number]["kind"][];
+    readonly edgeKinds: readonly string[];
+    definition<K extends Defs[number]["kind"]>(kind: K): Extract<Defs[number], {
+        kind: K;
+    }>;
+    tryDefinition(kind: string): Defs[number] | undefined;
+    edge(kind: string): EdgeKindInfo | undefined;
+    /** Whether an edge of `kind` may run from one node kind to another. */
+    edgeAllowed(kind: string, fromKind: string, toKind: string): boolean;
+    /** Runtime validation of a node against its declared fields. */
+    parseNode(node: unknown): NodeOf<Defs[number]>;
+    /** Phantom carrier for the node union — never populated at runtime. */
+    readonly __node: NodeOf<Defs[number]>;
+}
+export type AnySchema = Schema<readonly AnyNodeDefinition[]>;
+export type NodeOfSchema<S extends AnySchema> = S["__node"];
+export type KindOfSchema<S extends AnySchema> = NodeOfSchema<S>["kind"];
+export type NodeOfKind<S extends AnySchema, K extends KindOfSchema<S>> = Extract<NodeOfSchema<S>, {
+    kind: K;
+}>;
+export declare class SchemaError extends Error {
+    readonly hint?: string | undefined;
+    constructor(message: string, hint?: string | undefined);
+}
+/**
+ * Assembles declarations into one schema. The `ValidateEdgeTargets` guard
+ * makes an edge to an undeclared kind a typecheck failure; the runtime
+ * checks here catch the same class of mistake for dynamically built schemas.
+ */
+export declare function createSchema<const Defs extends readonly AnyNodeDefinition[]>(definitions: Defs & ValidateEdgeTargets<Defs>): Schema<Defs>;
+//# sourceMappingURL=schema.d.ts.map

package/dist/schema/schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../src/schema/schema.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,iBAAiB,EAEjB,MAAM,EACN,mBAAmB,EACpB,MAAM,YAAY,CAAC;AAEpB,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,sCAAsC;IACtC,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;IACjC,mDAAmD;IACnD,QAAQ,CAAC,EAAE,EAAE,SAAS,MAAM,EAAE,GAAG,GAAG,CAAC;IACrC,QAAQ,CAAC,WAAW,EAAE,KAAK,GAAG,MAAM,CAAC;IACrC,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;CAC/B;AAED,MAAM,WAAW,MAAM,CAAC,IAAI,SAAS,SAAS,iBAAiB,EAAE,GAAG,SAAS,iBAAiB,EAAE;IAC9F,QAAQ,CAAC,WAAW,EAAE,IAAI,CAAC;IAC3B,QAAQ,CAAC,KAAK,EAAE,SAAS,IAAI,CAAC,MAAM,CAAC,CAAC,MAAM,CAAC,EAAE,CAAC;IAChD,QAAQ,CAAC,SAAS,EAAE,SAAS,MAAM,EAAE,CAAC;IACtC,UAAU,CAAC,CAAC,SAAS,IAAI,CAAC,MAAM,CAAC,CAAC,MAAM,CAAC,EACvC,IAAI,EAAE,CAAC,GACN,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE;QAAE,IAAI,EAAE,CAAC,CAAA;KAAE,CAAC,CAAC;IACtC,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC,GAAG,SAAS,CAAC;IACtD,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,YAAY,GAAG,SAAS,CAAC;IAC7C,uEAAuE;IACvE,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC;IACrE,gEAAgE;IAChE,SAAS,CAAC,IAAI,EAAE,OAAO,GAAG,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC;IAC/C,uEAAuE;IACvE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC;CACvC;AAED,MAAM,MAAM,SAAS,GAAG,MAAM,CAAC,SAAS,iBAAiB,EAAE,CAAC,CAAC;AAC7D,MAAM,MAAM,YAAY,CAAC,CAAC,SAAS,SAAS,IAAI,CAAC,CAAC,QAAQ,CAAC,CAAC;AAC5D,MAAM,MAAM,YAAY,CAAC,CAAC,SAAS,SAAS,IAAI,YAAY,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;AACxE,MAAM,MAAM,UAAU,CAAC,CAAC,SAAS,SAAS,EAAE,CAAC,SAAS,YAAY,CAAC,CAAC,CAAC,IAAI,OAAO,CAC9E,YAAY,CAAC,CAAC,CAAC,EACf;IAAE,IAAI,EAAE,CAAC,CAAA;CAAE,CACZ,CAAC;AAEF,qBAAa,WAAY,SAAQ,KAAK;IAGlC,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM;gBADtB,OAAO,EAAE,MAAM,EACN,IAAI,CAAC,EAAE,MAAM,YAAA;CAKzB;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,KAAK,CAAC,IAAI,SAAS,SAAS,iBAAiB,EAAE,EAC1E,WAAW,EAAE,IAAI,GAAG,mBAAmB,CAAC,IAAI,CAAC,GAC5C,MAAM,CAAC,IAAI,CAAC,CAuGd"}

package/dist/schema/schema.js

@@ -0,0 +1,102 @@
+import { z } from "zod";
+export class SchemaError extends Error {
+    hint;
+    constructor(message, hint) {
+        super(hint ? `${message}\n  → ${hint}` : message);
+        this.hint = hint;
+        this.name = "SchemaError";
+    }
+}
+/**
+ * Assembles declarations into one schema. The `ValidateEdgeTargets` guard
+ * makes an edge to an undeclared kind a typecheck failure; the runtime
+ * checks here catch the same class of mistake for dynamically built schemas.
+ */
+export function createSchema(definitions) {
+    const defs = definitions;
+    const byKind = new Map();
+    for (const def of defs) {
+        if (byKind.has(def.kind)) {
+            throw new SchemaError(`Duplicate node kind "${def.kind}"`, "Each kind may be declared once; merge the two defineNode calls.");
+        }
+        byKind.set(def.kind, def);
+    }
+    const edges = new Map();
+    for (const def of defs) {
+        for (const [edgeKind, decl] of Object.entries(def.edges)) {
+            if (decl.to !== "*") {
+                for (const target of decl.to) {
+                    if (!byKind.has(target)) {
+                        throw new SchemaError(`Edge "${edgeKind}" on "${def.kind}" points at undeclared kind "${target}"`, `Declared kinds: ${[...byKind.keys()].join(", ")}`);
+                    }
+                }
+            }
+            const existing = edges.get(edgeKind);
+            if (existing) {
+                existing.from.push(def.kind);
+            }
+            else {
+                edges.set(edgeKind, { from: [def.kind], decl });
+            }
+        }
+    }
+    const edgeInfo = new Map();
+    for (const [kind, { from, decl }] of edges) {
+        // Every declaring kind's targets, not only the first's.
+        const targets = from.map((one) => byKind.get(one).edges[kind].to);
+        edgeInfo.set(kind, {
+            kind,
+            from,
+            to: targets.includes("*") ? "*" : [...new Set(targets.flat())],
+            cardinality: decl.cardinality ?? "many",
+            ...(decl.description === undefined ? {} : { description: decl.description }),
+        });
+    }
+    const nodeSchemas = new Map();
+    for (const def of defs) {
+        nodeSchemas.set(def.kind, def.fields.extend({ id: z.string().min(1), kind: z.literal(def.kind) }));
+    }
+    return {
+        definitions: defs,
+        kinds: defs.map((d) => d.kind),
+        edgeKinds: [...edgeInfo.keys()],
+        definition(kind) {
+            const def = byKind.get(kind);
+            if (!def) {
+                throw new SchemaError(`Unknown node kind "${String(kind)}"`, `Declared kinds: ${[...byKind.keys()].join(", ")}`);
+            }
+            return def;
+        },
+        tryDefinition(kind) {
+            return byKind.get(kind);
+        },
+        edge(kind) {
+            return edgeInfo.get(kind);
+        },
+        edgeAllowed(kind, fromKind, toKind) {
+            /*
+             * Asked of the DECLARING kind's own declaration. An edge name two
+             * kinds both declare kept the first one's targets for both, so the
+             * second kind's edge was refused to its own declared targets and
+             * allowed to the first kind's.
+             */
+            const declared = byKind.get(fromKind)?.edges[kind];
+            if (!declared)
+                return false;
+            return declared.to === "*" || declared.to.includes(toKind);
+        },
+        parseNode(node) {
+            const kind = node?.kind;
+            if (typeof kind !== "string") {
+                throw new SchemaError("Node is missing a `kind`");
+            }
+            const parser = nodeSchemas.get(kind);
+            if (!parser) {
+                throw new SchemaError(`Unknown node kind "${kind}"`, `Declared kinds: ${[...byKind.keys()].join(", ")}`);
+            }
+            return parser.parse(node);
+        },
+        __node: undefined,
+    };
+}
+//# sourceMappingURL=schema.js.map

package/dist/schema/schema.js.map

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

package/dist/schema/types.d.ts

@@ -0,0 +1,201 @@
+import type { z } from "zod";
+import type { Figure } from "./figures.js";
+/** How many edges of a kind may leave one node. */
+export type EdgeCardinality = "one" | "many";
+/**
+ * An edge declared on the node kind it leaves. `to` names the kinds it may
+ * point at; `"*"` opts out of target checking for genuinely universal edges
+ * (the household example's `justifies` is the motivating case).
+ */
+export interface EdgeDeclaration<TargetKind extends string = string> {
+    readonly to: readonly TargetKind[] | "*";
+    readonly cardinality?: EdgeCardinality;
+    /**
+     * How the edge reads FROM THE KIND THAT DECLARES IT — "who does the run",
+     * "the tasks in this list".
+     */
+    readonly description?: string;
+    /**
+     * How it reads from the OTHER END.
+     *
+     * An edge has one direction and two readings, and using the declaring side's
+     * words for both is how a task's page ended up captioned "the tasks in this
+     * list" — as though the task contained tasks. The list holds the task; the
+     * task is on a list. Same edge, and neither sentence works in both places.
+     *
+     * Without one, an incoming edge is captioned with the edge kind in plain
+     * words, which says less and is at least not wrong.
+     */
+    readonly inverse?: string;
+    /**
+     * Declares that this relation, once made, is never unmade — an entry in a
+     * record, not a tie anyone severs. `graview check` warns about any edge
+     * kind some mutation can make and none can break (`edge-without-severer`),
+     * because a way in with no way out is usually an oversight; this is the
+     * declaration that says it is not. The suppression is the documentation:
+     * a reader of the schema learns the edge is append-only on purpose.
+     */
+    readonly appendOnly?: boolean;
+}
+export type EdgeMap = Readonly<Record<string, EdgeDeclaration>>;
+/**
+ * A kind that declares no edges. Deliberately `{}` rather than
+ * `Record<string, never>`: the latter has `keyof` of `string`, which makes
+ * the edge-target extraction below fall back to its constraint and silently
+ * defeat the build-time check.
+ */
+export type EmptyEdgeMap = {};
+/** A field role lets a lens ask for "the start time" without knowing the field name. */
+export type FieldRoleMap = Readonly<Record<string, string>>;
+export interface NodeDefinitionSpec<F extends z.ZodObject<z.ZodRawShape>, E extends EdgeMap> {
+    /** Zod object: the single source of runtime validation, TS types and JSON Schema. */
+    readonly fields: F;
+    readonly edges?: E;
+    /** Human label for one node. Falls back to a `label` field, then the id. */
+    readonly label?: (node: {
+        id: string;
+    } & z.infer<F>) => string;
+    /** Longer prose used for accessibility labels and agent tool descriptions. */
+    readonly describe?: (node: {
+        id: string;
+    } & z.infer<F>) => string;
+    /** Plural noun for aggregates ("People"). Defaults to `kind + "s"`. */
+    readonly plural?: string;
+    /**
+     * What ONE of them is called, in lower case, where the kind's id does not
+     * say it: a kind called `staff` whose one member is "a staff member", a
+     * kind called `equipment` whose one is "a piece of equipment". Defaults to
+     * the id, spoken ("work-order" → "work order").
+     */
+    readonly noun?: string;
+    readonly description?: string;
+    /**
+     * Maps a node onto the invariant it requires. The engine uses this to detect
+     * nodes whose rule was never registered, and to skip or throw per config.
+     */
+    readonly requiresInvariant?: (node: {
+        id: string;
+    } & z.infer<F>) => string | null;
+    /**
+     * Names semantic roles the node's own fields fill, so lenses bind to roles
+     * rather than field names (`{ start: "at", end: "endsAt" }`).
+     */
+    readonly fieldRoles?: FieldRoleMap;
+    /**
+     * How this kind's fields READ to a person.
+     *
+     * The framework renders a record from the declaration alone, which is most
+     * of what makes a new kind usable before anyone writes a view — and it can
+     * only get so far on its own. `540` is a truthful rendering of a number of
+     * minutes and a useless one; `order: 0` is a truthful rendering of an
+     * implementation detail nobody should ever be shown.
+     *
+     * Both are decisions only the declaration can make, so this is where they
+     * are made — once, rather than in every view that renders the kind.
+     */
+    readonly display?: {
+        /** Field names never shown to a person. Ordering keys, internal ids. */
+        readonly hide?: readonly string[];
+        /** Overrides the humanised default for a field's label. */
+        readonly labels?: Readonly<Record<string, string>>;
+        /** Turns a stored value into the words for it. */
+        readonly format?: Readonly<Record<string, (value: unknown) => string>>;
+    };
+    /**
+     * When a node of this kind stops being CURRENT.
+     *
+     * The graph accumulates; the interface must not. A kind that declares its
+     * lifecycle lets every derived surface aggregate over the horizon by
+     * default — counts, districts, rosters, violations — with the past one
+     * deliberate step away rather than gone. Nothing here deletes: retiring
+     * is an ordinary field write through an ordinary mutation, and widening
+     * the horizon is ordinary view state.
+     *
+     * Two shapes, one field: `retired` lists the values that mean "past"
+     * (a status enum), or is the string "date", which reads the field as an
+     * ISO date after which the node has expired (effectivity's `until`).
+     */
+    readonly lifecycle?: LifecycleDeclaration;
+    /**
+     * Fields that NEVER change once set, and why.
+     *
+     * A field you could set at creation, you can change: every settable field
+     * no declared mutation writes is covered by a derived edit act per kind
+     * (`edit-<kind>`), so nothing is frozen by accident. Opting OUT is this
+     * declaration — the field name, and the sentence that says why it is not
+     * yours to change ("the client's words, as sent"). The reason is the
+     * documentation: a reader of the schema learns the field is fixed on
+     * purpose, and `graview check` stops asking who writes it.
+     */
+    readonly fixed?: Readonly<Record<string, string>>;
+    /**
+     * A DRAWING OF THE THING, wherever the kind is drawn.
+     *
+     * Inline SVG — one `viewBox`, `currentColor` strokes, no fill — or the
+     * name of one from the shipped set (`FIGURES`). The kind card stands it
+     * on its block at altitude, the district carries it beside the plural, a
+     * chip draws it where it stays legible, the record and list pages carry
+     * it, and the relation key uses it. All from here.
+     *
+     * A kind without one is drawn exactly as it was. Nothing about a figure
+     * is required, and a figure is never decoration: it is line art of the
+     * thing, at the isometric city's own angle, or it should not be there.
+     */
+    readonly figure?: Figure;
+    /**
+     * WHERE THIS KIND STANDS IN THE CITY, hand-laid, in lattice cells.
+     *
+     * The map is drawn from the declaration and needs no help; this is for
+     * an installation that wants a kind on a particular corner. Used
+     * verbatim — `graview check` reports two kinds laid on one block as
+     * `plot-overlap`. The studio will write these back one day; a plot is
+     * a fact about the declaration, so it belongs here rather than in a
+     * person's storage.
+     */
+    readonly plot?: {
+        readonly col: number;
+        readonly row: number;
+    };
+}
+export interface LifecycleDeclaration {
+    /** The field that carries the node's currency. */
+    readonly field: string;
+    /** Values meaning "past", or "date" to expire after the field's ISO date. */
+    readonly retired: readonly unknown[] | "date";
+}
+export interface NodeDefinition<K extends string = string, F extends z.ZodObject<z.ZodRawShape> = z.ZodObject<z.ZodRawShape>, E extends EdgeMap = EdgeMap> extends NodeDefinitionSpec<F, E> {
+    readonly kind: K;
+    readonly edges: E;
+}
+export type AnyNodeDefinition = NodeDefinition<string, z.ZodObject<z.ZodRawShape>, EdgeMap>;
+/**
+ * The runtime shape of a node of one declared kind. Distributive on purpose:
+ * given a union of declarations this yields a union of node types, not one
+ * node with every field intersected.
+ */
+export type NodeOf<D extends AnyNodeDefinition> = D extends AnyNodeDefinition ? {
+    readonly id: string;
+    readonly kind: D["kind"];
+} & z.infer<D["fields"]> : never;
+/**
+ * Every edge target named across a set of declarations. A `"*"` target is
+ * not an array, so it drops out here — a wildcard edge opts out of target
+ * checking by construction rather than by a special case.
+ */
+export type DeclaredEdgeTargets<Defs extends readonly AnyNodeDefinition[]> = {
+    [I in keyof Defs]: {
+        [N in keyof Defs[I]["edges"]]: Defs[I]["edges"][N]["to"] extends readonly (infer T extends string)[] ? T : never;
+    }[keyof Defs[I]["edges"]];
+}[number];
+/**
+ * Build-time guard: an edge pointing at a kind nobody declared makes the
+ * whole schema unassignable, so `tsc` fails at the declaration rather than
+ * the render.
+ */
+export type ValidateEdgeTargets<Defs extends readonly AnyNodeDefinition[]> = [
+    Exclude<DeclaredEdgeTargets<Defs>, Defs[number]["kind"]>
+] extends [never] ? Defs : {
+    readonly __graviewError: "Edge declared to an undeclared node kind";
+    readonly undeclaredKinds: Exclude<DeclaredEdgeTargets<Defs>, Defs[number]["kind"]>;
+};
+//# sourceMappingURL=types.d.ts.map

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

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

package/dist/schema/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/schema/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/schema/types.ts"],"names":[],"mappings":""}