@fayegram-ai/decision-bridge 0.1.0 → 0.1.2

package/CHANGELOG.md

@@ -2,6 +2,15 @@
 
 Notable user-facing changes by version.
 
+## 0.1.2
+
+- Add opt-in Jev images, typed bounding boxes, native JSON assets, and long context
+  across SDK and CLI, with capability preflight and nullable token usage.
+
+## 0.1.1
+
+- Add OpenAI `default`/`luna` selectors and requested/resolved model metadata; improve CLI configuration and documentation.
+
 ## 0.1.0
 
 Initial release of Decision Bridge as `@fayegram-ai/decision-bridge`.

package/README.md

@@ -29,7 +29,7 @@ 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.0 · Node.js 22.16+ or modern browsers (SDK) · ESM · zero runtime dependencies**
+**Version 0.1.2 · Node.js 22.16+ or modern browsers (SDK) · ESM · zero runtime dependencies**
 
 The npm package is
 [@fayegram-ai/decision-bridge](https://www.npmjs.com/package/@fayegram-ai/decision-bridge).
@@ -41,24 +41,30 @@ This is an independent project. The custom generative presets identify their
 probabilities as elicited model outputs.
 Changing providers does **not** make their accuracy or calibration equivalent.
 
-## Supported models
+## Model selectors
 
-The built-in decision providers support these model selectors in this release:
+Use these model selectors with the built-in decision providers:
 
-| Decision provider | Model selector | Accepted alias | Provider default |
-| --- | --- | --- | --- |
-| Jev through TypeSafe (`jev`) | `jev-latest` | — | `jev-latest` |
-| OpenAI Decisions (`openai-decisions`) | `gpt-6-luna` | — | `gpt-6-luna` |
-| Cloudflare (`cloudflare-decisions`) | `clef` | `@cf/cloudflare/clef` | `clef` |
-| Cloudflare (`cloudflare-decisions`) | `clef-flash` | `@cf/cloudflare/clef-flash` | — |
-| Cloudflare (`cloudflare-decisions`) | `clef-omni` | `@cf/cloudflare/clef-omni` | — |
+| Decision provider | Model selectors | Provider default |
+| --- | --- | --- |
+| Jev through TypeSafe (`jev`) | `jev-latest` | `jev-latest` |
+| OpenAI Decisions (`openai-decisions`) | `default`, `luna` | `default` |
+| Cloudflare (`cloudflare-decisions`) | `clef`, `@cf/cloudflare/clef` | `clef` |
+| Cloudflare (`cloudflare-decisions`) | `clef-flash`, `@cf/cloudflare/clef-flash` | — |
+| Cloudflare (`cloudflare-decisions`) | `clef-omni`, `@cf/cloudflare/clef-omni` | — |
 
-`jev-latest` is Jev's default alias. Jev also accepts explicit model IDs available through your TypeSafe account;
+`jev-latest` is Jev's default alias. Jev also accepts `jev-preview` and explicit model IDs available through your TypeSafe account;
 use `bridge.listModels()` or the CLI `models` command to inspect that catalog.
 The bridge does not maintain a static list of Jev versions. A moving alias or a
 catalog entry does not guarantee inference access or reproducible model quality.
-OpenAI Decisions currently accepts only `gpt-6-luna` in this integration.
-Cloudflare accepts only the three models above, in short or full-alias form.
+For OpenAI Decisions, `default` selects the provider default and `luna` selects
+the supported Luna-family model. Decision Bridge resolves selectors to supported
+upstream model IDs before calling the service. Mappings are fixed by the installed
+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.
 Model discovery is unsupported for OpenAI Decisions and Cloudflare.
 
 Additional decision protocols use [custom decision providers](docs/guides/CUSTOM_DECISION.md).
@@ -74,7 +80,7 @@ All native providers support shared state and the common `choice`, `noul`, and
 
 | Provider | Additional supported features | Guide |
 | --- | --- | --- |
-| Jev | Native decisions through the TypeSafe API | [Provider reference](docs/reference/PROVIDERS.md#native-jev) |
+| 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) |
 | 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) |

package/docs/README.md

@@ -7,8 +7,8 @@ Install `@fayegram-ai/decision-bridge` with npm; the
 [getting started guide](guides/GETTING_STARTED.md#install-into-your-application)
 also covers installation from a verified archive.
 The hosted playground is [Decision Playground](https://decision-pg.fayegram.com/).
-The root README lists [supported model selectors and aliases](../README.md#supported-models),
-including the distinction between built-in decision models and custom generative presets.
+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
@@ -17,7 +17,7 @@ validated, structured decisions.
 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 OpenAI and Cloudflare guides cover both.
+the Jev, OpenAI and Cloudflare guides cover both.
 
 ## Use the bridge
 
@@ -27,7 +27,8 @@ the OpenAI and Cloudflare guides cover both.
 | [Browser integration](guides/BROWSER.md) | Direct browser use, CORS requirements, and credential exposure |
 | [Platforms](guides/PLATFORMS.md) | Windows, macOS, and Linux setup |
 | [Switching models](guides/SWITCHING_MODELS.md) | Backend and model selection |
-| [OpenAI Decisions](guides/OPENAI_DECISIONS.md) | Native/common decision access, ordered images, typed values, and capability checks |
+| [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 |
 | [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 |
 | [Customization](guides/CUSTOMIZATION.md) | Questions, templates, extensions, and policies |
 | [Custom providers](guides/CUSTOM_PROVIDERS.md) | Common classified contract and explicit CLI module loading |

package/docs/development/ARCHITECTURE.md

@@ -5,7 +5,7 @@
 Decision Bridge exposes one application contract for structured decisions. The
 bridge owns request snapshots, common validation, extension sequencing, the total
 deadline, final result validation, immutable results, and bounded observations.
-A Provider owns its API encoding, transport, decoding, model defaults,
+A provider owns its API encoding, transport, decoding, model selection,
 capabilities, and native operations. Multiple models sharing a protocol can use
 one provider implementation.
 
@@ -38,7 +38,7 @@ Application / CLI
   application policy / storage / downstream action
 ```
 
-Native OpenAI and Cloudflare providers also expose `createDecision` directly.
+Native Jev, OpenAI and Cloudflare providers also expose `createDecision` directly.
 Common and native paths share provider validation, codecs, and bounded transport.
 Direct native calls use provider deadlines; bridge calls additionally enforce the
 shared evaluation deadline and extension lifecycle.
@@ -46,6 +46,26 @@ shared evaluation deadline and extension lifecycle.
 Application policy decides whether a downstream action is permitted. The SDK
 returns decisions without executing actions or maintaining an agent loop.
 
+## Model selection and request preparation
+
+The bridge applies the provider's configured default when a request omits `model`.
+Its validated request and extension context retain that selected string. A provider
+may resolve a selection to an upstream ID while preparing its outgoing request;
+the shared provider contract has no selector-resolution hook.
+
+OpenAI's `openai-profile.mjs` owns the `default` selection, accepted selectors,
+upstream targets, and capabilities. Common and native preparation retain the
+validated selection separately from the resolved native request. Preflight returns
+the selected request, while serialization and byte-limit checks use the resolved
+request. Common evaluation and native `createDecision()` share dispatch, which
+sends only that resolved request.
+
+Successful OpenAI calls report the selected string in `meta.requestedModel` and
+the outgoing ID in `meta.resolvedModel`. The response's `model` retains the
+service-reported identity. CLI offline validation and execution use the same
+preflight, and generated OpenAI requests inherit selection from configuration.
+See [OpenAI model selection](../guides/OPENAI_DECISIONS.md#model-selection).
+
 ## Module map
 
 | Module | Responsibility |
@@ -61,6 +81,8 @@ returns decisions without executing actions or maintaining an agent loop.
 | `src/custom/generative/` | Opt-in protocol presets, schema, prompts, and result derivation |
 | `schemas/decision.config.schema.json` | Shipped CLI configuration structure and editor support |
 | `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/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 |
@@ -81,7 +103,8 @@ claiming equivalent statistical semantics across models.
 
 The bridge takes result-validation policy from the provider contract. Cloudflare
 uses an allowance for four-decimal distributions; other built-ins retain the
-baseline. Response metadata cannot relax validation. See the [SDK reference](../reference/SDK.md).
+baseline. Jev additionally permits explicitly unknown token counts while requiring
+native confidence. Response metadata cannot relax validation. See the [SDK reference](../reference/SDK.md).
 Application code passes that precision explicitly when using `decideChoice`; the
 policy helper does not infer it from the answer or its metadata.
 

package/docs/development/DESIGN.md

@@ -43,6 +43,17 @@ Read JSON config only when named. Load custom ESM only when explicitly selected.
 Protect credential destinations and expose bounded callbacks. Consequence: plugins
 are powerful and must be trusted; cancellation is not a JavaScript sandbox.
 
+## Release-owned model selectors
+
+OpenAI Decisions offers `default` for the provider's default supported model and
+`luna` for the supported Luna-family model, alongside explicit supported upstream
+IDs. The installed package fixes the target and capability profile for each
+selector. The provider resolves it locally before serialization; no discovery,
+automatic upgrade, or fallback occurs during a call. Consequence: applications can
+use a stable selection string while inspecting selected, outgoing, and reported
+model identities separately. A future target change requires an intentional
+package update and verification of that model's protocol and capabilities.
+
 ## Conservative retries and independent observations
 
 Retry selected explicit transient HTTP statuses within a deadline. Do not retry

package/docs/development/TESTING.md

@@ -42,7 +42,7 @@ as evidence that every environment passed.
 - `transport.test.mjs`: HTTP policy, limits, retries, cancellation, and deadlines.
 - `deadlines.test.mjs`: synchronous preparation/dispatch/completion and inherited budgets.
 - `result-validation.test.mjs`: provider-selected precision and policy-hook boundaries.
-- `decisions*.test.mjs`: native/common OpenAI codecs, boundaries, preflight, CLI, and smoke-helper fixtures.
+- `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.
 - `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.
@@ -63,6 +63,28 @@ All model responses used by ordinary tests are synthetic. HTTP integration serve
 listen on loopback. Tests do not require account keys or make paid model calls.
 Test workspaces are temporary.
 
+### OpenAI model-selector coverage
+
+For changes to OpenAI selection or preparation, run the focused suites from the
+source root:
+
+```text
+node --test test/decisions-selectors.test.mjs test/decisions-preflight.test.mjs test/decisions-cli.test.mjs
+```
+
+These cover omitted, `default`, `luna`, and explicit upstream selection; unsupported
+and malformed values; independently selected, outgoing, and reported identities;
+capabilities and extension context; immutable input; SDK batch preflight; resolved
+wire-byte limits; CLI precedence and mixed-selector rows; and generated requests
+that inherit later configuration changes. Existing Decisions suites also cover
+revalidation after input preparation, refusals, retries, and deadlines.
+
+Type and installed-package checks exercise metadata declarations, SDK/CLI
+selection, and browser execution without Node globals. Use `npm run verify` for
+the complete integration check. A selector mapping change must be verified against
+the target model's protocol and capabilities; local fixtures alone do not establish
+compatibility with a newly selected upstream model.
+
 ## Optional authenticated provider smoke check
 
 Live inference is explicitly opted in and can incur charges. Configure credentials

package/docs/guides/BROWSER.md

@@ -35,6 +35,9 @@ headers used by the SDK. For Jev evaluation those include `POST`, `Authorization
 and `Content-Type`. If the preflight is rejected, the browser sends no evaluation
 request; neither the SDK nor a browser setting can override that server policy.
 Check your intended origin with TypeSafe before relying on direct Jev calls.
+When Jev experimental features are enabled, CORS must also permit the selected
+`TypeSafe-Danger-Zone-Images` and `TypeSafe-Danger-Zone-Long-Context` headers.
+The [Jev guide](JEV.md) covers browser-safe embedded assets and boxes.
 
 Any key delivered to browser JavaScript can be read by the app's users. Only use
 a credential that the provider explicitly permits for browser exposure. If an

package/docs/guides/CLOUDFLARE_DECISIONS.md

@@ -4,8 +4,8 @@ Use `cloudflare-decisions` for hosted inference with `clef` (the default),
 `clef-flash`, or `clef-omni`. All three support common bridge requests and the
 dedicated native API. Each accepts its full `@cf/cloudflare/<model>` alias.
 The provider normalizes the endpoint identifier and the required input selector together.
-See the root README's [model list](../../README.md#supported-models) for the exact
-short selectors and full aliases.
+See the [model selector inventory](../../README.md#model-selectors) for supported
+short selectors and full forms.
 
 | Model | Hosted context, in tokens | Default client request budget | Media |
 | --- | ---: | ---: | --- |

package/docs/guides/CUSTOM_PROVIDERS.md

@@ -17,7 +17,7 @@ extension path.
 `Provider` requires a nonempty `name`, explicit `kind: 'decision' | 'generative'`,
 and `evaluate(request, { signal? })`. Optional fields and hooks are:
 
-- `defaultModel`: a nonempty model ID, otherwise the request must supply one.
+- `defaultModel`: a nonempty selection string, otherwise the request must supply one.
 - `probabilitySource`: known provenance; generative providers use `elicited`.
 - `getCapabilities(model)`: a pure synchronous capability profile.
 - `validateRequest(request)`: pure synchronous provider preflight; no inference.
@@ -31,7 +31,9 @@ that implement this contract directly. Missing or invalid kinds fail at construc
 `bridge.providerKind` and `result.meta.providerKind` come from the contract and
 cannot be overridden by response metadata.
 
-The request is already snapshotted, validated, resolved to a model, and frozen.
+The request is already snapshotted, validated, supplied with an effective model
+selection, and frozen. Its model string retains the selection; any mapping to an
+upstream ID belongs to the provider's preparation and transport.
 Return canonical `{ model, answers, usage, meta? }`; the bridge validates and
 freezes the result. Custom providers own API encoding, transport, response mapping,
 credential destinations, bounded bodies, safe errors, and cancellation cleanup.

package/docs/guides/GETTING_STARTED.md

@@ -25,7 +25,7 @@ You can also install a verified local archive, replacing the path below. See
 a source checkout:
 
 ```bash
-npm install /path/to/fayegram-ai-decision-bridge-0.1.0.tgz
+npm install /path/to/fayegram-ai-decision-bridge-0.1.2.tgz
 ```
 
 The installed package contains the SDK, declarations, command runner, examples,

package/docs/guides/JEV.md

@@ -0,0 +1,174 @@
+# Jev images, boxes, and long context
+
+Jev uses TypeSafe's native `POST /v1/systemone` endpoint. The SDK defaults to
+`jev-latest`; `jev-preview` and explicit version IDs are also accepted. Model
+listing is account-specific and may list aliases without versioned IDs.
+The returned `model` records the service-reported version independently of
+`meta.requestedModel`.
+
+## Experimental opt-ins
+
+Jev images and long context are disabled by default. Enable each independently
+in provider configuration. TypeSafe treats these capabilities as experimental;
+their accuracy, formats, and limits can change.
+
+```javascript
+import { createBridge, JevProvider, box, noul } from '@fayegram-ai/decision-bridge';
+
+const provider = new JevProvider({
+    model: 'jev-1.14.0',
+    dangerZone: { images: true, longContext: true },
+});
+const bridge = createBridge({ provider });
+
+// imageBase64 is a caller-prepared PNG or JPEG, without a data URL prefix.
+const result = await bridge.evaluate({
+    input: [
+        { type: 'text', text: 'A photograph from the kitchen camera.' },
+        { type: 'image', dataUrl: 'data:image/png;base64,' + imageBase64 },
+    ],
+    questions: {
+        present: noul('Is there a coffee mug in the image?'),
+        mug: box('The coffee mug in the image'),
+    },
+});
+console.log(result.answers.present.noul, result.answers.mug.box);
+```
+
+`dangerZone.images` sends `TypeSafe-Danger-Zone-Images: true` and enables common
+image input and boxes. It works with Jev 1.13 and 1.14 for images. Boxes require
+`jev-preview` or a pinned Jev version of 1.14.0 or newer. Local box capability
+lookup remains conservative for moving stable aliases and unknown model names;
+use a supported pinned ID or `jev-preview` for boxes. Account access and hosted
+model availability are still checked by the service.
+
+`dangerZone.longContext` sends `TypeSafe-Danger-Zone-Long-Context: true`. TypeSafe
+documents 262k tokens for both the per-request and per-question contexts with
+this header, compared with default limits of 64k and 32k respectively. This
+option works on Jev 1.13 and 1.14. It does not change the byte budget or estimate
+token counts. Longer contexts are slower and less accurate.
+
+Ordered common input becomes a state array in the same order. Text stays text;
+each image becomes an asset reference. The SDK chooses references that do not
+collide with the input or question text. Jev does not support image detail
+controls: omit `detail`, or use `null` or `auto`. Audio/video, typed choices,
+labelled scores, and safety identifiers remain unsupported by this provider.
+
+## Native assets in instructions and criteria
+
+Use `provider.createDecision()` when images belong inside structured state,
+instructions, or criteria. It accepts the native JSON request shape and returns
+`{ decision, meta }`. Native calls share validation, transport, cancellation,
+and retry policy with common calls, and bypass bridge extensions and observers.
+
+```javascript
+const { decision, meta } = await provider.createDecision({
+    state: { photo: 'photo-unique-reference' },
+    assets: {
+        'photo-unique-reference': {
+            type: 'image', format: 'png', data_base64: imageBase64,
+        },
+        'example-unique-reference': {
+            type: 'image', format: 'jpg', data_base64: exampleBase64,
+        },
+    },
+    questions: {
+        same: noul('Does the object in `photo` match this picture: example-unique-reference?'),
+        target: box('The matching object in `photo`'),
+    },
+});
+console.log(decision.answers.target.box, meta.requestedModel);
+```
+
+References are substituted in string values, including inside sentences and
+nested JSON. Object keys are not substituted. Every asset must be referenced.
+Whole-value references are resolved first. In longer strings, matches are
+consumed from left to right; when keys overlap at the same position, the current
+API uses asset-map order. A reference hidden by another match does not count as
+used. Preflight rejects unused assets before dispatch. Place references in
+separate values when both images are intended.
+Use long unique references (for example, fresh UUIDs) that cannot accidentally
+match ordinary text. Each reference is at most 1024 UTF-8 bytes; all reference
+keys together are at most 65536 bytes. A file is uploaded once, but repeating
+its reference repeats the image in the model's expanded input.
+
+The bridge uses the JSON/base64 transport supported by TypeSafe. It does not
+accept multipart `part` assets, read local image files, fetch URLs, resize,
+rotate, or re-encode images. Base64 overhead counts toward the request limit.
+Native Jev assets are separate from the common request shape; use
+`createDecision` for images embedded in instructions or criteria.
+
+## Boxes and results
+
+`box(instructions)` takes no criteria. Its answer has `type: 'box'`, `box`,
+and native `confidence`. Coordinates are fractions measured from the top-left:
+`left` and `right` scale with width; `top` and `bottom` scale with height.
+All four values must be finite numbers in 0–1, with `left < right` and
+`top < bottom`. Validation rejects malformed boxes rather than repairing them.
+Common results containing box questions use result `meta.schemaVersion: 4`;
+the CLI configuration schema version remains 1.
+
+Each question returns one box. There is no absent-target result: a box is
+returned even when the target is absent. Pair it with a presence `noul` and
+choose your own presence/confidence thresholds using representative images.
+Jev token usage may be `null`; that means unknown, never zero. Native confidence
+and all other result checks remain enforced.
+
+## Image and request limits
+
+- PNG or JPEG (`png`, `jpg`, `jpeg`); still images only. Animated PNG is rejected.
+- At most 16 MiB per decoded image file.
+- Each dimension is 256–1568 pixels, and area is 78,400–2,458,624 pixels.
+  A 256 × 256 image fails the area minimum.
+- Jev requests default to a 32 MiB serialized JSON ceiling. `maxRequestBytes`
+  can lower it, but cannot exceed 32 MiB. Response budgets remain independently
+  configurable, with an 8 MiB default.
+- State, each instruction, and each criterion must fit 64 nested JSON levels.
+  General bridge snapshots also retain their 200,000-node limit.
+
+Preflight checks base64, headers, dimensions, PNG animation, references, original
+image bytes, and serialized request bytes. Full decoding, server re-encoding,
+the 32 MiB processed-image and expanded-input limits, and token limits remain
+service checks. Client header inspection cannot predict processed sizes.
+Prepare upright pixels yourself: TypeSafe removes metadata and does not apply
+EXIF orientation. No separate image-count cap is asserted by the bridge;
+`maxImages: null` means size and context determine capacity.
+
+## CLI
+
+```json
+{
+    "schemaVersion": 1,
+    "provider": "jev",
+    "model": "jev-1.14.0",
+    "apiKeyEnv": "TYPESAFE_API_KEY",
+    "dangerZone": { "images": true, "longContext": true }
+}
+```
+
+```shell
+decision-bridge validate request.json --config decision.config.json
+decision-bridge evaluate request.json --config decision.config.json --env-file .env
+decision-bridge validate native.json --native --model jev-preview --jev-images
+decision-bridge batch native.jsonl --native --config decision.config.json --env-file .env
+```
+
+Common/native validation is offline and uses the same preflight as inference.
+`--native` works with `init`, `validate`, `evaluate`, and `batch`. Jev keeps its
+`models` command. CLI JSON/JSONL input supports requests up to 32 MiB per record;
+the actual serialized request must also fit the configured provider ceiling.
+
+`--jev-images` / `--no-jev-images` and `--jev-long-context` /
+`--no-jev-long-context` override independent fields in `dangerZone`.
+`DECISION_JEV_IMAGES` and `DECISION_JEV_LONG_CONTEXT` accept exactly `true` or
+`false`. Flags override environment, then JSON configuration, then defaults.
+Switching providers discards Jev-specific settings; using these flags with
+another provider is a configuration error.
+
+## Protocol sources
+
+- [TypeSafe release announcement](https://typesafe.ai/blog/jev-1-14)
+- [Images, assets, limits, and experimental header](https://docs.typesafe.ai/images)
+- [Box questions and absence behavior](https://docs.typesafe.ai/primitives/box)
+- [Models, aliases, and context limits](https://docs.typesafe.ai/models)
+- [JavaScript SDK compatibility changes](https://docs.typesafe.ai/sdk/javascript/changelog)

package/docs/guides/OPENAI_DECISIONS.md

@@ -1,13 +1,50 @@
 # OpenAI Decisions
 
-The `openai-decisions` provider implements the native `POST /v1/decisions` API,
-supporting `gpt-6-luna` as its default and only accepted model in this release.
+The `openai-decisions` provider implements the native `POST /v1/decisions` API.
+Its default model selector is `default`; `luna` selects the supported Luna-family
+model, and `gpt-6-luna` selects that explicit upstream ID. Decision Bridge resolves
+all three selections to `gpt-6-luna` in this release before calling the service.
 This integration follows the official [Decisions guide](https://developers.openai.com/api/docs/guides/decisions)
 and [API reference](https://developers.openai.com/api/reference/resources/decisions/methods/create).
 Account access and remote limits still apply. Unknown models fail locally with
 `UNSUPPORTED_CAPABILITY`. The opt-in `openai-compatible` preset in `custom/generative` continues
 using Chat Completions.
 
+## Model selection
+
+```javascript
+import { createProvider } from '@fayegram-ai/decision-bridge';
+
+createProvider({ type: 'openai-decisions' }); // Selects default.
+createProvider({ type: 'openai-decisions', model: 'luna' });
+createProvider({ type: 'openai-decisions', model: 'gpt-6-luna' });
+```
+
+These are alternative configurations. An omitted request `model` inherits the
+provider's configured selection; an explicit request `model` overrides it.
+With no provider or request model configured, the selection is `default`:
+
+| Selection | Selected value | Current upstream target |
+| --- | --- | --- |
+| Omitted, with no configured model | `default` | `gpt-6-luna` |
+| `default` | `default` | `gpt-6-luna` |
+| `luna` | `luna` | `gpt-6-luna` |
+| `gpt-6-luna` | `gpt-6-luna` | `gpt-6-luna` |
+
+Mappings are fixed by the installed Decision Bridge release; there is
+no runtime model discovery, automatic upgrading, or fallback after failure.
+The `default` selector follows the provider default, while `luna` stays within
+the Luna family. The resolved upstream model must have a supported capability
+profile before a selector can target it.
+
+`provider.defaultModel` and `bridge.defaultModel` expose the configured selection,
+using `default` when provider configuration omits `model`. Validated requests and
+extension context retain the effective selected value. Successful common
+and native calls expose `meta.requestedModel` for that selection and
+`meta.resolvedModel` for the upstream ID sent. The common `result.model` and native
+`decision.model` preserve the service-reported identity, which may differ from
+the outgoing ID. Byte limits apply to the resolved wire request.
+
 ## Common bridge access
 
 Set `OPENAI_API_KEY` in the process environment:
@@ -141,14 +178,15 @@ const { decision, meta } = await provider.createDecision({
 }, { signal: controller.signal });
 ```
 
-An omitted model resolves to the provider default. Native input accepts text or
+An omitted model inherits the provider's configured selection. Native input accepts text or
 multiple user messages containing text or ordered `input_text`/`input_image`
 parts. Only user roles are supported. Files, external image URLs, audio, tools,
 and item references are rejected locally. Exported `NativeDecisionRequest` and
 related types describe this format.
 
 `decision` preserves native answer arrays, optional question names, probabilities,
-confidence, and full usage. `meta` contains transport duration, attempt count,
+confidence, and full usage. `meta` has the exported `OpenAIDecisionsTransportMetadata`
+shape: requested/resolved model identities, transport duration, attempt count,
 and request ID when available. Results are immutable. This method bypasses
 common bridge extensions.
 
@@ -197,6 +235,10 @@ provider. Native evaluation/validation/batch require an explicit file or `-`.
 Mode is never inferred from JSON. Initialization writes a native request, which
 must still be evaluated with `--native`. Offline validation checks built-in
 capabilities without credentials; custom capabilities are checked at evaluation.
+OpenAI initialization stores the model selection in configuration and omits it
+from the generated request so later configuration changes apply. The default
+configuration uses `default`. Offline validation reports the selected value as
+`model` and the outgoing upstream ID as `resolvedModel`.
 Decisions offline validation also checks native field limits and the configured
 request byte limit in both modes.
 

package/docs/guides/PLATFORMS.md

@@ -22,7 +22,7 @@ compatible native Node runtime. See [testing](../development/TESTING.md).
 Open PowerShell at the cloned repository or extracted source directory:
 
 ```powershell
-cd "C:\path\to\decision-bridge-0.1.0"
+cd "C:\path\to\decision-bridge-0.1.2"
 node --version
 node bin/decision.mjs validate examples/request.json
 Copy-Item .env.example .env
@@ -48,7 +48,7 @@ the archive rather than reusing generated `node_modules` or executable shims.
 ## macOS / Linux
 
 ```bash
-cd "/path/to/decision-bridge-0.1.0"
+cd "/path/to/decision-bridge-0.1.2"
 node --version
 node bin/decision.mjs validate examples/request.json
 cp .env.example .env

package/docs/guides/SWITCHING_MODELS.md

@@ -4,7 +4,7 @@ The bridge's request contains `questions`, either `state` or ordered `input`, an
 optionally `model`. Ordered input and richer question types require provider capabilities.
 The provider translates it into that service's wire protocol and validates the
 response. Select a provider when constructing your SDK bridge.
-The root README lists [supported model selectors and aliases](../../README.md#supported-models).
+See [model selectors and provider defaults](../../README.md#model-selectors).
 
 ## Native and custom selection
 
@@ -72,7 +72,7 @@ example and provide that backend's credential in `.env`:
 | Native SDK `createProvider` type | Credential variable | Model selection |
 | --- | --- | --- |
 | `jev` | `TYPESAFE_API_KEY` | Defaults to `jev-latest`; an explicit model overrides it |
-| `openai-decisions` | `OPENAI_API_KEY` | Defaults to `gpt-6-luna` |
+| `openai-decisions` | `OPENAI_API_KEY` | Defaults to `default`; also accepts `luna` and explicit `gpt-6-luna` |
 | `cloudflare-decisions` | `CLOUDFLARE_API_TOKEN` and `CLOUDFLARE_ACCOUNT_ID` for REST | Defaults to `clef`; also supports `clef-flash` and `clef-omni` |
 
 Custom generative presets use `createGenerativeProvider` instead. Their types are
@@ -83,7 +83,7 @@ using the following native alternatives:
 
 ```javascript
 createProvider({ type: 'jev', model: 'jev-latest' });
-createProvider({ type: 'openai-decisions', model: 'gpt-6-luna' });
+createProvider({ type: 'openai-decisions', model: 'luna' });
 createProvider({ type: 'cloudflare-decisions', model: 'clef-flash' });
 createGenerativeProvider({ type: 'openai-compatible', model: process.env.DECISION_MODEL });
 createGenerativeProvider({ type: 'anthropic', model: process.env.DECISION_MODEL });
@@ -96,6 +96,12 @@ The SDK does not automatically read `DECISION_*` settings: this example passes
 `process.env.DECISION_MODEL` explicitly. The SDK factory property is **`type`**;
 a command-runner JSON profile uses **`provider`**.
 
+OpenAI's `default` selector chooses the provider default and `luna` chooses the
+supported Luna-family model. Both currently resolve to upstream `gpt-6-luna`
+through Decision Bridge. Use `model: 'gpt-6-luna'` to select that explicit upstream
+ID. Mappings are fixed by the installed package release; results expose the
+selection in `meta.requestedModel` and outgoing ID in `meta.resolvedModel`.
+
 For Jev and the generative providers, list models with `await bridge.listModels()`.
 OpenAI Decisions and Cloudflare Clef do not implement model discovery and return
 `UNSUPPORTED_OPERATION`; their capability profiles do not prove account availability.
@@ -143,7 +149,7 @@ uppercase model placeholders with IDs available to your account/server:
 
 ```bash
 npm exec -- decision-bridge evaluate ./my-decisions/request.json --provider jev --model jev-latest --env-file .env
-npm exec -- decision-bridge evaluate ./my-decisions/request.json --provider openai-decisions --model gpt-6-luna --env-file .env
+npm exec -- decision-bridge evaluate ./my-decisions/request.json --provider openai-decisions --model default --env-file .env
 npm exec -- decision-bridge evaluate ./my-decisions/request.json --provider cloudflare-decisions --model clef-flash --env-file .env
 npm exec -- decision-bridge evaluate ./my-decisions/request.json --provider custom-generative --preset openrouter --model VENDOR/MODEL_ID --env-file .env
 npm exec -- decision-bridge evaluate ./my-decisions/request.json --provider custom-generative --preset openai-compatible --model MODEL_ID --env-file .env

package/docs/guides/TROUBLESHOOTING.md

@@ -18,6 +18,20 @@ explicit config. A compatible base includes its version prefix, not the final
 `/chat/completions` path. Jev and the custom Anthropic preset require origins
 without a path. See [configuration](../reference/CONFIGURATION.md#precedence).
 
+## OpenAI reports a versioned model after I select default or luna
+
+`default` and `luna` are Decision Bridge model selectors. Both currently resolve
+to `gpt-6-luna`, which is the upstream ID sent to OpenAI. Successful common and
+native calls expose the selection as `meta.requestedModel` and the outgoing ID
+as `meta.resolvedModel`. `result.model` or native `decision.model` preserves the
+service-reported identity, which may differ from the outgoing ID.
+
+An omitted request model inherits the configured model. OpenAI initialization
+omits `model` from its generated requests so later configuration edits apply.
+If selection fails with `UNSUPPORTED_CAPABILITY`, check the
+[accepted selectors](OPENAI_DECISIONS.md#model-selection); the bridge does not
+discover another model or fall back after failure.
+
 ## Structured output is rejected
 
 Check that the selected endpoint/model supports the requested `json_schema` mode.