@fayegram-ai/decision-bridge 0.1.2 → 0.1.3

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,6 +56,12 @@ 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 |
+| `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
@@ -57,9 +69,11 @@ initialization, and ordered batches. Experimental images/boxes require
 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 `evaluate`, `validate`, or `schema` selects the bundled sample,
+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
@@ -94,7 +108,7 @@ 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 |
@@ -103,7 +117,7 @@ later configuration changes to control selection.
 | `--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 |
@@ -117,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
@@ -138,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:
 
@@ -181,14 +200,16 @@ delivery needs separate validation.
 ## I/O and resource limits
 
 Single JSON input normally uses **8 MiB**. JSONL normally uses **8 MiB per line,
-64 MiB total**. Jev permits **32 MiB** for a single JSON input or JSONL record,
+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.
@@ -222,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,9 +47,9 @@ 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. Jev requests default/cap 32 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 |
@@ -59,8 +60,8 @@ 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 and are capped at 32 MiB; a smaller `maxRequestBytes`
-lowers that ceiling. `DECISION_JEV_IMAGES` and `DECISION_JEV_LONG_CONTEXT`
+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
@@ -173,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.

package/docs/reference/ERRORS.md

@@ -1,7 +1,9 @@
 # Errors and recovery
 
 `DecisionError` extends `Error` and exposes `code`, optional `status`, `requestId`,
-`gatewayLogId`, `attempts`, and numeric `upstreamCode` for Cloudflare diagnostics.
+`gatewayLogId`, `attempts`, and numeric `upstreamCode` for Cloudflare diagnostics. Optional `source`,
+`upstreamErrorCode`, `upstreamErrorType`, `retryAfterMs` and `retryable`
+distinguish client controls and upstream failures.
 OpenAI Decisions refusal errors can also carry validated `refusedQuestions` and
 `usage`. `toJSON()` and `publicError(error)` return safe structured details.
 Unknown exceptions become a generic message, not a copied stack/body. Custom
@@ -16,13 +18,13 @@ providers deliberately constructing `DecisionError` must keep its message safe.
 | `USAGE_ERROR` | Invalid CLI flags/arguments or stdin usage; consult help |
 | `IO_ERROR` | Input/output path or permissions failure; preserve previous output |
 | `INPUT_TOO_LARGE` | CLI byte limit exceeded; reduce or split input |
-| `REQUEST_TOO_LARGE` | Encoded provider request exceeds configured limit; reduce input/schema |
+| `REQUEST_TOO_LARGE` | Configured client byte budget or upstream size admission rejected the request; inspect `source` and optional status |
 | `RESPONSE_TOO_LARGE` | Provider response exceeds configured limit; inspect budget/model behavior |
 | `HTTP_ERROR` | Non-success HTTP response; use status/request ID, not raw error body |
 | `CAPACITY_EXCEEDED` | Cloudflare capacity unavailable (3040); busy mode does not queue/retry |
-| `ALLOCATION_EXCEEDED` | Cloudflare allocation limit exceeded (3036) |
-| `RATE_LIMITED` | Cloudflare HTTP 429 without a more specific code |
-| `AUTHENTICATION_ERROR`, `PERMISSION_DENIED` | Cloudflare authentication or authorization failure |
+| `ALLOCATION_EXCEEDED` | Provider allocation, credit or spending limit exceeded; not automatically retried |
+| `RATE_LIMITED` | Temporary provider throttling without a more specific allocation/capacity code |
+| `AUTHENTICATION_ERROR`, `PERMISSION_DENIED` | Provider authentication or authorization failure |
 | `UPSTREAM_TIMEOUT`, `UPSTREAM_ABORTED` | Cloudflare upstream timeout (3007) or abort (3008) |
 | `NETWORK_ERROR` | Transport failed ambiguously; no automatic network retry occurred |
 | `RETRY_BUDGET_EXCEEDED` | Server delay cannot fit remaining deadline; choose a later attempt explicitly |
@@ -35,6 +37,10 @@ providers deliberately constructing `DecisionError` must keep its message safe.
 | `PROVIDER_ERROR` | Sanitized custom-provider exception |
 | `UNSUPPORTED_OPERATION` | Provider does not implement listing or another requested operation |
 | `BATCH_SKIPPED` | SDK stop-on-error prevented a not-yet-started record |
+| `INVALID_REQUEST` | Upstream request rejection; inspect safe machine code/type and correct the request |
+| `CONNECTION_CLOSED`, `DISPOSED` | Live connection ended or controller was disposed; pending work is cancelled |
+| `RESOURCE_LIMIT` | Live client pending-operation budget exceeded; settle existing operations before submitting more |
+| `OBSERVER_ERROR` | Live observer notification failed; no command or application action is repeated |
 | `UNEXPECTED_ERROR` | Unrecognized error sanitized for public output |
 
 ## Retry policy
@@ -44,18 +50,27 @@ available HTTP diagnostics. A refusal of any question fails that complete call;
 successful siblings are not exposed as a partial result.
 
 The shared response transport retries statuses **429, 502, 503, 504, and 529**
-only, for both HTTP requests and Workers AI binding responses. `maxRetries`
+as a fallback for HTTP and binding responses. Provider decoders refine eligibility; known allocation/billing failures are never retried. `maxRetries`
 means additional attempts; the default 2 allows at most 3 total attempts. Native
-OpenAI Decisions and Cloudflare Clef default to 0; explicitly enabling retries can repeat a billed
+OpenAI Decisions, Cloudflare Clef and Clairic default to 0; explicitly enabling retries can repeat a billed
 request. All
 attempts, backoff, and response-body reading share one timeout budget.
 
-`Retry-After` seconds or HTTP dates are honored. Without it, exponential backoff
+Valid `Retry-After` decimal integer seconds or HTTP dates are honored. All three
+HTTP date forms are interpreted in UTC; an elapsed date means zero delay.
+Malformed values are ignored, including fractional, signed, hexadecimal and
+exponent numbers. Without a valid hint, exponential backoff
 starts at 250 ms with jitter and an 8-second base cap. A delay that cannot fit the
 remaining budget fails instead of violating the server's requested wait.
 
-Authentication failures, generic HTTP 500, invalid output, model refusal, and
-ambiguous network failures are not retried automatically. HTTP retries are not an
+When an HTTP rejection body is malformed, too large, or interrupted, the known
+status, safe request/Gateway IDs and valid `Retry-After` remain available. If the
+body cannot be decoded, classification and retry eligibility use the status
+alone; no missing upstream code is invented. Caller cancellation and the total
+deadline still take precedence over this fallback.
+
+Authentication failures, invalid output, model refusal, and
+ambiguous network failures are not retried automatically. OpenAI may classify HTTP 500 as retryable; other transports retain their fallback policy. HTTP retries are not an
 exactly-once billing guarantee. Set `maxRetries: 0` when your workflow requires
 manual retry decisions. The bridge never retries a successful request because an
 observer failed; inspect `meta.observerFailures` separately.
@@ -64,8 +79,9 @@ observer failed; inspect `meta.observerFailures` separately.
 
 401/403 usually requires checking key/account/model authorization with the provider;
 the client reports the actual status rather than claiming to diagnose account
-state. 404 can indicate an incorrect API base/model/route. 429 exposes throttling;
-repeated retries can increase load. For `INVALID_RESPONSE`, a schema-capable model
+state. 404 can indicate an incorrect API base/model/route. A 429 can represent
+temporary throttling or an allocation/billing failure; inspect `code`,
+`upstreamErrorCode`, `upstreamErrorType` and `retryable`. For `INVALID_RESPONSE`, a schema-capable model
 may still emit invalid probabilities or be routed through an incompatible endpoint.
 Change configuration deliberately and retest; do not disable local validation.
 
@@ -83,3 +99,16 @@ For successful OpenAI calls, retain
 the requested selection, resolved outgoing ID, and reported model separately;
 see [model identities](../guides/OPENAI_DECISIONS.md#model-selection). Log input or results only under your
 own data-handling policy. No logging or telemetry is enabled by default.
+
+## Extraction and Live
+
+Clairic preserves native nulls, empty lists and the `truncated` flag in a successful
+extraction envelope; truncation is not converted into a decision-style failure.
+The application decides whether that extraction is sufficient for its task.
+
+Live preserves native refusal answers on completed decision events. Malformed
+server events report `INVALID_RESPONSE`; the offline event-file validator reports
+caller input as `VALIDATION_ERROR`. Observer failures produce `observer_error`
+notifications containing a safe `OBSERVER_ERROR`. Command submission receipts do
+not promise a completed decision. No Live command or application action is
+automatically replayed. See [Live lifecycle](../guides/LIVE_DECISIONS.md).

package/docs/reference/PROVIDERS.md

@@ -45,20 +45,21 @@ contract. The following additional forms are checked before dispatch:
 | Provider | Ordered text / embedded images | Typed string/boolean choices | Labelled score levels | Safety identifier | Model listing |
 | --- | --- | --- | --- | --- | --- |
 | Jev | Ordered text; images with explicit opt-in | Unsupported | Unsupported | Unsupported | Supported |
-| OpenAI Decisions | Supported; up to 128 images, preserving order | Supported | Supported | Supported | Unsupported |
-| Cloudflare Clef / Clef-flash | Supported; up to four images before text | Supported | Supported; 2–10 levels | Unsupported | Unsupported |
-| Cloudflare Clef-omni | Supported; up to four images before audio/video/text | Supported | Supported; 2–10 levels | Unsupported | Unsupported |
+| OpenAI Decisions | Supported; preserving order | Supported | Supported | Supported | Unsupported |
+| Cloudflare Clef / Clef-flash | Supported; images before text | Supported | Supported; ordered levels | Unsupported | Unsupported |
+| Cloudflare Clef-omni | Supported; images before audio/video/text | Supported | Supported; ordered levels | Unsupported | Unsupported |
 | OpenAI-compatible / OpenRouter / Anthropic | Unsupported | Unsupported | Unsupported | Unsupported | Supported; service-specific catalog |
 
 `bridge.getCapabilities(model)` reports the local profile, and
 `bridge.validate(request)` checks that profile and provider preflight without
 inference. These methods do not authenticate an account or query availability.
-Legacy choice maps and score rubrics have their own limits, described in the
+Legacy choice maps and score rubrics have structural requirements, described in the
 [SDK reference](SDK.md#question-builders). Custom providers declare additional
 capabilities explicitly.
 
-Omni additionally accepts up to four audio clips and two videos. The optional
-capability fields `audio`, `videos`, `maxAudioClips`, and `maxVideos` normalize to
+Omni additionally accepts embedded audio clips and videos; service counts remain
+upstream. The optional capability fields `audio`, `videos`, `maxAudioClips`, and
+`maxVideos` normalize to
 false/zero when omitted, preserving legacy custom profiles. Cloudflare's older
 models and all other shipped providers reject audio/video before inference.
 
@@ -66,6 +67,11 @@ Jev additionally supports `box` questions on `jev-preview` and pinned 1.14+ mode
 when `dangerZone.images` is enabled. Other built-ins reject box questions.
 See the [Jev guide](../guides/JEV.md) for asset placement and experimental opt-ins.
 
+OpenAI additionally supports `conversation`, `toolHistory`, `remoteImages` and
+`promptCaching`. These optional capability flags default to false for existing
+custom providers. Built-in quantitative limits use `null` where admission is
+left to the service; explicit custom-provider limits remain enforced.
+
 Dedicated `createDecision()` access is available on Jev, OpenAI Decisions and
 Cloudflare providers. It uses each service's native request/response shape and
 bypasses bridge preparation and observation hooks.
@@ -124,3 +130,10 @@ do not override them. This release has no silent provider failover, model search
 credential refresh, provider-side batch API, or universal quality guarantee.
 Unsupported protocols require an explicit custom decision or generative provider; unsupported server
 features require an explicitly supported mode or a different model.
+
+## Dedicated operations
+
+Clairic is a native extraction model exposed through [extraction](../guides/EXTRACTION.md).
+Its provider is not a DecisionProvider and is not accepted by createBridge.
+[Live Decisions](../guides/LIVE_DECISIONS.md) owns a connection-oriented command
+and event lifecycle through a dedicated export.

package/docs/reference/SDK.md

@@ -7,6 +7,9 @@ TypeScript setup, and CommonJS dynamic import. The source-tree entry point is
 TypeScript declarations are in `src/index.d.mts`; runtime JavaScript is authoritative
 and checked independently of those declarations.
 
+This reference covers **0.1.3**. See
+[version availability](../README.md#version-availability) for earlier versions.
+
 ## Create a bridge
 
 ```javascript
@@ -48,7 +51,7 @@ guides. These are SDK options, not per-evaluation bridge options.
 | --- | --- |
 | `timeoutMs` | 30,000 ms; positive integer through 2,147,483,647; one transport budget for dispatch, retries, backoff, and response reading |
 | `maxRetries` | Additional eligible attempts, 0–10; Jev and generative presets default to 2, native OpenAI and Cloudflare to 0 |
-| `maxRequestBytes` | Complete serialized request ceiling; normally 8 MiB, configurable from 1 byte through 64 MiB; Jev defaults to and caps at 32 MiB; Cloudflare applies its [model-specific budgets](../guides/CLOUDFLARE_DECISIONS.md#embedded-images-and-limits) |
+| `maxRequestBytes` | Complete serialized request ceiling; normally 8 MiB, configurable from 1 byte through 64 MiB; Jev defaults to 32 MiB, with explicit client budgets through 64 MiB; Cloudflare applies its [model-specific budgets](../guides/CLOUDFLARE_DECISIONS.md#embedded-images-and-limits) |
 | `maxResponseBytes` | 8 MiB; configurable from 1 byte through 64 MiB; applies while reading the response body |
 | `fetchImpl` | Optional `(url: string, init?: RequestInit) => Promise<Response>`; defaults to the runtime's `fetch` |
 
@@ -68,8 +71,9 @@ they interact; [errors](ERRORS.md#retry-policy) lists retryable statuses.
 
 ### `bridge.evaluate(request, options?)`
 
-`request` has exactly one of `state` or ordered `input`, `questions`, and optional
-`model` and `safetyIdentifier`. New forms require declared provider capabilities;
+`request` has exactly one of `state`, ordered `input` or `conversation`, plus
+`questions`. Optional fields are `model`, `safetyIdentifier`, `promptCacheKey`
+and `promptCacheOptions`. New forms require declared provider capabilities;
 see [OpenAI Decisions](../guides/OPENAI_DECISIONS.md) and
 [Cloudflare Clef](../guides/CLOUDFLARE_DECISIONS.md). The request model
 wins over the provider's configured default, which an omitted request model inherits.
@@ -81,14 +85,20 @@ resolve to upstream IDs within the provider. No default is assumed for a generat
 independent transport timeout, including Workers AI binding calls.
 
 Ordered parts are `{ type: 'text', text }`, `{ type: 'image', dataUrl, detail? }`,
-`{ type: 'audio', dataUrl }`, or `{ type: 'video', dataUrl }`. Audio/video are
-supported by Cloudflare Clef-omni and explicitly capable custom providers; other
+`{ type: 'image', url, detail? }`, `{ type: 'audio', dataUrl }`, or
+`{ type: 'video', dataUrl }`. Image `url` and `dataUrl` are exclusive. Text/image
+parts may carry `promptCacheBreakpoint`. Remote HTTP(S) images and cache controls
+require their respective capabilities and are forwarded without URL fetching or
+cache-policy selection. `conversation` uses the native Decisions input-item union;
+see [conversation and prompt caching](../guides/OPENAI_DECISIONS.md#conversation-and-prompt-caching).
+Audio/video are supported by Cloudflare Clef-omni and explicitly capable custom providers; other
 built-ins reject them before dispatch. Cloudflare requires images → audio →
-videos → text. Media use embedded data URLs, with format and size checks described
-in the [Cloudflare guide](../guides/CLOUDFLARE_DECISIONS.md#omni-audio-and-video).
+videos → text. Its media use embedded data URLs, with format and client-budget
+checks described in the [Cloudflare guide](../guides/CLOUDFLARE_DECISIONS.md#omni-audio-and-video).
 
-The bridge snapshots and freezes its input, runs sequential state or input preparation,
-invokes the provider once, validates the result, then observes an immutable result.
+The bridge snapshots and freezes its input, runs preparation hooks for the
+selected input form, invokes the provider once, validates the result, then
+observes an immutable result.
 Built-in transports can retry eligible response statuses within that invocation
 when client retries are configured.
 
@@ -151,18 +161,17 @@ must declare `boxes: true`. Jev supports it with experimental image opt-in and
 a supported model; see [Jev images and boxes](../guides/JEV.md).
 
 Builders return immutable question objects. `choice(instructions, criteria)` accepts
-a label map containing 1 to 255 options. `noul(instructions, criteria?)` accepts an
+a nonempty label map. `noul(instructions, criteria?)` accepts an
 optional criteria object,
-with only `true` and `false` keys. `score(instructions, criteria)` accepts **2–10**
+with only `true` and `false` keys. `score(instructions, criteria)` accepts at least two
 ordered levels; numeric level indices are zero-based. There is no boolean alias:
 `noul` means a probability, not a thresholded truth value.
 
 `choice(instructions, options)` accepts ordered objects with unique string or
 boolean `value` fields and optional text or structured JSON descriptions. Boolean `true` and string
 `"true"` remain distinct. `scoreLevels(instructions, levels)` accepts at least two
-ordered label/description objects. Provider preflight applies service limits:
-OpenAI Decisions and Cloudflare require 2–255 choices; Cloudflare limits scores
-to 2–10 levels, while OpenAI labelled scores have no additional client count cap.
+ordered label/description objects. Provider preflight enforces structural requirements:
+OpenAI Decisions and Cloudflare require at least two choices; maximum service counts remain upstream.
 
 ## Returned data
 
@@ -233,21 +242,26 @@ estimated token count is fabricated.
 
 Metadata can have additional JSON fields. Application logic should not assume
 unavailable metadata exists. Result objects and nested data returned by the bridge
-are immutable. Standalone validation functions return snapshots, not frozen values.
+are immutable. Standalone common `validateRequest` and `validateResult` return
+snapshots without freezing them; dedicated extraction and Live validators return
+frozen snapshots.
 
-`schemaVersion` remains 1 for legacy requests and 2 for ordered images/text or
-richer question forms. Audio/video requests use 3; requests with boxes use 4.
-This result version is separate
-from the CLI configuration schema, which remains 1.
+`schemaVersion` is selected by the highest applicable feature: 5 for conversation,
+remote-image URLs or prompt-cache controls; 4 for boxes; 3 for audio/video; 2 for
+ordered images/text, typed choices, labelled scores or a safety identifier; and
+1 for legacy requests. The CLI configuration schema remains 1. Extraction and
+Live use their dedicated native envelopes rather than a common result version.
 
 ## Extensions
 
 An extension has a unique printable `name` (maximum 100 characters), optional
-`prepareState(state, context)`, `prepareInput(input, context)`, and
+`prepareState(state, context)`, `prepareInput(input, context)`,
+`prepareConversation(items, context)`, and
 `onResult(result, context)`. Preparation extensions must support the request's
 input form; incompatible hooks fail explicitly before dispatch.
 
-Preparation returns replacement state or input, or `undefined` to leave it unchanged.
+Preparation returns replacement state, ordered input or conversation, or
+`undefined` to leave it unchanged.
 Preparation exceptions fail before inference with `EXTENSION_ERROR`; transformed
 content is revalidated, including capabilities and provider preflight. Preparation
 cannot rewrite question definitions or switch the model.
@@ -362,14 +376,14 @@ decision providers may preserve custom string labels. Generative prompt and
 normalization helpers independently validate the shared-state, legacy-question
 profile and explicitly reject unsupported request capabilities.
 Decision-kind classification alone does not require confidence or known counts;
-`validateResult({ native: true })` is a separate strict validation option used for
+`validateResult(result, questions, { native: true })` is a separate strict validation option used for
 Jev's contract. See [custom decision](../guides/CUSTOM_DECISION.md),
 [custom generative](../guides/CUSTOM_GENERATIVE.md), and the shared
 [custom contract](../guides/CUSTOM_PROVIDERS.md).
 
 ## Validation guarantees
 
-Legacy choice criteria maps allow at most 255 options, matching Jev's contract. Noul
+Legacy choice criteria maps must be nonempty. Noul
 criteria must be omitted or an object; its present true/false descriptions cannot
 be raw null. Score levels likewise cannot be raw null (nested null JSON values are
 still allowed). These invalid forms now fail before provider dispatch.
@@ -379,7 +393,10 @@ the answer. `evaluateBatch()` validates array holes as invalid requests before a
 item is dispatched, rather than spending on adjacent valid entries.
 
 The optional third argument to `validateResult()` must be a plain options object
-with optional boolean `native` and integer `probabilityDecimalPlaces` (1–15) fields.
+with optional boolean `native`, boolean `nullableUsage`, and integer
+`probabilityDecimalPlaces` (1–15) fields. Both booleans default to false.
+`nullableUsage: true` permits null token counts when native validation is enabled;
+it does not relax the native confidence requirement.
 Providers can declare a pure synchronous `getResultValidationOptions(model)` hook;
 its policy is validated before inference and is not read from response metadata.
 Returning a Promise is a configuration error; its rejection is observed without
@@ -400,3 +417,24 @@ Native provider cancellation/timeout errors preserve the last observed sanitized
 request ID and attempt count when available. The bridge may settle its own
 cancellation race before the provider returns diagnostics; do not require those
 optional fields on every `ABORTED` or `TIMEOUT` error.
+
+## Dedicated operations
+
+Import these subpaths under `@fayegram-ai/decision-bridge/`. Neither is selected
+by the root `createProvider` factory or implements the bridge's `evaluate` contract.
+
+| Export | Runtime API | Result / integration |
+| --- | --- | --- |
+| `extraction` | `CloudflareExtractionProvider`, `validateExtractionRequest`, `extractBatch` | Immutable `{ extraction, meta }`, with native values and model/transport diagnostics; [extraction guide](../guides/EXTRACTION.md) |
+| `live` | `createLiveDecisions`, `validateLiveConfiguration`, `validateLiveCommand`, `validateLiveEvent` | Commands, acknowledgements and event subscriptions over a caller-owned connection; [Live guide](../guides/LIVE_DECISIONS.md) |
+
+Both export their request, result, configuration and transport types. Extraction
+supports REST or a Workers AI binding; Live owns no authentication, audio,
+connection establishment or reconnection. See the [CLI reference](CLI.md) for
+their command namespaces.
+
+Service quotas, maximum request counts, context/media limits and Gateway
+admission remain authoritative upstream. Offline validation checks adapter
+structure and client resource budgets. SDK and CLI do not estimate tokens or
+enforce RPM/TPM. Explicit transport budgets can select up to 64 MiB, including
+Jev and all Clef models; existing default budgets are retained.

package/docs/reference/SOURCES.md

@@ -22,6 +22,8 @@ reference does not imply that authenticated inference was run against its servic
 | OpenAI structured output modes | https://platform.openai.com/docs/guides/structured-outputs |
 | OpenAI native Decisions guide | https://developers.openai.com/api/docs/guides/decisions |
 | OpenAI Decisions request/response contract | https://developers.openai.com/api/reference/resources/decisions/methods/create |
+| OpenAI Live Decisions guide | https://developers.openai.com/api/docs/guides/decisions-voice |
+| OpenAI Live protocol | https://developers.openai.com/api/reference/resources/live/primary-websocket |
 | OpenRouter structured output and routing | https://openrouter.ai/docs/guides/features/structured-outputs |
 | Anthropic Messages, tools, usage, and stop reasons | https://platform.claude.com/docs/en/api/messages/create |
 | GitHub checkout action | https://github.com/actions/checkout |
@@ -48,6 +50,11 @@ separate operational check.
 - [Cloudflare-owned model implementation](https://huggingface.co/Cloudflare/clef-flash/blob/main/joint_schema_model.py), including output precision
 - [Cloudflare-owned Omni implementation](https://huggingface.co/Cloudflare/clef-omni/blob/main/joint_schema_model.py), including grouped media and output precision
 
+## Cloudflare extraction
+
+- [Extraction concepts](https://developers.cloudflare.com/workers-ai/concepts/extraction-models/)
+- [Clairic schema snapshot](https://github.com/cloudflare/cloudflare-docs/blob/a5cc2cba1a31b8bd95eda69dad151e6cd307ac7b/src/content/workers-ai-models/clairic.json), the pinned basis for established native fields; underspecified predictive JSON remains preserved
+
 ## Package and repository release
 
 - [Scoped public npm packages](https://docs.npmjs.com/creating-and-publishing-scoped-public-packages/)

package/examples/extraction.mjs

@@ -0,0 +1,16 @@
+// Explicit execution calls Cloudflare; configure account/token in your environment.
+import { CloudflareExtractionProvider } from '../src/extraction/index.mjs';
+import { publicError } from '../src/index.mjs';
+
+try {
+    const provider = new CloudflareExtractionProvider();
+    const result = 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' } },
+    });
+    console.log(JSON.stringify(result, null, 2));
+} catch (error) {
+    console.error(publicError(error));
+    process.exitCode = 1;
+}

package/examples/live-decisions.mjs

@@ -0,0 +1,24 @@
+// Call with your already authenticated, open WebSocket-like Live connection.
+import { createLiveDecisions } from '../src/live/index.mjs';
+
+export function attachLiveDecisions(connection) {
+    return createLiveDecisions({ transport: {
+        send(command) { connection.send(JSON.stringify(command)); },
+        subscribe(listener) {
+            const message = event => {
+                try { listener({ kind: 'event', event: JSON.parse(event.data) }); }
+                catch { listener({ kind: 'error' }); }
+            };
+            const close = () => listener({ kind: 'close' });
+            const error = () => listener({ kind: 'error' });
+            connection.addEventListener('message', message);
+            connection.addEventListener('close', close);
+            connection.addEventListener('error', error);
+            return () => {
+                connection.removeEventListener('message', message);
+                connection.removeEventListener('close', close);
+                connection.removeEventListener('error', error);
+            };
+        },
+    } });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fayegram-ai/decision-bridge",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "JavaScript SDK and CLI for structured decisions across native decision APIs and configurable model providers",
   "repository": {
     "type": "git",
@@ -44,6 +44,16 @@
       "browser": "./src/custom/generative/index.mjs",
       "import": "./src/custom/generative/index.mjs"
     },
+    "./extraction": {
+      "types": "./src/extraction/index.d.mts",
+      "browser": "./src/extraction/index.mjs",
+      "import": "./src/extraction/index.mjs"
+    },
+    "./live": {
+      "types": "./src/live/index.d.mts",
+      "browser": "./src/live/index.mjs",
+      "import": "./src/live/index.mjs"
+    },
     "./config.schema.json": "./schemas/decision.config.schema.json"
   },
   "bin": {