@fayegram-ai/decision-bridge 0.1.2 → 0.1.3

package/CHANGELOG.md

@@ -2,6 +2,25 @@
 
 Notable user-facing changes by version.
 
+## 0.1.3
+
+- Expand OpenAI Decisions with conversation/tool history, remote images and
+  prompt caching, including common input, extensions and schema version 5.
+- Add Clairic extraction over REST and Workers bindings, with nine field types,
+  native predictive metadata and extraction CLI commands.
+- Add an existing-connection Live Decisions controller and offline protocol
+  validation/replay tools through a dedicated package export.
+- Leave service quotas and admission ceilings upstream; preserve explicit client
+  resource budgets and improve safe errors and error-aware retries.
+- Preserve requested Clairic model aliases in batch diagnostics and parse valid
+  retry hints without losing HTTP status or safe IDs when an error body fails.
+- Harden Live configuration/history correlation, transcript ordering, item
+  acknowledgements, observer isolation, cancellation and connection cleanup.
+  Offline event validation and replay retain their respective input/server error
+  contracts.
+- Document the expanded SDK and CLI APIs, extraction and Live operations, and
+  client resource controls.
+
 ## 0.1.2
 
 - Add opt-in Jev images, typed bounding boxes, native JSON assets, and long context

package/CONTRIBUTING.md

@@ -20,9 +20,11 @@ configuration-schema validator from the lockfile. See the
 Start with the [architecture](docs/development/ARCHITECTURE.md),
 [design rationale](docs/development/DESIGN.md), and
 [repository layout](docs/development/REPOSITORY_LAYOUT.md).
-Preserve the provider-independent contract of `state` or ordered `input` plus
-`questions`, and explicit probability provenance. Add focused regression tests for bug fixes and wire-level
-tests for protocol changes. Fixtures must not contain credentials or live-account
+Preserve the provider-independent contract of exactly one of `state`, ordered
+`input` or `conversation`, plus `questions`, and explicit probability provenance.
+Extraction and Live use dedicated operation contracts. Keep service admission
+limits upstream and client resource controls explicit. Add focused regression
+tests for bug fixes and wire-level tests for protocol changes. Fixtures must not contain credentials or live-account
 data; label synthetic responses as synthetic.
 
 ## Make and verify a change

package/README.md

@@ -7,7 +7,7 @@ A JavaScript SDK that turns supplied information into structured decisions insid
 your application. An optional Node command runner is included for evaluating files.
 Give it a `state` (text or JSON to assess) and one or more `questions`; it returns
 validated choices, probabilities for yes/no (`noul`) questions, or rubric-based
-scores.
+scores. Capable providers also accept ordered media input or conversation history.
 For example, pass a failed test log to classify the failure and estimate whether
 a missing dependency caused it. Your application decides what to do with the result.
 
@@ -21,7 +21,7 @@ OpenRouter, and Anthropic presets. The bridge handles the shared request and res
 contract; each provider handles its API protocol and model capabilities.
 
 [OpenAI Decisions](docs/guides/OPENAI_DECISIONS.md) also supports ordered text/image
-input, typed string/boolean choices, labelled scores, and dedicated native access.
+input, typed string/boolean choices, labelled scores, conversation/tool history, remote images, prompt caching, and dedicated native access.
 [Cloudflare Clef, Clef-flash, and Clef-omni](docs/guides/CLOUDFLARE_DECISIONS.md) provide
 common/native access, embedded images, typed choices, labelled scores, REST,
 Workers AI bindings, and optional AI Gateway routing. Omni additionally supports
@@ -29,7 +29,12 @@ embedded WAV/MP3 audio and MP4/WebM video, ordered images → audio → videos
 The common API checks provider/model capabilities before dispatch; refusals are
 errors.
 
-**Version 0.1.2 · Node.js 22.16+ or modern browsers (SDK) · ESM · zero runtime dependencies**
+**Version 0.1.3 · Node.js 22.16+ or modern browsers (SDK) · ESM · zero runtime dependencies**
+
+These docs cover 0.1.3. For supported features by version, see
+[version availability](docs/README.md#version-availability) and the
+[changelog](CHANGELOG.md). Start with the
+[installation options](docs/guides/GETTING_STARTED.md#install-into-your-application).
 
 The npm package is
 [@fayegram-ai/decision-bridge](https://www.npmjs.com/package/@fayegram-ai/decision-bridge).
@@ -64,7 +69,7 @@ Decision Bridge release. Explicit supported model IDs can also be selected; see
 the [OpenAI model selection guide](docs/guides/OPENAI_DECISIONS.md#model-selection)
 for details. Results retain the selected value in `meta.requestedModel`,
 the outgoing ID in `meta.resolvedModel`, and the service-reported model in `model`.
-Cloudflare accepts only the three models above, in short or full form.
+The Cloudflare decision provider accepts the three decision models above, in short or full form.
 Model discovery is unsupported for OpenAI Decisions and Cloudflare.
 
 Additional decision protocols use [custom decision providers](docs/guides/CUSTOM_DECISION.md).
@@ -73,6 +78,16 @@ entry point, with `openai-compatible`, `openrouter`, or `anthropic` presets, or
 an explicit provider module. Those presets require a model ID supported by your
 configured service and have no default model or fixed model catalog.
 
+Clairic uses the dedicated [extraction API](docs/guides/EXTRACTION.md), with
+selectors `clairic` and `@cf/cloudflare/clairic` (default `clairic`). It returns
+typed values, estimates and forecasts through REST or Workers bindings.
+[Live Decisions](docs/guides/LIVE_DECISIONS.md) attaches to an application-owned
+GPT-Live connection for delegation, transcript triggers and Decision events.
+These operations have dedicated `/extraction` and `/live` package exports.
+
+Service quotas and admission limits are handled upstream. The SDK validates its
+contracts and configurable client resource budgets and returns structured errors.
+
 ## Choose a provider
 
 All native providers support shared state and the common `choice`, `noul`, and
@@ -81,7 +96,7 @@ All native providers support shared state and the common `choice`, `noul`, and
 | Provider | Additional supported features | Guide |
 | --- | --- | --- |
 | Jev | Native decisions, opt-in images, boxes, and long context through TypeSafe | [Jev guide](docs/guides/JEV.md) |
-| OpenAI Decisions | Ordered text/images, typed choices, labelled scores, safety identifiers, native access | [OpenAI Decisions](docs/guides/OPENAI_DECISIONS.md) |
+| OpenAI Decisions | Ordered text/images, conversation/tool history, remote images, prompt caching, typed choices, labelled scores, safety identifiers, native access | [OpenAI Decisions](docs/guides/OPENAI_DECISIONS.md) |
 | Cloudflare Clef / Clef-flash | Embedded images before text, typed choices, labelled scores, native access, Workers AI binding, optional Gateway | [Cloudflare decisions](docs/guides/CLOUDFLARE_DECISIONS.md) |
 | Cloudflare Clef-omni | The same decision and transport features, plus embedded audio/video | [Omni media and limits](docs/guides/CLOUDFLARE_DECISIONS.md#omni-audio-and-video) |
 | Custom decision service | Explicit decision provider contract | [Custom decision providers](docs/guides/CUSTOM_DECISION.md) |
@@ -254,12 +269,13 @@ test suite and development scripts.
 
 | Area | Implementation |
 | --- | --- |
-| Stable contract | Runtime-defined [questions](docs/reference/SDK.md#question-builders), structured state or ordered input, typed answers, immutable results |
+| Stable contract | Runtime-defined [questions](docs/reference/SDK.md#question-builders), state, ordered input or conversation according to capabilities, typed answers, immutable results |
 | Native providers | Jev, OpenAI Decisions, Cloudflare Clef/Clef-flash/Clef-omni |
 | Custom providers | Separate decision and generative contracts; opt-in Chat Completions, OpenRouter, and Anthropic presets |
 | SDK | Provider factory, [capability preflight](docs/reference/SDK.md#bridgegetcapabilitiesmodel-and-bridgevalidaterequest), [cancellation](docs/reference/SDK.md#cancellation-and-deadlines), and [ordered batch evaluation](docs/reference/SDK.md#sdk-batch-evaluation) |
-| Application extensions | [State/input preparation and result observation](docs/guides/CUSTOMIZATION.md), plus [choice thresholds and abstention policies](docs/guides/CUSTOMIZATION.md#application-policy-is-a-separate-stage) |
-| Node command | [Initialize, evaluate, validate, schema, models, and ordered JSONL batches](docs/reference/CLI.md#commands), with [explicit JSON profiles](docs/reference/CONFIGURATION.md) |
+| Dedicated operations | [Clairic extraction](docs/guides/EXTRACTION.md) and [Live Decisions](docs/guides/LIVE_DECISIONS.md), with separate exports and native results |
+| Application extensions | [State/input/conversation preparation and result observation](docs/guides/CUSTOMIZATION.md), plus [choice thresholds and abstention policies](docs/guides/CUSTOMIZATION.md#application-policy-is-a-separate-stage) |
+| Node command | [Decision/extraction commands and offline Live validation/replay](docs/reference/CLI.md#commands), with [explicit JSON profiles](docs/reference/CONFIGURATION.md) |
 | Reliability | [Transport byte limits and fetch injection](docs/reference/SDK.md#provider-transport-options), deadlines, [limited retries and safe errors](docs/reference/ERRORS.md), strict response validation, atomic output |
 | Development | Functional tests, coverage, TypeScript and Workers binding contracts, offline tarball-install checks, cross-platform CI configuration |
 

package/SECURITY.md

@@ -5,8 +5,11 @@
 Keep keys in the process environment or an explicitly loaded local environment
 file. Never place them in request JSON, committed profiles, command-line arguments,
 or shared logs. The package contains no key, telemetry client, or background job.
-By design it sends the supplied state and question definitions to the selected
-provider when evaluation is explicitly requested. Review data-sharing requirements
+It sends supplied decision evidence/question definitions or extraction evidence/
+fields to the selected provider when the operation is explicitly requested.
+Conversation/tool history is also request data. Remote HTTP(S) image references
+are forwarded to OpenAI without being fetched by the SDK; the provider handles
+their retrieval. Review data-sharing requirements
 before sending private repository content or documents.
 Optional Cloudflare Gateway routing can cache requests/responses or collect logs
 according to explicit options and the Gateway's configuration. Review that
@@ -32,8 +35,9 @@ verbose HTTP logger that prints Authorization or x-api-key headers.
 ## Input and output
 
 Strict plain-JSON checks reject accessors, cycles, non-finite numbers, lossy objects,
-and unknown fields. Bytes, nesting, nodes, retries, concurrency, and waiting time
-are bounded. These checks do not establish decision accuracy or resist every
+and unknown request fields. Clairic additionally preserves safe native response
+fields, including predictive JSON and truncation. Bytes, nesting, nodes, retries,
+concurrency, and waiting time are bounded. These checks do not establish decision accuracy or resist every
 adversarial semantic input. Question instructions are trusted configuration;
 state is untrusted evidence. Prompt separation is a mitigation, not a guarantee.
 
@@ -51,6 +55,13 @@ the bridge can stop awaiting a non-cooperative promise, not terminate arbitrary
 code or undo side effects. A provider timeout or cancellation does not prove remote
 inference stopped before billing.
 
+The Live controller attaches to a connection supplied by the application. That
+application owns authentication, audio, connection setup and reconnection. The
+controller sends Decisions commands and consumes parsed notifications; disposing
+it releases its listeners/waits without closing the application connection or
+undoing actions. Decisions with unmatched or stale correlation require application
+policy; receipt of a decision is not proof that an action completed.
+
 ## Dependencies and CI
 
 There are zero runtime dependencies. This reduces dependency surface but is not a
@@ -63,13 +74,9 @@ commits under your organization's policy before using CI in a privileged setting
 
 ## Reporting
 
-For a hosted public repository, use its **Security** tab and **Report a
-vulnerability** to submit a private report. The repository owner must enable
-private vulnerability reporting when making the repository public, before
-announcing the release; this source tree has no dedicated security inbox or other
-private contact channel. If the reporting button is absent, ask the maintainer
-for a private contact method without
-including vulnerability details in a public issue.
+Use the repository's **Security** tab and **Report a vulnerability** to submit a
+private report. If the reporting button is unavailable, ask the maintainer for a
+private contact method without including vulnerability details in a public issue.
 
 Include the affected version, impact, and a minimal redacted reproduction. Do
 not publish credentials, confidential inputs, or exploit details in an issue.

package/docs/README.md

@@ -11,14 +11,25 @@ See [model selectors and provider defaults](../README.md#model-selectors) for
 built-in decision models and the separate custom generative presets.
 
 Decision Bridge is a JavaScript SDK with an optional command runner. It evaluates
-supplied `state` or ordered `input`, plus `questions`, with an explicitly selected
-provider and returns
-validated, structured decisions.
+exactly one of `state`, ordered `input` or `conversation`, plus `questions`, with
+an explicitly selected capable provider and returns validated, structured decisions.
+Dedicated extraction and Live APIs have their own operation contracts.
 For provider-specific input forms, consult the
 [capability comparison](reference/PROVIDERS.md#common-request-capabilities).
 The common bridge API and dedicated native APIs have separate request shapes;
 the Jev, OpenAI and Cloudflare guides cover both.
 
+## Version availability
+
+These guides cover **0.1.3**. Use the documentation bundled with your installed
+package. For version 0.1.2, see the
+[0.1.2 documentation](https://github.com/Fayegram-AI/decision-bridge/tree/decision-bridge-v0.1.2/docs).
+
+OpenAI conversation/tool history, remote images and prompt caching, plus Clairic
+extraction and Live Decisions, require 0.1.3 or later. See
+[installation](guides/GETTING_STARTED.md#install-into-your-application).
+See the [changelog](../CHANGELOG.md) for version history.
+
 ## Use the bridge
 
 | Guide | Purpose |
@@ -28,8 +39,10 @@ the Jev, OpenAI and Cloudflare guides cover both.
 | [Platforms](guides/PLATFORMS.md) | Windows, macOS, and Linux setup |
 | [Switching models](guides/SWITCHING_MODELS.md) | Backend and model selection |
 | [Jev](guides/JEV.md) | Common/native images, boxes, experimental long context, model selection, and CLI opt-ins |
-| [OpenAI Decisions](guides/OPENAI_DECISIONS.md) | Model selectors and upstream targets, selection metadata, common/native access, ordered images, and typed values |
+| [OpenAI Decisions](guides/OPENAI_DECISIONS.md) | Model selectors, common/native access, conversation/tool history, remote images, cache controls and typed values |
 | [Cloudflare Clef / Clef-flash / Clef-omni](guides/CLOUDFLARE_DECISIONS.md) | Common/native decisions, embedded images and Omni audio/video, REST and Workers AI binding, busy-mode compatibility, and optional Gateway |
+| [Clairic extraction](guides/EXTRACTION.md) | Nine extraction/prediction types, REST/binding, native results and extraction CLI |
+| [Live Decisions](guides/LIVE_DECISIONS.md) | Existing-connection controller, acknowledgements, correlation and offline replay |
 | [Customization](guides/CUSTOMIZATION.md) | Questions, templates, extensions, and policies |
 | [Custom providers](guides/CUSTOM_PROVIDERS.md) | Common classified contract and explicit CLI module loading |
 | [Custom decision](guides/CUSTOM_DECISION.md) | Extend a native decision model protocol |

package/docs/development/ARCHITECTURE.md

@@ -17,12 +17,12 @@ and Jev default before constructing the SDK bridge.
 
 ```text
 Application / CLI
-  state or ordered input + question definitions + optional model
+  state, ordered input or conversation + question definitions + optional model
         |
         v
   request snapshot, common validation, capabilities, provider preflight
         |
-  ordered prepareState or prepareInput extensions + revalidation
+  ordered prepareState, prepareInput or prepareConversation extensions + revalidation
         |
   Provider.evaluate (explicit decision/generative kind)
         +-- Jev: native systemone
@@ -83,6 +83,10 @@ See [OpenAI model selection](../guides/OPENAI_DECISIONS.md#model-selection).
 | `src/providers/` | API orchestration, model profiles, preflight, codecs, bounded image/audio/video inspection, and transports |
 | `src/providers/openai-profile.mjs`, `src/providers/decisions-preflight.mjs` | Release-owned OpenAI selection, capabilities, and preparation of selected and outgoing requests |
 | `src/providers/jev-profile.mjs`, `src/providers/jev-preflight.mjs`, `src/providers/jev-images.mjs` | Jev experimental policy, common/native assets, and image preflight |
+| `src/providers/decisions-input.mjs`, `src/providers/decisions-codec.mjs` | Decisions item/cache validation and lossless common/native encoding |
+| `src/providers/cloudflare-transport.mjs` | Shared decision/extraction REST and binding authentication, dispatch and diagnostics |
+| `src/extraction/` | Clairic native field/request/response validation, provider, ordered batches and declarations |
+| `src/live/` | Live protocol validation, bounded correlation state, supplied-connection controller and declarations |
 | `src/embedded.mjs` | Shared embedded data URL and canonical base64 checks |
 | `src/transport.mjs`, `src/response-transport.mjs` | Credential destinations, bounded bodies, safe errors, retries |
 | `src/async.mjs` | Deadlines and cancellation races |
@@ -110,14 +114,24 @@ policy helper does not infer it from the answer or its metadata.
 
 ## Reliability and configuration
 
+Built-in validators check structure, representation, adapter capabilities and
+response integrity. They leave service-owned question/media counts, text/context
+ceilings, quotas and RPM/TPM upstream. Custom quantitative capability limits remain
+part of those providers' contracts. Client byte budgets, JSON safeguards,
+cancellation and deadlines remain local controls.
+
 Provider deadlines include dispatch, configured retries, backoff, and bounded body
 reading. The bridge deadline additionally covers validation, preparation, provider
 waiting, and result processing. Expired synchronous work cannot dispatch a call.
 Cancellation bounds waiting for custom promises; custom code must honor signals
 to release its own resources. Observations use a separate bounded budget.
 
-Retries cover selected explicit transient responses. Ambiguous failures and failed
-observers do not trigger another inference. CLI atomic files protect previous
+Retries cover selected explicit transient responses, with machine-code
+classification preventing billing/allocation retries. OpenAI Decisions and
+Clairic default to zero retries. Valid Retry-After hints share the total deadline;
+attempt counts describe adapter dispatches, not hidden Gateway retries.
+Malformed rejection bodies retain known safe HTTP diagnostics. Ambiguous failures
+and failed observers do not trigger another inference. CLI atomic files protect previous
 output but cannot undo remote work or emitted stdout.
 
 JSON configuration is explicit. Custom ESM executes only when selected. Custom
@@ -135,7 +149,20 @@ mutable request limit or response identifiers. Header/container inspection is
 bounded and does not perform full media decoding.
 
 The SDK does not host models or provide a server API, persistent state, autonomous
-actions, streaming, transcription, transcoding, frame extraction,
+actions, HTTP decision streaming, audio transcription, transcoding, frame extraction,
 provider-side asynchronous batch jobs, platform
 management, automatic model search, or automatic provider failover. SDK arrays and
 CLI JSONL batches provide bounded client-side concurrency.
+
+Extraction owns its request/result contract and uses shared Cloudflare dispatch.
+Its inference options remain in model input; binding execution options use the
+third `ai.run` argument. Native nulls, empty lists, predictive JSON and truncation
+are preserved in an immutable `{ extraction, meta }` envelope.
+Live owns protocol validation, a bounded pure correlation reducer and a supplied-
+connection controller. Offline replay uses that same reducer. Their dedicated
+exports do not widen the existing decision/generative provider contract.
+Live configuration changes activate on acknowledgement. Source snapshots and
+observed per-direction transcript order support correlation; unavailable evidence
+stays unmatched. Manual evaluation and commentary return submission receipts;
+completed decisions arrive through subscriptions, preserving native refusals.
+The application owns authentication, audio, connection setup and reconnection.

package/docs/development/DESIGN.md

@@ -2,7 +2,7 @@
 
 ## Native decisions as the application contract
 
-Use shared state or ordered input and independent typed questions as the public
+Use shared state, ordered input or conversation and independent typed questions as the public
 contract. The bridge owns orchestration; providers own their model API protocols.
 This gives applications a stable decision interface and makes customization
 explicit at each call. Native decision models are the main package scope;
@@ -10,6 +10,11 @@ generative protocols are opt-in custom strategies with their own public subpath.
 Every provider declares its decision/generative kind. Consequence: not every model can satisfy this contract
 reliably; compatibility and quality must be tested separately.
 
+Extraction and Live are dedicated operations. Clairic keeps its native fields
+and predictive response envelope; Live attaches commands and events to an
+application-owned connection. Each has its own API and result contract, separate
+from the bridge's `evaluate` interface.
+
 ## ESM JavaScript with declarations and no runtime dependencies
 
 Use standard fetch, streams, and JSON in the SDK; keep Node's test runner,
@@ -30,13 +35,26 @@ calibration or correctness.
 
 ## Fail explicitly instead of silently repairing or falling back
 
-Reject invalid JSON, extra fields, wrong labels, distributions outside the provider
-precision allowance, explicit output truncation, and refusals. Require explicit
+Decision calls reject invalid JSON, unsupported request fields, wrong labels,
+distributions outside the provider precision allowance, malformed results and
+refusals; generative paths also reject explicit output truncation. Require explicit
 output modes and models. Services may truncate input without reporting it; local
 byte limits do not guarantee token fit. Consequence:
 some calls fail that a permissive wrapper might guess at, but failures remain
 observable and cannot silently change budgets or decision policies.
 
+Clairic preserves additional safe native JSON and its truncation flag. Live
+preserves native refusal events and marks ambiguous correlation as unmatched.
+Those operation contracts avoid inventing success or discarding native evidence.
+
+## Service admission and client resources
+
+The server owns quotas, rate limits, service counts, context admission and media
+ceilings. Report rejection through safe structured errors; do not estimate tokens,
+track account allocations, split requests or schedule service capacity. Local
+byte/JSON safeguards, cancellation, deadlines and caller-selected concurrency
+bound client resources. Custom-provider quantitative contracts remain explicit.
+
 ## Trusted extensions and explicit configuration
 
 Read JSON config only when named. Load custom ESM only when explicitly selected.

package/docs/development/RELEASING.md

@@ -30,8 +30,10 @@ node scripts/package-smoke.mjs --tarball release/fayegram-ai-decision-bridge-VER
 Check public documentation against the implementation, including supported API
 shapes, examples, limits, errors, and service compatibility notes. Inspect the MIT
 copyright notice and package contents. Complete hosted checks relevant to changed
-features using an authorized account/runtime;
-fixture and declaration checks do not establish hosted binding/Gateway behavior.
+features only when needed to resolve a specific wire-contract uncertainty, using
+an explicitly authorized account/runtime. Offline fixtures are sufficient for
+routine development and CI; fixture and declaration checks do not establish
+hosted binding/Gateway/Live behavior. Report the actual verification scope.
 Keep completed verification evidence separate from maintained consumer guidance.
 These content and verification checks do not depend on publication account setup.
 
@@ -49,7 +51,9 @@ name and registry are `@fayegram-ai/decision-bridge` and the public npm registry
 Coordinate the GitHub source release and publication of the verified tarball to
 npm as one release. The source release commit and archive must contain the same
 intended files, including README and documentation. A packed or uploaded archive
-is a snapshot: subsequent source edits do not change its contents.
+is a snapshot: subsequent source edits do not change its contents. Finalize the
+changelog and version-availability notices before building. If packaged files
+change afterward, rebuild and verify the archive before publication.
 
 The tracked `.npmrc` routes this scope to npm in this checkout without changing
 the user's npm configuration. Keep credentials in the user configuration, never

package/docs/development/REPOSITORY_LAYOUT.md

@@ -15,6 +15,8 @@ package-lock.json          Pinned development dependency metadata
 .env.example               Provider credential placeholders
 src/                       Common SDK, native providers, CLI, declarations
 src/custom/                Explicit decision definitions and generative presets
+src/extraction/            Dedicated Clairic provider, validation, batches and types
+src/live/                  Supplied-connection Live controller, protocol state and types
 bin/                       Node.js CLI entry point
 examples/                  Native SDK examples and request profiles
 examples/custom/           Opt-in generative and native delegation examples

package/docs/development/TESTING.md

@@ -16,7 +16,7 @@ Source and installed-consumer type checks use the same local compiler.
 | `npm test` | SDK, CLI, provider, and file/transport behavior using fixtures and loopback servers |
 | `npm run test:coverage` | The functional suite with production source/bin coverage floors |
 | `npm run typecheck` | Positive and expected-negative TypeScript API contracts |
-| `npm run test:package` | Pack, offline install, root/custom exports and types, browser-safe imports, presets/modules, contents and docs |
+| `npm run test:package` | Pack, offline install, root/custom/extraction/Live exports and types, browser-safe imports, presets/modules, contents and docs |
 | `npm run build` | Retain a versioned npm tarball after checking its offline installation |
 | `npm run verify` | Source checks, tests, type contracts, and package smoke check |
 
@@ -44,6 +44,11 @@ as evidence that every environment passed.
 - `result-validation.test.mjs`: provider-selected precision and policy-hook boundaries.
 - `decisions*.test.mjs`: native/common OpenAI codecs, selectors and model identities, boundaries, preflight, CLI, and smoke-helper fixtures.
 - `cloudflare*.test.mjs`: models, images, codecs, REST/binding/Gateway arguments, errors, and CLI limits.
+- `jev*.test.mjs`: native/common assets, reference substitution, boxes, opt-ins, nullable usage and CLI behavior.
+- `capability-expansion.test.mjs`: conversation/tool history, remote images, cache controls, extension revalidation, service-limit ownership and safe rejection diagnostics.
+- `extraction.test.mjs`: all nine Clairic field families, native JSON preservation, REST/binding options, batch preflight and model-selection diagnostics.
+- `live.test.mjs`: commands/acknowledgements, configuration history, transcript ordering, unmatched/stale/duplicate results, observer isolation and lifecycle cleanup.
+- `expansion-cli.test.mjs`: extraction commands/configuration, offline Live validation/replay, per-row errors and provider-switch isolation.
 - `custom-providers.test.mjs`, `custom-config.test.mjs`: classified SDK paths, provenance, presets/modules, schema and initialization.
 - `generative-helpers.test.mjs`: exported prompt/normalization helper contracts and unsupported input rejection.
 - `config.test.mjs`: file/environment/flag precedence and provider transitions.
@@ -54,6 +59,7 @@ as evidence that every environment passed.
 - `types.mts`, `providers.types.mts`, `custom.types.mts`: public type inference and rejected API usage.
 - `decisions.types.mts`, `cloudflare.types.mts`: richer questions, native APIs, and precision settings.
 - `cloudflare-worker.types.mts`: compatibility with official Workers binding declarations.
+- `expansion.types.mts`: conversation/cache inputs, extraction value inference, unions, batches and Live transport/notification contracts.
 
 Node's reported test count includes each row of a parameterized input table. It
 is not a count of independent features; retain separate rows when they protect
@@ -85,6 +91,23 @@ the complete integration check. A selector mapping change must be verified again
 the target model's protocol and capabilities; local fixtures alone do not establish
 compatibility with a newly selected upstream model.
 
+### Capability expansion coverage
+
+For changes across expanded OpenAI input, Clairic or Live, use the existing
+functional fixtures and declaration checks. A focused source-root command is:
+
+```text
+node --test test/capability-expansion.test.mjs test/extraction.test.mjs test/live.test.mjs test/expansion-cli.test.mjs
+npm run typecheck
+```
+
+REST doubles and binding doubles verify inference/execution option separation and
+safe upstream errors. Live uses a supplied in-memory connection adapter and the
+same state reducer as offline replay. No test intentionally exhausts service
+quotas or treats accepted local structure as hosted admission. Installed-package
+checks exercise the dedicated exports, CLI tools, declarations and SDK imports
+without Node globals.
+
 ## Optional authenticated provider smoke check
 
 Live inference is explicitly opted in and can incur charges. Configure credentials
@@ -132,13 +155,18 @@ Header/dimension preflight does not fully decode images, so live image fixtures
 must also contain valid encoded image data.
 Omni fixtures must contain genuinely decodable WAV/MP3 and MP4/WebM media for
 hosted tests. Local authored container fixtures verify inspection and protocol
-behavior without claiming codec validity. Include grouped modalities, duration
-and size boundaries, effective-model overrides, request bodies above 13 MiB,
+behavior without claiming codec validity. Cover grouped modalities, container
+validity, configured client byte budgets, effective-model overrides, request bodies above 13 MiB,
 and explicit smaller ceilings. Gateway caching/logging should be disabled for
 test payloads, and each bounded run should have a request and total time budget.
 
 The SDK, CLI, and ordinary checks do not create Workers or Gateways. Provisioning
 and cleanup belong to the application's separately authorized environment setup.
+The smoke helper does not qualify Clairic or a GPT-Live connection. When a specific
+wire-contract uncertainty requires hosted verification, use the intended
+application-owned runtime/connection and a bounded, explicitly authorized case.
+Offline fixtures remain sufficient for routine development and CI; record hosted
+behavior only when that exact path was exercised.
 
 ## Package verification
 

package/docs/guides/BROWSER.md

@@ -6,6 +6,11 @@ The SDK exports browser-compatible ESM. Follow the
 optional `decision-bridge` command still requires Node.js.
 Omni's embedded audio/video validation is browser-safe and adds no runtime media
 library. Build data URLs in the application; the SDK does not fetch remote media.
+The dedicated [extraction](EXTRACTION.md) and [Live](LIVE_DECISIONS.md) exports
+also use browser-compatible APIs. Clairic REST still requires provider CORS and
+explicit credentials. Live attaches to an already established application-owned
+connection; it does not create or authenticate one. OpenAI remote-image URLs are
+forwarded to the provider without a browser-side SDK fetch.
 
 Built-in REST providers need explicitly supplied credentials in browser code;
 Node environment-variable defaults and `.env` files are not available. Cloudflare

package/docs/guides/CLOUDFLARE_DECISIONS.md

@@ -16,8 +16,7 @@ short selectors and full forms.
 Questions and media consume context before text state; the service truncates
 remaining text state to fit. Requests whose questions/media exhaust context can
 fail. Byte checks cannot guarantee token fit or detect remote truncation.
-Clef's serving improvements and Clef-flash's lower pricing apply upstream without
-client configuration. Consult the official [model pages](#official-references)
+Consult the official [model pages](#official-references)
 for current pricing and availability; the bridge does not discover account access.
 
 ## Supported inference paths
@@ -108,7 +107,7 @@ extensions and the bridge's separate total deadline.
 
 ## Embedded images and limits
 
-Clef accepts up to four embedded PNG, JPEG, or WebP images. Native `images` entries
+Clef accepts embedded PNG, JPEG, or WebP images; the service owns count admission. Native `images` entries
 can be base64 data URLs or `{ content_type, base64 }` objects. Remote URLs are
 rejected. Common ordered input places all images before all text:
 
@@ -130,24 +129,15 @@ Text parts concatenate exactly, without inserted separators. Image detail can be
 omitted, `null`, or `auto`; explicit `low`, `high`, and `original` are unsupported.
 Safety identifiers are unsupported by this provider.
 
-| Boundary | Limit |
-| --- | --- |
-| Questions per request | 1–64 |
-| Question IDs | 1–100 ASCII letters, digits, `_`, `.`, or `-` |
-| Choice options | 2–255 |
-| Score levels | 2–10, ordered lowest first, indexed from zero |
-| Images | At most four |
-| Decoded image size | 4 MiB each; 8 MiB combined |
-| Image dimensions | Positive dimensions; at most 16 million pixels each |
-| Serialized request | Clef/Clef-flash: at most 13 MiB; Omni: 36 MiB by default, configurable through 64 MiB |
-
-Preflight checks supported formats, base64 syntax, headers, dimensions, and size.
-Header inspection is not full image decoding; the service can reject corrupt image data.
-Limits include execution options and binding envelope overhead. Omni's 36 MiB
-default is a bridge policy allowing base64 expansion of the permitted decoded
-media; its published schema specifies no whole-request byte ceiling. The effective
-request model selects the budget, including per-call overrides. An explicit
-`maxRequestBytes` remains a caller ceiling and is never enlarged by selecting Omni.
+Preflight validates supported representations, canonical base64, positive image
+dimensions and container structure. Service question/media counts, decoded sizes,
+dimensions, duration and context ceilings are not enforced locally. Header
+inspection is not full decoding; upstream admission and decoding remain authoritative.
+
+Client request budgets default to 13 MiB for Clef/Clef-flash and 36 MiB for Omni.
+An explicit `maxRequestBytes` overrides either default through the shared 64 MiB
+client ceiling. Binding envelope overhead counts toward that budget. Response
+budgets remain separate. No automatic resizing, splitting or truncation occurs.
 
 Cloudflare's four-decimal probability precision receives a count-aware sum
 allowance: the larger of 0.001 and half a decimal unit per option, plus floating-point
@@ -204,19 +194,10 @@ audio/video parts accept only `type` and `dataUrl`; remote URLs, paths, image
 detail, and caller-provided durations are rejected. Other providers and the older
 Clef models reject audio/video before dispatch.
 
-| Media | Count | Decoded size per item | Duration per item |
-| --- | ---: | ---: | ---: |
-| Audio | 4 | 8 MiB | 300 seconds |
-| Video | 2 | 16 MiB | 60 seconds |
-
-Audio and video together are limited to 16 MiB decoded. Image limits above remain
-separate. Bounded inspectors validate canonical base64, MIME/header consistency,
-and container structure, and reject excessive duration when PCM/float WAV,
-ordinary MP3 frames, MP4 metadata, or WebM metadata establishes it reliably.
-Full decoding, codec validity, and duration that cannot be established locally
-(including compressed WAV, free-format MP3, or missing container duration) remain
-service validation. The bridge performs no transcription, transcoding, frame
-extraction, or streaming, and adds no runtime media dependency.
+Inspectors validate canonical base64, MIME/header consistency and supported
+container structure. Service count, decoded-size and duration limits are handled
+as upstream errors. The bridge performs no transcription, transcoding, frame
+extraction or streaming, and adds no runtime media dependency.
 
 Cloudflare samples video at two frames per second. Video soundtracks are processed
 only when **every supplied video has a soundtrack**. Common results use
@@ -302,23 +283,20 @@ binding sends Gateway settings in the third `ai.run()` argument.
 
 | Setting | Accepted value |
 | --- | --- |
-| `id` | Required nonblank printable ASCII string, 1–64 characters |
-| `cacheKey` | Optional nonblank printable ASCII string, 1–200 characters |
-| `cacheTtl` | Integer seconds, 60–2,592,000 (30 days) |
+| `id` | Required nonblank printable ASCII string |
+| `cacheKey` | Optional nonblank printable ASCII string |
+| `cacheTtl` | Nonnegative integer seconds; service cache policy applies upstream |
 | `skipCache`, `collectLog` | Optional booleans |
-| `metadata` | At most five entries with JSON primitive values; caller-supplied `cf.*` keys are reserved |
+| `metadata` | JSON primitive values; caller-supplied `cf.*` keys are reserved |
 | `requestTimeoutMs` | Positive integer milliseconds, up to 2,147,483,647 |
-| `retries.maxAttempts` | 1–5; defaults to 1 when Gateway is configured |
-| `retries.retryDelayMs` | 0–60,000 milliseconds |
+| `retries.maxAttempts` | Positive integer; defaults to 1 when Gateway is configured |
+| `retries.retryDelayMs` | Nonnegative integer milliseconds |
 | `retries.backoff` | `constant`, `linear`, or `exponential` |
 
 The shared validator rejects invalid Gateway settings with `CONFIGURATION_ERROR`
-before dispatch. Metadata is preserved unchanged: the bridge rejects entries
-that [Cloudflare would ignore or remove](https://developers.cloudflare.com/ai-gateway/observability/custom-metadata/)
-instead of silently dropping them. Cloudflare's [cache TTL documentation](https://developers.cloudflare.com/ai-gateway/features/caching/)
-describes the upper limit as one month; its [official numeric reference](https://github.com/cloudflare/skills/blob/0cb6116228ad153126f474dce1dfbd05f7944604/skills/cloudflare/references/ai-gateway/README.md)
-specifies 2,592,000 seconds (30 days). Cache TTL and first-response timeout have
-separate validation bounds.
+before dispatch. Metadata is preserved unchanged. Reserved `cf.*` keys and
+non-primitive values are rejected; service entry-count and cache admission
+limits remain upstream. The adapter does not infer Gateway acceptance.
 
 Gateway timeout covers time to the first response; the bridge's total deadline
 continues to bound the call. Gateway logging/caching follows the explicit options

package/docs/guides/CUSTOMIZATION.md

@@ -1,6 +1,7 @@
 # Customizing decisions and extending the bridge
 
-Customization is **per request**. You supply context in `state`, the judgment in
+Customization is **per request**. You supply context in `state`, ordered `input`
+or `conversation` according to provider capabilities, the judgment in
 `instructions`, and the allowed categories/rubric in `criteria`. The same bridge
 instance can evaluate unrelated tasks on successive calls. This changes the
 question sent to the existing model, not its weights or account configuration.
@@ -79,6 +80,10 @@ const bridge = createBridge({
 Extensions run in registration order. They receive immutable snapshots and must
 return replacements rather than mutate input. Async retrieval can use the supplied
 context signal. No content is persisted unless your extension explicitly saves it.
+Use `prepareInput(parts, context)` for ordered input and
+`prepareConversation(items, context)` for conversation history. A preparation
+extension must implement the selected form's hook; transformed content is
+revalidated before dispatch. Observer-only extensions work with every form.
 
 ## Observe without changing decisions
 
@@ -133,7 +138,8 @@ and [SDK validation contract](../reference/SDK.md#additional-exports).
 
 ## Develop additions without changing the public call
 
-Add retrieval/redaction through `prepareState` or `prepareInput`, metrics through
+Add retrieval/redaction through `prepareState`, `prepareInput` or
+`prepareConversation`, metrics through
 `onResult`, and another protocol through the explicit [custom decision](CUSTOM_DECISION.md)
 or [custom generative](CUSTOM_GENERATIVE.md) contract. Keep routing/threshold policies
 outside the provider and cover additions with relevant regression tests. Persisted templates,