@graview/core 0.1.0

package/dist/mutations/form.js

@@ -0,0 +1,113 @@
+import { describeArg, nodeRefKinds, unwrap } from "./node-ref.js";
+const isOptional = (schema) => schema.safeParse?.(undefined).success ?? false;
+const shapeOf = (schema) => unwrap(schema).shape;
+/** The single literal value of a zod literal, or undefined. */
+const literalValue = (schema) => {
+    const field = unwrap(schema);
+    if (field._def?.type !== "literal")
+        return undefined;
+    const values = field._def.values;
+    return values && values.length === 1 && typeof values[0] === "string" ? values[0] : undefined;
+};
+/** Describes one argument as a form control tree. */
+export function formField(name, schema) {
+    const optional = isOptional(schema);
+    const field = unwrap(schema);
+    const type = field._def?.type;
+    const kinds = nodeRefKinds(schema);
+    if (kinds)
+        return { control: "node", name, optional, kinds };
+    if (type === "boolean")
+        return { control: "boolean", name, optional };
+    if (type === "object") {
+        const shape = field.shape ?? {};
+        return {
+            control: "group",
+            name,
+            optional,
+            fields: Object.entries(shape).map(([child, childSchema]) => formField(child, childSchema)),
+        };
+    }
+    if (type === "union") {
+        const options = field._def?.options ?? [];
+        /*
+         * A DISCRIMINATED union renders as one picker and then that option's
+         * fields — the household example's constraint spec is the canonical case. The tag is
+         * whichever literal field every option shares; without one, a union of
+         * scalars collapses to a choice when every arm is a literal, and
+         * anything else is opaque rather than guessed at.
+         */
+        const shapes = options.map((option) => shapeOf(option));
+        if (shapes.every((shape) => shape !== undefined)) {
+            const tag = Object.keys(shapes[0] ?? {}).find((key) => shapes.every((shape) => literalValue(shape?.[key]) !== undefined));
+            if (tag) {
+                return {
+                    control: "variant",
+                    name,
+                    optional,
+                    tag,
+                    options: options.map((_, index) => ({
+                        value: literalValue(shapes[index]?.[tag]) ?? "",
+                        fields: Object.entries(shapes[index] ?? {})
+                            .filter(([key]) => key !== tag)
+                            .map(([child, childSchema]) => formField(child, childSchema)),
+                    })),
+                };
+            }
+        }
+        const literals = options.map((option) => literalValue(option));
+        if (literals.every((value) => value !== undefined)) {
+            return { control: "choice", name, optional, options: literals };
+        }
+        return { control: "opaque", name, optional };
+    }
+    if (type === "array") {
+        const element = field._def?.element;
+        if (element !== undefined) {
+            return { control: "list", name, optional, item: formField(name, element) };
+        }
+        return { control: "opaque", name, optional };
+    }
+    const scalar = describeArg(schema);
+    if (scalar.type === "text")
+        return { control: "text", name, optional };
+    if (scalar.type === "date")
+        return { control: "date", name, optional, ...(scalar.time ? { time: true } : {}) };
+    if (scalar.type === "number") {
+        return {
+            control: "number",
+            name,
+            optional,
+            ...(scalar.min === undefined ? {} : { min: scalar.min }),
+            ...(scalar.max === undefined ? {} : { max: scalar.max }),
+        };
+    }
+    if (scalar.type === "choice")
+        return { control: "choice", name, optional, options: scalar.options };
+    return { control: "opaque", name, optional };
+}
+/** The whole form for a mutation input object, one field per argument. */
+export function formFields(input) {
+    const shape = input.shape;
+    if (!shape)
+        return [];
+    return Object.entries(shape).map(([name, schema]) => formField(name, schema));
+}
+/** True when every control in the tree is renderable — nothing opaque. */
+export function formComplete(fields) {
+    return fields.every((field) => {
+        switch (field.control) {
+            case "opaque":
+                return false;
+            case "group":
+                return formComplete(field.fields);
+            case "variant":
+                return field.options.every((option) => formComplete(option.fields));
+            case "list":
+                return formComplete([field.item]);
+            default:
+                return true;
+        }
+    });
+}
+//# sourceMappingURL=form.js.map

package/dist/mutations/form.js.map

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

package/dist/mutations/node-ref.d.ts

@@ -0,0 +1,83 @@
+import { z } from "zod";
+/**
+ * A mutation argument that names a node. Declaring the acceptable kinds is
+ * what lets the affordance layer bind a selection to an argument without
+ * anyone writing per-selection code, and lets an agent tool schema say
+ * which ids are legal.
+ */
+export declare function nodeRef<const K extends string>(kinds?: readonly K[] | "*"): z.ZodString;
+/** The node kinds an argument accepts, or undefined if it is not a node ref. */
+export declare function nodeRefKinds(schema: unknown): readonly string[] | undefined;
+/** Reads the node-ref arguments off a mutation input object schema. */
+export declare function nodeRefArgs(input: z.ZodType): {
+    name: string;
+    kinds: readonly string[];
+    optional: boolean;
+}[];
+/**
+ * What sort of answer an argument wants, read off its own declaration.
+ *
+ * The affordance layer could already say "this needs a `label`" and offer
+ * candidate ids for a node reference — but for a plain string or a date it
+ * offered a list of nothing, so half the actions in an interface were dead
+ * ends that looked live. The mutation's schema knows perfectly well that
+ * `label` is a non-empty string and `date` is `YYYY-MM-DD`; nothing had
+ * asked it.
+ */
+export type ArgShape = {
+    readonly type: "text";
+}
+/**
+ * A DATE, AND WITH `time` A TIME OF DAY IN IT. A workshop's start is
+ * `YYYY-MM-DDTHH:MM`; read as a plain date it got a date picker, whose
+ * `YYYY-MM-DD` the act's own pattern refused — on every face, so the
+ * workshop could not be made and the talk could not be given its slot.
+ */
+ | {
+    readonly type: "date";
+    readonly time?: true;
+} | {
+    readonly type: "number";
+    readonly min?: number;
+    readonly max?: number;
+} | {
+    readonly type: "choice";
+    readonly options: readonly string[];
+}
+/**
+ * YES OR NO — an argument that takes a boolean.
+ *
+ * Undescribable until now, for the same reason a list was: an interface
+ * can only offer what it can ask for, so "Add a field" — whose `required`
+ * is a plain boolean — was derived NOWHERE. The studio's central act, in
+ * the studio, unreachable, because nothing could ask one question.
+ */
+ | {
+    readonly type: "boolean";
+}
+/**
+ * SEVERAL OF A THING — an argument that takes a list.
+ *
+ * "Invite somebody as coordinator and gardener" is one act with two roles
+ * in one argument, and without this shape it described itself as `unknown`:
+ * an interface can only offer what it can ask for, so the act was offered
+ * NOWHERE. Not hidden behind a refusal — simply never derived, in every
+ * installation the framework ships.
+ */
+ | {
+    readonly type: "several";
+    readonly of: ArgShape;
+} | {
+    readonly type: "unknown";
+};
+/** Unwraps optional/default/nullable so a wrapped field still describes itself. */
+export declare function unwrap(schema: unknown): unknown;
+/**
+ * Zod 4 keeps the primitive type on `_def.type` and the refinements a UI
+ * actually needs — bounds, patterns — in `_zod.bag`. Reading them here, in
+ * one place, keeps every other layer free of zod internals.
+ */
+export declare function describeArg(schema: unknown): ArgShape;
+/** The declared shape of one named argument of a mutation input object. */
+export declare function argShape(input: unknown, name: string): ArgShape;
+//# sourceMappingURL=node-ref.d.ts.map

package/dist/mutations/node-ref.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"node-ref.d.ts","sourceRoot":"","sources":["../../src/mutations/node-ref.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB;;;;;GAKG;AACH,wBAAgB,OAAO,CAAC,KAAK,CAAC,CAAC,SAAS,MAAM,EAC5C,KAAK,GAAE,SAAS,CAAC,EAAE,GAAG,GAAS,GAC9B,CAAC,CAAC,SAAS,CAab;AAED,gFAAgF;AAChF,wBAAgB,YAAY,CAAC,MAAM,EAAE,OAAO,GAAG,SAAS,MAAM,EAAE,GAAG,SAAS,CAW3E;AAED,uEAAuE;AACvE,wBAAgB,WAAW,CACzB,KAAK,EAAE,CAAC,CAAC,OAAO,GACf;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IAAC,QAAQ,EAAE,OAAO,CAAA;CAAE,EAAE,CAUjE;AAED;;;;;;;;;GASG;AACH,MAAM,MAAM,QAAQ,GAChB;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE;AAC3B;;;;;GAKG;GACD;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,IAAI,CAAA;CAAE,GAC/C;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAA;CAAE,GACzE;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE;AAClE;;;;;;;GAOG;GACD;IAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAA;CAAE;AAC9B;;;;;;;;GAQG;GACD;IAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IAAC,QAAQ,CAAC,EAAE,EAAE,QAAQ,CAAA;CAAE,GACnD;IAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAA;CAAE,CAAC;AAEjC,mFAAmF;AACnF,wBAAgB,MAAM,CAAC,MAAM,EAAE,OAAO,GAAG,OAAO,CAG/C;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,OAAO,GAAG,QAAQ,CAmDrD;AAED,2EAA2E;AAC3E,wBAAgB,QAAQ,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,QAAQ,CAI/D"}

package/dist/mutations/node-ref.js

@@ -0,0 +1,113 @@
+import { z } from "zod";
+const NODE_REFS = new WeakMap();
+/**
+ * A mutation argument that names a node. Declaring the acceptable kinds is
+ * what lets the affordance layer bind a selection to an argument without
+ * anyone writing per-selection code, and lets an agent tool schema say
+ * which ids are legal.
+ */
+export function nodeRef(kinds = "*") {
+    const schema = z.string().min(1);
+    const accepted = kinds === "*" ? ["*"] : kinds;
+    NODE_REFS.set(schema, accepted);
+    /*
+     * `.describe()` and `.meta()` CLONE the schema and share its def, so a
+     * described node reference — the natural thing to write, since the
+     * description is the question a decision provider is asked — used to
+     * come back as a plain string. The def is the stable identity.
+     */
+    const def = schema._def;
+    if (def)
+        NODE_REFS.set(def, accepted);
+    return schema;
+}
+/** The node kinds an argument accepts, or undefined if it is not a node ref. */
+export function nodeRefKinds(schema) {
+    if (typeof schema !== "object" || schema === null)
+        return undefined;
+    const direct = NODE_REFS.get(schema);
+    if (direct)
+        return direct;
+    const def = schema._def;
+    const byDef = def ? NODE_REFS.get(def) : undefined;
+    if (byDef)
+        return byDef;
+    // Unwrap optional/default/nullable wrappers so `nodeRef([...]).optional()`
+    // keeps its meaning.
+    const inner = schema._def?.innerType;
+    return inner ? nodeRefKinds(inner) : undefined;
+}
+/** Reads the node-ref arguments off a mutation input object schema. */
+export function nodeRefArgs(input) {
+    const shape = input.shape;
+    if (!shape)
+        return [];
+    const args = [];
+    for (const [name, field] of Object.entries(shape)) {
+        const kinds = nodeRefKinds(field);
+        if (!kinds)
+            continue;
+        args.push({ name, kinds, optional: field.safeParse(undefined).success });
+    }
+    return args;
+}
+/** Unwraps optional/default/nullable so a wrapped field still describes itself. */
+export function unwrap(schema) {
+    const inner = schema._def?.innerType;
+    return inner === undefined ? schema : unwrap(inner);
+}
+/**
+ * Zod 4 keeps the primitive type on `_def.type` and the refinements a UI
+ * actually needs — bounds, patterns — in `_zod.bag`. Reading them here, in
+ * one place, keeps every other layer free of zod internals.
+ */
+export function describeArg(schema) {
+    const field = unwrap(schema);
+    const type = field?._def?.type;
+    const bag = field?._zod?.bag ?? {};
+    if (type === "enum")
+        return { type: "choice", options: Object.keys(field?._def?.entries ?? {}) };
+    if (type === "boolean")
+        return { type: "boolean" };
+    /*
+     * A list describes itself through what it holds. An array of something
+     * nothing can describe is still unknown — saying "several unknowns" would
+     * make an unaskable argument look askable, which is the failure this whole
+     * shape exists to prevent.
+     */
+    if (type === "array") {
+        const of = describeArg(field._def?.element);
+        return of.type === "unknown" ? { type: "unknown" } : { type: "several", of };
+    }
+    if (type === "number") {
+        const min = typeof bag["minimum"] === "number" ? bag["minimum"] : undefined;
+        const max = typeof bag["maximum"] === "number" ? bag["maximum"] : undefined;
+        return {
+            type: "number",
+            ...(min === undefined ? {} : { min }),
+            ...(max === undefined ? {} : { max }),
+        };
+    }
+    if (type === "string") {
+        // A date is a string with a date-shaped pattern. Recognising it means
+        // the interface offers a date picker instead of a free text box, which
+        // is the difference between an action anyone can run and one only its
+        // author knows the format for.
+        const patterns = bag["patterns"];
+        const sources = patterns instanceof Set ? [...patterns].map((pattern) => String(pattern.source)) : [];
+        if (sources.some((source) => source.includes("\\d{4}"))) {
+            // A time of day in the pattern as well: `T\d{2}:\d{2}`, or a space before it.
+            return sources.some((source) => source.includes("\\d{2}:\\d{2}")) ? { type: "date", time: true } : { type: "date" };
+        }
+        return { type: "text" };
+    }
+    return { type: "unknown" };
+}
+/** The declared shape of one named argument of a mutation input object. */
+export function argShape(input, name) {
+    const shape = input?.shape;
+    if (!shape || !(name in shape))
+        return { type: "unknown" };
+    return describeArg(shape[name]);
+}
+//# sourceMappingURL=node-ref.js.map

package/dist/mutations/node-ref.js.map

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

package/dist/mutations/types.d.ts

@@ -0,0 +1,136 @@
+import type { z } from "zod";
+import type { Primitive } from "../graph/primitives.js";
+import type { GraphEdge, GraphReader } from "../graph/types.js";
+import type { AnySchema, KindOfSchema, NodeOfSchema } from "../schema/schema.js";
+/**
+ * What a mutation is handed. Reads go through a tracked reader so the op log
+ * records causality; writes go out as primitives so every op has an inverse.
+ */
+export interface MutationContext<S extends AnySchema> {
+    readonly graph: GraphReader<NodeOfSchema<S>>;
+    readonly schema: S;
+    addNode(node: NodeOfSchema<S>): void;
+    /** Removes a node together with every edge touching it. */
+    removeNode(id: string): void;
+    patchNode(id: string, fields: Record<string, unknown>): void;
+    addEdge(edge: GraphEdge): void;
+    removeEdge(edge: GraphEdge): void;
+    /** Replaces every `kind` edge arriving at `to` with one from `from`. */
+    setSingleSource(kind: string, to: string, from: string): void;
+    /** A deterministic, collision-free id derived from a label. */
+    freshId(label: string, prefix?: string): string;
+    /** Raw escape hatch — prefer the helpers above. */
+    emit(primitive: Primitive): void;
+}
+export interface MutationDefinitionSpec<S extends AnySchema, I extends z.ZodType> {
+    readonly input: I;
+    /** Short human title, e.g. "Reassign run". */
+    readonly title?: string;
+    readonly description?: string;
+    /**
+     * Node kinds this mutation acts on, and the argument the subject binds to.
+     * This is the seam that makes affordances derivable: given a selection of
+     * `duty` nodes, every mutation whose subject accepts `duty` is legal.
+     */
+    readonly subject?: {
+        readonly kinds: readonly KindOfSchema<S>[] | "*";
+        readonly arg: string;
+    };
+    /**
+     * True when applying this loses something a person made — a node removed,
+     * work dropped, an edge severed for good. The interface lists these after
+     * everything else and marks them; an agent seat inherits the same order.
+     * Absent means safe, which is the common case and the safe default to get
+     * wrong: an unmarked destructive mutation is merely unranked, a marked
+     * safe one is merely over-cautious.
+     */
+    readonly destructive?: boolean;
+    /**
+     * Node kinds this mutation brings into existence.
+     *
+     * The other half of the affordance seam. `subject` answers "what can I do
+     * WITH this thing"; `creates` answers the question an empty kind card
+     * poses — "how does the first one get here". Declared rather than
+     * inferred, because what `apply` adds is not statically knowable, and the
+     * empty state is exactly where a wrong guess would strand someone.
+     *
+     * An act that declares this also takes an optional `id` argument the
+     * framework adds: the id of the node it makes, when the caller has one —
+     * a seed being synced, an agent that will refer to the node in its next
+     * call. `freshId` hands it out first; an id already in the graph is
+     * refused by name rather than quietly suffixed.
+     */
+    readonly creates?: readonly KindOfSchema<S>[];
+    /**
+     * Edge kinds this mutation makes, and edge kinds it breaks.
+     *
+     * The seam that lets a LINE offer its own actions: select the drawn edge
+     * and every mutation that declares its kind derives an offer, endpoints
+     * prefilled by matching argument kinds. Declared, like `creates`, because
+     * what `apply` does to edges is not statically knowable.
+     */
+    readonly connects?: readonly string[];
+    readonly severs?: readonly string[];
+    /**
+     * How this act reads from the OTHER end of the tie.
+     *
+     * An act that declares what it connects or severs is offered from either
+     * endpoint — standing on a person, "take this one off the run" is the
+     * natural thing to say. The button there was labelled with `title`, which
+     * is written from the subject's side: "Hand it to someone", offered on the
+     * person, reads as handing the PERSON to someone.
+     *
+     * Declared rather than derived, for the reason `connects` is: an edge's
+     * `inverse` gives the relation's two readings but not the verb, and a
+     * guessed verb on a control that changes the graph is the wrong place to
+     * be nearly right. `graview check` warns `act-without-far-end-reading`
+     * when an act is offerable from an end it has no words for, naming that
+     * end — the same warning shape as `edge-without-inverse`.
+     */
+    readonly fromTheOtherEnd?: string;
+    /**
+     * Fields of the SUBJECT this mutation writes.
+     *
+     * The declared answer to "what changes this field", which the in-place
+     * edit and the derived edit act both read. Without it the framework
+     * guesses from names — an input argument called exactly like a field
+     * writes that field — which is right for `rename(label)` and blind to
+     * `finish()` setting `done`. Declared, the guess is replaced rather than
+     * added to: a mutation that says what it writes is believed about it, and
+     * only about it.
+     */
+    readonly writes?: readonly string[];
+    /**
+     * The app saying "this is the act of this product". A pinned mutation
+     * ranks above its unpinned peers wherever actions are offered — never
+     * above a rule's repairs, never out of the destructive tail — and sits
+     * in the menu's head section. A person's own pins, made from the menu,
+     * outrank the app's.
+     */
+    readonly pinned?: boolean;
+    /** One-line description of a concrete application, for previews and logs. */
+    readonly describe?: (args: z.infer<I>, graph: GraphReader<NodeOfSchema<S>>) => string;
+    readonly apply: (context: MutationContext<S>, args: z.infer<I>) => void;
+}
+export interface MutationDefinition<S extends AnySchema = AnySchema, Name extends string = string, I extends z.ZodType = z.ZodType> extends MutationDefinitionSpec<S, I> {
+    readonly name: Name;
+    /**
+     * Set by the framework on a mutation it derived rather than an app
+     * declared: the per-kind edit act, or the per-kind remove act. An edit's
+     * permission resolves through the declared acts that already write or
+     * create the kind; a remove's through the acts that create it — who may
+     * bring a thing into being may take it out — so a policy needs no second
+     * list for either.
+     */
+    readonly derived?: {
+        readonly kind: string;
+        readonly act: "edit" | "remove";
+    };
+}
+export type AnyMutationDefinition<S extends AnySchema = AnySchema> = MutationDefinition<S, string, z.ZodType>;
+/** A concrete, ready-to-apply mutation: a name plus validated arguments. */
+export interface MutationCall<Name extends string = string> {
+    readonly name: Name;
+    readonly args: Record<string, unknown>;
+}
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/mutations/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAC7B,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AACxD,OAAO,KAAK,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChE,OAAO,KAAK,EAAE,SAAS,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAEjF;;;GAGG;AACH,MAAM,WAAW,eAAe,CAAC,CAAC,SAAS,SAAS;IAClD,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,CAAC;IAC7C,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAC;IACnB,OAAO,CAAC,IAAI,EAAE,YAAY,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC;IACrC,2DAA2D;IAC3D,UAAU,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,SAAS,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAC7D,OAAO,CAAC,IAAI,EAAE,SAAS,GAAG,IAAI,CAAC;IAC/B,UAAU,CAAC,IAAI,EAAE,SAAS,GAAG,IAAI,CAAC;IAClC,wEAAwE;IACxE,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9D,+DAA+D;IAC/D,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAChD,mDAAmD;IACnD,IAAI,CAAC,SAAS,EAAE,SAAS,GAAG,IAAI,CAAC;CAClC;AAED,MAAM,WAAW,sBAAsB,CAAC,CAAC,SAAS,SAAS,EAAE,CAAC,SAAS,CAAC,CAAC,OAAO;IAC9E,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAC;IAClB,8CAA8C;IAC9C,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B;;;;OAIG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE;QACjB,QAAQ,CAAC,KAAK,EAAE,SAAS,YAAY,CAAC,CAAC,CAAC,EAAE,GAAG,GAAG,CAAC;QACjD,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;KACtB,CAAC;IACF;;;;;;;OAOG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,OAAO,CAAC;IAC/B;;;;;;;;;;;;;;OAcG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,YAAY,CAAC,CAAC,CAAC,EAAE,CAAC;IAC9C;;;;;;;OAOG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACtC,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC;;;;;;;;;;;;;;;OAeG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;IAClC;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC;;;;;;OAMG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC;IAC1B,6EAA6E;IAC7E,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,WAAW,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,KAAK,MAAM,CAAC;IACtF,QAAQ,CAAC,KAAK,EAAE,CAAC,OAAO,EAAE,eAAe,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC;CACzE;AAED,MAAM,WAAW,kBAAkB,CACjC,CAAC,SAAS,SAAS,GAAG,SAAS,EAC/B,IAAI,SAAS,MAAM,GAAG,MAAM,EAC5B,CAAC,SAAS,CAAC,CAAC,OAAO,GAAG,CAAC,CAAC,OAAO,CAC/B,SAAQ,sBAAsB,CAAC,CAAC,EAAE,CAAC,CAAC;IACpC,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC;IACpB;;;;;;;OAOG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE;QAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,QAAQ,CAAA;KAAE,CAAC;CAC/E;AAED,MAAM,MAAM,qBAAqB,CAAC,CAAC,SAAS,SAAS,GAAG,SAAS,IAC/D,kBAAkB,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC;AAE3C,4EAA4E;AAC5E,MAAM,WAAW,YAAY,CAAC,IAAI,SAAS,MAAM,GAAG,MAAM;IACxD,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACxC"}

package/dist/mutations/types.js

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

package/dist/mutations/types.js.map

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

package/dist/ops/log.d.ts

@@ -0,0 +1,35 @@
+import { Graph } from "../graph/graph.js";
+import type { AnySchema } from "../schema/schema.js";
+import type { Batch, Operation } from "./types.js";
+/**
+ * The append-only log. Nothing here mutates or removes an entry: an undo is
+ * a new op carrying the inverse, so history is never destroyed and the log
+ * doubles as an audit trail of what an agent did on your behalf.
+ */
+export declare class OperationLog {
+    private readonly ops;
+    get length(): number;
+    all(): readonly Operation[];
+    append(op: Operation): void;
+    /** Restores a log from storage, checking the sequence is intact. */
+    static from(ops: readonly Operation[]): OperationLog;
+    get(id: string): Operation | undefined;
+    /** Ops that have not been inverted by a later op. */
+    live(): Operation[];
+    /**
+     * An op stands unless a LIVE op undoes it. That one sentence is the whole
+     * redo mechanism: undoing an undo makes the undo itself not live, which
+     * revives its target. Undoers always follow their target, so resolving
+     * from the end of the log backwards terminates in one pass.
+     */
+    undoneIds(): Set<string>;
+    opsInBatch(batchId: string): Operation[];
+    batches(): Batch[];
+    /** Rebuilds the graph from empty by folding every live op forward. */
+    fold<S extends AnySchema>(schema: S, options?: {
+        validate?: boolean;
+    }): Graph<S>;
+    /** Serializable form for a persistence adapter. */
+    toJSON(): Operation[];
+}
+//# sourceMappingURL=log.d.ts.map

package/dist/ops/log.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"log.d.ts","sourceRoot":"","sources":["../../src/ops/log.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAC;AAC1C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AACrD,OAAO,KAAK,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAEnD;;;;GAIG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAmB;IAEvC,IAAI,MAAM,IAAI,MAAM,CAEnB;IAED,GAAG,IAAI,SAAS,SAAS,EAAE;IAI3B,MAAM,CAAC,EAAE,EAAE,SAAS,GAAG,IAAI;IAS3B,oEAAoE;IACpE,MAAM,CAAC,IAAI,CAAC,GAAG,EAAE,SAAS,SAAS,EAAE,GAAG,YAAY;IAMpD,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS;IAItC,qDAAqD;IACrD,IAAI,IAAI,SAAS,EAAE;IAKnB;;;;;OAKG;IACH,SAAS,IAAI,GAAG,CAAC,MAAM,CAAC;IAqBxB,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,EAAE;IAIxC,OAAO,IAAI,KAAK,EAAE;IA0BlB,sEAAsE;IACtE,IAAI,CAAC,CAAC,SAAS,SAAS,EAAE,MAAM,EAAE,CAAC,EAAE,OAAO,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,KAAK,CAAC,CAAC,CAAC;IAQhF,mDAAmD;IACnD,MAAM,IAAI,SAAS,EAAE;CAGtB"}

package/dist/ops/log.js

@@ -0,0 +1,103 @@
+import { Graph } from "../graph/graph.js";
+/**
+ * The append-only log. Nothing here mutates or removes an entry: an undo is
+ * a new op carrying the inverse, so history is never destroyed and the log
+ * doubles as an audit trail of what an agent did on your behalf.
+ */
+export class OperationLog {
+    ops = [];
+    get length() {
+        return this.ops.length;
+    }
+    all() {
+        return this.ops;
+    }
+    append(op) {
+        if (op.seq !== this.ops.length) {
+            throw new Error(`Op "${op.id}" has seq ${op.seq} but the log is ${this.ops.length} long`);
+        }
+        this.ops.push(op);
+    }
+    /** Restores a log from storage, checking the sequence is intact. */
+    static from(ops) {
+        const log = new OperationLog();
+        for (const op of ops)
+            log.append(op);
+        return log;
+    }
+    get(id) {
+        return this.ops.find((op) => op.id === id);
+    }
+    /** Ops that have not been inverted by a later op. */
+    live() {
+        const undone = this.undoneIds();
+        return this.ops.filter((op) => !undone.has(op.id));
+    }
+    /**
+     * An op stands unless a LIVE op undoes it. That one sentence is the whole
+     * redo mechanism: undoing an undo makes the undo itself not live, which
+     * revives its target. Undoers always follow their target, so resolving
+     * from the end of the log backwards terminates in one pass.
+     */
+    undoneIds() {
+        const undoers = new Map();
+        for (const op of this.ops) {
+            if (!op.undoes)
+                continue;
+            const list = undoers.get(op.undoes);
+            if (list)
+                list.push(op.id);
+            else
+                undoers.set(op.undoes, [op.id]);
+        }
+        const live = new Map();
+        for (let i = this.ops.length - 1; i >= 0; i--) {
+            const op = this.ops[i];
+            const mine = undoers.get(op.id) ?? [];
+            live.set(op.id, !mine.some((id) => live.get(id) === true));
+        }
+        return new Set(this.ops.filter((op) => live.get(op.id) === false).map((op) => op.id));
+    }
+    opsInBatch(batchId) {
+        return this.ops.filter((op) => op.batch === batchId);
+    }
+    batches() {
+        const undone = this.undoneIds();
+        const order = [];
+        const grouped = new Map();
+        for (const op of this.ops) {
+            const list = grouped.get(op.batch);
+            if (list)
+                list.push(op);
+            else {
+                grouped.set(op.batch, [op]);
+                order.push(op.batch);
+            }
+        }
+        return order.map((id) => {
+            const ops = grouped.get(id) ?? [];
+            const first = ops[0];
+            return {
+                id,
+                author: first.author,
+                intent: first.intent,
+                at: first.at,
+                ops,
+                undone: ops.every((op) => undone.has(op.id)),
+            };
+        });
+    }
+    /** Rebuilds the graph from empty by folding every live op forward. */
+    fold(schema, options) {
+        const graph = new Graph(schema, options);
+        for (const op of this.ops) {
+            graph.applyPrimitives(op.primitives);
+        }
+        return graph;
+    }
+    /** Serializable form for a persistence adapter. */
+    toJSON() {
+        return [...this.ops];
+    }
+}
+//# sourceMappingURL=log.js.map

package/dist/ops/log.js.map

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