@graview/tools 0.1.0

package/dist/providers/structure.js

@@ -0,0 +1,211 @@
+import { fieldWords, humaniseField, labelOf, nodeRefKinds } from "@graview/core";
+const SHARED_SCORE = 70;
+const ALIGN_SCORE = 80;
+const IGNORED_FIELDS = new Set(["id", "kind"]);
+/**
+ * What is TRUE about this selection, and what that makes worth doing.
+ *
+ * Nothing here knows what a duty or a person is. It notices shared
+ * neighbours, agreement on a field, and the one node that breaks the
+ * agreement — then looks for a declared mutation that could resolve the
+ * difference. "Move the Wednesday run to Tuesday like the other three" comes
+ * out of this without anyone writing a rule about days, because the schema
+ * already said which mutation writes that field.
+ */
+export function structureProvider() {
+    return {
+        name: "structure",
+        derive({ store, nodes }) {
+            // A node's name as its kind says it, not its label field alone.
+            const named = (node) => labelOf(store.schema.tryDefinition(node.kind), node);
+            if (nodes.length < 2)
+                return {};
+            const observations = [];
+            const affordances = [];
+            const ids = nodes.map((node) => node.id);
+            // ---------------------------------------------------- shared neighbours
+            for (const edgeKind of store.schema.edgeKinds) {
+                const shared = intersect(nodes.map((node) => new Set([
+                    ...store.graph.out(node.id, edgeKind).map((n) => n.id),
+                    ...store.graph.in(node.id, edgeKind).map((n) => n.id),
+                ])));
+                for (const neighbourId of shared) {
+                    const neighbour = store.graph.getNode(neighbourId);
+                    if (!neighbour)
+                        continue;
+                    observations.push({
+                        id: `shared:${edgeKind}:${neighbourId}`,
+                        text: `all ${nodes.length} share "${named(neighbour)}" (${humaniseField(edgeKind).toLowerCase()})`,
+                        nodeIds: [...ids, neighbourId],
+                    });
+                }
+                // The near-miss is more interesting than the agreement: one node out
+                // of step is a thing you can fix.
+                const counts = new Map();
+                for (const node of nodes) {
+                    for (const neighbour of [
+                        ...store.graph.out(node.id, edgeKind),
+                        ...store.graph.in(node.id, edgeKind),
+                    ]) {
+                        counts.set(neighbour.id, (counts.get(neighbour.id) ?? 0) + 1);
+                    }
+                }
+                for (const [neighbourId, count] of counts) {
+                    if (count !== nodes.length - 1 || nodes.length < 3)
+                        continue;
+                    const neighbour = store.graph.getNode(neighbourId);
+                    if (!neighbour)
+                        continue;
+                    const odd = nodes.find((node) => ![
+                        ...store.graph.out(node.id, edgeKind),
+                        ...store.graph.in(node.id, edgeKind),
+                    ].some((n) => n.id === neighbourId));
+                    if (!odd)
+                        continue;
+                    observations.push({
+                        id: `near-shared:${edgeKind}:${neighbourId}`,
+                        text: `all but "${named(odd)}" share "${named(neighbour)}" (${humaniseField(edgeKind).toLowerCase()})`,
+                        nodeIds: [...ids, neighbourId],
+                    });
+                    for (const mutation of store.allMutations()) {
+                        const subject = mutation.subject;
+                        if (!subject)
+                            continue;
+                        if (subject.kinds !== "*" && !subject.kinds.includes(odd.kind)) {
+                            continue;
+                        }
+                        const target = argAccepting(mutation.input, neighbour.kind);
+                        if (!target)
+                            continue;
+                        affordances.push({
+                            id: `structure:join:${mutation.name}:${odd.id}:${neighbourId}`,
+                            label: `${mutation.title ?? mutation.name}: bring "${named(odd)}" in line with the others`,
+                            provider: "structure",
+                            mutation: mutation.name,
+                            args: { [subject.arg]: odd.id, [target]: neighbourId },
+                            open: [],
+                            score: SHARED_SCORE,
+                            why: `every other selected node is connected to "${named(neighbour)}"`,
+                            nodeIds: [odd.id, neighbourId],
+                        });
+                    }
+                }
+            }
+            // ------------------------------------------------- agreement on a field
+            const fields = new Set();
+            for (const node of nodes) {
+                for (const key of Object.keys(node)) {
+                    if (!IGNORED_FIELDS.has(key))
+                        fields.add(key);
+                }
+            }
+            // A field and its value in words: "all 3 share status open" read the key and the JSON.
+            const definitionOf = (kind) => store.schema.definitions.find((definition) => definition.kind === kind);
+            for (const field of [...fields].sort()) {
+                const words = fieldWords(definitionOf(nodes[0].kind), field).toLowerCase();
+                const values = nodes.map((node) => node[field]);
+                const groups = new Map();
+                values.forEach((value, index) => {
+                    const key = JSON.stringify(value ?? null);
+                    const list = groups.get(key);
+                    if (list)
+                        list.push(nodes[index]);
+                    else
+                        groups.set(key, [nodes[index]]);
+                });
+                if (groups.size === 1) {
+                    const [key] = [...groups.keys()];
+                    if (key === "null")
+                        continue;
+                    observations.push({
+                        id: `agree:${field}`,
+                        text: `all ${nodes.length} share the ${words} ${key}`,
+                        nodeIds: ids,
+                    });
+                    continue;
+                }
+                // A majority and exactly one hold-out: that is an alignment.
+                if (nodes.length < 3 || groups.size !== 2)
+                    continue;
+                const sorted = [...groups.entries()].sort((a, b) => b[1].length - a[1].length);
+                const [majorityKey, majority] = sorted[0];
+                const [, minority] = sorted[1];
+                if (minority.length !== 1 || majorityKey === "null")
+                    continue;
+                const odd = minority[0];
+                const majorityValue = JSON.parse(majorityKey);
+                observations.push({
+                    id: `odd-one-out:${field}`,
+                    text: `${majority.length} share the ${words} ${majorityKey}; "${named(odd)}" does not`,
+                    nodeIds: ids,
+                });
+                for (const mutation of store.allMutations()) {
+                    const subject = mutation.subject;
+                    if (!subject)
+                        continue;
+                    if (subject.kinds !== "*" && !subject.kinds.includes(odd.kind)) {
+                        continue;
+                    }
+                    const shape = shapeOf(mutation.input);
+                    if (!shape || !(field in shape))
+                        continue;
+                    // Fill every other argument this mutation needs from the node's own
+                    // current values, so the aligned change is exactly the one field.
+                    const args = {
+                        [subject.arg]: odd.id,
+                        [field]: majorityValue,
+                    };
+                    let satisfiable = true;
+                    for (const [name, schema] of Object.entries(shape)) {
+                        if (name in args)
+                            continue;
+                        if (schema.safeParse(undefined).success)
+                            continue;
+                        const current = odd[name];
+                        if (current === undefined) {
+                            satisfiable = false;
+                            break;
+                        }
+                        args[name] = current;
+                    }
+                    if (!satisfiable)
+                        continue;
+                    affordances.push({
+                        id: `structure:align:${mutation.name}:${field}:${odd.id}`,
+                        label: `Align the ${words} of "${named(odd)}" with the other ${majority.length}`,
+                        provider: "structure",
+                        mutation: mutation.name,
+                        args,
+                        open: [],
+                        score: ALIGN_SCORE,
+                        why: `${majority.length} of ${nodes.length} share the ${words} ${majorityKey}`,
+                        nodeIds: ids,
+                    });
+                }
+            }
+            return { affordances, observations };
+        },
+    };
+}
+function intersect(sets) {
+    if (sets.length === 0)
+        return [];
+    const [first, ...rest] = sets;
+    return [...first].filter((value) => rest.every((set) => set.has(value))).sort();
+}
+function shapeOf(input) {
+    return input.shape ?? null;
+}
+/** The first argument of a mutation that accepts a node of `kind`. */
+function argAccepting(input, kind) {
+    const shape = shapeOf(input);
+    if (!shape)
+        return null;
+    for (const [name] of Object.entries(shape)) {
+        const kinds = nodeRefKinds(shape[name]);
+        if (kinds && (kinds.includes("*") || kinds.includes(kind)))
+            return name;
+    }
+    return null;
+}
+//# sourceMappingURL=structure.js.map

package/dist/providers/structure.js.map

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

package/dist/questions.d.ts

@@ -0,0 +1,162 @@
+import { type AnySchema, type Store, type Violation } from "@graview/core";
+/**
+ * THE QUESTIONS ARE DERIVED, NOT AUTHORED.
+ *
+ * A Graview declaration already types every question worth asking. A
+ * `z.enum` is a Choice whose criteria are its own options; a `nodeRef` is a
+ * Choice over the live nodes of that kind, labelled the way every surface
+ * labels them; a `z.boolean` and an invariant are a truth with the rule as
+ * what "yes" means; a bounded number is a Score over its own levels. None
+ * of it is written by hand, for the same reason no agent tool is: two
+ * descriptions of one domain will disagree, and the one in the declaration
+ * is the one the store enforces.
+ *
+ * The shapes here are the wire shapes of a decision provider — a map of
+ * typed questions over one state, typed answers back under the same keys —
+ * so a derived question is sent as it is, and an answer is read straight
+ * into an argument of the act that writes the thing asked about.
+ */
+export type ChoiceQuestion = {
+    readonly type: "choice";
+    readonly instructions: string;
+    /** Option name → what it means, or null when the name says it all. */
+    readonly criteria: Readonly<Record<string, string | null>>;
+};
+export type NoulQuestion = {
+    readonly type: "noul";
+    readonly instructions: string;
+    readonly criteria?: {
+        readonly true?: string;
+        readonly false?: string;
+    };
+};
+export type ScoreQuestion = {
+    readonly type: "score";
+    readonly instructions: string;
+    /** Ordered level descriptions, lowest first. At least two. */
+    readonly criteria: readonly string[];
+};
+export type Question = ChoiceQuestion | NoulQuestion | ScoreQuestion;
+/** Where a question came from, and where its answer goes. */
+export type QuestionAbout = {
+    readonly about: "field";
+    readonly kind: string;
+    readonly field: string;
+    /** The act that writes the field, and the argument the answer fills. */
+    readonly writes?: {
+        readonly mutation: string;
+        readonly arg: string;
+        readonly subjectArg: string;
+    };
+} | {
+    readonly about: "argument";
+    readonly mutation: string;
+    readonly arg: string;
+    /** For a pair question: the other node the argument would name. Carried, not parsed — an id may hold a colon. */
+    readonly other?: string;
+} | {
+    readonly about: "rule";
+    readonly invariant: string;
+    readonly subjectId?: string;
+} | {
+    readonly about: "repair";
+    readonly invariant: string;
+    readonly subjectId?: string;
+    /** Option name → the call it means, arguments already settled. */
+    readonly options: Readonly<Record<string, {
+        readonly mutation: string;
+        readonly args: Readonly<Record<string, unknown>>;
+    }>>;
+};
+export type DerivedQuestion = QuestionAbout & {
+    /** Stable, code-facing. Never sent to the model. */
+    readonly id: string;
+    readonly question: Question;
+    /** For a Score: the field's own scale, so level 0 is `min`. */
+    readonly scale?: {
+        readonly min: number;
+        readonly max: number;
+    };
+};
+/**
+ * A QUESTION FOR A PERSON, because the answer was not one.
+ *
+ * "turf 0.5, bed 0.45" is a split, not an answer, and a low confidence is a
+ * shrug. Either is offered rather than applied: the question, the node it
+ * is about by name, and each option with its probability and the call it
+ * would be — so a surface can stand the question AT that node, with the
+ * choices as presses, rather than in a list somewhere else.
+ */
+export interface OfferedQuestion {
+    readonly id: string;
+    /** The node it is about, when it is about one. */
+    readonly nodeId?: string;
+    /** Its label, so a surface can say it without a lookup. */
+    readonly nodeLabel?: string;
+    /** The question in the declaration's words. */
+    readonly asks: string;
+    /** Why it is offered rather than applied. */
+    readonly because: "split" | "unsure";
+    readonly confidence: number;
+    readonly options: readonly {
+        readonly value: string;
+        readonly probability: number;
+        /** The call taking this option would be; absent when "no" means do nothing. */
+        readonly call?: {
+            readonly mutation: string;
+            readonly args: Readonly<Record<string, unknown>>;
+            readonly why?: string;
+        };
+    }[];
+}
+/** The number a Score answer means, on the field's own scale. */
+export declare function scoreToValue(field: {
+    readonly min: number;
+}, level: number): number;
+/**
+ * The questions a KIND asks of one of its members: one per settable field
+ * with a typed answer, each naming the act that writes it. A kind whose
+ * every field is prose asks nothing, and says so by an empty list.
+ */
+export declare function questionsForKind<S extends AnySchema>(store: Store<S>, kind: string): readonly DerivedQuestion[];
+/**
+ * The questions an ACT asks before it can be called: one per argument with
+ * a typed answer that `given` has not already settled. The subject is
+ * usually given — a run fans out over nodes and asks each one's questions
+ * — and an argument with no typed answer is simply not asked, which is
+ * what the checker already guaranteed a decision provider would never
+ * meet on its allowlist.
+ */
+export declare function questionsForMutation<S extends AnySchema>(store: Store<S>, name: string, given?: Readonly<Record<string, unknown>>): readonly DerivedQuestion[];
+/**
+ * A RULE IS A TRUTH, and its repairs are the closed set that follows.
+ *
+ * The invariant's own words are what "yes" means; a violation the store
+ * already raised narrows the follow-on Choice to the repairs it named, each
+ * with its arguments settled, so the answer is a call and not a guess.
+ * Asked without a violation, the follow-on is over the repairs the
+ * invariant declares it may name, which is what a loop asks before the
+ * store has judged.
+ */
+export declare function questionsForInvariant<S extends AnySchema>(store: Store<S>, name: string, violation?: Violation): readonly DerivedQuestion[];
+/**
+ * A PAIR IS A TRUTH. An act that joins a subject to one other node —
+ * "says it helps": a practice and a concern — asked of one particular pair
+ * is a yes-or-no question, and the act's own title and description are
+ * its words. Fan this out over every pair and you have a matrix nobody
+ * ever had to author.
+ */
+export declare function pairQuestion<S extends AnySchema>(store: Store<S>, name: string, subjectId: string, otherId: string): (DerivedQuestion & {
+    readonly about: "argument";
+}) | undefined;
+/**
+ * THE STATE A QUESTION IS ASKED OVER: one node as the model should see it
+ * — its kind and what the kind is for, its label, its readable fields in
+ * the declaration's own words, and what it is joined to, by label. Nothing
+ * a card would not show. Ids are kept beside labels so an answer that is
+ * an id can be checked against what was shown.
+ */
+export declare function nodeState<S extends AnySchema>(store: Store<S>, id: string): Readonly<Record<string, unknown>> | undefined;
+/** Every derived question in the app, for a reader — or a test — that wants the whole surface. */
+export declare function allQuestions<S extends AnySchema>(store: Store<S>): readonly DerivedQuestion[];
+//# sourceMappingURL=questions.d.ts.map

package/dist/questions.d.ts.map

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