@jarenjs/linq 0.83.3 → 0.84.3

package/README.md

@@ -16,7 +16,7 @@ it by hand, as JSON, with nothing checking it until it ran.
 This package removes the price. You write the query, the schema, the
 model, the migration, the contract, the stylesheet, the state machine,
 the dataflow, the application, the form, chart, project, text template,
-message catalog or AI program as ordinary typed JavaScript,
+message catalog as ordinary typed JavaScript,
 and what comes back is the document — exactly the one its engine
 already takes, byte for byte, with its types derived beside it. The
 chain is the pen; the document is the deliverable.
@@ -49,7 +49,7 @@ SQL — and nothing is hidden: the chain's `explain()` shows the document
 it sent, and the store's `explain(document)` shows what that became,
 `SELECT … FROM "User" WHERE "age" > ? ORDER BY "name"`.
 
-Coverage: <!--fact:coverage.pens-->15 public pen/client subpaths beside the chain; 69/69 owned schema keywords have dedicated emission routes.<!--/fact-->
+Coverage: <!--fact:coverage.pens-->15 public pen/client/authoring subpaths beside the chain; 69/69 owned schema keywords have dedicated emission routes.<!--/fact-->
 
 ## What you gain
 
@@ -100,7 +100,6 @@ Coverage: <!--fact:coverage.pens-->15 public pen/client subpaths beside the chai
 | a state machine, a dataflow | `@jarenjs/linq/flow` | `@jarenjs/flow` | [flow pen](#by-code-the-flow-pen) · [FLOW-PEN](docs/FLOW-PEN.md) |
 | an application | `@jarenjs/linq/app` | `@jarenjs/app` | [app pen](#by-code-the-app-pen) · [APP-PEN](docs/APP-PEN.md) |
 | a form | `@jarenjs/linq/forms` | `@jarenjs/forms` | [forms pen](#by-code-the-forms-pen) · [FORMS-PEN](docs/FORMS-PEN.md) |
-| an AI action program | `@jarenjs/linq/ai` | `@jarenjs/ai` | [AI-PEN](docs/AI-PEN.md) |
 | a message catalog | `@jarenjs/linq/messages` | `@jarenjs/core/message` | [MESSAGES-PEN](docs/MESSAGES-PEN.md) |
 | a text template | `@jarenjs/linq/jtlt` | `@jarenjs/json/jtlt` | [JTLT-PEN](docs/JTLT-PEN.md) |
 | a Studio project | `@jarenjs/linq/project` | `@jarenjs/studio` | [PROJECT-PEN](docs/PROJECT-PEN.md) |
@@ -730,8 +729,8 @@ Every subpath a consumer can import, derived from the manifest by
 | `@jarenjs/linq/project` | JavaScript | declared |
 | `@jarenjs/linq/jtlt` | JavaScript | declared |
 | `@jarenjs/linq/messages` | JavaScript | declared |
-| `@jarenjs/linq/ai` | JavaScript | declared |
 | `@jarenjs/linq/formula` | JavaScript | declared |
+| `@jarenjs/linq/authoring` | JavaScript | declared |
 <!--/fact-->
 
 Explicit cross-provider joins use `federate({ sources, maxRows, maxBytes,
@@ -744,3 +743,13 @@ planning, buffering limits and cleanup guarantees.
 ## Saved formula documents
 
 `@jarenjs/linq/formula` exports `defineFormula` for immutable JSON Query profiles with revision, bindings and schema/helper references. See [FORMULA-PEN](docs/FORMULA-PEN.md); execution remains in json/formula.
+
+## Authoring custom documents
+
+`@jarenjs/linq/authoring` exposes `DocumentBuilder`, `snapshot`, `optionsOf` and
+`captureQuery` for pens that produce ordinary JSON documents. Builder snapshots
+are deeply frozen; `with()` creates a new instance of the same subclass.
+`optionsOf` enforces a closed set of option keys. `captureQuery` uses the same
+expression capture as the built-in pens; external names are explicit and an
+undeclared name retains the `JL0104` refusal. Compilation remains the consumer's
+responsibility. Use expression `get()` for field names that overlap methods.

package/docs/JSLT-PEN.md

@@ -893,7 +893,7 @@ non-judgement is itself gated.
 ### 6.6 When not to reach for this pen
 
 - **The stylesheet is data.** A `$jslt` document loaded from a file,
-  authored by a model ([@jarenjs/ai](../../ai/README.md)'s authoring
+  authored by a model ([Tangle authoring](https://github.com/jklarenbeek/tangleai/blob/main/packages/jaren/docs/AUTHORING.md)'s authoring
   profile writes them) or edited in the studio is a value;
   `compileJsltStylesheet` takes it directly and nothing here has to be in
   the path.

package/docs/LINQ-FORMAT.md

@@ -16,9 +16,9 @@ A **pen** is a by-code front-end to one of the suite's document formats:
 named functions that build a standard document — a JSON Schema, a
 `$model`, a `$jslt` stylesheet — the way the chain builds a query
 document. `@jarenjs/linq` exports each pen under its own subpath
-(<!--fact:coverage.subpaths-->`./ai`, `./app`, `./charts`, `./contract`, `./db`, `./flow`, `./forms`, `./formula`, `./jslt`, `./jtlt`, `./messages`, `./migration`, `./model`, `./project`, `./schema`<!--/fact-->); `.` stays the chain.
+(<!--fact:coverage.subpaths-->`./app`, `./authoring`, `./charts`, `./contract`, `./db`, `./flow`, `./forms`, `./formula`, `./jslt`, `./jtlt`, `./messages`, `./migration`, `./model`, `./project`, `./schema`<!--/fact-->); `.` stays the chain.
 
-Coverage: <!--fact:coverage.pens-->15 public pen/client subpaths beside the chain; 69/69 owned schema keywords have dedicated emission routes.<!--/fact-->
+Coverage: <!--fact:coverage.pens-->15 public pen/client/authoring subpaths beside the chain; 69/69 owned schema keywords have dedicated emission routes.<!--/fact-->
 
 **This document is the family's normative reference**: §1 states the
 rules every pen keeps, §1.3 the error codes they share, and §4–§7 the
@@ -36,7 +36,7 @@ is the index of those guides, and it is how a reader reaches any of them.
 <!--fact:pens.index-->
 | Document | Lines | What it writes, and when to open it |
 |---|---:|---|
-| [LINQ-FORMAT.md](LINQ-FORMAT.md) | 965 | this file, the binder and the family's **normative reference**: what a pen is, the rules all of them keep, the shared `JL01xx` table, and the cross-pen views derived from the guides it indexes. **Read it when** you want a rule that is true of every pen, an index of the documents, or one place to look up a method without knowing which pen owns it |
+| [LINQ-FORMAT.md](LINQ-FORMAT.md) | 944 | this file, the binder and the family's **normative reference**: what a pen is, the rules all of them keep, the shared `JL01xx` table, and the cross-pen views derived from the guides it indexes. **Read it when** you want a rule that is true of every pen, an index of the documents, or one place to look up a method without knowing which pen owns it |
 | [QUERY-PEN.md](QUERY-PEN.md) | 1,752 | the chain, `.` — query documents (`jaren-query`) and the provider seam. **Read it when** you are querying data, or implementing a provider that answers a query document |
 | [SCHEMA-PEN.md](SCHEMA-PEN.md) | 1,205 | `./schema` — JSON Schema 2020-12: the structural keywords, the constraints and the annotations, each with a method of its own, plus `$query`, `$defs`/`$ref` recursion and the normalizer's per-field predicates. **Read it when** you are describing the shape of data — for validation, for a form, or as the base of an entity |
 | [MODEL-PEN.md](MODEL-PEN.md) | 1,116 | `./model` — the `x-entity` vocabulary on JSON Schema, and the `$model` 0.1 document `openStore` accepts unchanged. **Read it when** you are declaring a store's entities, their keys and their relations |
@@ -46,7 +46,6 @@ is the index of those guides, and it is how a reader reaches any of them.
 | [FLOW-PEN.md](FLOW-PEN.md) | 1,033 | `./flow` — `jaren-fsm` 0.1 machines and `jaren-dag` 0.1 dataflows, every query-valued member captured. **Read it when** you are declaring a state machine or a dependency graph of tasks |
 | [APP-PEN.md](APP-PEN.md) | 1,143 | `./app` — the `jaren-app` 0.1 document `createApp` runs, and the JSON Schema of its state beside it. **Read it when** you are declaring a whole application: state, view, actions, effects |
 | [FORMS-PEN.md](FORMS-PEN.md) | 940 | `./forms` — the `x-form` vocabulary on JSON Schema, and `assertOnSubmit()`, the same rules' layer-3 `$query` twin. **Read it when** you are turning a schema into a form |
-| [AI-PEN.md](AI-PEN.md) | 98 | `./ai` — the public action program over environment slots. **Read it when** you want typed fixtures or host-authored programs without a model client. |
 | [MESSAGES-PEN.md](MESSAGES-PEN.md) | 105 | `./messages` — JSON message catalogs and message references. **Read it when** you want checked translation keys, placeholders and explicit completeness. |
 | [JTLT-PEN.md](JTLT-PEN.md) | 83 | `./jtlt` — text templates with JSLT dispatch and query expressions. **Read it when** you want to author Markdown, XML or source text as portable JSON. |
 | [PROJECT-PEN.md](PROJECT-PEN.md) | 81 | `./project` — Studio projects with named, typed files. **Read it when** you want a portable editor workspace containing documents written by several pens. |
@@ -95,7 +94,6 @@ data rather than for a program has no compile step to be faithful to.
 | `$fsm` 0.1, `$dag` 0.1 (`jaren-fsm`, `jaren-dag`) | `@jarenjs/flow` | **`./flow`** | [FLOW-PEN.md](FLOW-PEN.md) |
 | `jaren-app` 0.1 | `@jarenjs/app` | **`./app`** | [APP-PEN.md](APP-PEN.md) |
 | `x-form` on JSON Schema | `@jarenjs/forms` | **`./forms`** | [FORMS-PEN.md](FORMS-PEN.md) |
-| AI action program | `@jarenjs/ai` | **`./ai`** | [AI-PEN.md](AI-PEN.md) |
 | message catalogs / MessageSpec | `@jarenjs/core`, validate/forms/contract | **`./messages`** | [MESSAGES-PEN.md](MESSAGES-PEN.md) |
 | `$jtlt` 0.1 (`jaren-jtlt`) | `@jarenjs/json` | **`./jtlt`** | [JTLT-PEN.md](JTLT-PEN.md) |
 | `jaren-project` | `@jarenjs/studio` | **`./project`** | [PROJECT-PEN.md](PROJECT-PEN.md) |
@@ -205,7 +203,7 @@ and the bundle is the byte count the tree-shaking probe builds.
 <!--fact:pens.census-->
 | Document | Subpath | Lines | Mapping rows | Worked examples | Refusals | Bundle |
 |---|---|---:|---:|---:|---:|---:|
-| [LINQ-FORMAT.md](LINQ-FORMAT.md) | — | 965 | — | — | — | — |
+| [LINQ-FORMAT.md](LINQ-FORMAT.md) | — | 944 | — | — | — | — |
 | [QUERY-PEN.md](QUERY-PEN.md) | `.` | 1,752 | 34 | 8 | 15 | 175,221 B |
 | [SCHEMA-PEN.md](SCHEMA-PEN.md) | `./schema` | 1,205 | 82 | 10 | 4 | 35,285 B |
 | [MODEL-PEN.md](MODEL-PEN.md) | `./model` | 1,116 | 30 | 6 | 3 | 44,143 B |
@@ -215,14 +213,13 @@ and the bundle is the byte count the tree-shaking probe builds.
 | [FLOW-PEN.md](FLOW-PEN.md) | `./flow` | 1,033 | 16 | 7 | 3 | 18,478 B |
 | [APP-PEN.md](APP-PEN.md) | `./app` | 1,143 | 22 | 7 | 3 | 49,574 B |
 | [FORMS-PEN.md](FORMS-PEN.md) | `./forms` | 940 | 18 | 6 | 3 | 39,441 B |
-| [AI-PEN.md](AI-PEN.md) | `./ai` | 98 | 12 | 1 | 3 | 15,472 B |
 | [MESSAGES-PEN.md](MESSAGES-PEN.md) | `./messages` | 105 | 9 | 2 | 1 | 16,931 B |
 | [JTLT-PEN.md](JTLT-PEN.md) | `./jtlt` | 83 | 13 | 1 | 2 | 15,293 B |
 | [PROJECT-PEN.md](PROJECT-PEN.md) | `./project` | 81 | 9 | 1 | 1 | 13,793 B |
 | [CHARTS-PEN.md](CHARTS-PEN.md) | `./charts` | 94 | 21 | 1 | 1 | 15,582 B |
 | [DB-CLIENT.md](DB-CLIENT.md) | `./db` | 1,085 | 46 | 4 | 2 | 675,752 B |
 | [FORMULA-PEN.md](FORMULA-PEN.md) | `./formula` | 41 | 2 | — | — | 14,850 B |
-| **17 documents** | | **12,698** | **380** | **73** | | |
+| **16 documents** | | **12,579** | **368** | **72** | | |
 <!--/fact-->
 
 A pen whose mapping rows are far below its worked examples is a pen
@@ -241,10 +238,10 @@ throws, so this table moves when a pen's source does.
 <!--fact:pens.codes-->
 | Code | Raised by |
 |---|---|
-| `JL0101` | [SCHEMA-PEN.md](SCHEMA-PEN.md), [MODEL-PEN.md](MODEL-PEN.md), [JSLT-PEN.md](JSLT-PEN.md), [MIGRATION-PEN.md](MIGRATION-PEN.md), [CONTRACT-PEN.md](CONTRACT-PEN.md), [FLOW-PEN.md](FLOW-PEN.md), [APP-PEN.md](APP-PEN.md), [FORMS-PEN.md](FORMS-PEN.md), [AI-PEN.md](AI-PEN.md), [MESSAGES-PEN.md](MESSAGES-PEN.md), [JTLT-PEN.md](JTLT-PEN.md), [PROJECT-PEN.md](PROJECT-PEN.md), [CHARTS-PEN.md](CHARTS-PEN.md), [DB-CLIENT.md](DB-CLIENT.md) |
-| `JL0102` | [SCHEMA-PEN.md](SCHEMA-PEN.md), [MODEL-PEN.md](MODEL-PEN.md), [JSLT-PEN.md](JSLT-PEN.md), [MIGRATION-PEN.md](MIGRATION-PEN.md), [CONTRACT-PEN.md](CONTRACT-PEN.md), [FLOW-PEN.md](FLOW-PEN.md), [APP-PEN.md](APP-PEN.md), [FORMS-PEN.md](FORMS-PEN.md), [AI-PEN.md](AI-PEN.md) |
+| `JL0101` | [SCHEMA-PEN.md](SCHEMA-PEN.md), [MODEL-PEN.md](MODEL-PEN.md), [JSLT-PEN.md](JSLT-PEN.md), [MIGRATION-PEN.md](MIGRATION-PEN.md), [CONTRACT-PEN.md](CONTRACT-PEN.md), [FLOW-PEN.md](FLOW-PEN.md), [APP-PEN.md](APP-PEN.md), [FORMS-PEN.md](FORMS-PEN.md), [MESSAGES-PEN.md](MESSAGES-PEN.md), [JTLT-PEN.md](JTLT-PEN.md), [PROJECT-PEN.md](PROJECT-PEN.md), [CHARTS-PEN.md](CHARTS-PEN.md), [DB-CLIENT.md](DB-CLIENT.md) |
+| `JL0102` | [SCHEMA-PEN.md](SCHEMA-PEN.md), [MODEL-PEN.md](MODEL-PEN.md), [JSLT-PEN.md](JSLT-PEN.md), [MIGRATION-PEN.md](MIGRATION-PEN.md), [CONTRACT-PEN.md](CONTRACT-PEN.md), [FLOW-PEN.md](FLOW-PEN.md), [APP-PEN.md](APP-PEN.md), [FORMS-PEN.md](FORMS-PEN.md) |
 | `JL0103` | [SCHEMA-PEN.md](SCHEMA-PEN.md), [CONTRACT-PEN.md](CONTRACT-PEN.md) |
-| `JL0104` | [SCHEMA-PEN.md](SCHEMA-PEN.md), [MODEL-PEN.md](MODEL-PEN.md), [JSLT-PEN.md](JSLT-PEN.md), [MIGRATION-PEN.md](MIGRATION-PEN.md), [FLOW-PEN.md](FLOW-PEN.md), [APP-PEN.md](APP-PEN.md), [FORMS-PEN.md](FORMS-PEN.md), [AI-PEN.md](AI-PEN.md), [JTLT-PEN.md](JTLT-PEN.md) |
+| `JL0104` | [SCHEMA-PEN.md](SCHEMA-PEN.md), [MODEL-PEN.md](MODEL-PEN.md), [JSLT-PEN.md](JSLT-PEN.md), [MIGRATION-PEN.md](MIGRATION-PEN.md), [FLOW-PEN.md](FLOW-PEN.md), [APP-PEN.md](APP-PEN.md), [FORMS-PEN.md](FORMS-PEN.md), [JTLT-PEN.md](JTLT-PEN.md) |
 | `JL0105` | [QUERY-PEN.md](QUERY-PEN.md) |
 | `JL0106` | [MIGRATION-PEN.md](MIGRATION-PEN.md) |
 | `JL0107` | [DB-CLIENT.md](DB-CLIENT.md) |
@@ -273,7 +270,6 @@ it and each document publishes it. The rounded column is what
 | `@jarenjs/linq/flow` | [FLOW-PEN.md](FLOW-PEN.md) | 18,478 B | 18 kB |
 | `@jarenjs/linq/app` | [APP-PEN.md](APP-PEN.md) | 49,574 B | 50 kB |
 | `@jarenjs/linq/forms` | [FORMS-PEN.md](FORMS-PEN.md) | 39,441 B | 39 kB |
-| `@jarenjs/linq/ai` | [AI-PEN.md](AI-PEN.md) | 15,472 B | 15 kB |
 | `@jarenjs/linq/messages` | [MESSAGES-PEN.md](MESSAGES-PEN.md) | 16,931 B | 17 kB |
 | `@jarenjs/linq/jtlt` | [JTLT-PEN.md](JTLT-PEN.md) | 15,293 B | 15 kB |
 | `@jarenjs/linq/project` | [PROJECT-PEN.md](PROJECT-PEN.md) | 13,793 B | 14 kB |
@@ -796,23 +792,6 @@ it says.
 | `computed` | query | `x-form.computed` | the field's derived value, mapped to plain JSON. A failure leaves the value absent |
 | `message` | string or MessageSpec | `x-form.message`, verbatim | what an `assert` failure renders — an inline template, or `{ $msgid, message?, params? }` for the catalog |
 
-### The AI program pen — [AI-PEN.md §2](AI-PEN.md)
-
-| Factory / method | Emits | Type | Status |
-|---|---|---|---|
-| `program(slots?)` | empty `steps` | declared input names | native |
-| `chunk(from, as, options?)`, `.chunk(...)` | chunk; strategy and size | result family | native |
-| `grep(from, as, options)`, `.grep(...)` | grep; pattern, flags, limit | match-list slot | native |
-| `select(from, as, query)`, `.select(...)` | select; query JSON | result slot | native |
-| `stat(from, as)`, `.stat(...)` | stat | result slot | native |
-| `peek(from, as)`, `.peek(...)` | peek | result slot | native |
-| `map(from, as, prompt)`, `.map(...)` | map; bounded instruction | result family | native |
-| `reduce(from, as, query, options?)`, `.reduce(...)` | reduce; query JSON and optional `outputSchema` | result slot | native |
-| `answer(from, options?)`, `.answer(...)` | answer; optional chars, no as | terminal program | native |
-| `.step(step)` | appends a public step | tracks its input/result names | native |
-| `from(document)` | raw program | no binding-order inference | native |
-| `.schema`, `.toJSON()` | frozen public JSON | program document | native |
-
 ### The messages pen — [MESSAGES-PEN.md §2](MESSAGES-PEN.md)
 
 | Method | Emits | Type | Status |

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@jarenjs/linq",
   "private": false,
-  "version": "0.83.3",
+  "version": "0.84.3",
   "type": "module",
   "main": "./src/index.js",
   "types": "./types/index.d.ts",
@@ -64,13 +64,13 @@
       "types": "./types/messages.d.ts",
       "default": "./src/messages/index.js"
     },
-    "./ai": {
-      "types": "./types/ai.d.ts",
-      "default": "./src/ai/index.js"
-    },
     "./formula": {
       "types": "./types/formula.d.ts",
       "default": "./src/formula/index.js"
+    },
+    "./authoring": {
+      "types": "./types/authoring.d.ts",
+      "default": "./src/authoring.js"
     }
   },
   "files": [
@@ -108,13 +108,13 @@
     "prepack": "npm run build:types"
   },
   "dependencies": {
-    "@jarenjs/core": "^0.83.3",
-    "@jarenjs/json": "^0.83.3"
+    "@jarenjs/core": "^0.84.3",
+    "@jarenjs/json": "^0.84.3"
   },
   "peerDependencies": {
-    "@jarenjs/db": "^0.83.3",
-    "@jarenjs/formats": "^0.83.3",
-    "@jarenjs/validate": "^0.83.3"
+    "@jarenjs/db": "^0.84.3",
+    "@jarenjs/formats": "^0.84.3",
+    "@jarenjs/validate": "^0.84.3"
   },
   "peerDependenciesMeta": {
     "@jarenjs/db": {

package/src/authoring.js

@@ -0,0 +1,4 @@
+//@ts-check
+/** Immutable document building and query capture for authored-format pens. */
+export { DocumentBuilder, optionsOf, snapshot } from './authored.js';
+export { captureQuery } from './capture-root.js';

package/types/authoring.d.ts

@@ -0,0 +1,17 @@
+import type { Expr } from './index.js';
+
+/** A captured immutable JSON document; replacement preserves subclasses. */
+export class DocumentBuilder<T extends object = Record<string, unknown>> {
+  constructor(document: T);
+  readonly schema: Readonly<T>;
+  toJSON(): Readonly<T>;
+  with(patch: Partial<T>): this;
+}
+/** Snapshot and freeze a JSON value; invalid JSON retains LinqBuildError codes. */
+export function snapshot<T>(value: T): Readonly<T>;
+/** Reject options outside the named closed boundary, then snapshot. */
+export function optionsOf<T extends object>(value: T, keys: readonly string[], what: string): Readonly<T>;
+/** Capture a query; undeclared external names retain JL0104 errors. */
+export function captureQuery<T, E extends string>(what: string, externals: readonly E[],
+  rule: (value: Expr<T>, externals: Record<E, unknown>) => unknown,
+  options?: { advice?: (name: string) => string; fold?: boolean; noun?: string }): unknown;

package/types/contract.d.ts

@@ -408,7 +408,7 @@ export type ToolName<S extends string> =
   S extends `${infer A}.${infer B}` ? `${A}_${ToolName<B>}` : S;
 
 /** One tool definition, typed by the operation it invokes — the
- * `ToolDef` shape `@jarenjs/ai`'s `createToolbox().add` takes. */
+ * `ToolDef` shape browser or host operation registries takes. */
 export type TypedTool<C> = {
   [K in keyof InvokableOf<C>]: {
     name: ToolName<Extract<K, string>>;

package/docs/AI-PEN.md

@@ -1,98 +0,0 @@
-# The AI program pen
-
-> `./ai` — the public action program over environment slots. **Read it when**
-> you want typed fixtures or host-authored programs without a model client.
-
-## 1. What it writes
-
-The pen emits exactly `{ steps: [...] }`, the document consumed by the AI
-program schema, compiler and runner. It imports no AI engine or environment.
-`.schema` is an independent, deeply frozen JSON snapshot; `JSON.stringify()`
-writes that document. Updates return a new builder.
-
-`program(['corpus'])` declares input names for TypeScript; those names never
-become extra document members or an embedded registry. The compiler checks the
-real environment. Queries can be raw JSON or callbacks recorded over the input
-document, using the same capture as other pens and no runtime query engine.
-
-## 2. The mapping table
-
-Factories return frozen public steps. The same method on a program appends that
-step. Every non-answer step writes `op`, `from` and `as` before its options.
-
-| Factory / method | Emits | Type | Status |
-|---|---|---|---|
-| `program(slots?)` | empty `steps` | declared input names | native |
-| `chunk(from, as, options?)`, `.chunk(...)` | chunk; strategy and size | result family | native |
-| `grep(from, as, options)`, `.grep(...)` | grep; pattern, flags, limit | match-list slot | native |
-| `select(from, as, query)`, `.select(...)` | select; query JSON | result slot | native |
-| `stat(from, as)`, `.stat(...)` | stat | result slot | native |
-| `peek(from, as)`, `.peek(...)` | peek | result slot | native |
-| `map(from, as, prompt)`, `.map(...)` | map; bounded instruction | result family | native |
-| `reduce(from, as, query, options?)`, `.reduce(...)` | reduce; query JSON and optional `outputSchema` | result slot | native |
-| `answer(from, options?)`, `.answer(...)` | answer; optional chars, no as | terminal program | native |
-| `.step(step)` | appends a public step | tracks its input/result names | native |
-| `from(document)` | raw program | no binding-order inference | native |
-| `.schema`, `.toJSON()` | frozen public JSON | program document | native |
-
-`chunk` options are `strategy: 'size' | 'line' | 'separator'` and `size`.
-`grep` requires `pattern`, with optional `flags: 'i' | 'm' | 'im' | ''` and
-`limit`. `answer` takes `chars`. The schema owns numeric and string bounds.
-
-## 3. Worked examples
-
-```js
-import { program } from '@jarenjs/linq/ai';
-export const plan = program(['corpus'])
-  .chunk('corpus', 'pieces', { strategy: 'line', size: 200 })
-  .map('pieces', 'found', 'Return the number in this piece as JSON')
-  .reduce('found', 'count', { $count: '$[*]' })
-  .answer('count', { chars: 50 });
-```
-```json
-{"steps":[{"op":"chunk","from":"corpus","as":"pieces","strategy":"line","size":200},{"op":"map","from":"pieces","as":"found","prompt":"Return the number in this piece as JSON"},{"op":"reduce","from":"found","as":"count","query":{"$count":"$[*]"}},{"op":"answer","from":"count","chars":50}]}
-```
-
-Validate with `PROGRAM_SCHEMA` (or `programSchema({ queryRef })`), then
-`compileProgram`/`programGate` with the query compiler and known environment
-names. `createProgramRunner` does both shape and compile checks before execution.
-The standalone compile gate checks semantics; it does not replace the shape
-schema's numeric ranges, member closure or step-count cap.
-
-## 4. Refusals
-
-| Code | Condition |
-|---|---|
-| `JL0101` | invalid slot/result name shape, unknown option/operation, non-JSON input, or a malformed input-name list |
-| `JL0102` | appending a step after answer |
-| `JL0104` | a query callback reads an external; program queries bind only their input document |
-
-The schema/compiler own unknown environment names, duplicate result bindings,
-missing answers, limits, query validity and family/slot semantics. `from()`
-preserves raw programs for those checks rather than carrying a second compiler.
-
-## 5. The types
-
-`ProgramBuilder<Bindings, Done>` tracks names and whether answer has closed the
-program. `ProgramDocument`, `Step`, `StepDocument`, `StepOptions`, `Operation`,
-`Query`, `ChunkOptions`, `GrepOptions` and `AnswerOptions` are types only.
-
-A later step may read only a declared input or previous result. `select` and
-`answer` read individual slots, not chunk/map families; `reduce` reads map
-results. A result cannot be rebound, although an input slot can be shadowed as
-in the compiler. Standalone step factories retain literal names and `.step()`
-checks them on insertion. Raw documents claim neither binding order nor a
-terminal state. No inferred data schema, budget or successful-run guarantee is
-attached to a program.
-
-## 6. What it cannot spell
-
-This is the action document, not a prompt/client wrapper. It neither pastes
-corpus contents into a private envelope nor runs model calls in query expressions.
-Only the existing runner's map step calls a model. Cancellation, concurrency,
-sub-call budgets, storage and result interpretation remain runner concerns.
-
-## 7. Cost
-
-The isolated AI program pen costs **<!--fact:bundle.ai-->15,472<!--/fact--> bytes**.
-Its tree probe excludes AI, other target engines and the query chain.

package/src/ai/index.js

@@ -1,76 +0,0 @@
-//@ts-check
-/** The AI action document, authored without an AI client, environment or engine. */
-import { DocumentBuilder, optionsOf, snapshot } from '../authored.js';
-import { captureQuery } from '../capture-root.js';
-import { LinqBuildError } from '../errors.js';
-
-const FIELDS = {
-  chunk: ['strategy', 'size'], grep: ['pattern', 'flags', 'limit'], select: ['query'],
-  stat: [], peek: [], map: ['prompt'], reduce: ['query', 'outputSchema'], answer: ['chars'],
-};
-function make(op, from, as, options) {
-  if (typeof from !== 'string' || !from || (op !== 'answer' && (typeof as !== 'string' || !as)))
-    throw new LinqBuildError('JL0101', 'A step needs a source name and, except answer, a result name');
-  return snapshot({ op, from, ...(op === 'answer' ? {} : { as }), ...optionsOf(options, FIELDS[op], `${op}()`) });
-}
-function expression(value) {
-  // The program query receives only its input document: an undeclared external
-  // is the shared capture's JL0104 refusal, not an invented environment lookup.
-  return typeof value === 'function' ? captureQuery('program query', [], value, { fold: false }) : value;
-}
-/** Split a slot into a family of pieces. */
-export function chunk(from, as, options = {}) { return make('chunk', from, as, options); }
-/** Find matching slots with a bounded pattern and options. */
-export function grep(from, as, options) { return make('grep', from, as, options); }
-/** Query one JSON slot; a callback is captured as ordinary query JSON. */
-export function select(from, as, query) { return make('select', from, as, { query: expression(query) }); }
-/** Inspect counts and shape. */
-export function stat(from, as) { return make('stat', from, as, {}); }
-/** Inspect a slot's metadata and excerpt. */
-export function peek(from, as) { return make('peek', from, as, {}); }
-/** Ask one bounded prompt per member of a slot/family. */
-export function map(from, as, prompt) { return make('map', from, as, { prompt }); }
-/** Query the collected results of an earlier map. */
-export function reduce(from, as, query, options = {}) {
-  return make('reduce', from, as, { query: expression(query), ...optionsOf(options, ['outputSchema'], 'reduce()') });
-}
-/** Declare the final answer slot and optional excerpt bound. */
-export function answer(from, options = {}) { return make('answer', from, undefined, options); }
-
-/** An immutable ordered program; binding types are phantoms. */
-export class ProgramBuilder extends DocumentBuilder {
-  /** Append a public step. An answer closes this builder. @param {any} value */
-  step(value) {
-    if (this.schema.steps.at(-1)?.op === 'answer')
-      throw new LinqBuildError('JL0102', 'answer is terminal; start another program to append work');
-    if (value === null || typeof value !== 'object' || !Object.hasOwn(FIELDS, value.op))
-      throw new LinqBuildError('JL0101', 'step() needs a known program operation');
-    const step = optionsOf(value, ['op', 'from', ...(value.op === 'answer' ? [] : ['as']), ...FIELDS[value.op]], 'step()');
-    return this.with({ steps: [...this.schema.steps, step] });
-  }
-  /** Append a chunk step. */
-  chunk(from, as, options = {}) { return this.step(chunk(from, as, options)); }
-  /** Append a grep step. */
-  grep(from, as, options) { return this.step(grep(from, as, options)); }
-  /** Append a select step. */
-  select(from, as, query) { return this.step(select(from, as, query)); }
-  /** Append a stat step. */
-  stat(from, as) { return this.step(stat(from, as)); }
-  /** Append a peek step. */
-  peek(from, as) { return this.step(peek(from, as)); }
-  /** Append a map step. */
-  map(from, as, prompt) { return this.step(map(from, as, prompt)); }
-  /** Append a reduce step. */
-  reduce(from, as, query, options = {}) { return this.step(reduce(from, as, query, options)); }
-  /** Append the terminal answer. */
-  answer(from, options = {}) { return this.step(answer(from, options)); }
-}
-
-/** Declare input slot names for TypeScript; they never become document members. @param {readonly string[]} slots */
-export function program(slots = []) {
-  if (!Array.isArray(slots) || slots.some((name) => typeof name !== 'string' || !name))
-    throw new LinqBuildError('JL0101', 'program() takes input slot names');
-  return new ProgramBuilder({ steps: [] });
-}
-/** A raw public program. Compilation remains authoritative for names and semantics. @param {any} document */
-export function from(document) { return new ProgramBuilder(document); }

package/types/ai.d.ts

@@ -1,56 +0,0 @@
-import type { Json } from './schema.js';
-import type { ExprBase, UnknownExpr } from './index.js';
-export type Query = Json | ((value: UnknownExpr) => ExprBase<unknown> | Json);
-export interface ChunkOptions { readonly strategy?: 'size' | 'line' | 'separator'; readonly size?: number }
-export interface GrepOptions { readonly pattern: string; readonly flags?: 'i' | 'm' | 'im' | ''; readonly limit?: number }
-export interface AnswerOptions { readonly chars?: number }
-export interface ReduceOptions { readonly outputSchema?: Json }
-export interface StepOptions {
-  chunk: ChunkOptions; grep: GrepOptions; select: { readonly query: Json };
-  stat: {}; peek: {}; map: { readonly prompt: string }; reduce: { readonly query: Json } & ReduceOptions; answer: AnswerOptions;
-}
-export type Operation = keyof StepOptions;
-export type Step<K extends Operation, F extends string = string, N extends string = string> = {
-  readonly op: K; readonly from: F;
-} & (K extends 'answer' ? {} : { readonly as: N }) & StepOptions[K];
-export type StepDocument = { [K in Operation]: Step<K> }[Operation];
-export interface ProgramDocument { readonly steps: readonly StepDocument[] }
-export function chunk<const F extends string, const N extends string>(from: F, as: N, options?: ChunkOptions): Step<'chunk', F, N>;
-export function grep<const F extends string, const N extends string>(from: F, as: N, options: GrepOptions): Step<'grep', F, N>;
-export function select<const F extends string, const N extends string>(from: F, as: N, query: Query): Step<'select', F, N>;
-export function stat<const F extends string, const N extends string>(from: F, as: N): Step<'stat', F, N>;
-export function peek<const F extends string, const N extends string>(from: F, as: N): Step<'peek', F, N>;
-export function map<const F extends string, const N extends string>(from: F, as: N, prompt: string): Step<'map', F, N>;
-export function reduce<const F extends string, const N extends string>(from: F, as: N, query: Query, options?: ReduceOptions): Step<'reduce', F, N>;
-export function answer<const F extends string>(from: F, options?: AnswerOptions): Step<'answer', F>;
-
-type Kind = Exclude<Operation, 'answer'> | 'slot';
-type Bindings = Record<string, Kind>;
-type Names<B, K extends Kind = Kind> = { [N in keyof B]: B[N] extends K ? N : never }[keyof B] & string;
-type Single<B> = Names<B, Exclude<Kind, 'chunk' | 'map'>>;
-type Fresh<B, N extends string> = N extends keyof B ? B[N] extends 'slot' ? N : never : N;
-type Add<B, N extends string, K extends Kind> = Omit<B, N> & Record<N, K>;
-type InputFor<B, K extends Operation> = K extends 'reduce' ? Names<B, 'map'> : K extends 'select' | 'answer' ? Single<B> : Names<B>;
-type StepKeys<K extends Operation> = 'op' | 'from' | (K extends 'answer' ? never : 'as') | keyof StepOptions[K];
-type CheckStep<B, T extends StepDocument> = Exclude<keyof T, StepKeys<T['op']>> extends never ? T['from'] extends InputFor<B, T['op']>
-  ? T extends { readonly as: infer N extends string } ? N extends Fresh<B, N> ? unknown : never : unknown : never : never;
-type AfterStep<B, T extends StepDocument> = T extends { readonly as: infer N extends string; readonly op: infer K extends Kind } ? Add<B, N, K> : B;
-export class ProgramBuilder<B extends Bindings = {}, Done extends boolean = false> {
-  protected constructor();
-  readonly __bindings: B;
-  readonly __done: Done;
-  readonly schema: ProgramDocument;
-  toJSON(): ProgramDocument;
-  step<const T extends StepDocument>(this: ProgramBuilder<B, false>, step: T & CheckStep<B, T>): ProgramBuilder<AfterStep<B, T>, T['op'] extends 'answer' ? true : false>;
-  chunk<N extends string>(this: ProgramBuilder<B, false>, from: Names<B>, as: Fresh<B, N>, options?: ChunkOptions): ProgramBuilder<Add<B, N, 'chunk'>>;
-  grep<N extends string>(this: ProgramBuilder<B, false>, from: Names<B>, as: Fresh<B, N>, options: GrepOptions): ProgramBuilder<Add<B, N, 'grep'>>;
-  select<N extends string>(this: ProgramBuilder<B, false>, from: Single<B>, as: Fresh<B, N>, query: Query): ProgramBuilder<Add<B, N, 'select'>>;
-  stat<N extends string>(this: ProgramBuilder<B, false>, from: Names<B>, as: Fresh<B, N>): ProgramBuilder<Add<B, N, 'stat'>>;
-  peek<N extends string>(this: ProgramBuilder<B, false>, from: Names<B>, as: Fresh<B, N>): ProgramBuilder<Add<B, N, 'peek'>>;
-  map<N extends string>(this: ProgramBuilder<B, false>, from: Names<B>, as: Fresh<B, N>, prompt: string): ProgramBuilder<Add<B, N, 'map'>>;
-  reduce<N extends string>(this: ProgramBuilder<B, false>, from: Names<B, 'map'>, as: Fresh<B, N>, query: Query, options?: ReduceOptions): ProgramBuilder<Add<B, N, 'reduce'>>;
-  answer(this: ProgramBuilder<B, false>, from: Single<B>, options?: AnswerOptions): ProgramBuilder<B, true>;
-}
-export function program<const S extends readonly string[] = []>(slots?: S): ProgramBuilder<Record<S[number], 'slot'>>;
-/** Raw documents make no binding-order or terminal-state inference. */
-export function from(document: ProgramDocument): ProgramBuilder<Record<string, Kind>, boolean>;