@fayegram-ai/decision-bridge 0.1.1 → 0.1.3

package/docs/guides/LIVE_DECISIONS.md

@@ -0,0 +1,163 @@
+# Live Decisions
+
+Requires **0.1.3 or later**. See [version availability](../README.md#version-availability)
+and [installation](GETTING_STARTED.md#install-into-your-application).
+
+`@fayegram-ai/decision-bridge/live` attaches Decisions handling to an existing
+GPT-Live connection. Your application owns authentication, audio, connection
+setup and reconnection. The controller owns Decisions commands, acknowledgements
+and conservative result correlation. It does not issue additional HTTP inference.
+
+```javascript
+import { createLiveDecisions } from '@fayegram-ai/decision-bridge/live';
+
+const live = createLiveDecisions({ transport: {
+    send(event) { connection.send(JSON.stringify(event)); },
+    subscribe(listener) {
+        const message = event => listener({ kind: 'event', event: JSON.parse(event.data) });
+        const closed = () => listener({ kind: 'close' });
+        const failed = () => listener({ kind: 'error' });
+        connection.addEventListener('message', message);
+        connection.addEventListener('close', closed);
+        connection.addEventListener('error', failed);
+        return () => {
+            connection.removeEventListener('message', message);
+            connection.removeEventListener('close', closed);
+            connection.removeEventListener('error', failed);
+        };
+    },
+} });
+
+live.subscribe(event => {
+    if (event.type === 'decision') {
+        console.log(event.decision, event.correlation);
+    }
+});
+await live.configure({
+    delegation: { type: 'decisions', decisions: {
+        model: 'gpt-6-luna',
+        questions: [{ type: 'predicate', name: 'ready', instructions: 'Is the requested action fully specified?' }],
+    } },
+});
+```
+
+The connection must already support the required Live events and Decisions
+permissions. Start the session with Decisions delegation if it will delegate to
+Decisions; Live does not allow changing the delegation type after startup.
+`transport.subscribe` receives a listener for `{ kind: 'event',
+event }`, `{ kind: 'close' }`, and `{ kind: 'error' }` notifications and must
+return an unsubscribe function. `send` may return a promise. Dispose the
+controller before replacing a connection; disposal does not close the connection.
+
+## Commands and acknowledgements
+
+| Method | Completion |
+| --- | --- |
+| `configure(configuration, options?)` | Matching `session.updated` acknowledgement |
+| `createItem(item, options?)` | Matching `decision.item.created` acknowledgement |
+| `deleteItem(itemId, options?)` | Matching `decision.item.deleted` acknowledgement |
+| `requestDecision(options?)` | Submission receipt, not an inference-result promise |
+| `appendCommentary(content, { delegationId, ...options }?)` | Submission receipt, not a speech-completion promise |
+| `subscribe(observer)` | Returns an unsubscribe function |
+| `dispose()` | Cancels pending waits and detaches owned listeners |
+
+Configuration accepts Decisions `delegation` and transcript `triggers`. Each
+trigger specifies `type: 'decisions'`, `event_type` as input or output transcript
+delta, and `decisions: { questions }`. Trigger arrays replace the trigger list;
+an empty list disables them. Omitted fields preserve server configuration.
+Questions use the native predicate/choice/score representation.
+
+Decision items are user messages containing text or embedded image parts. Live
+items do not inherit the HTTP Decisions conversation, remote-image or cache
+input extensions. Item creation appends evidence for later evaluations; it does
+not itself request evaluation. IDs are generated uniquely for commands.
+
+An application can execute a selected action, append its confirmed outcome with
+`createItem`, wait for acknowledgement, then submit commentary. The controller
+does not execute application actions. Commentary is forwarded with the explicit
+delegation ID or null; any service rejection is reported as an error event.
+
+## Results and correlation
+
+Completed native decisions arrive as `type: 'decision'` notifications containing
+the full model, ordered answers and usage. Native refusal answers are preserved.
+The controller does not fabricate partial common success from a refusal.
+
+`correlation` contains `matched`, `stale`, source event ID/type, delegation ID,
+trigger ID and a configuration generation when known. Match quality describes
+available protocol evidence, not model accuracy.
+
+- Transcript fragments are tracked in delivery order separately for input and
+  output. Results can arrive out of order; older/equal source results are stale.
+  A newer result from an observed source makes older results stale even when its
+  configuration cannot be matched. An unknown source or conflicting direction
+  cannot advance the observed order.
+- Configuration becomes active after acknowledgement. Sources observed during
+  an in-flight or unresolved update remain unmatched.
+- A rejected update preserves the last acknowledged configuration. If unresolved
+  update IDs are evicted from history, future sources stay unmatched for this
+  controller's lifetime. Attach a new controller with a known accepted snapshot
+  to restore correlation after losing that history.
+- A known delegation or transcript source carries its question snapshot. Missing
+  or evicted source/configuration history remains observable and unmatched.
+- Duplicate server event IDs produce `duplicate` notifications within retained
+  history. Delegation results consume their source snapshot; repeated results
+  cannot become newly matched work.
+- Manual request IDs are not assumed to be echoed by completion events. A manual
+  submission receipt cannot be used as proof that a later result belongs to it.
+- Unrelated events do not enter the Decisions state machine.
+
+Only apply application actions when your own policy accepts the result and its
+correlation. A supplied starting `configuration` asserts that the application
+already knows the connection's accepted Decisions configuration.
+
+## Resources and failures
+
+Defaults are a 30-second command deadline, 128 pending operations, 4096 retained
+history entries per correlation map, and 8 MiB command/event budgets (configurable
+through 64 MiB). These are local resource budgets, independent of server quotas.
+History eviction can make late results unmatched. No service RPM/TPM enforcement,
+automatic command replay or reconnect policy is introduced.
+
+Call options accept `signal` and `timeoutMs`. Disconnect and disposal settle
+pending operations. Invalid signal values fail with `CONFIGURATION_ERROR` before
+dispatch. Application cleanup exceptions are isolated, including when the
+connection closes synchronously during attachment.
+A timed-out update may still be accepted upstream; a later
+acknowledgement updates observed state without resolving an unrelated call.
+Cancellation before dispatch preserves the accepted configuration. A correlated
+item acknowledgement with the wrong item ID rejects that operation with
+`INVALID_RESPONSE` immediately.
+Observer failures emit safe `observer_error` notifications and do not repeat work.
+Subscription changes during delivery apply to subsequent notifications; a
+recipient is called at most once for the current notification.
+Server errors are normalized without exposing their raw messages.
+Malformed server events, including nested items and configuration snapshots,
+report `INVALID_RESPONSE`. Unknown validation exceptions use a generic message.
+
+## Offline protocol tools
+
+```shell
+decision live validate configuration.json --kind config
+decision live validate command.json --kind command
+decision live validate event.json --kind event
+decision live replay session.jsonl
+```
+
+Replay records are `{ "direction": "client" | "server", "event": ... }`.
+The same correlation reducer processes them and emits ordered JSONL records.
+No connection, audio device or credential is used. Malformed rows are reported
+individually and make the final exit status nonzero.
+Offline `live validate` treats malformed event files as caller input: it reports
+`VALIDATION_ERROR` and exits 2. Replay retains `INVALID_RESPONSE` for malformed
+server records, continues processing later records, and exits 1 if any row fails.
+A replay represents one connection lifecycle. `session.closed` releases its
+history; subsequent records report `CONNECTION_CLOSED` and make the exit status
+nonzero. Use a separate replay for a replacement connection. Configuration
+updates without event IDs are valid wire commands, but prevent trustworthy
+configuration correlation for the rest of that replay. Controller-generated
+commands always include unique IDs.
+
+See the [connection adapter example](../../examples/live-decisions.mjs),
+[OpenAI guide](https://developers.openai.com/api/docs/guides/decisions-voice) and
+[Live protocol reference](https://developers.openai.com/api/reference/resources/live/primary-websocket).

package/docs/guides/OPENAI_DECISIONS.md

@@ -1,5 +1,8 @@
 # OpenAI Decisions
 
+Conversation/tool history, remote images and prompt caching require **0.1.3 or
+later**. See [version availability](../README.md#version-availability).
+
 The `openai-decisions` provider implements the native `POST /v1/decisions` API.
 Its default model selector is `default`; `luna` selects the supported Luna-family
 model, and `gpt-6-luna` selects that explicit upstream ID. Decision Bridge resolves
@@ -80,8 +83,9 @@ That native choice's confidence is retained in provider metadata.
 
 ## Ordered text and images
 
-Provide exactly one of `state` or `input`. An existing JSON array supplied as
-`state` retains its original meaning. New `input` is a nonempty ordered array:
+Choose exactly one of `state`, ordered `input` or `conversation`. An existing
+JSON array supplied as `state` retains its original meaning. Ordered `input` is
+a nonempty array:
 
 ```javascript
 const result = await bridge.evaluate({
@@ -95,9 +99,9 @@ const result = await bridge.evaluate({
 });
 ```
 
-Images must be nonempty inline base64 data URLs, such as
-`data:image/png;base64,...`. The bridge does not fetch image URLs or read files.
-Convert image bytes in your application. OpenAI permits at most 128 images.
+Images accept inline base64 data URLs or an exclusive common `url` HTTP(S)
+reference. Native images use `image_url` for either form. References are forwarded;
+the bridge does not fetch URLs or read files. Image-count admission is server-owned.
 Detail accepts `low`, `high`, `auto`, `original`, or null; omission uses the service
 default. Text/image ordering is preserved.
 
@@ -105,9 +109,8 @@ The default transport request/response limits are 8 MiB each, including encoded
 images. Set `maxRequestBytes` explicitly for larger requests, up to the existing
 64 MiB ceiling. These local limits do not override service limits.
 
-`safetyIdentifier` is an optional per-request opaque string of at most 128
-Unicode characters, or null. It maps to `safety_identifier`; avoid private identity
-data. Character limits count Unicode code points rather than UTF-16 code units.
+`safetyIdentifier` is an optional per-request opaque string or null. It maps
+to `safety_identifier`; length admission remains upstream.
 
 ## Typed choices and labelled scores
 
@@ -130,35 +133,38 @@ coercion to object keys are not supported. TypeScript preserves literal unions.
 `scoreLevels` stores ordered `levels` instead of `criteria` and requires at least
 two `{ label, description? }` objects. Its answer retains the numeric score and
 index-keyed probability map, with the original level objects in the legend.
-OpenAI choice questions require 2–255 unique options in both common forms and
-native requests. Labelled scores do not inherit Jev's 10-level limit; legacy
-score criteria retain the 2–10-level limit. JSON snapshots and transport caps
-apply to all requests.
+Choices require at least two distinct options for OpenAI. Service count ceilings
+are not enforced locally. Both labelled and legacy scores retain ordered levels;
+JSON safety and configured client wire budgets apply to all forms.
 
 ## Capabilities and preparation
 
 `bridge.getCapabilities(model?)` synchronously reports support and limits for
 ordered input, images, typed choices, labelled scores, and safety identifiers.
+It also reports conversation/tool history, remote images and prompt caching.
 `bridge.validate(request)` resolves the model, snapshots/freezes the request,
 and checks capabilities without inference. Unsupported combinations fail before
 dispatch with `UNSUPPORTED_CAPABILITY`.
 
-Preflight also checks the encoded native field limits and the complete UTF-8 wire
+Preflight also checks the encoded native structure and the complete UTF-8 wire
 body against `maxRequestBytes`. SDK array batches check every raw request before
 dispatching any entry. Prepared input is revalidated during each evaluation.
 
-Jev, OpenAI-compatible, OpenRouter, and Anthropic currently support the legacy
-common forms. Existing custom providers default to that profile; implement
+Jev supports shared state and ordered text, with experimental images and boxes;
+the maintained generative presets use legacy shared-state forms. Existing custom
+providers default to the legacy profile; implement
 `getCapabilities(model)` and corresponding behavior to support new forms.
 
-Use `prepareInput(parts, context)` for ordered input and `prepareState` for state.
+Use `prepareInput(parts, context)` for ordered input, `prepareState` for state,
+and `prepareConversation(items, context)` for conversation history.
 A preparation extension must implement the hook for the form being used;
 incompatible extensions fail explicitly rather than being skipped. Extensions
-can implement both hooks. `onResult` works with either form and runs only after
+can implement all three preparation hooks. `onResult` works with every form and runs only after
 success, with the existing isolated-failure policy.
 
 Legacy common requests retain `meta.schemaVersion: 1`. New input/question forms
-or safety identifiers use version 2.
+or safety identifiers use version 2. Conversation, remote image URLs or cache
+controls select version 5; see [conversation and prompt caching](#conversation-and-prompt-caching).
 
 ## Dedicated native access
 
@@ -178,11 +184,11 @@ const { decision, meta } = await provider.createDecision({
 }, { signal: controller.signal });
 ```
 
-An omitted model inherits the provider's configured selection. Native input accepts text or
-multiple user messages containing text or ordered `input_text`/`input_image`
-parts. Only user roles are supported. Files, external image URLs, audio, tools,
-and item references are rejected locally. Exported `NativeDecisionRequest` and
-related types describe this format.
+An omitted model inherits the provider's configured selection. Native input accepts
+text, role-aware messages, assistant output/refusal content and function/custom-tool
+calls and outputs. Images may be embedded or remote HTTP(S) references. File IDs,
+audio and item references remain unsupported. Exported native types describe the
+Decisions-specific representation; tool payload strings remain verbatim.
 
 `decision` preserves native answer arrays, optional question names, probabilities,
 confidence, and full usage. `meta` has the exported `OpenAIDecisionsTransportMetadata`
@@ -239,7 +245,7 @@ OpenAI initialization stores the model selection in configuration and omits it
 from the generated request so later configuration changes apply. The default
 configuration uses `default`. Offline validation reports the selected value as
 `model` and the outgoing upstream ID as `resolvedModel`.
-Decisions offline validation also checks native field limits and the configured
+Decisions offline validation also checks native structure and the configured
 request byte limit in both modes.
 
 The `schema` command remains a generative utility and rejects the new request
@@ -250,3 +256,25 @@ From a source checkout, the optional `npm run smoke:live -- --decisions --env-fi
 checks four bounded requests when `RUN_LIVE_TESTS=1` is explicitly set. It checks
 protocol behavior rather than prediction quality, disables retries, and prints
 only model identities and token usage. Normal verification never runs it.
+
+## Conversation and prompt caching
+
+Common requests select exactly one of `state`, ordered `input` or `conversation`.
+Conversation items use `NativeDecisionInputItem`: user/developer/system messages,
+assistant messages with optional commentary/final_answer phase, function calls,
+custom tool calls and their outputs. Tool outputs reference preceding call IDs.
+System/developer content is text; assistant parts are output text or refusal.
+
+`promptCacheKey` and `promptCacheOptions` map to native `prompt_cache_key` and
+`prompt_cache_options`. Options support implicit/explicit mode and Decisions'
+30m TTL. Eligible common text/image parts accept `promptCacheBreakpoint` with
+explicit mode or null; native content uses `prompt_cache_breakpoint`. The adapter
+preserves breakpoints, omission and explicit nulls without selecting cache writes.
+
+Use `prepareConversation(items, context)` to transform conversation input.
+Transformations are snapshotted, frozen and revalidated before dispatch. Capability
+flags are `conversation`, `toolHistory`, `remoteImages` and `promptCaching`;
+existing custom providers default to false. New-feature requests use common
+schema version 5; existing forms retain versions 1–4.
+
+See [Live Decisions](LIVE_DECISIONS.md) for the separate connection lifecycle.

package/docs/guides/PLATFORMS.md

@@ -22,7 +22,7 @@ compatible native Node runtime. See [testing](../development/TESTING.md).
 Open PowerShell at the cloned repository or extracted source directory:
 
 ```powershell
-cd "C:\path\to\decision-bridge-0.1.1"
+cd "C:\path\to\decision-bridge"
 node --version
 node bin/decision.mjs validate examples/request.json
 Copy-Item .env.example .env
@@ -48,7 +48,7 @@ the archive rather than reusing generated `node_modules` or executable shims.
 ## macOS / Linux
 
 ```bash
-cd "/path/to/decision-bridge-0.1.1"
+cd "/path/to/decision-bridge"
 node --version
 node bin/decision.mjs validate examples/request.json
 cp .env.example .env
@@ -73,7 +73,7 @@ Install the package with npm from your application's directory:
 npm install @fayegram-ai/decision-bridge
 ```
 
-For installation from a verified local archive, see
+For version requirements and installation from a verified local archive, see
 [getting started](GETTING_STARTED.md#install-into-your-application).
 
 Import from `@fayegram-ai/decision-bridge` in ESM JavaScript, or invoke the installed

package/docs/guides/SWITCHING_MODELS.md

@@ -1,7 +1,8 @@
 # Switching models without rewriting the application
 
-The bridge's request contains `questions`, either `state` or ordered `input`, and
-optionally `model`. Ordered input and richer question types require provider capabilities.
+The bridge's request contains `questions`, exactly one of `state`, ordered `input`
+or `conversation`, and optionally `model`. Ordered input, conversation/tool history,
+remote images, cache controls and richer questions require provider capabilities.
 The provider translates it into that service's wire protocol and validates the
 response. Select a provider when constructing your SDK bridge.
 See [model selectors and provider defaults](../../README.md#model-selectors).
@@ -15,6 +16,9 @@ entry point. A new decision protocol uses [custom decision](CUSTOM_DECISION.md).
 The example below demonstrates the opt-in generative path; native alternatives
 follow it.
 
+Clairic [extraction](EXTRACTION.md) and [Live Decisions](LIVE_DECISIONS.md) use
+dedicated APIs. They cannot replace a provider in an existing `createBridge` call.
+
 ## SDK: same request, different provider
 
 Install the package as described in [getting started](GETTING_STARTED.md).

package/docs/guides/TROUBLESHOOTING.md

@@ -1,5 +1,13 @@
 # Troubleshooting
 
+## An export or command from these guides is missing
+
+Run `npm exec -- decision-bridge --version` in the consuming project and compare
+it with [version availability](../README.md#version-availability). The `/extraction`
+and `/live` exports, their CLI commands, and expanded OpenAI history/cache inputs
+require 0.1.3 or later. See [installation options](GETTING_STARTED.md#install-into-your-application)
+to install a compatible version.
+
 ## The command cannot find a key
 
 General `node bin/decision.mjs ...` calls need exported environment variables or an
@@ -81,6 +89,23 @@ file output is not finalized in that case; stdout can contain a completed prefix
 Some requests may already have been sent/billed. Retrying an entire prefix can
 repeat work, so retain completed records externally when designing resumability.
 
+## Extraction or Live does not behave like bridge evaluation
+
+For Clairic, use `CloudflareExtractionProvider` from the `/extraction` export or
+the `extraction` CLI namespace with `cloudflare-extraction`. The root decision
+factory and `createBridge` do not accept extraction providers. An explicit
+provider from config or environment overrides the namespace default and must
+match the operation. A null value, empty list or `truncated: true` can be a valid
+native result; inspect it according to your application's needs.
+
+For Live, `requestDecision` and `appendCommentary` resolve on submission. Consume
+completed decisions through `subscribe`. An unmatched result indicates missing or
+ambiguous source/configuration history; a stale result refers to older observed
+transcript order. Neither is proof of a current request result. Disposal and
+connection closure cancel pending waits. Malformed offline event validation exits
+2, while failed replay rows produce exit 1 and processing continues. See
+[Live lifecycle](LIVE_DECISIONS.md#results-and-correlation).
+
 ## Type checks fail because tsc is missing
 
 Runtime and tests have no TypeScript dependency. Development type checks require

package/docs/reference/CLI.md

@@ -1,7 +1,11 @@
 # Command runner reference
 
-The optional command runner evaluates files using the same bridge available in
-the SDK. For application integration, start with the [SDK guide](../guides/GETTING_STARTED.md).
+The optional command runner evaluates decision files, runs Clairic extraction,
+and validates or replays Live protocol records offline. For application
+integration, start with the [SDK guide](../guides/GETTING_STARTED.md).
+
+The extraction and Live commands require **0.1.3 or later**; see
+[version availability](../README.md#version-availability).
 
 After [installing the package](../guides/GETTING_STARTED.md#install-into-your-application)
 in your project, run:
@@ -17,8 +21,10 @@ it with `node bin/decision.mjs` from a source checkout. `decision` and
 `faye-decision` are equivalent aliases with the same commands and options.
 `--help` and `--version` do not access credentials or services.
 
-The CLI defaults to Jev. Flags override `DECISION_*` environment settings, which
-override an explicit config file and then built-in defaults. It constructs an
+Decision commands default to Jev. The extraction namespace defaults to
+`cloudflare-extraction` only when no provider was selected. Flags override
+`DECISION_*` environment settings, which override an explicit config file and
+then built-in defaults. It constructs an
 explicit provider for the SDK; `createBridge` itself has no implicit selection.
 Choose a supported native model from the
 [model selector inventory](../../README.md#model-selectors).
@@ -50,10 +56,24 @@ there is no CLI binding selector. Gateway settings route the selected REST reque
 | `schema [FILE\|-]` | Print the generative response schema for these questions; local only |
 | `models` | List the configured provider's models; may be paginated |
 | `batch FILE\|-` | Stream JSONL inputs and ordered JSONL result/error records |
-
-No input filename on `evaluate`, `validate`, or `schema` selects the bundled sample,
+| `extraction run FILE\|-` | One native extraction; returns `{ extraction, meta }` |
+| `extraction validate FILE\|-` | Offline structural and client-budget validation |
+| `extraction batch FILE\|-` | Ordered extraction JSONL results and per-row errors |
+| `extraction init [DIRECTORY]` | Create an extraction profile, request, schema and credential template |
+| `live validate FILE\|- --kind config\|command\|event` | Offline Live structure validation |
+| `live replay FILE\|-` | Offline JSONL protocol replay; no connection is opened |
+
+Jev supports both common and `--native` requests for evaluation, validation,
+initialization, and ordered batches. Experimental images/boxes require
+`--jev-images`, and longer context requires `--jev-long-context` (or matching
+JSON configuration). Use `--no-jev-images` and `--no-jev-long-context` to
+override enabled settings. See the [Jev guide](../guides/JEV.md).
+
+No input filename on decision `evaluate`, `validate`, or `schema` selects the bundled sample,
 not stdin. Use `-` explicitly for stdin. Empty invocation prints help. Configuration
 and credential errors do not cause fallback to another backend.
+Extraction and Live file operations require an explicit filename or `-`.
+Extraction rejects `--native` because its request already uses native fields.
 
 ```bash
 cat request.json | decision-bridge evaluate - --env-file .env --compact
@@ -88,14 +108,16 @@ later configuration changes to control selection.
 | --- | --- |
 | `--config FILE` | Explicit JSON configuration; never autodiscovered |
 | `--env-file FILE` | Load an explicit environment file without changing the parent shell |
-| `--provider NAME` | `jev`, `openai-decisions`, `cloudflare-decisions`, `custom-decision`, `custom-generative` |
+| `--provider NAME` | `jev`, `openai-decisions`, `cloudflare-decisions`, `cloudflare-extraction` (extraction namespace), `custom-decision`, `custom-generative` |
 | `--preset NAME` | custom-generative preset: `openai-compatible`, `openrouter`, or `anthropic`; exclusive with module |
 | `--native` | Explicit native Decisions input/output; init/evaluate/validate/batch only |
+| `--jev-images`, `--no-jev-images` | Enable/disable experimental Jev images and boxes |
+| `--jev-long-context`, `--no-jev-long-context` | Enable/disable experimental Jev 262k context |
 | `--model SELECTOR` | Model selector or supported upstream ID; overrides input JSON model and configured default |
 | `--base-url URL` | Custom endpoint; requires explicit credential selection |
 | `--api-key-env NAME` | Environment variable name, never the key itself |
 | `--account-id ID` | Cloudflare REST account ID |
-| `--reject-if-busy`, `--no-reject-if-busy` | Explicit Cloudflare native-request override. Enabling fails local REST preflight with `UNSUPPORTED_CAPABILITY`; disabling permits ordinary inference. See the [REST limitation](../guides/CLOUDFLARE_DECISIONS.md#capacity-rejection-and-ai-gateway) |
+| `--reject-if-busy`, `--no-reject-if-busy` | Override Cloudflare request/provider busy settings. Enabling fails Clef REST preflight; Clairic forwards the setting. See the [Clef REST limitation](../guides/CLOUDFLARE_DECISIONS.md#capacity-rejection-and-ai-gateway) |
 | `--gateway-id ID` | Existing Cloudflare Gateway; richer settings in config |
 | `--no-auth` | Only for a loopback OpenAI-compatible endpoint |
 | `--timeout-ms N` | HTTP and bridge deadline for each evaluation/listing |
@@ -109,6 +131,7 @@ later configuration changes to control selection.
 | `--force` | Replace existing output; valid only with `--output` |
 | `--concurrency N` | Batch in-flight limit 1–64; default 4 |
 | `--pretty`, `--compact` | JSON formatting; pretty by default; batches always JSONL |
+| `--kind config\|command\|event` | Required by `live validate`; rejected by other commands |
 | `--help`, `-h`, `--version`, `-v` | Informational commands |
 
 Unknown or duplicate flags fail. Provider-inapplicable flags fail instead of being
@@ -130,6 +153,10 @@ includes `validationScope: 'provider'` for known native/preset profiles or
 `'structure'` for a custom module. Structure validation cannot verify an unknown
 module's capabilities or protocol. `schema` is an offline generative-output tool;
 it does not add generative support to a native provider.
+Decision validation reports `operation: 'decision'` and `questionCount`;
+extraction reports `operation: 'extraction'` and `fieldCount`. Neither authenticates
+an account or claims server admission. Live validation reports its `kind` and
+`validationScope: 'structure'`.
 
 A batch emits one compact record per nonblank input line:
 
@@ -172,12 +199,17 @@ delivery needs separate validation.
 
 ## I/O and resource limits
 
-Single JSON input: **8 MiB**. JSONL: **8 MiB per line, 64 MiB total**. Config:
+Single JSON input normally uses **8 MiB**. JSONL normally uses **8 MiB per line,
+64 MiB total**. Jev defaults to **32 MiB** for a single JSON input or JSONL record,
+then checks serialized requests against its configured ceiling (32 MiB by default).
+An explicit larger client request budget raises the input reader budget through 64 MiB.
+Config:
 **1 MiB**. Environment file: **64 KiB**. Provider request and response default to
 8 MiB each, configurable to at most 64 MiB. Cloudflare reads single JSON inputs
 and individual JSONL records within 64 MiB, then applies model-specific serialized
-request validation: Clef/Clef-flash default/cap 13 MiB; Omni default 36 MiB,
-configurable through 64 MiB. Explicit smaller ceilings remain in force. Request
+request validation: Clef/Clef-flash default 13 MiB, configurable through 64 MiB; Omni default 36 MiB,
+configurable through 64 MiB; Clairic defaults to 8 MiB, configurable through 64 MiB.
+Explicit smaller ceilings remain in force. Request
 model overrides and mixed-model JSONL batches use each effective model's budget.
 The 64 MiB JSONL total remains. These are client limits, not a promise
 that every remote model has an equivalent context window.
@@ -211,3 +243,20 @@ Already-cancelled CLI work does not initialize a project or create an output fil
 File writers check cancellation before writes and before submitting the atomic
 commit. A commit already submitted to the operating system cannot be undone;
 cancellation does not roll back a completed write or remote inference billing.
+
+## Offline Live tools
+
+Live tools load no provider configuration, environment files or credentials and
+open no connection. They accept input/output and formatting flags; `--kind` is
+required only for validation. Replay always emits compact JSONL.
+
+Replay input records are `{ direction: 'client' | 'server', event }`. Each row
+produces `{ line, ok, event }` or `{ line, ok: false, error }` using the same
+correlation state as the SDK controller. Malformed rows remain explicit errors
+and later rows are processed. A closed session ends that replay lifecycle;
+subsequent protocol rows fail with `CONNECTION_CLOSED`.
+
+Malformed event-file validation reports `VALIDATION_ERROR` and exits 2. Malformed
+server replay rows retain `INVALID_RESPONSE`; any failed row makes replay exit 1.
+See the [Live guide](../guides/LIVE_DECISIONS.md) for correlation guarantees and
+the [extraction guide](../guides/EXTRACTION.md) for native extraction requests.

package/docs/reference/CONFIGURATION.md

@@ -29,16 +29,17 @@ is native-only. Generative presets use `createGenerativeProvider` from the
 `@fayegram-ai/decision-bridge/config.schema.json` and in
 [schemas/decision.config.schema.json](../../schemas/decision.config.schema.json).
 It checks profile structure; runtime preflight additionally checks endpoint,
-credential, capability, and model-specific limits.
+credential, capability, and serialized client-byte budgets.
 Cloudflare CLI configuration always selects REST. Inject a Workers AI binding
-through the SDK's `CloudflareDecisionsProvider` constructor instead of a JSON
-profile. Gateway configuration is optional for either SDK transport and for CLI REST.
+through the SDK's `CloudflareDecisionsProvider` or `CloudflareExtractionProvider`
+constructor instead of a JSON profile. Gateway configuration is optional for
+either SDK transport and for CLI REST.
 
 | Field | Values / scope |
 | --- | --- |
 | `$schema` | Optional nonempty schema reference for editors |
 | `schemaVersion` | 1; optional, but generated profiles include it |
-| `provider` | `jev` default, `openai-decisions`, `cloudflare-decisions`, `custom-decision`, `custom-generative` |
+| `provider` | `jev` default for decision commands, `openai-decisions`, `cloudflare-decisions`, `cloudflare-extraction` for extraction commands, `custom-decision`, `custom-generative` |
 | `preset` | `custom-generative` only: `openai-compatible`, `openrouter`, `anthropic`; mutually exclusive with module |
 | `model` | Nonempty model selector or supported upstream ID; built-in native providers have defaults; required for generative evaluation unless the request supplies it |
 | `baseURL` | HTTPS API base; loopback may use HTTP |
@@ -46,10 +47,11 @@ profile. Gateway configuration is optional for either SDK transport and for CLI
 | `noAuth` | Boolean; true only for loopback OpenAI-compatible endpoints |
 | `timeoutMs` | Positive integer up to 2,147,483,647 milliseconds |
 | `maxRetries` | Integer 0–10; OpenAI/Cloudflare default 0; Jev and generative presets default 2 |
-| `maxRequestBytes`, `maxResponseBytes` | Positive integer through 64 MiB; default 8 MiB. Cloudflare requests: Clef/Clef-flash default/cap 13 MiB; Omni default 36 MiB, configurable through 64 MiB |
+| `maxRequestBytes`, `maxResponseBytes` | Positive integer through 64 MiB; default 8 MiB, including Clairic. Jev requests default 32 MiB. Clef/Clef-flash requests default 13 MiB; Omni 36 MiB. Explicit request budgets can select through 64 MiB for every built-in provider |
 | `accountId` | Cloudflare REST account ID; otherwise `CLOUDFLARE_ACCOUNT_ID` |
-| `rejectIfBusy` | Cloudflare boolean; default false, incompatible with retries. Effective true fails REST preflight with `UNSUPPORTED_CAPABILITY`; see the [binding support and REST limitation](../guides/CLOUDFLARE_DECISIONS.md#capacity-rejection-and-ai-gateway) |
+| `rejectIfBusy` | Cloudflare boolean; default false, incompatible with retries. Effective true fails Clef REST preflight with `UNSUPPORTED_CAPABILITY`; Clairic forwards the setting for server acceptance/rejection. See the [Clef limitation](../guides/CLOUDFLARE_DECISIONS.md#capacity-rejection-and-ai-gateway) and [extraction options](../guides/EXTRACTION.md#images-binding-and-gateway) |
 | `gateway` | Cloudflare Gateway object; see the [Cloudflare guide](../guides/CLOUDFLARE_DECISIONS.md) |
+| `dangerZone` | Jev-only `{ images?: boolean, longContext?: boolean }`; both default false; see the [Jev guide](../guides/JEV.md) |
 | `maxTokens` | Generative output budget, 1–1,048,576; default 4096 |
 | `responseFormat` | Compatible generative presets: `json_schema`, `json_object`, `text` |
 | `tokenParameter` | Compatible generative presets: `max_completion_tokens` or `max_tokens` |
@@ -58,6 +60,10 @@ profile. Gateway configuration is optional for either SDK transport and for CLI
 | `options` | Custom factory's JSON options, e.g. its own baseURL |
 
 Upper numeric limits validate client configuration, not vendor model capabilities.
+Jev requests default to a 32 MiB client budget; an explicit `maxRequestBytes`
+can select a budget through 64 MiB. `DECISION_JEV_IMAGES` and `DECISION_JEV_LONG_CONTEXT`
+accept `true` or `false`; their CLI overrides are `--jev-images`,
+`--no-jev-images`, `--jev-long-context`, and `--no-jev-long-context`.
 Cloudflare selects its byte budget from the effective request model, including
 per-call overrides. An explicit smaller `maxRequestBytes` remains the ceiling;
 selecting Omni cannot enlarge it. Omni's default is a bridge policy, not a
@@ -168,3 +174,25 @@ presets, and separate custom decision/generative modules. Use
 with `--provider-module FILE`. The module flag does not infer classification. Replace placeholder model identifiers
 with IDs returned by the intended account/server. Profiles intentionally contain
 no real key or claim that one model is available to every user.
+
+## Extraction and Live configuration
+
+The `extraction` namespace supplies provider `cloudflare-extraction` only when
+flags, environment and an explicit file have selected no provider. Its default
+model is `clairic`; `@cf/cloudflare/clairic` is also accepted. An explicit
+incompatible provider is rejected. Provider switching follows the same isolation
+rules above, including transitions between Clef and Clairic. The configuration
+schema stays at version 1.
+
+OpenAI prompt-cache controls and Clairic inference settings (`include_quantiles`,
+`return_state_text`) belong in request JSON. Extraction busy-mode flags override
+the request's `options.rejectIfBusy`; otherwise that request value overrides the
+provider setting. See [extraction](../guides/EXTRACTION.md).
+
+Live SDK configuration is passed directly to `createLiveDecisions` with a supplied
+transport. Offline `live validate` and `live replay` do not load provider profiles,
+credentials or environment files. See [Live Decisions](../guides/LIVE_DECISIONS.md).
+
+Offline validation checks structure and client resource budgets. Service quotas,
+context/media admission and Gateway limits remain upstream; the SDK and CLI do
+not estimate tokens or enforce RPM/TPM.