@toclocoinc/lattice-grid 1.42.0 → 1.44.0

package/README.md

@@ -4,7 +4,7 @@
 dependencies, no build step required. Optional adapters for React, Vue, Svelte
 and Web Components ship alongside it.
 
-Version 1.42.0 · [latticegrid.dev](https://www.latticegrid.dev) · TOCLOCO Inc
+Version 1.44.0 · [latticegrid.dev](https://www.latticegrid.dev) · TOCLOCO Inc
 
 ---
 

package/docs/API.html

@@ -2498,6 +2498,101 @@ grid.permissions.setContext({ role: 'clerk' });      // re-resolves everything</
     </div>
     <div class="note"><p>Actions: <code>setFilters</code>, <code>setSort</code>, <code>groupBy</code>, <code>showColumns</code>, <code>hideColumns</code>, <code>setQuick</code>, <code>clear</code>. Nothing else is executable, so a model cannot be talked into an operation the vocabulary does not contain. <code>docs/AI-SKILL.md</code> is the reference to hand your model.</p></div>
 
+    <h3 id="ai-askdata">Ask-your-data (<code>modules/ai</code>)</h3>
+    <p>The opt-in AI module (<code>createAI</code>, UMD <code>LatticeGridAI</code>) turns a question into
+    a validated <strong>read-only</strong> query spec, runs it in the grid's own engine over the
+    <code>grid.ai</code> skill layer, and — on apply — fans the answer to any router-attached viewers
+    (a chart, a KPI tile) through the Data Router's <code>load()</code>. It uses the same BYO
+    <code>ask()</code> seam as the rest of the module: the grid makes no model call and holds no key.
+    Ask-your-data is read-only; a write/mutation the model asks for is <strong>refused and never
+    executed</strong> (writes are a separate, human-gated feature).</p>
+    <div class="table-wrap">
+      <table>
+        <thead><tr><th>Method</th><th>Returns</th><th>Description</th></tr></thead>
+        <tbody>
+          <tr><td class="sig">query(question, opts?)</td><td class="type">Promise&lt;result&gt;</td><td class="desc">Ask the model, validate the reply into a read-only spec. <code>result.describe()</code> shows the resolved query; nothing applies until <code>result.apply()</code> (or <code>autoApply</code>).</td></tr>
+          <tr><td class="sig">applyQuery(result, opts?)</td><td class="type">object</td><td class="desc">Apply a reviewed result. Re-gated at the seam: an unsafe plan is refused. <code>opts.router</code> fans the answer to other viewers.</td></tr>
+          <tr><td class="sig">askBar(el, opts?)</td><td class="type">controller</td><td class="desc">Mount the ask/review/apply bar with an "auto-apply safe reads" toggle (off by default).</td></tr>
+        </tbody>
+      </table>
+    </div>
+    <pre data-run="js" data-expect="2 rows; write refused" data-covers="export:createAI"><code>const { createHeadlessGrid } = await import('../packages/core/src/index.js');
+const { createAI } = await import('../packages/modules/ai/index.js');
+const grid = createHeadlessGrid({
+  rowKey: 'id',
+  columns: [{ field: 'id' }, { field: 'region' }, { field: 'amount', type: 'number' }],
+  rows: [{ id: 1, region: 'EMEA', amount: 100 }, { id: 2, region: 'AMER', amount: 300 }, { id: 3, region: 'EMEA', amount: 200 }],
+});
+// Your model returns a schema-constrained SPEC, never rows. WE run it, read-only.
+const reads = createAI(grid, { ask: async () =&gt; ({ actions: [{ type: 'setFilters', filters: { col: 'region', op: 'eq', value: 'EMEA' } }] }) });
+const result = await reads.query('EMEA only');
+result.apply();
+const rows = grid.rows.data().length;
+// A write verb is refused by the read-only gate and never executed.
+const writes = createAI(grid, { ask: async () =&gt; ({ actions: [{ type: 'setCells', edits: [] }] }) });
+const write = await writes.query('change the data');
+return `${rows} rows; write ${write.ok ? 'allowed' : 'refused'}`;</code></pre>
+
+    <h3 id="ai-actor">AI as a governed actor (<code>modules/ai</code>, writes)</h3>
+    <p>The governed actor lets the model <strong>propose</strong> edits &mdash; a single NL-targeted
+    change (&ldquo;set the Network Upgrade project to In&nbsp;Progress&rdquo;) or a bulk cleanup &mdash;
+    that a human previews as a <strong>before/after diff</strong> and approves. The model NEVER writes.
+    On approval the edit applies through the grid's <em>own</em> gate, exactly like a person's edit:
+    a grid cell edit via <code>grid.edit.setCells(writes, 'cell', { origin: 'ai' })</code> (the
+    <code>beforeEdit</code> veto), a Kanban card move via <code>board.move(&hellip;, { origin: 'ai' })</code>
+    (the <code>beforeMove</code> veto). <strong>The AI can never bypass the gate:</strong> a host
+    <code>beforeEdit</code>/<code>beforeMove</code> handler that calls <code>preventDefault()</code>
+    (or vetoes async) stops the write, and nothing persists. Writes carry <code>origin: 'ai'</code>
+    on the before-event payload, so a host can allow a person's edit while vetoing the AI's &mdash;
+    policing AI writes distinctly. Approved edits are optimistic and revert on a source reject
+    through the shipped write-back (there is no separate <code>beforeCommit</code> event; the edit gate
+    is <code>beforeEdit</code>, and the optimistic/revert half is <code>grid.edit.settle</code>).</p>
+    <p>NL targeting and any bulk edit bind to the <strong>current filtered view</strong>
+    (<code>grid.rows.data()</code>), never the whole table implicitly; a target not in the view is
+    surfaced for an explicit opt-in <code>widen</code>, not edited silently. A human label is resolved
+    to the column's stored option value; an unknown label is rejected, not coerced. An ambiguous match
+    (more than one row) surfaces its candidates for the user to pick.</p>
+    <div class="table-wrap">
+      <table>
+        <thead><tr><th>Method</th><th>Returns</th><th>Description</th></tr></thead>
+        <tbody>
+          <tr><td class="sig">propose(instruction, opts?)</td><td class="type">Promise&lt;proposal&gt;</td><td class="desc">Ask the model for structured edits, validate + resolve them against the current view, and return a reviewable proposal with a before/after <code>diff</code>. Nothing is written. <code>opts.widen</code> opts into the full dataset; <code>opts.board</code> routes a Kanban move.</td></tr>
+          <tr><td class="sig">applyProposal(proposal, opts?)</td><td class="type">Promise&lt;report&gt;</td><td class="desc">Apply an approved proposal through the gate (<code>origin: 'ai'</code>). A vetoing before-handler stops it; the report gives <code>applied</code>/<code>vetoed</code>.</td></tr>
+          <tr><td class="sig">actorBar(el, opts?)</td><td class="type">controller</td><td class="desc">Mount the propose &rarr; review-diff &rarr; approve bar, stating the scope.</td></tr>
+        </tbody>
+      </table>
+    </div>
+    <pre data-run="js" data-expect="diff To do then In Progress; vetoed kept todo; approved wrote doing" data-covers="export:createAI"><code>const { createHeadlessGrid } = await import('../packages/core/src/index.js');
+const { createAI } = await import('../packages/modules/ai/index.js');
+const status = { options: [{ id: 'todo', label: 'To do' }, { id: 'doing', label: 'In Progress' }] };
+const seed = () =&gt; createHeadlessGrid({
+  rowKey: 'id',
+  columns: [{ field: 'id' }, { field: 'name' }, { field: 'status', lookup: status, edit: { enabled: true } }],
+  rows: [{ id: 'r1', name: 'Network Upgrade', status: 'todo' }, { id: 'r2', name: 'Payroll', status: 'todo' }],
+});
+// A MOCK ask() returns a structured PROPOSAL — never a write, never rows.
+const ask = async () =&gt; ({ structured: { edits: [{ match: 'Network Upgrade', column: 'status', value: 'In Progress' }] } });
+
+// Propose: a before/after diff, nothing written yet.
+let grid = seed();
+let ai = createAI(grid, { ask });
+const proposal = await ai.propose('set the Network Upgrade project to In Progress');
+const d = proposal.diff[0];
+const before = `${d.oldDisplay} then ${d.newDisplay}`;
+
+// A vetoing beforeEdit handler on the AI write => NOTHING persists.
+grid.on('beforeEdit', (e) =&gt; { if (e.origin === 'ai') e.preventDefault('reviewed elsewhere'); });
+await ai.applyProposal(proposal);
+const vetoed = grid.rows.byKey('r1').data.status;
+
+// Approve on a grid with no veto => the edit lands through the gate.
+grid = seed();
+ai = createAI(grid, { ask });
+await ai.applyProposal(await ai.propose('set the Network Upgrade project to In Progress'));
+const approved = grid.rows.byKey('r1').data.status;
+
+return `diff ${before}; vetoed kept ${vetoed}; approved wrote ${approved}`;</code></pre>
+
     <h2 id="overlay">grid.overlay</h2>
     <div class="table-wrap">
       <table>
@@ -7658,7 +7753,7 @@ return `next ${p.mean.toFixed(1)}; r2 ${f.r2.toFixed(1)}; band ${p.upper - p.low
           <tr><td class="name">stop</td><td class="type">(cancel?: boolean): void</td><td class="desc"></td></tr>
           <tr><td class="name">undo</td><td class="type">(): void</td><td class="desc"></td></tr>
           <tr><td class="name">redo</td><td class="type">(): void</td><td class="desc"></td></tr>
-          <tr><td class="name">setCells</td><td class="type">(writes: { key: string; colId: string; value: unknown }[], type?: 'cell' | 'fill' | 'paste'): number</td><td class="desc"></td></tr>
+          <tr><td class="name">setCells</td><td class="type">(</td><td class="desc">Write several cells as one undoable step (§12). `opts.origin` defaults to `'api'` — the ungated seam every existing caller uses (a fill, a paste, a kanban move), unchanged. Pass `{ origin: 'ai' }` (or `'user'`) to route the write through the cancellable `beforeEdit` gate, exactly as an interactive edit is (BACKLOG-0000967): the AI writes through this so a host `beforeEdit` handler can veto it and nothing persists when it does. With a gated origin and an async (deferring) before-handler, the return is a `Promise&lt;number&gt;`.</td></tr>
           <tr><td class="name">bulkSet</td><td class="type">(value: unknown, opts?: { cells?: { key: string; colId: string }[] }): number</td><td class="desc">Set one value across a block of cells as a single undoable step (§12, card 740). Defaults to the selected range; read-only and non-editable cells are skipped and every write runs the normal parse/validate path.</td></tr>
           <tr><td class="name">fill</td><td class="type">(opts?: { direction?: 'down' | 'up' | 'left' | 'right'; series?: boolean; range?: CellRange }): number</td><td class="desc">Fill a selected range from its leading edge as one undoable step (§12, card 740). The default copies the anchor across the range (Excel's Ctrl+D and its natural siblings); `series: true` extrapolates a numeric or date series from the first one or two cells of each line, falling back to a copy for types with no series. `direction` defaults to `'down'`.</td></tr>
           <tr><td class="name">pasteInto</td><td class="type">(anchor: { key: string; colId: string }, text: string, extent?: { rows?: number; columns?: number }): number</td><td class="desc"></td></tr>
@@ -8202,7 +8297,7 @@ return `next ${p.mean.toFixed(1)}; r2 ${f.r2.toFixed(1)}; band ${p.upper - p.low
         <thead><tr><th>Member</th><th>Type</th><th>Description</th></tr></thead>
         <tbody>
           <tr><td class="name">type</td><td class="type">string</td><td class="desc"></td></tr>
-          <tr><td class="name">origin</td><td class="type">'api' | 'user' | 'init'</td><td class="desc"></td></tr>
+          <tr><td class="name">origin</td><td class="type">'api' | 'user' | 'init' | 'ai'</td><td class="desc">Who caused the action. `'ai'` (BACKLOG-0000967) tags a write an AI proposed and a human approved, applied through `grid.edit.setCells(writes, type, { origin: 'ai' })`; it fires the same cancellable `beforeEdit` gate a `'user'` edit does, so a host can policy-gate AI writes distinctly.</td></tr>
           <tr><td class="name">grid</td><td class="type">Grid</td><td class="desc"></td></tr>
         </tbody>
       </table>

package/docs/api-detail.html

@@ -437,7 +437,7 @@
 <div class="shell">
   <aside class="rail">
     <p class="rail__brand">Lattice Grid</p>
-    <p class="rail__sub">Developer guide · v1.42.0</p>
+    <p class="rail__sub">Developer guide · v1.44.0</p>
     <nav>
       <div class="rail__group">
         <span class="rail__label">Start here</span>

package/lattice-grid.d.ts

@@ -1,5 +1,5 @@
 /*!
- * Lattice Grid 1.42.0, type declarations
+ * Lattice Grid 1.44.0, type declarations
  * Copyright (c) 2026 TOCLOCO Inc. All rights reserved.
  * https://latticegrid.dev
  */
@@ -3772,7 +3772,13 @@ export type EventName =
 
 export interface GridEvent {
   type: string;
-  origin: 'api' | 'user' | 'init';
+  /**
+   * Who caused the action. `'ai'` (BACKLOG-0000967) tags a write an AI proposed
+   * and a human approved, applied through `grid.edit.setCells(writes, type,
+   * { origin: 'ai' })`; it fires the same cancellable `beforeEdit` gate a
+   * `'user'` edit does, so a host can policy-gate AI writes distinctly.
+   */
+  origin: 'api' | 'user' | 'init' | 'ai';
   grid: Grid;
   [key: string]: unknown;
 }
@@ -4101,7 +4107,20 @@ export interface EditApi {
   stop(cancel?: boolean): void;
   undo(): void;
   redo(): void;
-  setCells(writes: { key: string; colId: string; value: unknown }[], type?: 'cell' | 'fill' | 'paste'): number;
+  /**
+   * Write several cells as one undoable step (§12). `opts.origin` defaults to
+   * `'api'` — the ungated seam every existing caller uses (a fill, a paste, a
+   * kanban move), unchanged. Pass `{ origin: 'ai' }` (or `'user'`) to route the
+   * write through the cancellable `beforeEdit` gate, exactly as an interactive
+   * edit is (BACKLOG-0000967): the AI writes through this so a host `beforeEdit`
+   * handler can veto it and nothing persists when it does. With a gated origin
+   * and an async (deferring) before-handler, the return is a `Promise<number>`.
+   */
+  setCells(
+    writes: { key: string; colId: string; value: unknown }[],
+    type?: 'cell' | 'fill' | 'paste',
+    opts?: { origin?: 'api' | 'ai' | 'user' },
+  ): number | Promise<number>;
   /**
    * Set one value across a block of cells as a single undoable step (§12, card
    * 740). Defaults to the selected range; read-only and non-editable cells are
@@ -8083,8 +8102,32 @@ declare module 'lattice-grid/modules/ai' {
   interface AIConfig {
     /** The host's model callback. Falls back to the grid's `ai.ask` when omitted. */
     ask?: AIAsk;
-    /** Opt into specific features: `'narrative'`, `'insights'`. All on when omitted. */
+    /** Opt into specific features: `'narrative'`, `'insights'`, `'query'`/`'ask'`. All on when omitted. */
     enable?: string[];
+    /**
+     * Ask-your-data: apply a safe (read-only) query result without a confirm
+     * step. Off by default — the resolved query is shown and waits for Apply.
+     */
+    autoApply?: boolean;
+    /**
+     * A Data Router instance; on applying a query the answer rows are fanned to
+     * its attached viewers (grid + chart + KPI together) via `load()`.
+     */
+    router?: unknown;
+    /** Budgets passed to the schema builder for ask-your-data. */
+    schemaOptions?: object;
+    /** Extra context passed through to `ask()`. */
+    context?: unknown;
+    /** Called with each ask-your-data result. */
+    onQuery?: (result: AIQueryResult) => void;
+    /** Called with each governed-actor proposal (Play C), before any approval. */
+    onProposal?: (result: AIProposal) => void;
+    /**
+     * A Kanban board (from `createKanban`) the governed actor writes moves
+     * through: an NL card move applies via the board's own `beforeMove` gate
+     * (BACKLOG-0000967), never a kanban-specific write bypass.
+     */
+    board?: unknown;
     /** Cap on rows any tool result carries to `ask()`. */
     maxRows?: number;
     /** Columns whose values must never leave the browser. */
@@ -8105,11 +8148,124 @@ declare module 'lattice-grid/modules/ai' {
     onError?: (error: { error: unknown; target: AITarget }) => void;
   }
 
+  /** The report from applying an ask-your-data query. */
+  interface AIApplyReport {
+    ok: boolean;
+    /** The action types that were applied. */
+    applied: string[];
+    /** Actions that threw while applying. */
+    failed: Array<{ type: string; reason: string }>;
+    /** Actions refused by the read-only gate — a mutation is never applied. */
+    refused: Array<{ type: string; reason: string }>;
+    /** How many answer rows were fanned to a router's viewers. */
+    fannedOut: number;
+  }
+
   /**
-   * An AI narrative / insights controller over a live grid. Read-only: it
-   * explains the grid's computed figures and never mutates data. `grid.ai` (in
-   * core) is the complementary intent/plan skill layer; this is the
-   * narrative/insights consumer.
+   * The result of an ask-your-data question (BACKLOG-0000966): a validated,
+   * READ-ONLY query spec — never rows — that the host reviews before applying.
+   */
+  interface AIQueryResult {
+    /** True when the spec is safe to apply: at least one read, nothing unsafe. */
+    ok: boolean;
+    /** The user's question. */
+    question: string;
+    /** The core plan (from `grid.ai.plan`). */
+    plan: Record<string, unknown>;
+    /** The read-only actions that will run — the validated query spec. */
+    actions: object[];
+    /** Actions refused as not read-only (a mutation the model asked for). */
+    unsafe: Array<{ type: string; reason: string }>;
+    /** Parts the core validator dropped (unknown column, bad operator, …). */
+    rejected: Array<{ at: string; what: string; reason: string }>;
+    /** The model's own one-line summary, if any. */
+    explain: string;
+    /** The validated query spec as data. */
+    spec: { actions: object[] };
+    /** The apply report once applied, or null. */
+    applied: AIApplyReport | null;
+    /** The resolved query in one human sentence, from the validated spec. */
+    describe(): string;
+    /** Apply the query (re-gated), fanning the answer to a router if configured. */
+    apply(opts?: { router?: unknown; onResult?: (rows: object[]) => void }): AIApplyReport;
+  }
+
+  /** One before/after change in a governed-actor proposal (BACKLOG-0000967). */
+  interface AIDiffEntry {
+    /** The target row key. */
+    key: string;
+    /** A human label identifying the row (a name-like column, else the key). */
+    rowLabel: string;
+    /** The target column id. */
+    colId: string;
+    /** The column's title, for the diff header. */
+    colTitle: string;
+    /** The current stored value. */
+    oldValue: unknown;
+    /** The current value as shown (a lookup id mapped to its label). */
+    oldDisplay: string;
+    /** The proposed stored value (a label resolved to its option id). */
+    newValue: unknown;
+    /** The proposed value as shown. */
+    newDisplay: string;
+  }
+
+  /**
+   * A governed-actor proposal (Play C, BACKLOG-0000967): the model's structured
+   * edits, VALIDATED and resolved against the current view — never written until
+   * a human approves. `apply()` writes ONLY through the grid's own gate.
+   */
+  interface AIProposal {
+    /** True when there is at least one applicable change and nothing needs a pick first. */
+    ok: boolean;
+    /** The user's instruction. */
+    instruction: string;
+    /** `'view'` (the filtered set, the default) or `'all'` (an opted-in widen). */
+    scope: 'view' | 'all';
+    /** How many rows the scope covers. */
+    scopeCount: number;
+    /** The scope in words, always stated in the confirm/diff. */
+    scopeText: string;
+    /** Whether any proposal was a bulk (`scope:'view'`) edit. */
+    bulk: boolean;
+    /** The before/after diff — exactly what would change. Nothing is written yet. */
+    diff: AIDiffEntry[];
+    /** Proposals refused before apply (unknown column, unknown label, bad type/range, no match). */
+    rejected: Array<{ reason: string; [k: string]: unknown }>;
+    /** Matches needing a human pick (>1 row for one phrase), with candidates. */
+    ambiguous: Array<{ reason: string; candidates: Array<{ key: string; label: string }>; [k: string]: unknown }>;
+    /** Named targets found only outside the view, offered for an opt-in widen. */
+    outOfView: Array<{ reason: string; candidates: Array<{ key: string; label: string }>; [k: string]: unknown }>;
+    /** Matches whose value already equals the ask (nothing to change). */
+    noops: Array<{ reason: string; [k: string]: unknown }>;
+    /** The apply report once applied, or null. */
+    applied: AIProposalReport | null;
+    /** The proposal in one human sentence, always stating the scope. */
+    describe(): string;
+    /** Apply the approved diff through the gate (`beforeEdit`, or `beforeMove` for a board). */
+    apply(opts?: { board?: unknown }): Promise<AIProposalReport>;
+  }
+
+  /** The report from applying a governed-actor proposal. */
+  interface AIProposalReport {
+    /** True when at least one edit landed. */
+    ok: boolean;
+    /** How many edits landed through the gate. */
+    applied: number;
+    /** How many edits were attempted. */
+    requested: number;
+    /** How many were stopped by a before-handler veto. */
+    vetoed: number;
+    /** Which gated path applied them: `'setCells'`, `'board.move'`, or `'none'`. */
+    via: string;
+  }
+
+  /**
+   * An AI controller over a live grid. It explains the grid's computed figures
+   * (Play A), answers questions with validated read-only query specs (Play B),
+   * and PROPOSES governed edits a human approves and the grid's own gate applies
+   * (Play C). `grid.ai` (in core) is the complementary intent/plan skill layer
+   * this consumes.
    */
   interface AI {
     /** The mounted insights panel element, or null. */
@@ -8126,7 +8282,46 @@ declare module 'lattice-grid/modules/ai' {
     attachExplain(target: AITarget, opts?: object): HTMLElement | null;
     /** Build the facts packet for a target without calling `ask()`. */
     facts(target?: AITarget, opts?: object): AIFactsPacket;
-    on(name: 'narrative' | 'error' | string, fn: (payload: object) => void): () => void;
+    /**
+     * Ask-your-data: turn a question into a validated, read-only query spec, run
+     * it in the engine, and (on apply) fan the answer to router-attached viewers.
+     * Returns a result the host reviews; `autoApply` applies a safe read for you.
+     */
+    query(question: string, opts?: {
+      autoApply?: boolean; router?: unknown; schemaOptions?: object;
+      context?: unknown; tools?: boolean; signal?: AbortSignal;
+      onResult?: (rows: object[]) => void;
+    }): Promise<AIQueryResult>;
+    /** Apply a reviewed query result (the confirm path); re-gated at the seam. */
+    applyQuery(result: AIQueryResult, opts?: { router?: unknown; onResult?: (rows: object[]) => void }): AIApplyReport;
+    /** Mount the ask-your-data bar (input, Ask, auto-apply toggle, preview, Apply/Discard). */
+    askBar(el?: HTMLElement, opts?: object): AI;
+    /**
+     * Governed actor (Play C): ask the model for structured edit PROPOSALS over
+     * the current view, validate and resolve them (label -> stored value, locate
+     * a named row, reject unknown columns/labels/out-of-range), and return a
+     * reviewable {@link AIProposal} with a before/after diff. NOTHING is written
+     * — the model proposes; a human approves.
+     */
+    propose(instruction: string, opts?: {
+      widen?: boolean; board?: unknown; schemaOptions?: object; maxRows?: number;
+      context?: unknown; redact?: string | string[] | ((colId: string) => boolean);
+      signal?: AbortSignal;
+    }): Promise<AIProposal>;
+    /**
+     * Apply an approved proposal — the human-approval step. Writes ONLY through
+     * the gate: a grid cell edit via `grid.edit.setCells({ origin: 'ai' })` (the
+     * `beforeEdit` veto), a kanban move via `board.move({ origin: 'ai' })` (the
+     * `beforeMove` veto). A vetoing host handler stops the write.
+     */
+    applyProposal(result: AIProposal, opts?: { board?: unknown }): Promise<AIProposalReport>;
+    /**
+     * Mount the governed-actor bar: an instruction input, Propose, a before/after
+     * diff preview stating the scope, and Approve/Discard. Approve applies
+     * through the gate.
+     */
+    actorBar(el?: HTMLElement, opts?: object): AI;
+    on(name: 'narrative' | 'query' | 'proposal' | 'error' | string, fn: (payload: object) => void): () => void;
     off(name: string, fn: (payload: object) => void): void;
     destroy(): void;
   }