@graview/tools 0.1.0

package/dist/types.d.ts

@@ -0,0 +1,122 @@
+import type { AnySchema, NodeOfSchema, Refusal, Store, Violation } from "@graview/core";
+/** Which provider contributed an action. Ranking reads this. */
+export type ProviderName = "invariant" | "structure" | "schema" | "lens" | "llm" | "insight";
+/** An argument the action still needs, and what would satisfy it. */
+import type { ArgShape } from "@graview/core";
+export interface OpenParameter {
+    readonly name: string;
+    /** May be omitted — an empty picker must not suppress the whole offer. */
+    readonly optional?: boolean;
+    /** Node kinds this argument accepts, when it names a node. */
+    readonly kinds?: readonly string[];
+    /** Ids the framework already knows would fit, so the UI can offer them. */
+    readonly candidates?: readonly string[];
+    /**
+     * What sort of answer it wants, read off the mutation's own schema.
+     *
+     * Without this an interface can only offer candidate ids, so every action
+     * needing a name, a date or a time was a dead end that looked live —
+     * "Rename · needs label" opened a list of nothing. The declaration always
+     * knew `label` was a non-empty string; nobody had asked it.
+     */
+    readonly shape?: ArgShape;
+}
+/**
+ * A legal thing to do with the current selection.
+ *
+ * Nobody authored these per selection. Each one is a typed mutation the
+ * providers below found by looking at the schema, the invariants and the
+ * shape of the graph — which is why a useful suggestion can appear that no
+ * rule was written to produce.
+ */
+export interface Affordance {
+    readonly id: string;
+    readonly label: string;
+    readonly provider: ProviderName;
+    /** Set when the mutation declares edge kinds it connects or severs. */
+    readonly ties?: boolean;
+    /** The mutation this would run. Every action is a typed mutation. */
+    readonly mutation: string;
+    /** Arguments already determined. */
+    readonly args: Readonly<Record<string, unknown>>;
+    /** Arguments the person or agent still has to choose. */
+    readonly open: readonly OpenParameter[];
+    /** Several calls when the action applies across a whole selection. */
+    readonly batch?: readonly Readonly<Record<string, unknown>>[];
+    /** Higher sorts first. */
+    readonly score: number;
+    /** Loses something a person made. Listed last, and marked, everywhere. */
+    readonly destructive?: boolean;
+    /**
+     * Held to the top of its band: by the person at this browser ("user") or
+     * by the app's declaration ("declared"). User pins outrank declared ones;
+     * neither outranks a repair or escapes the destructive tail.
+     */
+    readonly pinned?: "user" | "declared";
+    /** The observation that produced it, in the interface's own words. */
+    readonly why: string;
+    /** Nodes this acts on, for highlighting across planes. */
+    readonly nodeIds: readonly string[];
+    /**
+     * For a repair, the node whose declaration produced the broken check —
+     * the violation's own subject. Read by the ranking so that clicking a
+     * rule leads with the rule's repairs.
+     */
+    readonly subjectId?: string;
+    /**
+     * Where this sits in the ONE order every surface reads, stamped by the
+     * derivation after ranking: allowed acts from 0, then the withheld ones.
+     *
+     * Nothing needs it to render a list in order — the arrays are already in
+     * it — but a surface that regroups (the record page's acts beside its
+     * fields, the menu's fold) can say which entry the derivation put first
+     * instead of deciding for itself and disagreeing with the strip.
+     */
+    readonly rank?: number;
+}
+/** Something true about the selection that no rule was written to notice. */
+export interface Observation {
+    readonly id: string;
+    readonly text: string;
+    readonly nodeIds: readonly string[];
+}
+export interface DeriveContext<S extends AnySchema> {
+    readonly store: Store<S>;
+    readonly selection: readonly string[];
+    readonly nodes: readonly NodeOfSchema<S>[];
+    /** Kinds the selection denotes when it is kind cards rather than nodes. */
+    readonly kindSelection: readonly string[];
+    /** Concrete edges the selection names, when lines are selected. */
+    readonly edgeSelection: readonly {
+        kind: string;
+        from: string;
+        to: string;
+    }[];
+    /** Current violations, evaluated once and shared by every provider. */
+    readonly violations: readonly Violation[];
+    readonly context: Readonly<Record<string, unknown>>;
+}
+export interface AffordanceProvider<S extends AnySchema> {
+    readonly name: ProviderName;
+    derive(context: DeriveContext<S>): {
+        affordances?: readonly Affordance[];
+        observations?: readonly Observation[];
+    };
+}
+/** An action that exists, that this principal may not take, and why. */
+export interface WithheldAffordance extends Affordance {
+    readonly refusal: Refusal;
+}
+export interface AffordanceSet {
+    readonly affordances: readonly Affordance[];
+    /**
+     * Actions withheld by permission. Stated rather than hidden: an interface
+     * shows them disabled with the reason, and an agent is told a capability
+     * exists that it may not use, which is not the same as it not existing.
+     */
+    readonly withheld: readonly WithheldAffordance[];
+    readonly observations: readonly Observation[];
+    /** Milliseconds spent deriving, so a caller can see it stays cheap. */
+    readonly ms: number;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

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

package/dist/types.js

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

package/dist/types.js.map

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

package/dist/usage.d.ts

@@ -0,0 +1,10 @@
+import type { Operation } from "@graview/core";
+/** Decayed use per mutation name, from the tail of the log. */
+export declare function usageWeights(ops: readonly Operation[]): ReadonlyMap<string, number>;
+/**
+ * A bounded score boost from decayed use. Monotonic in use, capped at
+ * CEILING so history shuffles a band and never jumps one — a much-used act
+ * still ranks below every repair and above no destructive tail.
+ */
+export declare function usageBoost(weight: number): number;
+//# sourceMappingURL=usage.d.ts.map

package/dist/usage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"usage.d.ts","sourceRoot":"","sources":["../src/usage.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AA0B/C,+DAA+D;AAC/D,wBAAgB,YAAY,CAAC,GAAG,EAAE,SAAS,SAAS,EAAE,GAAG,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAqBnF;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAEjD"}

package/dist/usage.js

@@ -0,0 +1,59 @@
+/**
+ * WHAT YOU ACTUALLY USE, read off the op log.
+ *
+ * A menu that ranks only by what is structurally possible treats the act a
+ * workspace performs forty times a week exactly like the one it has never
+ * touched. The log already knows the difference — every applied mutation is
+ * an op with a name and a position — so the boost is DERIVED, deterministic
+ * and free of any model: recent and frequent use counts, decaying by
+ * half-lives of log distance so the menu tracks the season rather than the
+ * archive.
+ *
+ * This is the simple, derived stand-in for the deferred ELM ranking
+ * evaluation (ba7345a2): it feeds the same score field, and if that
+ * evaluation ever revisits with real data, its model replaces this
+ * arithmetic behind the same seam.
+ */
+/** How far back the boost reads, in ops. Everything older says nothing. */
+const WINDOW = 512;
+/** Ops of distance over which a use loses half its weight. */
+const HALF_LIFE = 64;
+/** The most a mutation's history may add to its score — well inside a band. */
+const CEILING = 8;
+/** Decayed use per mutation name, from the tail of the log. */
+export function usageWeights(ops) {
+    const weights = new Map();
+    if (ops.length === 0)
+        return weights;
+    const tail = ops.slice(-WINDOW);
+    /*
+     * A RETRACTED ACT IS NOT A USE. Undo ops themselves carry no mutation,
+     * so they never counted — but the ORIGINAL op they undo did, which
+     * taught the menu to promote exactly the acts people keep taking back.
+     * An undo always lands after its target, so a target inside the window
+     * has its undo inside it too.
+     */
+    const retracted = new Set();
+    for (const op of tail)
+        if (op.undoes)
+            retracted.add(op.undoes);
+    const last = ops[ops.length - 1].seq;
+    for (const op of tail) {
+        if (!op.mutation)
+            continue;
+        if (retracted.has(op.id))
+            continue;
+        const weight = Math.pow(0.5, (last - op.seq) / HALF_LIFE);
+        weights.set(op.mutation.name, (weights.get(op.mutation.name) ?? 0) + weight);
+    }
+    return weights;
+}
+/**
+ * A bounded score boost from decayed use. Monotonic in use, capped at
+ * CEILING so history shuffles a band and never jumps one — a much-used act
+ * still ranks below every repair and above no destructive tail.
+ */
+export function usageBoost(weight) {
+    return CEILING * (weight / (weight + 1));
+}
+//# sourceMappingURL=usage.js.map

package/dist/usage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"usage.js","sourceRoot":"","sources":["../src/usage.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;GAeG;AAEH,2EAA2E;AAC3E,MAAM,MAAM,GAAG,GAAG,CAAC;AACnB,8DAA8D;AAC9D,MAAM,SAAS,GAAG,EAAE,CAAC;AACrB,+EAA+E;AAC/E,MAAM,OAAO,GAAG,CAAC,CAAC;AAElB,+DAA+D;AAC/D,MAAM,UAAU,YAAY,CAAC,GAAyB;IACpD,MAAM,OAAO,GAAG,IAAI,GAAG,EAAkB,CAAC;IAC1C,IAAI,GAAG,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,OAAO,CAAC;IACrC,MAAM,IAAI,GAAG,GAAG,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC,CAAC;IAChC;;;;;;OAMG;IACH,MAAM,SAAS,GAAG,IAAI,GAAG,EAAU,CAAC;IACpC,KAAK,MAAM,EAAE,IAAI,IAAI;QAAE,IAAI,EAAE,CAAC,MAAM;YAAE,SAAS,CAAC,GAAG,CAAC,EAAE,CAAC,MAAM,CAAC,CAAC;IAC/D,MAAM,IAAI,GAAG,GAAG,CAAC,GAAG,CAAC,MAAM,GAAG,CAAC,CAAE,CAAC,GAAG,CAAC;IACtC,KAAK,MAAM,EAAE,IAAI,IAAI,EAAE,CAAC;QACtB,IAAI,CAAC,EAAE,CAAC,QAAQ;YAAE,SAAS;QAC3B,IAAI,SAAS,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,CAAC;YAAE,SAAS;QACnC,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC,IAAI,GAAG,EAAE,CAAC,GAAG,CAAC,GAAG,SAAS,CAAC,CAAC;QAC1D,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,QAAQ,CAAC,IAAI,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,GAAG,MAAM,CAAC,CAAC;IAC/E,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,UAAU,CAAC,MAAc;IACvC,OAAO,OAAO,GAAG,CAAC,MAAM,GAAG,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC;AAC3C,CAAC"}

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@graview/tools",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./cli": {
+      "types": "./dist/cli.d.ts",
+      "default": "./dist/cli.js"
+    }
+  },
+  "dependencies": {
+    "@graview/core": "0.1.0",
+    "@graview/ship": "0.1.0"
+  },
+  "devDependencies": {
+    "zod": "^4.4.3"
+  },
+  "description": "Derived affordances and the agent tool surface, generated from the same declarations; graview mcp and graview apply host it against a real store.",
+  "keywords": [
+    "graview",
+    "context-graph",
+    "typed-graph",
+    "interface",
+    "declarative",
+    "agents",
+    "llm",
+    "tool-calling",
+    "mcp",
+    "affordances"
+  ],
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "sideEffects": false,
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/en-dash-consulting/graview.git",
+    "directory": "packages/tools"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "Elastic-2.0",
+  "homepage": "https://graview.dev/docs/packages/tools.html",
+  "bugs": {
+    "url": "https://github.com/en-dash-consulting/graview/issues"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "build": "tsc -b"
+  }
+}