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

package/.env.example

@@ -0,0 +1,10 @@
+# Set only the keys for providers you actually use. Never commit the populated .env.
+TYPESAFE_API_KEY=replace_with_your_typesafe_api_key
+# JEV_MODEL=jev-latest
+# OPENAI_API_KEY=replace_with_your_openai_api_key
+# CLOUDFLARE_ACCOUNT_ID=replace_with_your_cloudflare_account_id
+# CLOUDFLARE_API_TOKEN=replace_with_your_cloudflare_api_token
+# Custom generative preset credentials (opt-in custom/generative).
+# The OpenAI-compatible preset shares OPENAI_API_KEY at the official OpenAI origin.
+# OPENROUTER_API_KEY=replace_with_your_openrouter_api_key
+# ANTHROPIC_API_KEY=replace_with_your_anthropic_api_key

package/CHANGELOG.md

@@ -0,0 +1,75 @@
+# Changelog
+
+Notable user-facing changes by version.
+
+## 0.1.0
+
+Initial release of Decision Bridge as `@fayegram-ai/decision-bridge`.
+
+### SDK and providers
+
+- Provider-neutral `createBridge` interface with explicit provider selection,
+  immutable requests/results, typed questions, capability preflight, context
+  preparation, bounded observations, and ordered batch evaluation.
+- Native Jev, OpenAI Decisions, and Cloudflare Clef/Clef-flash/Clef-omni providers, alongside
+  explicit custom decision and generative paths. General-purpose adapters are
+  retained as maintained OpenAI-compatible, OpenRouter, and Anthropic presets in
+  `custom/generative`; the root factory and exports are native-only.
+- Required decision/generative provider classification, authoritative
+  `providerKind` metadata, definition helpers, and generative provenance validation.
+- Explicit CLI custom kinds with preset/module selection, initialization templates,
+  editor JSON Schema, and structure-only module validation without execution.
+- Common/native OpenAI and Cloudflare access, ordered embedded images, typed
+  string/boolean choices, labelled score rubrics, and preserved native values.
+- Clef-omni common/native WAV/MP3 audio and MP4/WebM video, grouped media ordering,
+  bounded container/duration inspection, and audio/video result schema version 3.
+  Omni defaults to a 36 MiB client request budget, configurable through 64 MiB;
+  older Clef models retain 13 MiB. Effective request models select their own
+  budgets without enlarging explicit smaller ceilings.
+- Cloudflare REST and Workers AI binding transports, binding capacity rejection,
+  optional AI Gateway controls on both transports, and provider-selected
+  four-decimal probability allowance.
+  Enabled Clef/Clef-flash/Clef-omni REST busy options fail local preflight with
+  `UNSUPPORTED_CAPABILITY`, preventing predictably rejected inference requests; see the
+  [Cloudflare compatibility notes](docs/guides/CLOUDFLARE_DECISIONS.md#capacity-rejection-and-ai-gateway).
+- Shared Cloudflare Gateway validation enforces 64-character names, cache TTL
+  from 60 seconds through 30 days, and at most five metadata entries without
+  caller-supplied `cf.*` keys. Invalid settings fail before dispatch; metadata
+  is never silently truncated or stripped.
+- Choice policies accept explicit provider probability precision; OpenAI Decisions
+  preflight enforces its documented 2–255 choice-option range.
+- Explicit native/elicited probability provenance and reported token accounting;
+  missing common usage remains null and generative confidence is not fabricated.
+- Generative presets reserve tool/function controls, including legacy `functions`
+  and `function_call`, with matching CLI editor and runtime validation.
+- Invalid async capability hooks raise configuration errors without leaving
+  rejected promises unobserved or dispatching inference.
+- Custom decision provenance labels are validated as nonempty strings, while
+  preserving service-specific labels and provider defaults.
+- Exported generative prompt and normalization helpers validate their complete
+  request profile, rejecting unsupported input instead of discarding it.
+- Bounded requests/responses, cancellation, end-to-end deadlines, conservative
+  retries, strict response validation, and safe structured DecisionError details.
+- Response-body deadlines also cover continuously ready streams; fragmented
+  responses use bounded byte storage. Model-list snapshots reject accessors
+  before reading their values.
+- Choice policies reject sparse abstention arrays and accessor entries before
+  applying thresholds or abstention rules.
+
+### CLI and distribution
+
+- `decision-bridge`, `decision`, and `faye-decision` commands for initialization, evaluation,
+  offline validation, generative schemas, supported model listing, and ordered
+  JSONL batches with common/native decision dispatch.
+- CLI settings retain flags, environment, explicit JSON config, and default
+  precedence, including custom module request models and resolved module identity.
+  Its built-in provider default is Jev.
+- JSONL record limits remain consistent when CRLF delimiters arrive in separate
+  chunks, without expanding the per-record or total input ceilings.
+- Cloudflare CLI reads within 64 MiB, then uses model-specific SDK preflight for
+  embedded media, per-request overrides, and mixed-model batches. The JSONL total
+  cap remains 64 MiB and the configuration schema remains version 1.
+- ESM source, browser-safe SDK imports, TypeScript declarations, Node.js 22.16+,
+  MIT licensing, and zero runtime dependencies.
+- Consumer/provider guides, examples, cross-platform CI, functional/type checks,
+  and verification by offline installation of the exact npm tarball.

package/CONTRIBUTING.md

@@ -0,0 +1,57 @@
+# Contributing
+
+## Report an issue or propose a change
+
+Search [existing issues](https://github.com/Fayegram-AI/decision-bridge/issues) before
+opening a new one. For a bug, include the bridge version, Node.js version,
+operating system, a minimal reproducible request with synthetic data, expected
+behavior, and actual behavior. For a feature proposal, describe the use case and
+how it fits the provider-independent contract. Report vulnerabilities through the
+private route in [SECURITY.md](SECURITY.md), not in an issue.
+
+Use a source checkout with Node.js 22.16 or newer. No build step or runtime
+dependencies are required. `npm ci --ignore-scripts` installs the pinned
+development-only TypeScript compiler, official Workers declarations, and Ajv
+configuration-schema validator from the lockfile. See the
+[testing guide](docs/development/TESTING.md).
+
+## Understand the design
+
+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
+data; label synthetic responses as synthetic.
+
+## Make and verify a change
+
+Work on a focused branch. Use ESM JavaScript, four-space indentation for new code,
+LF line endings, and a final newline. Avoid unrelated reformatting of existing
+files. Update `.d.mts` declarations and compile-time regressions when public APIs
+change. Document user-visible changes in the changelog.
+
+```text
+npm run verify
+```
+
+Verification includes syntax/JSON/doc-link checks, functional tests, strict public
+type contracts, and a clean offline installation of the npm tarball. Coverage is
+a separate command. Tests use fixtures and local servers; they do not contact
+model accounts. Package checks require npm. Run `npm run test:coverage` when
+reviewing coverage; it reruns the same functional suite.
+
+Keep generated files and credentials out of commits. Maintained contributor
+documentation belongs in `docs/development/`.
+
+## Review and release
+
+Keep commits focused and explain behavior changes and the checks performed.
+Open a pull request with a short description of the behavior change and the
+verification you ran; link the relevant issue when one exists.
+Inspect `git diff` and `git diff --cached` before committing. Respect existing
+authorship and use the project identity configured for the repository.
+
+Follow the [packaging guide](docs/development/RELEASING.md) for the coordinated
+source and npm release. The project is licensed under [MIT](LICENSE).

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Fayegram AI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,308 @@
-# Temporary Holding Version
+# Decision Bridge
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![MIT license](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
+[![Zero runtime dependencies](https://img.shields.io/badge/runtime%20dependencies-0-brightgreen)](package.json)
+
+A JavaScript SDK that turns supplied information into structured decisions inside
+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.
+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.
+
+Try the [Decision Playground](https://decision-pg.fayegram.com/).
+
+The main SDK supports native decision models: Jev through TypeSafe, OpenAI
+Decisions, and Cloudflare Clef. Custom decision services use the explicit
+`custom/decision` entry point. General-purpose models remain available through
+the opt-in `custom/generative` entry point, with maintained OpenAI-compatible,
+OpenRouter, and Anthropic presets. The bridge handles the shared request and result
+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.
+[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
+embedded WAV/MP3 audio and MP4/WebM video, ordered images → audio → videos → text.
+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**
+
+The npm package is
+[@fayegram-ai/decision-bridge](https://www.npmjs.com/package/@fayegram-ai/decision-bridge).
+Source and issue reports are maintained at
+[Fayegram-AI/decision-bridge](https://github.com/Fayegram-AI/decision-bridge).
+Report security issues privately as described in [SECURITY.md](SECURITY.md).
+
+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
+
+The built-in decision providers support these model selectors in this release:
+
+| 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` | — |
+
+`jev-latest` is Jev's default alias. Jev also accepts 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.
+Model discovery is unsupported for OpenAI Decisions and Cloudflare.
+
+Additional decision protocols use [custom decision providers](docs/guides/CUSTOM_DECISION.md).
+General-purpose models use the separate [custom generative](docs/guides/CUSTOM_GENERATIVE.md)
+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.
+
+## Choose a provider
+
+All native providers support shared state and the common `choice`, `noul`, and
+`score` questions. Additional input and question forms depend on the provider:
+
+| Provider | Additional supported features | Guide |
+| --- | --- | --- |
+| Jev | Native decisions through the TypeSafe API | [Provider reference](docs/reference/PROVIDERS.md#native-jev) |
+| 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) |
+| Custom decision service | Explicit decision provider contract | [Custom decision providers](docs/guides/CUSTOM_DECISION.md) |
+| Custom generative presets / modules | General-purpose output mapped into decisions; explicit opt-in | [Custom generative providers](docs/guides/CUSTOM_GENERATIVE.md) |
+
+For Cloudflare REST, provide an account ID and API token. Workers binding and
+Gateway are optional paths with their own configured resources. Enabled
+`rejectIfBusy` currently requires the binding path for all three Clef models.
+Enabling it for REST fails local preflight with `UNSUPPORTED_CAPABILITY`; see the
+[service compatibility note](docs/guides/CLOUDFLARE_DECISIONS.md#capacity-rejection-and-ai-gateway).
+Use [provider capabilities](docs/reference/PROVIDERS.md#common-request-capabilities)
+and `bridge.validate()` to check a request before inference. Capability support
+does not establish account access or model quality.
+
+## Use in your application
+
+For this server-side example, use Node.js **22.16 or newer**. Install the package
+in your application's directory:
+
+```bash
+npm install @fayegram-ai/decision-bridge
+```
+
+The installed SDK runs without a compilation step. See
+[getting started](docs/guides/GETTING_STARTED.md) for source and archive setup.
+
+Create `.env` in your application's directory and set your TypeSafe API key:
+
+```dotenv
+TYPESAFE_API_KEY=your_real_key_here
+```
+
+Add `.env` to your application's `.gitignore`. The SDK reads the process
+environment; the Node command below explicitly loads this file before startup.
+
+Save this complete example as `app.mjs` beside `.env`. The `.mjs` extension enables
+ESM imports without changing your application's `package.json`:
+
+```javascript
+import { createBridge, choice, noul, publicError } from '@fayegram-ai/decision-bridge';
+
+try {
+    const bridge = createBridge({ jev: {} }); // TYPESAFE_API_KEY; model defaults to jev-latest.
+    const result = await bridge.evaluate({
+        state: { log: "ModuleNotFoundError: No module named 'pytest'" },
+        questions: {
+            category: choice('Classify the failure using only the evidence.', {
+                dependency: 'A required package or module is unavailable.',
+                network: 'A network operation failed.',
+                unknown: 'The evidence is insufficient.',
+            }),
+            missing_package: noul('Does the error indicate a missing package?'),
+        },
+    });
+    console.log(result.answers.category.choice);
+    console.log(result.answers.missing_package.noul);
+    console.log(result.meta.probabilitySource);
+} catch (error) {
+    console.error(publicError(error));
+    process.exitCode = 1;
+}
+```
+
+```bash
+node --env-file=.env app.mjs
+```
+
+This makes one real Jev evaluation and may incur charges. The first output is one
+of your category labels. The second is a probability between 0 and 1; `noul` does
+not turn it into a boolean. For Jev, `probabilitySource` is `native`. Answers depend
+on the model; the example does not assume a particular prediction.
+
+Edit `state` and the question definitions for each call. No saved prompt
+registration is required. `publicError()` exposes a stable error code and safe
+message, with HTTP diagnostics when available; see [errors](docs/reference/ERRORS.md).
+
+The example explicitly selects Jev using the `jev` shortcut. For a native provider,
+construct it with `createProvider({ type: 'YOUR_PROVIDER', ...options })` or a
+built-in provider class, then pass it to `createBridge({ provider })`.
+`createBridge()` and `createBridge({})` reject missing provider selection.
+
+Continue with [getting started](docs/guides/GETTING_STARTED.md) for TypeScript,
+CommonJS, and optional command-runner usage, or the [SDK reference](docs/reference/SDK.md)
+for the complete request and result contracts.
+
+## Browser use
+
+The same SDK import works in modern browser applications. Supply credentials
+explicitly; browsers do not have Node's process environment. Direct requests work
+only when the provider permits your web origin through CORS, including the
+authorization and content-type headers. The default Jev endpoint needs TypeSafe
+to allow the app's origin before a browser can call it. A browser-visible API key
+is accessible to users of that app, so use only credentials intended for client
+exposure. See [browser integration](docs/guides/BROWSER.md) for the boundary and
+an example. The optional command runner remains Node-only.
+
+## Change the backend, not the request
+
+[Switching models](docs/guides/SWITCHING_MODELS.md) provides a complete SDK example
+for changing native providers. To elicit decisions from a locally served general-purpose
+model, explicitly opt into the maintained custom generative preset:
+
+```javascript
+import { createBridge } from '@fayegram-ai/decision-bridge';
+import { OpenAICompatibleProvider } from '@fayegram-ai/decision-bridge/custom/generative';
+
+const provider = new OpenAICompatibleProvider({
+    baseURL: 'http://127.0.0.1:8000/v1',
+    apiKey: null,                       // Explicitly allowed only for loopback.
+    model: process.env.LOCAL_MODEL,     // Your locally served model ID.
+    responseFormat: 'json_schema',      // Must be supported by that endpoint.
+    tokenParameter: 'max_tokens',
+});
+const bridge = createBridge({ provider });
+// await bridge.evaluate(theSameRequest);
+```
+
+The `custom/generative` entry point also exports the other presets. For OpenRouter, use `new OpenRouterProvider({ model: 'your-provider/your-model' })`
+with `OPENROUTER_API_KEY`. For Anthropic, use
+`new AnthropicProvider({ model: 'your-account-model-id' })` with
+`ANTHROPIC_API_KEY`. Substitute real available model IDs; the bridge does not
+choose an arbitrary remote model on your behalf.
+
+A server may implement only JSON-object or text output. Select that mode explicitly
+with `responseFormat: 'json_object'` or `'text'`; the client still validates every
+answer. It never silently downgrades formats, repairs JSON, or changes models.
+
+## Optional command runner
+
+The installed package includes `decision-bridge` for working with request files.
+The `decision` and `faye-decision` aliases run the same CLI with the same options.
+Run it through npm from your application directory:
+
+```bash
+npm exec -- decision-bridge init ./my-decisions
+npm exec -- decision-bridge validate ./my-decisions/request.json
+```
+
+These two commands are offline. To evaluate with a real account, copy the generated
+`.env.example` to `.env` inside `my-decisions`, set the key, then run:
+
+```bash
+npm exec -- decision-bridge evaluate ./my-decisions/request.json --config ./my-decisions/decision.config.json --env-file ./my-decisions/.env
+```
+
+The runner uses explicit environment/configuration paths. See the
+[command reference](docs/reference/CLI.md) for flags, streams, and exit codes.
+Its built-in provider default is Jev; SDK construction requires explicit selection.
+
+## What this repository produces
+
+| Component | What you get |
+| --- | --- |
+| JavaScript SDK | Import `@fayegram-ai/decision-bridge` in your application; TypeScript declarations are included |
+| Optional command runner | `decision-bridge`, `decision`, and `faye-decision`, all backed by `bin/decision.mjs` |
+| npm package artifact | `npm run build` creates and verifies `release/fayegram-ai-decision-bridge-VERSION.tgz` |
+
+For maintainers, `npm run build` archives the ESM source and verifies an offline
+install of the exact tarball used for the npm release. See
+[packaging and release](docs/development/RELEASING.md).
+
+For running the source examples, see [source setup](docs/guides/GETTING_STARTED.md#run-from-a-source-checkout).
+See [platform setup](docs/guides/PLATFORMS.md) for Windows/macOS/Linux details.
+
+## What is included
+
+The source checkout includes these runtime features and development tools. The npm
+tarball contains the SDK, Node command, small examples, and maintained docs; it excludes the
+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 |
+| 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) |
+| 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 |
+
+## Result semantics
+
+`result` contains `answers`, `model`, `usage`, and `meta`. Native provider confidence is
+preserved. `bridge.providerKind` and `result.meta.providerKind` distinguish
+`'decision'` from `'generative'`; the bridge takes this classification from the
+provider contract. Generative backends **do not invent confidence**; missing token counts
+are `null`, not zero. Their choices and scores are derived from the returned
+probability distributions. See [SDK reference](docs/reference/SDK.md) and
+[provider compatibility](docs/reference/PROVIDERS.md).
+
+This library does not execute the selected action, operate an agent loop, train a
+model, enforce user authorization, or guarantee decision correctness. It is the
+integration layer on which you can build those policies explicitly.
+
+## Documentation
+
+Start with the [documentation index](docs/README.md), including:
+
+- [Getting started](docs/guides/GETTING_STARTED.md), [customization](docs/guides/CUSTOMIZATION.md), and [custom providers](docs/guides/CUSTOM_PROVIDERS.md), including [generative presets](docs/guides/CUSTOM_GENERATIVE.md).
+- [SDK](docs/reference/SDK.md), [configuration](docs/reference/CONFIGURATION.md), [errors](docs/reference/ERRORS.md), and the optional [command runner](docs/reference/CLI.md).
+- [Contributor documentation](docs/development/README.md) and [security](SECURITY.md).
+
+## Project origins
+
+Decision Bridge builds on the original
+[Jev Adapter repository](https://github.com/Fayegram-AI/jev-adapter).
+It carries forward the structured-decision SDK and CLI, with Jev supported
+alongside the other providers.
+
+## Contributing and verification
+
+Start with [CONTRIBUTING.md](CONTRIBUTING.md). User guides and API references live
+under `docs/guides/` and `docs/reference/`; maintained contributor documentation
+lives under `docs/development/`. See the [repository layout](docs/development/REPOSITORY_LAYOUT.md)
+for the source and package contents.
+
+From a source checkout, run `npm run verify` for routine code, contract, and
+package checks. `npm run test:coverage` reruns the functional suite with coverage
+floors; the [release guide](docs/development/RELEASING.md) gives a single-pass
+verification sequence. These software checks use synthetic fixtures and local
+HTTP servers; they do not measure model quality. The
+[testing guide](docs/development/TESTING.md) covers code and package checks plus
+an optional live integration smoke check. Package preparation is described in the
+[release guide](docs/development/RELEASING.md).
+Public behavior changes are recorded in the [changelog](CHANGELOG.md).
+
+## License
+
+This project is licensed under the [MIT License](LICENSE).

package/SECURITY.md

@@ -0,0 +1,88 @@
+# Security and operational boundaries
+
+## Credentials and data
+
+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
+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
+configuration as part of your data-handling policy; Gateway is disabled until
+selected. See the [Cloudflare guide](docs/guides/CLOUDFLARE_DECISIONS.md#capacity-rejection-and-ai-gateway).
+
+Built-in constructors do not forward ambient credentials to unrelated custom
+origins. The CLI requires explicit credential selection for custom URLs. URL
+credentials/query/fragment are rejected; HTTP is limited to loopback and redirects
+are not followed. These controls do not authenticate an arbitrary configured host,
+resolve all DNS-rebinding risks, or sandbox untrusted URLs. An embedding server
+must impose its own allowlist and network controls.
+
+## Safe errors, not a universal secret scanner
+
+HTTP failure bodies/headers and unknown exception stacks are not copied into public
+errors. Known keys are removed from request IDs and CLI error string values.
+Model outputs, requested labels, state, and arbitrary application logs are not
+universally scrubbed. Do not deliberately include secrets in prompts. A custom
+provider constructing DecisionError is responsible for a safe message. Never add a
+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
+adversarial semantic input. Question instructions are trusted configuration;
+state is untrusted evidence. Prompt separation is a mitigation, not a guarantee.
+
+Output files use exclusive temporary files and mode 0600 where supported, then
+same-directory finalization. Existing output requires explicit --force. Atomicity
+and permissions depend on the filesystem/OS; there is no power-loss-proof
+transaction across model billing, stdout, and filesystem writes.
+
+## Plugins and cancellation
+
+Custom provider modules execute ordinary trusted JavaScript with process access.
+They are not sandboxed and are never auto-discovered. Extensions can perform I/O
+and log data by their own design. Honor supplied AbortSignals and close resources;
+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.
+
+## Dependencies and CI
+
+There are zero runtime dependencies. This reduces dependency surface but is not a
+security certification. Maintain Node.js security updates. The pinned TypeScript
+compiler, official Workers declarations, and Ajv configuration-schema validator
+are development-only dependencies; none is required by the installed SDK or CLI.
+The supplied CI uses read-only repository permissions, no model
+keys, and no publishing. Review third-party action updates and pin audited action
+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.
+
+Include the affected version, impact, and a minimal redacted reproduction. Do
+not publish credentials, confidential inputs, or exploit details in an issue.
+
+## Release assurance
+
+Automated tests and package verification are engineering checks, not an
+independent security audit. Consult CI results for the specific commit or
+release. Ordinary tests do not establish authenticated vendor
+compatibility. See [Testing](docs/development/TESTING.md) for the verification scope.
+
+The input-overwrite guard resolves known path/file aliases; it does not lock the
+whole filesystem against concurrent changes. File-output cancellation is honored
+until atomic finalization is submitted. It cannot retract an OS operation already
+submitted. Parameter objects are validated before inspection/spreading so accessors
+are rejected without being invoked by the provider constructors.

package/bin/decision.mjs

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+import { runCli } from '../src/cli/main.mjs';
+
+const controller = new AbortController();
+const interrupt = () => controller.abort();
+process.once('SIGINT', interrupt);
+process.once('SIGTERM', interrupt);
+// Stream errors are handled by write callbacks; avoid unhandled EPIPE events.
+process.stdout.on('error', () => {});
+process.stderr.on('error', () => {});
+process.exitCode = await runCli(process.argv.slice(2), { signal: controller.signal });
+// An interrupted, backpressured pipe must not keep the process alive.
+if (controller.signal.aborted) { process.stdin.destroy(); process.stdout.destroy(); }
+process.removeListener('SIGINT', interrupt);
+process.removeListener('SIGTERM', interrupt);

package/docs/README.md

@@ -0,0 +1,58 @@
+# Documentation
+
+Start with [using the SDK in your application](../README.md#use-in-your-application)
+for installation and a complete first call. This index separates usage guides,
+API reference, and contributor documentation.
+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.
+
+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.
+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.
+
+## Use the bridge
+
+| Guide | Purpose |
+| --- | --- |
+| [Getting started](guides/GETTING_STARTED.md) | Package installation, credentials, JavaScript/TypeScript integration, and first evaluation |
+| [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 |
+| [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 |
+| [Custom decision](guides/CUSTOM_DECISION.md) | Extend a native decision model protocol |
+| [Custom generative](guides/CUSTOM_GENERATIVE.md) | Opt-in OpenAI-compatible, OpenRouter, Anthropic presets, strategy helpers, and new protocols |
+| [Troubleshooting](guides/TROUBLESHOOTING.md) | Configuration, network, model, and output errors |
+
+## Reference
+
+| Document | Purpose |
+| --- | --- |
+| [SDK](reference/SDK.md) | Questions/results, exports and types, transport options, validation, cancellation, batching, extensions, and policies |
+| [Command runner](reference/CLI.md) | Optional commands, flags, streams, and exit codes |
+| [Configuration](reference/CONFIGURATION.md) | Precedence, credentials, and profiles |
+| [Providers](reference/PROVIDERS.md) | Protocols and probability provenance |
+| [Errors](reference/ERRORS.md) | Error codes and retry behavior |
+| [Sources](reference/SOURCES.md) | Primary protocol documentation |
+
+## Contribute
+
+Read [CONTRIBUTING.md](../CONTRIBUTING.md), then the
+[contributor documentation](development/README.md) for architecture, design
+choices, testing, and packaging. The
+[repository layout](development/REPOSITORY_LAYOUT.md) explains source and package
+contents.
+
+The [security policy](../SECURITY.md) and [changelog](../CHANGELOG.md) cover
+operational boundaries and public compatibility history.