@graview/tools 0.1.0

package/dist/providers/jev.d.ts

@@ -0,0 +1,115 @@
+import type { Question } from "../questions.js";
+/**
+ * THE PROVIDER ITSELF: one call, many questions, honest about failure.
+ *
+ * A decision provider takes one state and a MAP of typed questions and
+ * answers under the same keys — so a node's whole unset half is one
+ * request, not one per field, and a fan-out over every node of a kind is
+ * as many requests as there are nodes, never as many as there are fields.
+ *
+ * What comes back is typed by construction: a Choice is one of the names
+ * we sent, a truth is a probability, a Score is a weighted position on the
+ * levels we sent. There is no parse-and-refuse layer because there is
+ * nothing to parse.
+ *
+ * Failure is told apart by whose it is. 429 and 529 are the service busy,
+ * and are retried with backoff; 401 is the SEAT's problem — the key was
+ * refused — and is said so; 422 is OURS — we sent a malformed question —
+ * and is said so, because blaming the model for a bug in the derivation
+ * would send somebody looking in the wrong place.
+ *
+ * The key is read from the environment and travels in one header. It is
+ * never in a thrown error, never in a log line, never in the graph.
+ */
+export declare const JEV_ENDPOINT = "https://api.typesafe.ai/v1/systemone";
+export declare const JEV_MODEL = "jev-latest";
+/** Input is metered at this rate; output is not metered at all. */
+export declare const JEV_INPUT_USD_PER_MILLION = 0.042;
+export type ChoiceAnswer = {
+    readonly type: "choice";
+    readonly choice: string;
+    readonly confidence: number;
+    readonly probabilities: Readonly<Record<string, number>>;
+};
+export type NoulAnswer = {
+    readonly type: "noul";
+    readonly noul: number;
+};
+export type ScoreAnswer = {
+    readonly type: "score";
+    readonly score: number;
+    readonly confidence: number;
+    readonly probabilities: Readonly<Record<string, number>>;
+    readonly legend: Readonly<Record<string, string>>;
+};
+export type Answer = ChoiceAnswer | NoulAnswer | ScoreAnswer;
+export interface Usage {
+    readonly inputTokens: number;
+    readonly outputTokens: number;
+    /** Requests made, retries excluded. */
+    readonly calls: number;
+    readonly questions: number;
+}
+export interface Decided {
+    readonly answers: Readonly<Record<string, Answer>>;
+    /** This call's own usage. */
+    readonly usage: {
+        readonly inputTokens: number;
+        readonly outputTokens: number;
+    };
+}
+/** The whole provider surface: one state, a map of questions, typed answers back. */
+export type Decide = (state: unknown, questions: Readonly<Record<string, Question>>) => Promise<Decided>;
+/** Whose failure it was, so a surface can say so. */
+export type JevFailure = "seat" | "ours" | "busy" | "network" | "shape";
+export declare class JevError extends Error {
+    readonly failure: JevFailure;
+    readonly status: number | undefined;
+    constructor(failure: JevFailure, message: string, status?: number);
+}
+type FetchLike = (input: string, init: {
+    method: string;
+    headers: Record<string, string>;
+    body: string;
+    signal?: AbortSignal;
+}) => Promise<{
+    ok: boolean;
+    status: number;
+    text(): Promise<string>;
+}>;
+export interface JevOptions {
+    /**
+     * The key, when the call goes straight to the provider. Absent when the
+     * call goes to a bridge that holds the key itself (see `baseUrl`).
+     */
+    readonly apiKey?: string;
+    /** Where to post. The provider itself, or a same-origin bridge. */
+    readonly baseUrl?: string;
+    readonly model?: string;
+    /** How many times a busy answer is retried before it is given up on. */
+    readonly retries?: number;
+    /** Injectable: how long to wait before retry `n` (1-based), in ms. */
+    readonly backoffMs?: (attempt: number) => number;
+    /** Injectable for tests. */
+    readonly fetch?: FetchLike;
+    readonly sleep?: (ms: number) => Promise<void>;
+    /** Told after every completed request, with the running total. */
+    readonly onUsage?: (usage: Usage) => void;
+}
+/**
+ * The key, from the environment: TYPESAFE_API_KEY is the documented name;
+ * JEV_API_KEY is accepted for the person who set it before reading the
+ * docs. In a browser there is no environment, and this answers undefined —
+ * which is what makes a bridge the right door there.
+ */
+export declare function jevKeyFromEnvironment(env?: Readonly<Record<string, string | undefined>> | undefined): string | undefined;
+/** What a number of input tokens costs, in dollars. Output is free. */
+export declare function jevCostUsd(inputTokens: number): number;
+/**
+ * One Decide from one key (or one bridge). Retries are the service's busy
+ * answers only — 429, 529 — with backoff; everything else is said once,
+ * with whose failure it was, and never with the key in it.
+ */
+export declare function jevDecide(options?: JevOptions): Decide;
+export {};
+//# sourceMappingURL=jev.d.ts.map

package/dist/providers/jev.d.ts.map

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

package/dist/providers/jev.js

@@ -0,0 +1,148 @@
+/**
+ * THE PROVIDER ITSELF: one call, many questions, honest about failure.
+ *
+ * A decision provider takes one state and a MAP of typed questions and
+ * answers under the same keys — so a node's whole unset half is one
+ * request, not one per field, and a fan-out over every node of a kind is
+ * as many requests as there are nodes, never as many as there are fields.
+ *
+ * What comes back is typed by construction: a Choice is one of the names
+ * we sent, a truth is a probability, a Score is a weighted position on the
+ * levels we sent. There is no parse-and-refuse layer because there is
+ * nothing to parse.
+ *
+ * Failure is told apart by whose it is. 429 and 529 are the service busy,
+ * and are retried with backoff; 401 is the SEAT's problem — the key was
+ * refused — and is said so; 422 is OURS — we sent a malformed question —
+ * and is said so, because blaming the model for a bug in the derivation
+ * would send somebody looking in the wrong place.
+ *
+ * The key is read from the environment and travels in one header. It is
+ * never in a thrown error, never in a log line, never in the graph.
+ */
+export const JEV_ENDPOINT = "https://api.typesafe.ai/v1/systemone";
+export const JEV_MODEL = "jev-latest";
+/** Input is metered at this rate; output is not metered at all. */
+export const JEV_INPUT_USD_PER_MILLION = 0.042;
+export class JevError extends Error {
+    failure;
+    status;
+    constructor(failure, message, status) {
+        super(message);
+        this.name = "JevError";
+        this.failure = failure;
+        this.status = status;
+    }
+}
+/**
+ * The key, from the environment: TYPESAFE_API_KEY is the documented name;
+ * JEV_API_KEY is accepted for the person who set it before reading the
+ * docs. In a browser there is no environment, and this answers undefined —
+ * which is what makes a bridge the right door there.
+ */
+export function jevKeyFromEnvironment(env = globalThis.process?.env) {
+    const key = env?.["TYPESAFE_API_KEY"] || env?.["JEV_API_KEY"];
+    return key && key.length > 0 ? key : undefined;
+}
+/** What a number of input tokens costs, in dollars. Output is free. */
+export function jevCostUsd(inputTokens) {
+    return (inputTokens / 1_000_000) * JEV_INPUT_USD_PER_MILLION;
+}
+const isAnswer = (value) => {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const answer = value;
+    switch (answer.type) {
+        case "choice":
+            return typeof answer.choice === "string";
+        case "noul":
+            return typeof answer.noul === "number";
+        case "score":
+            return typeof answer.score === "number";
+        default:
+            return false;
+    }
+};
+/**
+ * One Decide from one key (or one bridge). Retries are the service's busy
+ * answers only — 429, 529 — with backoff; everything else is said once,
+ * with whose failure it was, and never with the key in it.
+ */
+export function jevDecide(options = {}) {
+    const call = options.fetch ?? globalThis.fetch;
+    const url = options.baseUrl ?? JEV_ENDPOINT;
+    const retries = options.retries ?? 3;
+    const backoff = options.backoffMs ?? ((attempt) => 400 * 2 ** (attempt - 1));
+    const sleep = options.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+    const total = { inputTokens: 0, outputTokens: 0, calls: 0, questions: 0 };
+    return async (state, questions) => {
+        const asked = Object.keys(questions).length;
+        if (asked === 0)
+            return { answers: {}, usage: { inputTokens: 0, outputTokens: 0 } };
+        const body = JSON.stringify({ model: options.model ?? JEV_MODEL, state, questions });
+        const headers = { "content-type": "application/json" };
+        if (options.apiKey)
+            headers["authorization"] = `Bearer ${options.apiKey}`;
+        for (let attempt = 0;; attempt++) {
+            let response;
+            try {
+                response = await call(url, {
+                    method: "POST",
+                    headers,
+                    body,
+                    ...(typeof AbortSignal !== "undefined" && "timeout" in AbortSignal ? { signal: AbortSignal.timeout(60_000) } : {}),
+                });
+            }
+            catch (error) {
+                throw new JevError("network", `The decision provider could not be reached: ${error instanceof Error ? error.message : String(error)}`);
+            }
+            if (response.status === 429 || response.status === 529) {
+                if (attempt < retries) {
+                    await sleep(backoff(attempt + 1));
+                    continue;
+                }
+                throw new JevError("busy", `The decision provider is ${response.status === 429 ? "rate-limiting" : "overloaded"} and stayed so through ${retries} retries.`, response.status);
+            }
+            if (response.status === 401 || response.status === 403) {
+                throw new JevError("seat", "The decision provider refused the key. That is a seat problem — check TYPESAFE_API_KEY — not the model's.", response.status);
+            }
+            if (response.status === 422) {
+                const said = (await response.text()).slice(0, 240);
+                throw new JevError("ours", `The decision provider could not read a question we sent. That is our bug, not the model's: ${said}`, 422);
+            }
+            if (!response.ok) {
+                throw new JevError("network", `The decision provider answered ${response.status}: ${(await response.text()).slice(0, 160)}`, response.status);
+            }
+            let parsed;
+            try {
+                parsed = JSON.parse(await response.text());
+            }
+            catch {
+                throw new JevError("shape", "The decision provider answered in a shape that is not JSON.");
+            }
+            if (typeof parsed.error === "string") {
+                throw new JevError("network", `The decision provider said: ${parsed.error}`, response.status);
+            }
+            const answers = {};
+            for (const [key, value] of Object.entries(parsed.answers ?? {})) {
+                if (!(key in questions))
+                    continue;
+                if (!isAnswer(value))
+                    throw new JevError("shape", `The answer to "${key}" is not a typed answer.`);
+                answers[key] = value;
+            }
+            for (const key of Object.keys(questions)) {
+                if (!(key in answers))
+                    throw new JevError("shape", `No answer came back for "${key}".`);
+            }
+            const usage = { inputTokens: parsed.usage?.input_tokens ?? 0, outputTokens: parsed.usage?.output_tokens ?? 0 };
+            total.inputTokens += usage.inputTokens;
+            total.outputTokens += usage.outputTokens;
+            total.calls += 1;
+            total.questions += asked;
+            options.onUsage?.({ ...total });
+            return { answers, usage };
+        }
+    };
+}
+//# sourceMappingURL=jev.js.map

package/dist/providers/jev.js.map

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

package/dist/providers/lens.d.ts

@@ -0,0 +1,24 @@
+import type { AnySchema, NodeOfSchema } from "@graview/core";
+import type { AffordanceProvider } from "../types.js";
+export interface LensAction<S extends AnySchema> {
+    readonly id: string;
+    readonly label: string;
+    readonly mutation: string;
+    /** Whether this lens can do anything with the given selection. */
+    readonly applies: (nodes: readonly NodeOfSchema<S>[]) => boolean;
+    readonly args: (nodes: readonly NodeOfSchema<S>[]) => Readonly<Record<string, unknown>>;
+    readonly why?: string;
+}
+/**
+ * What the ACTIVE lens can do with this selection — collapse, align, group.
+ *
+ * A lens is a way of looking, so its actions belong to the looking rather
+ * than to the schema: "collapse this week" means nothing outside a timeline.
+ * Registering them here keeps them in the same ranked set as everything else,
+ * so the interface never has two competing action surfaces.
+ */
+export declare function lensProvider<S extends AnySchema>(lens: {
+    name: string;
+    actions: readonly LensAction<S>[];
+}): AffordanceProvider<S>;
+//# sourceMappingURL=lens.d.ts.map

package/dist/providers/lens.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lens.d.ts","sourceRoot":"","sources":["../../src/providers/lens.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAC7D,OAAO,KAAK,EAAc,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAIlE,MAAM,WAAW,UAAU,CAAC,CAAC,SAAS,SAAS;IAC7C,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,kEAAkE;IAClE,QAAQ,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,SAAS,YAAY,CAAC,CAAC,CAAC,EAAE,KAAK,OAAO,CAAC;IACjE,QAAQ,CAAC,IAAI,EAAE,CAAC,KAAK,EAAE,SAAS,YAAY,CAAC,CAAC,CAAC,EAAE,KAAK,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACxF,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,CAAC,SAAS,SAAS,EAC9C,IAAI,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,SAAS,UAAU,CAAC,CAAC,CAAC,EAAE,CAAA;CAAE,GACxD,kBAAkB,CAAC,CAAC,CAAC,CAuBvB"}

package/dist/providers/lens.js

@@ -0,0 +1,36 @@
+const LENS_SCORE = 55;
+/**
+ * What the ACTIVE lens can do with this selection — collapse, align, group.
+ *
+ * A lens is a way of looking, so its actions belong to the looking rather
+ * than to the schema: "collapse this week" means nothing outside a timeline.
+ * Registering them here keeps them in the same ranked set as everything else,
+ * so the interface never has two competing action surfaces.
+ */
+export function lensProvider(lens) {
+    return {
+        name: "lens",
+        derive({ nodes }) {
+            if (nodes.length === 0)
+                return {};
+            const affordances = [];
+            for (const action of lens.actions) {
+                if (!action.applies(nodes))
+                    continue;
+                affordances.push({
+                    id: `lens:${lens.name}:${action.id}`,
+                    label: action.label,
+                    provider: "lens",
+                    mutation: action.mutation,
+                    args: action.args(nodes),
+                    open: [],
+                    score: LENS_SCORE,
+                    why: action.why ?? `the ${lens.name} lens can do this here`,
+                    nodeIds: nodes.map((node) => node.id),
+                });
+            }
+            return { affordances };
+        },
+    };
+}
+//# sourceMappingURL=lens.js.map

package/dist/providers/lens.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lens.js","sourceRoot":"","sources":["../../src/providers/lens.ts"],"names":[],"mappings":"AAGA,MAAM,UAAU,GAAG,EAAE,CAAC;AAYtB;;;;;;;GAOG;AACH,MAAM,UAAU,YAAY,CAC1B,IAAyD;IAEzD,OAAO;QACL,IAAI,EAAE,MAAM;QACZ,MAAM,CAAC,EAAE,KAAK,EAAE;YACd,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;gBAAE,OAAO,EAAE,CAAC;YAClC,MAAM,WAAW,GAAiB,EAAE,CAAC;YACrC,KAAK,MAAM,MAAM,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;gBAClC,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC;oBAAE,SAAS;gBACrC,WAAW,CAAC,IAAI,CAAC;oBACf,EAAE,EAAE,QAAQ,IAAI,CAAC,IAAI,IAAI,MAAM,CAAC,EAAE,EAAE;oBACpC,KAAK,EAAE,MAAM,CAAC,KAAK;oBACnB,QAAQ,EAAE,MAAM;oBAChB,QAAQ,EAAE,MAAM,CAAC,QAAQ;oBACzB,IAAI,EAAE,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC;oBACxB,IAAI,EAAE,EAAE;oBACR,KAAK,EAAE,UAAU;oBACjB,GAAG,EAAE,MAAM,CAAC,GAAG,IAAI,OAAO,IAAI,CAAC,IAAI,wBAAwB;oBAC3D,OAAO,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC;iBACtC,CAAC,CAAC;YACL,CAAC;YACD,OAAO,EAAE,WAAW,EAAE,CAAC;QACzB,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/providers/llm.d.ts

@@ -0,0 +1,25 @@
+import type { AnySchema } from "@graview/core";
+import type { Affordance, DeriveContext } from "../types.js";
+export interface LlmProposal {
+    readonly label: string;
+    readonly mutation: string;
+    readonly args: Readonly<Record<string, unknown>>;
+    readonly why: string;
+}
+export interface LlmProvider<S extends AnySchema> {
+    propose(context: DeriveContext<S>): Promise<readonly LlmProposal[]>;
+}
+/**
+ * The LLM is ONE affordance provider, and an optional one — not the
+ * mechanism. It runs last, only when the schema, the invariants and the
+ * structure of the graph came up short, and everything it returns is checked
+ * against the same schema and invariants as everything else.
+ *
+ * Nothing here talks to a model. An app injects one, which keeps the whole
+ * tools package headless and testable, and keeps "no LLM configured" an
+ * ordinary state rather than a degraded one.
+ */
+export declare function deriveWithLlm<S extends AnySchema>(provider: LlmProvider<S>, context: DeriveContext<S>, existing: readonly Affordance[], options?: {
+    minimum?: number;
+}): Promise<Affordance[]>;
+//# sourceMappingURL=llm.d.ts.map

package/dist/providers/llm.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"llm.d.ts","sourceRoot":"","sources":["../../src/providers/llm.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAC/C,OAAO,KAAK,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAE7D,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACjD,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,WAAW,CAAC,CAAC,SAAS,SAAS;IAC9C,OAAO,CAAC,OAAO,EAAE,aAAa,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,SAAS,WAAW,EAAE,CAAC,CAAC;CACrE;AAID;;;;;;;;;GASG;AACH,wBAAsB,aAAa,CAAC,CAAC,SAAS,SAAS,EACrD,QAAQ,EAAE,WAAW,CAAC,CAAC,CAAC,EACxB,OAAO,EAAE,aAAa,CAAC,CAAC,CAAC,EACzB,QAAQ,EAAE,SAAS,UAAU,EAAE,EAC/B,OAAO,GAAE;IAAE,OAAO,CAAC,EAAE,MAAM,CAAA;CAAO,GACjC,OAAO,CAAC,UAAU,EAAE,CAAC,CA8BvB"}

package/dist/providers/llm.js

@@ -0,0 +1,44 @@
+const LLM_SCORE = 20;
+/**
+ * The LLM is ONE affordance provider, and an optional one — not the
+ * mechanism. It runs last, only when the schema, the invariants and the
+ * structure of the graph came up short, and everything it returns is checked
+ * against the same schema and invariants as everything else.
+ *
+ * Nothing here talks to a model. An app injects one, which keeps the whole
+ * tools package headless and testable, and keeps "no LLM configured" an
+ * ordinary state rather than a degraded one.
+ */
+export async function deriveWithLlm(provider, context, existing, options = {}) {
+    const minimum = options.minimum ?? 3;
+    if (existing.length >= minimum)
+        return [];
+    const proposals = await provider.propose(context);
+    const affordances = [];
+    proposals.forEach((proposal, index) => {
+        // A proposal naming a mutation that does not exist is a hallucination,
+        // and it stops here rather than reaching the interface.
+        let known = true;
+        try {
+            context.store.mutation(proposal.mutation);
+        }
+        catch {
+            known = false;
+        }
+        if (!known)
+            return;
+        affordances.push({
+            id: `llm:${index}`,
+            label: proposal.label,
+            provider: "llm",
+            mutation: proposal.mutation,
+            args: proposal.args,
+            open: [],
+            score: LLM_SCORE - index,
+            why: proposal.why,
+            nodeIds: context.selection,
+        });
+    });
+    return affordances;
+}
+//# sourceMappingURL=llm.js.map

package/dist/providers/llm.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"llm.js","sourceRoot":"","sources":["../../src/providers/llm.ts"],"names":[],"mappings":"AAcA,MAAM,SAAS,GAAG,EAAE,CAAC;AAErB;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CACjC,QAAwB,EACxB,OAAyB,EACzB,QAA+B,EAC/B,UAAgC,EAAE;IAElC,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,IAAI,CAAC,CAAC;IACrC,IAAI,QAAQ,CAAC,MAAM,IAAI,OAAO;QAAE,OAAO,EAAE,CAAC;IAE1C,MAAM,SAAS,GAAG,MAAM,QAAQ,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;IAClD,MAAM,WAAW,GAAiB,EAAE,CAAC;IACrC,SAAS,CAAC,OAAO,CAAC,CAAC,QAAQ,EAAE,KAAK,EAAE,EAAE;QACpC,uEAAuE;QACvE,wDAAwD;QACxD,IAAI,KAAK,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC;YACH,OAAO,CAAC,KAAK,CAAC,QAAQ,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;QAC5C,CAAC;QAAC,MAAM,CAAC;YACP,KAAK,GAAG,KAAK,CAAC;QAChB,CAAC;QACD,IAAI,CAAC,KAAK;YAAE,OAAO;QAEnB,WAAW,CAAC,IAAI,CAAC;YACf,EAAE,EAAE,OAAO,KAAK,EAAE;YAClB,KAAK,EAAE,QAAQ,CAAC,KAAK;YACrB,QAAQ,EAAE,KAAK;YACf,QAAQ,EAAE,QAAQ,CAAC,QAAQ;YAC3B,IAAI,EAAE,QAAQ,CAAC,IAAI;YACnB,IAAI,EAAE,EAAE;YACR,KAAK,EAAE,SAAS,GAAG,KAAK;YACxB,GAAG,EAAE,QAAQ,CAAC,GAAG;YACjB,OAAO,EAAE,OAAO,CAAC,SAAS;SAC3B,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;IACH,OAAO,WAAW,CAAC;AACrB,CAAC"}

package/dist/providers/schema.d.ts

@@ -0,0 +1,12 @@
+import { type AnySchema } from "@graview/core";
+import type { AffordanceProvider } from "../types.js";
+/**
+ * Which typed mutations are legal across the WHOLE selection.
+ *
+ * The declaration already says which kinds a mutation acts on and which
+ * argument the subject binds to, so "all three selected nodes are duties, and
+ * reassign acts on duties" is a fact the schema can answer — no per-selection
+ * code, and a new node kind gets its affordances the moment it is declared.
+ */
+export declare function schemaProvider<S extends AnySchema>(): AffordanceProvider<S>;
+//# sourceMappingURL=schema.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../src/providers/schema.ts"],"names":[],"mappings":"AAAA,OAAO,EAA6D,KAAK,SAAS,EAAc,MAAM,eAAe,CAAC;AACtH,OAAO,KAAK,EAAc,kBAAkB,EAA8B,MAAM,aAAa,CAAC;AAI9F;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,CAAC,SAAS,SAAS,KAAK,kBAAkB,CAAC,CAAC,CAAC,CAye3E"}