@fayegram-ai/decision-bridge 0.1.2 → 0.1.3

package/docs/guides/CUSTOM_GENERATIVE.md

@@ -72,8 +72,9 @@ or zero-based level indices. It checks probabilities, derives argmax/weighted
 scores and matching legends, and marks absent usage as unknown. It does not repair
 JSON, strip Markdown, or create confidence. `buildPrompt` and `normalizeGenerated`
 independently validate and snapshot the request. They require shared state and
-legacy questions, and reject ordered input, typed choices, labelled scores, and
-safety identifiers with `UNSUPPORTED_CAPABILITY`. Malformed request JSON raises
+legacy questions, and reject ordered input, conversation/tool history, remote
+images, prompt-cache controls, typed choices, labelled scores and safety
+identifiers with `UNSUPPORTED_CAPABILITY`. Malformed request JSON raises
 `VALIDATION_ERROR`; unsupported input is never silently discarded. New modules
 implement their own encoding and normalization for richer capabilities.
 
@@ -110,7 +111,8 @@ provenance and `confidenceSource: 'unavailable'`, and rejects returned native
 confidence claims or answer confidence fields. Their output is an estimate elicited
 from a model, not a native probability, logprob, or calibration guarantee.
 Presets support shared state and legacy `choice`, `noul`, and `score`; ordered
-media, typed choices, labelled scores, and safety identifiers are unsupported.
+media, conversation/tool history, remote images, prompt-cache controls, typed
+choices, labelled scores and safety identifiers are unsupported.
 A new module may declare capabilities only after implementing and validating them.
 
 ## OpenAI-compatible servers

package/docs/guides/CUSTOM_PROVIDERS.md

@@ -41,7 +41,9 @@ Internal transport helpers are not stable public exports. Delegate a maintained
 preset for a protocol already supported, or implement and test your own transport.
 
 Capability omissions retain the legacy shared-state and question profile. Audio
-and video additions default to false/zero. Declare richer forms only when their
+and video additions default to false/zero; conversation, tool history, remote
+images and prompt caching default to false. Explicit quantitative custom limits
+are enforced; `null` leaves that admission limit to the service. Declare richer forms only when their
 encoding and validation are implemented. The bridge runs preflight again after
 preparation hooks. Unknown usage is null; no provider should invent token counts,
 confidence, or calibration. Generative native-provenance claims are rejected.
@@ -68,8 +70,8 @@ relative to that file; flag paths
 resolve relative to the working directory. Explicit modules execute trusted code;
 this extension point is not a sandbox. No module is discovered automatically.
 
-`init` creates an honest service implementation placeholder when no implementation
-is selected. When given an existing module, it references that module without
+`init` creates a provider module with an unimplemented service call when no
+implementation is selected. When given an existing module, it references that module without
 loading or overwriting it. Offline `validate` never imports custom modules or
 requires credentials; it reports structure-only validation for unknown protocols.
 `bridge.validate()` on an instantiated provider includes capabilities and preflight.

package/docs/guides/EXTRACTION.md

@@ -0,0 +1,125 @@
+# Clairic extraction
+
+Requires **0.1.3 or later**. See [version availability](../README.md#version-availability)
+and [installation](GETTING_STARTED.md#install-into-your-application).
+
+Import extraction from `@fayegram-ai/decision-bridge/extraction`. This operation
+returns typed values and predictive statistics, using Cloudflare Clairic through
+REST or an injected Workers AI binding. Its result is independent of the decision
+bridge's question/answer contract.
+
+```javascript
+import { CloudflareExtractionProvider } from '@fayegram-ai/decision-bridge/extraction';
+
+const provider = new CloudflareExtractionProvider();
+const { extraction, meta } = await provider.extract({
+    state: 'Invoice total: 1080 USD. Due date: 2026-11-01.',
+    reference_date: '2026-10-20',
+    fields: {
+        amount: { type: 'number', unit: 'USD' },
+        due_date: { type: 'date' },
+        payment_days: { type: 'estimate', min: 0, max: 90, step: 1 },
+    },
+    options: { include_quantiles: true, return_state_text: true },
+});
+console.log(extraction.answers.amount.value, extraction.truncated, meta.requestId);
+```
+
+REST reads `CLOUDFLARE_API_TOKEN` and `CLOUDFLARE_ACCOUNT_ID` only for the official
+origin, or accepts explicit `apiKey` and `accountId`. Custom origins require
+explicit credentials. The default model is `clairic`; the full selector
+`@cf/cloudflare/clairic` is also accepted. Requested, resolved and reported model
+identities remain separate. There is no model-discovery request.
+
+## Fields and results
+
+| Type | Definition | Returned value |
+| --- | --- | --- |
+| `text` | Instructions describing a text value | String or null |
+| `number` | Optional unit, integer and decimal settings | Number or null |
+| `date`, `time`, `datetime` | Instructions describing the temporal value | String or null; no implicit timezone conversion |
+| `duration` | Unit: seconds, minutes, hours, days, weeks, months or years | Number or null |
+| `list` | Required `items`: text, number or date | Ordered list, including an empty list, or null |
+| `estimate` | Required numeric or ISO-date `min` and `max`; optional `step` and `scale` | Number, date string or null, plus available distribution summaries |
+| `forecast` | Prediction bounds plus optional positive `horizon` and `interval` | Native value and ordered predictive `steps`, retained as JSON |
+
+`instructions` and `null_threshold` describe individual fields. `null_threshold`
+must be greater than zero and at most one. `number` and `duration` accept boolean
+`integer` and nonnegative integer `decimals`; numeric lists also accept `decimals`.
+Grids support positive numeric steps or `month`/`year`;
+`scale` is `linear` or `log`. Forecast intervals are `step`, `minute`, `hour`,
+`day`, `week`, `month`, `quarter`, or `year`. Server ceilings remain server-owned.
+
+The immutable envelope is `{ extraction, meta }`. The native extraction retains
+all returned fields: values, guesses, confidence, `p_null`, spans, means,
+medians, `p10`/`p90`, bounds probabilities, quantiles, forecast steps, `truncated`,
+optional `state_text`, and usage including optional pass counts. Unknown native
+response fields are retained after safe JSON validation.
+
+A null value can coexist with a guess and span. Typed output does not establish
+factual accuracy. The adapter does not recalculate predictions or token totals.
+Predictive substructures with an underspecified schema remain JSON values in the
+types; span offsets are preserved without assuming JavaScript slicing units.
+
+## Images, binding and Gateway
+
+Provide text `state`, embedded `images`, or both. Images accept PNG/JPEG/WebP data
+URLs or `{ content_type, base64 }` objects. Remote images are not supported by
+this operation. The adapter checks format and container structure, while the
+service owns image-count, decoded-size, dimension and context admission.
+
+```javascript
+const provider = new CloudflareExtractionProvider({
+    transport: 'binding',
+    ai: env.AI,
+    gateway: { id: 'existing-gateway', skipCache: true },
+});
+```
+
+`include_quantiles` and `return_state_text` stay in the model input's `options`.
+`rejectIfBusy` is an execution setting, configurable on the provider or request
+options; binding dispatch places it in the third `ai.run` argument. Gateway
+settings use the same routing and diagnostics as the Clef provider. A service
+rejection of an execution setting is reported without dropping the setting.
+
+## Validation, batching and errors
+
+`validateExtractionRequest(request, options?)` is credential-free offline
+validation. `provider.validate(request)` uses the configured provider settings.
+Both check structure and client resource budgets, without promising admission.
+
+Request/response budgets default to 8 MiB each and can be configured through
+64 MiB. Requests are checked before media decoding. `extract(request, { signal })`
+accepts an `AbortSignal`. Set `timeoutMs` on the provider constructor to bound
+validation, dispatch and response handling; extraction call options accept only
+`signal` and have no per-call timeout override.
+Retries default to zero. Billing/allocation errors are not retried even when
+retries are enabled; temporary eligible failures use the shared error policy.
+See [errors and recovery](../reference/ERRORS.md).
+
+`extractBatch(provider, requests, { concurrency, signal, stopOnError })` validates
+all array requests before dispatch and returns ordered `{ index, ok, result }`
+or `{ index, ok, error }` records. Concurrency defaults to four and is a client
+execution setting, independent of any service quota.
+Batch results retain each caller's `requestedModel`, including the full
+`@cf/cloudflare/clairic` alias, while `resolvedModel` and dispatched input use
+`clairic`, just as for individual extraction calls.
+
+## CLI
+
+```shell
+decision extraction init my-extraction
+decision extraction validate request.json
+decision extraction run request.json --env-file .env
+decision extraction batch requests.jsonl --concurrency 4 --env-file .env
+```
+
+The namespace defaults to `cloudflare-extraction`; incompatible explicit
+providers are rejected. Configuration schema version remains 1. Use the existing
+Cloudflare account, credential, Gateway, timeout and retry settings. Inference
+options belong in request JSON. Validation is offline and reports `fieldCount`.
+Streaming JSONL batches can complete valid rows before a later row fails.
+
+See the [runnable extraction example](../../examples/extraction.mjs), the
+[official model schema](https://developers.cloudflare.com/workers-ai/models/clairic/)
+and [extraction concepts](https://developers.cloudflare.com/workers-ai/concepts/extraction-models/).

package/docs/guides/GETTING_STARTED.md

@@ -20,18 +20,22 @@ In your application's directory, install the package from npm:
 npm install @fayegram-ai/decision-bridge
 ```
 
-You can also install a verified local archive, replacing the path below. See
-[packaging and release](../development/RELEASING.md) to build and verify one from
-a source checkout:
+You can also install a verified package archive. Replace the example archive
+path with your own; see [packaging and release](../development/RELEASING.md) to
+build and verify one from a source checkout:
 
 ```bash
-npm install /path/to/fayegram-ai-decision-bridge-0.1.2.tgz
+npm install /path/to/fayegram-ai-decision-bridge-0.1.3.tgz
 ```
 
 The installed package contains the SDK, declarations, command runner, examples,
 and docs. It runs without compilation; source development scripts and tests are
 excluded.
 
+Check the installed version with `npm exec -- decision-bridge --version`.
+Use the documentation bundled with your installed package, or select the
+matching [versioned documentation](../README.md#version-availability).
+
 ## Configure credentials
 
 Create `.env` in your application's directory and edit it locally:

package/docs/guides/JEV.md

@@ -114,25 +114,18 @@ choose your own presence/confidence thresholds using representative images.
 Jev token usage may be `null`; that means unknown, never zero. Native confidence
 and all other result checks remain enforced.
 
-## Image and request limits
-
-- PNG or JPEG (`png`, `jpg`, `jpeg`); still images only. Animated PNG is rejected.
-- At most 16 MiB per decoded image file.
-- Each dimension is 256–1568 pixels, and area is 78,400–2,458,624 pixels.
-  A 256 × 256 image fails the area minimum.
-- Jev requests default to a 32 MiB serialized JSON ceiling. `maxRequestBytes`
-  can lower it, but cannot exceed 32 MiB. Response budgets remain independently
-  configurable, with an 8 MiB default.
-- State, each instruction, and each criterion must fit 64 nested JSON levels.
-  General bridge snapshots also retain their 200,000-node limit.
-
-Preflight checks base64, headers, dimensions, PNG animation, references, original
-image bytes, and serialized request bytes. Full decoding, server re-encoding,
-the 32 MiB processed-image and expanded-input limits, and token limits remain
-service checks. Client header inspection cannot predict processed sizes.
-Prepare upright pixels yourself: TypeSafe removes metadata and does not apply
-EXIF orientation. No separate image-count cap is asserted by the bridge;
-`maxImages: null` means size and context determine capacity.
+## Images and client budgets
+
+PNG/JPEG formats, canonical base64, positive dimensions, still-image structure
+and asset reference semantics are checked locally. Service image dimensions,
+decoded/processed sizes and context admission remain upstream. The bridge does
+not resize, rotate or re-encode images. Prepare upright pixels in the application.
+
+Jev requests default to a 32 MiB client serialized-JSON budget. An explicit
+`maxRequestBytes` can select a budget through 64 MiB. Responses default to 8 MiB.
+General JSON processing retains a 100-level depth and 200,000-node safeguard;
+reference-pattern safeguards bound local regex construction. These are client
+resource controls, independent of service quotas.
 
 ## CLI
 
@@ -155,7 +148,7 @@ decision-bridge batch native.jsonl --native --config decision.config.json --env-
 
 Common/native validation is offline and uses the same preflight as inference.
 `--native` works with `init`, `validate`, `evaluate`, and `batch`. Jev keeps its
-`models` command. CLI JSON/JSONL input supports requests up to 32 MiB per record;
+`models` command. CLI JSON/JSONL input defaults to 32 MiB per record and permits a larger explicit client budget through 64 MiB;
 the actual serialized request must also fit the configured provider ceiling.
 
 `--jev-images` / `--no-jev-images` and `--jev-long-context` /

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.2"
+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.2"
+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