@fayegram-ai/decision-bridge 0.0.0-stage → 0.1.0

package/docs/reference/CLI.md

@@ -0,0 +1,202 @@
+# 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).
+
+After [installing the package](../guides/GETTING_STARTED.md#install-into-your-application)
+in your project, run:
+
+```bash
+npm exec -- decision-bridge --help
+npm exec -- decision-bridge validate
+```
+
+The examples below use `decision-bridge` as shorthand: prefix it with `npm exec --`
+for a local installation, use it directly after a global installation, or replace
+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
+explicit provider for the SDK; `createBridge` itself has no implicit selection.
+Use the root README's [model list](../../README.md#supported-models) to select a
+supported native model. Custom generative presets require an explicit model ID.
+
+## Commands
+
+`--provider openai-decisions` selects OpenAI Decisions; `--provider cloudflare-decisions`
+selects Clef. Add `--native`
+for native request/response structures on `init`, `evaluate`, `validate`, or
+`batch`; input mode is never inferred. Native calls require an explicit input file
+or `-`. See [OpenAI Decisions](../guides/OPENAI_DECISIONS.md) and
+[Cloudflare Clef](../guides/CLOUDFLARE_DECISIONS.md) for examples. Both providers report
+model listing as unsupported.
+Cloudflare CLI execution uses REST. The Workers AI binding is an SDK transport;
+there is no CLI binding selector. Gateway settings route the selected REST request.
+
+| Command | Behavior |
+| --- | --- |
+| `init [DIRECTORY]` | Create config and schema, sample request, environment template, and gitignore; generate a custom module when needed; never overwrite |
+| `evaluate [FILE\|-]` | One evaluation; aliases `eval` and `ask` |
+| `validate [FILE\|-]` | Validate input locally; does not call a provider |
+| `schema [FILE\|-]` | Print the generative response schema for these questions; local only |
+| `models` | List the configured provider's models; may be paginated |
+| `batch FILE\|-` | Stream JSONL inputs and ordered JSONL result/error records |
+
+No input filename on `evaluate`, `validate`, or `schema` selects the bundled sample,
+not stdin. Use `-` explicitly for stdin. Empty invocation prints help. Configuration
+and credential errors do not cause fallback to another backend.
+
+```bash
+cat request.json | decision-bridge evaluate - --env-file .env --compact
+decision-bridge evaluate request.json --env-file .env --output result.json
+decision-bridge batch requests.jsonl --env-file .env --concurrency 4 --output results.jsonl
+```
+
+On PowerShell, `Get-Content -Raw request.json | decision-bridge evaluate - --env-file .env`
+is an alternative for stdin. File arguments avoid shell encoding differences.
+
+## Custom initialization
+
+```bash
+decision-bridge init ./my-model --provider custom-generative --preset openrouter --model VENDOR/MODEL_ID
+decision-bridge init ./my-service --provider custom-decision
+decision-bridge init ./my-protocol --provider custom-generative
+```
+
+Preset initialization writes a ready-to-configure profile and credential
+placeholders. An unselected custom implementation writes `provider.mjs` with an
+explicit service implementation error until you connect it. An existing
+`--provider-module` is referenced without execution or overwrite. All profiles
+include a copied JSON Schema for editor validation. See [custom providers](../guides/CUSTOM_PROVIDERS.md).
+
+## Flags
+
+| Flag | Meaning |
+| --- | --- |
+| `--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` |
+| `--preset NAME` | custom-generative preset: `openai-compatible`, `openrouter`, or `anthropic`; exclusive with module |
+| `--native` | Explicit native Decisions input/output; init/evaluate/validate/batch only |
+| `--model ID` | Overrides input JSON model and provider default |
+| `--base-url URL` | Custom endpoint; requires explicit credential selection |
+| `--api-key-env NAME` | Environment variable name, never the key itself |
+| `--account-id ID` | Cloudflare REST account ID |
+| `--reject-if-busy`, `--no-reject-if-busy` | Explicit Cloudflare native-request override. Enabling fails local REST preflight with `UNSUPPORTED_CAPABILITY`; disabling permits ordinary inference. See the [REST limitation](../guides/CLOUDFLARE_DECISIONS.md#capacity-rejection-and-ai-gateway) |
+| `--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 |
+| `--retries N` | Additional eligible HTTP attempts; 0–10; native OpenAI/Cloudflare default to 0, Jev and generative presets to 2 |
+| `--max-tokens N` | Generative output budget; default 4096 |
+| `--response-format MODE` | `json_schema`, `json_object`, or `text`; compatible generative presets only |
+| `--token-parameter NAME` | `max_completion_tokens` or `max_tokens` |
+| `--provider-module FILE` | Explicit trusted ESM module; requires custom-decision or custom-generative |
+| `--input FILE` | Alternative to positional request filename |
+| `--output FILE`, `-o FILE` | Atomic file output; `-` means stdout |
+| `--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 |
+| `--help`, `-h`, `--version`, `-v` | Informational commands |
+
+Unknown or duplicate flags fail. Provider-inapplicable flags fail instead of being
+ignored. `--model` wins over request.model; otherwise request.model wins over the
+configured model. See [configuration](CONFIGURATION.md) for full precedence.
+
+## JSON output contract
+
+Single evaluation stdout is exactly the result object plus a newline. It is not
+wrapped in a progress log or Markdown. Errors are `{ "error": { "code", "message",
+... } }` on stderr. No debug stacks or raw HTTP error bodies are printed.
+
+Native Decisions output is `{ decision, meta }`. OpenAI refused questions fail the
+complete evaluation, with allowlisted refusal diagnostics and validated usage.
+
+Common results include `meta.providerKind` from the provider contract. Offline
+`validate` requires no credentials and never imports custom modules. Its JSON
+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.
+
+A batch emits one compact record per nonblank input line:
+
+```text
+{"line":1,"ok":true,"result":{...}}
+{"line":2,"ok":false,"error":{"code":"VALIDATION_ERROR","message":"..."}}
+```
+
+This is a schematic shape, not an inference example. `line` is the original
+one-based physical line number, including blank lines in the numbering. Blank
+lines produce no record. Malformed JSON on a single line is a failed record and
+processing continues. Evaluation failures likewise remain explicit records.
+
+The CLI streams input with a bounded, ordered window. A completed oldest result
+is emitted even when stdin remains open and the producer has not sent another
+line; the window does not have to fill before output begins. A slow earlier request can
+hold back emission and dispatch even when later requests finish; this prioritizes
+bounded memory and stable ordering over maximum throughput. Up to `concurrency`
+requests may already be running when a failure is encountered. There is no CLI
+`stopOnError` flag; the SDK array batch API provides that policy.
+
+Invalid UTF-8, input-size violations, unreadable input, or interrupted execution are
+global failures. Work already sent to a provider may have been billed. Do not assume
+that a failed batch sent no requests: unlike the SDK array API, streaming CLI input
+is not entirely prevalidated before execution.
+
+## Exit codes
+
+| Code | Meaning |
+| --- | --- |
+| 0 | Success; also a closed downstream pipe (EPIPE) |
+| 1 | Provider/evaluation failure or at least one failed batch record |
+| 2 | Usage, input, configuration, or filesystem failure |
+| 130 | Caller interruption/cancellation, including handled SIGINT/SIGTERM |
+
+Both signals are handled as cancellation by this CLI; it intentionally does not
+use 143 for SIGTERM. Cancellation also interrupts a blocked stdout write. The
+POSIX subprocess SIGINT check is excluded on Windows, where console signal
+delivery needs separate validation.
+
+## I/O and resource limits
+
+Single JSON input: **8 MiB**. JSONL: **8 MiB per line, 64 MiB total**. 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
+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.
+
+Per-line limits exclude LF or CRLF delimiters, regardless of stream chunking.
+A final record may omit its newline; its complete bytes must still fit the limit.
+The total input limit includes delimiters.
+
+Output files are written to a same-directory exclusive temporary file with mode
+0600, synced, then committed. Existing paths are protected unless `--force` is
+explicit. A batch containing ordinary failed records still produces a complete
+JSONL file and exits 1. A global failure removes the unfinished temporary output.
+Stdout cannot be rolled back and may contain a valid prefix after interruption.
+No parent output directories are created automatically. Filesystems without hard
+link support can reject no-clobber finalization; the error is explicit. File mode
+and atomic filesystem semantics remain operating-system/filesystem dependent.
+
+## Input and cancellation boundaries
+
+String-valued flags cannot be empty or whitespace-only, including `--config`,
+`--env-file`, `--input` and `--output`. Such values return `USAGE_ERROR` before
+configuration loading or paid calls, rather than selecting an unintended default.
+Valid paths with embedded spaces remain supported.
+
+The input/output check resolves existing paths and file identities, so directory
+symlinks/junctions and hard-link aliases cannot bypass the input-overwrite guard.
+This is an accidental-overwrite safeguard, not a filesystem sandbox against
+another process racing to change paths.
+
+Already-cancelled CLI work does not initialize a project or create an output file.
+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.

package/docs/reference/CONFIGURATION.md

@@ -0,0 +1,168 @@
+# Configuration and credentials
+
+## Explicit CLI JSON configuration
+
+```json
+{
+  "$schema": "./decision.config.schema.json",
+  "schemaVersion": 1,
+  "provider": "jev",
+  "model": "jev-latest",
+  "apiKeyEnv": "TYPESAFE_API_KEY",
+  "timeoutMs": 30000,
+  "maxRetries": 2
+}
+```
+
+Load it with `--config path/to/decision.config.json`. The CLI never scans a working
+directory for executable configuration. It does not read `.env` implicitly; use
+`--env-file .env`. Runtime SDK configuration uses constructor options instead.
+
+Jev is the CLI's built-in provider default. In SDK code, `createBridge` requires
+an explicit `provider` or `jev` selection, and `createProvider` requires `type`.
+Provider-specific model defaults apply after that selection. Root SDK selection
+is native-only. Generative presets use `createGenerativeProvider` from the
+`custom/generative` subpath. CLI custom modules declare their kind explicitly.
+
+`init` copies the configuration JSON Schema beside the generated config and adds
+`$schema` for editor completion. The packaged schema is available at
+`@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.
+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.
+
+| 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` |
+| `preset` | `custom-generative` only: `openai-compatible`, `openrouter`, `anthropic`; mutually exclusive with module |
+| `model` | Nonempty model ID; built-in native providers have defaults; required for generative evaluation unless the request supplies it |
+| `baseURL` | HTTPS API base; loopback may use HTTP |
+| `apiKeyEnv` | Credential environment variable name; inline `apiKey` is rejected |
+| `noAuth` | Boolean; true only for loopback OpenAI-compatible endpoints |
+| `timeoutMs` | Positive integer up to 2,147,483,647 milliseconds |
+| `maxRetries` | Integer 0–10; OpenAI/Cloudflare default 0; Jev and generative presets default 2 |
+| `maxRequestBytes`, `maxResponseBytes` | Positive integer through 64 MiB; default 8 MiB. Cloudflare requests: Clef/Clef-flash default/cap 13 MiB; Omni default 36 MiB, configurable through 64 MiB |
+| `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) |
+| `gateway` | Cloudflare Gateway object; see the [Cloudflare guide](../guides/CLOUDFLARE_DECISIONS.md) |
+| `maxTokens` | Generative output budget, 1–1,048,576; default 4096 |
+| `responseFormat` | Compatible generative presets: `json_schema`, `json_object`, `text` |
+| `tokenParameter` | Compatible generative presets: `max_completion_tokens` or `max_tokens` |
+| `parameters` | Extra JSON generation parameters, excluding bridge-controlled fields |
+| `module` | Required for custom-decision; alternative to preset for custom-generative; explicit local ESM file |
+| `options` | Custom factory's JSON options, e.g. its own baseURL |
+
+Upper numeric limits validate client configuration, not vendor model capabilities.
+Cloudflare selects its byte budget from the effective request model, including
+per-call overrides. An explicit smaller `maxRequestBytes` remains the ceiling;
+selecting Omni cannot enlarge it. Omni's default is a bridge policy, not a
+documented whole-request service guarantee.
+Provider-specific unused fields are rejected. In a module profile, transport and
+generation settings belong inside `options`; the custom factory owns them. Top-level
+`timeoutMs` still bounds the bridge. The module may implement its own networking.
+
+`parameters` cannot override model, messages, system instructions, schemas, tools,
+streaming, token-limit fields, or credentials. Legacy `functions` and
+`function_call` controls are also reserved. Unrecognized model-specific
+parameters may be rejected by the server; they are not silently dropped by us.
+
+## Precedence
+
+For provider/configuration settings:
+
+```text
+CLI flags > DECISION_* environment variables > explicit JSON file > defaults
+```
+
+For credentials loaded from an explicit environment file:
+
+```text
+existing process environment > --env-file values
+```
+
+The loader does not mutate the process environment. The SDK independently reads
+its documented ambient credential variables at provider construction.
+
+The [supported-model list](../../README.md#supported-models) records native
+selectors, aliases and defaults. Configuration precedence does not expand a
+provider's accepted models or grant account access.
+
+For evaluation model selection:
+
+```text
+--model > request.model > resolved config/environment model > provider default
+```
+
+Jev defaults to `jev-latest`, with `JEV_MODEL` as a legacy/direct convenience.
+Native OpenAI Decisions defaults to `gpt-6-luna`; it accepts transport settings
+and rejects generative output settings. Its default retry count is zero. Cloudflare Clef defaults to `clef`, uses
+account/token credentials, rejects generation settings, and also defaults to zero retries.
+A `DECISION_MODEL` or file model takes precedence over that convenience.
+Custom generative presets and modules do not inherit a
+Jev model. Offline validation of a generative/module request without a model reports
+`model: null`; evaluation requires a request model or provider default.
+
+Each layer is merged separately. Changing provider, preset, or module at a layer
+boundary discards all lower-layer implementation settings: endpoint, key selector,
+model, generation parameters, transport retries/byte limits, preset/module/options,
+and Cloudflare account/busy/Gateway settings. Only `timeoutMs` is shared. This
+prevents stale credentials and protocol options crossing implementation boundaries.
+Same-implementation overrides retain compatible settings. Supply new settings
+explicitly when switching. A module-to-preset or preset-to-module switch clears
+the old selector. Module identity uses the resolved file path: a file-relative
+module and a working-directory-relative flag retain settings only when both
+identify the same file.
+
+## Recognized environment variables
+
+| Variable | Purpose |
+| --- | --- |
+| `TYPESAFE_API_KEY` | Native Jev credential |
+| `OPENAI_API_KEY` | Native Decisions and OpenAI-compatible credential at the OpenAI origin |
+| `OPENROUTER_API_KEY` | OpenRouter credential |
+| `ANTHROPIC_API_KEY` | Anthropic credential |
+| `CLOUDFLARE_ACCOUNT_ID` | Cloudflare REST account ID |
+| `CLOUDFLARE_API_TOKEN` | Cloudflare REST token at the official origin |
+| `DECISION_ACCOUNT_ID` | CLI Cloudflare account selection |
+| `DECISION_REJECT_IF_BUSY` | CLI Cloudflare busy mode; literal `true` or `false` |
+| `DECISION_GATEWAY_ID` | CLI Cloudflare Gateway ID |
+| `JEV_MODEL` | Native Jev default model convenience |
+| `DECISION_PROVIDER` | CLI provider selection |
+| `DECISION_PRESET` | CLI custom-generative preset selection |
+| `DECISION_MODEL` | CLI configured model |
+| `DECISION_BASE_URL` | CLI explicit endpoint |
+| `DECISION_API_KEY_ENV` | CLI credential variable selector |
+| `DECISION_TIMEOUT_MS` | CLI timeout, decimal integer |
+| `DECISION_MAX_RETRIES` | CLI retry count, decimal integer |
+| `DECISION_RESPONSE_FORMAT` | CLI compatible output mode |
+
+`RUN_LIVE_TESTS=1` applies only to the explicit development smoke helper.
+No background access or live testing is enabled by normal test commands.
+
+## Custom endpoint credential boundary
+
+A CLI `baseURL` always requires explicit `apiKeyEnv`, even when it happens to equal
+a preset origin, or `noAuth: true` for loopback compatible servers. This makes the
+credential destination a deliberate selection. OpenRouter's preset origin cannot
+be changed; use the `openai-compatible` custom-generative preset for a different gateway.
+
+In SDK constructors, an ambient key is used only for the provider's original
+origin. A caller-supplied third-party origin requires an explicit `apiKey`.
+`apiKey: null` disables authentication only for OpenAI-compatible loopback URLs.
+Credentials in URL userinfo, query strings, or fragments are rejected. Redirects
+are not followed. These protections are not an SSRF sandbox: applications that
+accept untrusted endpoint configuration must enforce their own destination policy.
+
+## Profiles
+
+See [examples/configs/](../../examples/configs/) for native profiles, generative
+presets, and separate custom decision/generative modules. Use
+`--provider custom-generative --preset NAME` for a preset, or select a custom kind
+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.

package/docs/reference/ERRORS.md

@@ -0,0 +1,82 @@
+# Errors and recovery
+
+`DecisionError` extends `Error` and exposes `code`, optional `status`, `requestId`,
+`gatewayLogId`, `attempts`, and numeric `upstreamCode` for Cloudflare diagnostics.
+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
+providers deliberately constructing `DecisionError` must keep its message safe.
+
+| Code | Meaning and response |
+| --- | --- |
+| `DECISION_ERROR` | Generic code for a deliberately constructed DecisionError without a more specific code |
+| `CONFIGURATION_ERROR` | Invalid/unknown option, missing credential, incompatible provider setting, or invalid endpoint; fix configuration |
+| `VALIDATION_ERROR` | Invalid request/template/JSON; fix input before retrying |
+| `UNSUPPORTED_CAPABILITY` | Selected provider/model or preparation extension cannot support this request; fails before dispatch |
+| `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 |
+| `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 |
+| `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 |
+| `TIMEOUT` | Provider, bridge, preparation, or listing deadline exceeded |
+| `ABORTED` | Caller cancelled; remote work might already have been billed |
+| `INVALID_RESPONSE` | Non-byte response chunks, wrong envelope, or invalid UTF-8/JSON/schema/distribution/usage; do not trust partial answers |
+| `MODEL_REFUSAL` | Provider explicitly declined the evaluation; no fabricated result |
+| `TRUNCATED_OUTPUT` | Output/context budget exhausted; revise budget/input explicitly |
+| `EXTENSION_ERROR` | Preparation failed; inference was not issued after that failure |
+| `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 |
+| `UNEXPECTED_ERROR` | Unrecognized error sanitized for public output |
+
+## Retry policy
+
+OpenAI Decisions refusals include `refusedQuestions` and validated `usage`, plus
+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`
+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
+request. All
+attempts, backoff, and response-body reading share one timeout budget.
+
+`Retry-After` seconds or HTTP dates are honored. Without it, 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
+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.
+
+## Practical diagnosis
+
+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
+may still emit invalid probabilities or be routed through an incompatible endpoint.
+Change configuration deliberately and retest; do not disable local validation.
+
+Enabling busy execution options for Cloudflare Clef REST fails local preflight
+with `UNSUPPORTED_CAPABILITY`, without an HTTP status, upstream code, or dispatch.
+Direct calls to the hosted service were observed to reject that field with
+HTTP 422 and `upstreamCode: 5012`, distinct from capacity code 3040. Other upstream
+validation failures can still return HTTP 422/5012 and retain safe diagnostics.
+Keep the default disabled setting for ordinary REST
+inference; see the [Cloudflare guide](../guides/CLOUDFLARE_DECISIONS.md#capacity-rejection-and-ai-gateway).
+
+Keep a request ID and available Gateway log ID, bridge version, configured provider, requested/reported model,
+and template revision for incident analysis. Log input or results only under your
+own data-handling policy. No logging or telemetry is enabled by default.

package/docs/reference/PROVIDERS.md

@@ -0,0 +1,113 @@
+# Provider contracts and compatibility
+
+## Native routes
+
+| Provider type | Wire API | Credential | Default model | Output strategy |
+| --- | --- | --- | --- | --- |
+| `jev` | `POST /v1/systemone` at api.typesafe.ai | `TYPESAFE_API_KEY` | `jev-latest` | Native typed decisions |
+| `openai-decisions` | `POST /v1/decisions` at api.openai.com | `OPENAI_API_KEY` | `gpt-6-luna` | Native Decisions with common and dedicated access |
+| `cloudflare-decisions` | Workers AI REST model route or `AI.run` binding | `CLOUDFLARE_API_TOKEN` and account ID for REST | `clef` | Native Clef decisions with common and dedicated access |
+
+`createProvider()` and the root SDK export these three native providers only.
+Custom decision services use `defineDecisionProvider` from `custom/decision`.
+General-purpose adapters are opt-in presets in `custom/generative`; they are
+maintained, but are not native decision models. See [custom providers](../guides/CUSTOM_PROVIDERS.md).
+
+## Supported model selection
+
+See the root README's [model list](../../README.md#supported-models) for the
+built-in selectors and aliases. Jev accepts `jev-latest` and explicit Jev IDs from
+its account catalog. OpenAI Decisions supports only `gpt-6-luna` in this release.
+Cloudflare supports `clef`, `clef-flash`, and `clef-omni`, including each full
+`@cf/cloudflare/<model>` alias. Unsupported OpenAI/Cloudflare selectors fail
+local preflight with `UNSUPPORTED_CAPABILITY`.
+
+Custom generative presets require an explicit available model and have no default.
+Custom decision or generative modules define their own model/capability contract.
+Local model support is separate from account permission and hosted availability.
+
+The interface is model-neutral, not a guarantee that every model or endpoint
+supports every strategy. A compatible URL alone is insufficient: the chosen model
+must follow the decision instruction, fit the input/schema, and return valid data.
+Provider behavior is covered by local protocol tests and checked against official
+specifications. These checks do not establish compatibility with every account or
+model. Run the optional [live checks](../development/TESTING.md) for the provider,
+account, model, and transport you intend to use; see the protocol [sources](SOURCES.md).
+
+## Common request capabilities
+
+All native providers and custom generative presets accept the legacy shared-state and `choice` / `noul` / `score`
+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 | Unsupported | 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-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
+[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
+false/zero when omitted, preserving legacy custom profiles. Cloudflare's older
+models and all other shipped providers reject audio/video before inference.
+
+Dedicated `createDecision()` access is available on OpenAI Decisions and
+Cloudflare providers. It uses each service's native request/response shape and
+bypasses bridge preparation and observation hooks.
+
+## Native Jev
+
+The request directly contains `model`, shared `state`, and `questions`. Jev's
+`choice`, `noul`, and `score` results are preserved and strictly validated. No
+intermediate language model, skill, portal prompt, or chat conversion is used.
+`GET /v1/models` lists native models. A listed catalog can differ from valid aliases;
+`jev-latest` is the documented stable alias.
+
+Pin a version after evaluating it for your workload rather than assuming a moving
+alias yields reproducible quality. Store the returned `model` along with the
+requested model and your question-template revision.
+
+## Native OpenAI Decisions
+
+For the native Decisions endpoint, use `openai-decisions`; its capabilities,
+refusal policy, image input, and dedicated API are documented in the
+[OpenAI Decisions guide](../guides/OPENAI_DECISIONS.md). Native decision providers
+report native probabilities, with provider-specific confidence semantics.
+
+## Native Cloudflare Clef
+
+Use `cloudflare-decisions` for Clef, Clef-flash, and Clef-omni through REST or an injected
+Workers AI binding. Common and native access share validation and codecs. See the
+[Cloudflare guide](../guides/CLOUDFLARE_DECISIONS.md) for image/audio/video limits, structured
+content, typed values, rounding, capacity rejection, Gateway, and CLI examples.
+
+## Native versus elicited probabilities
+
+Jev, OpenAI Decisions, and Clef report native outputs and confidence. Generative models are prompted
+to produce probability distributions. Those estimates are not logprobs, repeated
+sampling frequencies, calibrated confidence, or proof of correctness.
+
+Generative providers derive an argmax choice and a probability-weighted score from the
+elicited distributions. They do not synthesize native confidence statistics. Both
+paths use the same application contract, but metadata records their provenance:
+`native` versus `elicited`. `meta.providerKind` separately records `decision` or
+`generative` from the provider contract. Classification does not force Jev's
+confidence/usage requirements on a custom decision service. Evaluate performance and calibration on representative
+labeled data before adopting thresholds or comparing costs/latencies.
+
+## Compatibility boundaries
+
+Remote context limits, JSON Schema limits, model availability, output budgets,
+pricing, and rate limits are provider/account specific. The bridge's local caps
+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.