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

package/docs/development/ARCHITECTURE.md

@@ -0,0 +1,118 @@
+# Architecture
+
+## Bridge and provider responsibilities
+
+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,
+capabilities, and native operations. Multiple models sharing a protocol can use
+one provider implementation.
+
+`createBridge` requires an explicitly selected provider or the Jev shortcut.
+`createProvider` requires an explicit native type. `custom/decision` and
+`custom/generative` expose classified extension helpers; maintained generative
+adapters are loaded only through their opt-in subpath. The CLI resolves its own configuration
+and Jev default before constructing the SDK bridge.
+
+```text
+Application / CLI
+  state or ordered input + question definitions + optional model
+        |
+        v
+  request snapshot, common validation, capabilities, provider preflight
+        |
+  ordered prepareState or prepareInput extensions + revalidation
+        |
+  Provider.evaluate (explicit decision/generative kind)
+        +-- Jev: native systemone
+        +-- OpenAI Decisions: native /v1/decisions
+        +-- Cloudflare Clef / Clef-flash / Clef-omni: REST or Workers AI binding
+        +-- custom/decision: new native decision protocol
+        +-- custom/generative: OpenAI-compatible / OpenRouter / Anthropic or new protocol
+        |
+  canonical result validation using provider precision policy
+        |
+  immutable result + bounded observation
+        |
+  application policy / storage / downstream action
+```
+
+Native 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.
+
+Application policy decides whether a downstream action is permitted. The SDK
+returns decisions without executing actions or maintaining an agent loop.
+
+## Module map
+
+| Module | Responsibility |
+| --- | --- |
+| `src/index.mjs`, `src/index.d.mts` | Public runtime exports and TypeScript contract |
+| `src/bridge.mjs` | Orchestration, extension lifecycle, total deadline, immutable results |
+| `src/validation.mjs`, `src/input.mjs` | Lossless snapshots, common input and result invariants |
+| `src/questions.mjs` | Immutable typed question builders, independent of inference selection |
+| `src/capabilities.mjs` | Provider/model capability checks and common schema versions |
+| `src/probabilities.mjs` | Provider-selected precision allowance without normalization |
+| `src/provider-contract.mjs` | Required classification, authoritative metadata, and generative provenance |
+| `src/custom/decision.mjs` | Explicit native decision definition helper |
+| `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/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 |
+| `src/options.mjs` | Unknown-field/accessor rejection for options |
+| `src/errors.mjs` | DecisionError and safe public diagnostics |
+| `src/batch.mjs` | Ordered bounded-concurrency SDK arrays |
+| `src/policy.mjs` | Explicit choice thresholds, without action execution |
+| `src/cli/ordered.mjs` | Concurrent JSONL processing with a bounded ordered window |
+| `src/cli/`, `bin/decision.mjs` | Configuration, input/output, commands, process signals |
+
+## Results and precision
+
+Generative providers elicit distributions and derive argmax choices, weighted
+scores, and rubric legends in code. Native decision providers validate and retain
+their returned values, confidence, and reported usage. No path repairs malformed
+distributions or invents confidence. The common shape preserves provenance without
+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).
+Application code passes that precision explicitly when using `decideChoice`; the
+policy helper does not infer it from the answer or its metadata.
+
+## Reliability and configuration
+
+Provider deadlines include dispatch, configured retries, backoff, and bounded body
+reading. The bridge deadline additionally covers validation, preparation, provider
+waiting, and result processing. Expired synchronous work cannot dispatch a call.
+Cancellation bounds waiting for custom promises; custom code must honor signals
+to release its own resources. Observations use a separate bounded budget.
+
+Retries cover selected explicit transient responses. Ambiguous failures and failed
+observers do not trigger another inference. CLI atomic files protect previous
+output but cannot undo remote work or emitted stdout.
+
+JSON configuration is explicit. Custom ESM executes only when selected. Custom
+origins do not inherit unrelated ambient credentials. Gateway settings remain
+provider configuration, and do not replace the bridge's total deadline.
+
+## Extension boundaries
+
+Use preparation hooks for context, observation hooks for metrics, classified custom providers
+for another API, and application code for policy. Ordered images and richer
+questions require declared capabilities. Native provider guides document limits.
+Cloudflare Omni supports grouped embedded images/audio/video before text. Model
+profiles resolve request byte limits per call; transport instances share no
+mutable request limit or response identifiers. Header/container inspection is
+bounded and does not perform full media decoding.
+
+The SDK does not host models or provide a server API, persistent state, autonomous
+actions, streaming, transcription, transcoding, frame extraction,
+provider-side asynchronous batch jobs, platform
+management, automatic model search, or automatic provider failover. SDK arrays and
+CLI JSONL batches provide bounded client-side concurrency.

package/docs/development/DESIGN.md

@@ -0,0 +1,66 @@
+# Design rationale
+
+## Native decisions as the application contract
+
+Use shared state or ordered input and independent typed questions as the public
+contract. The bridge owns orchestration; providers own their model API protocols.
+This gives applications a stable decision interface and makes customization
+explicit at each call. Native decision models are the main package scope;
+generative protocols are opt-in custom strategies with their own public subpath.
+Every provider declares its decision/generative kind. Consequence: not every model can satisfy this contract
+reliably; compatibility and quality must be tested separately.
+
+## ESM JavaScript with declarations and no runtime dependencies
+
+Use standard fetch, streams, and JSON in the SDK; keep Node's test runner,
+argument parser, and filesystem APIs in development tools and the optional CLI.
+Ship ESM source plus `.d.mts` types without a transpilation build. Consequence:
+Node 22.16+ is required for Node use, while browser use depends on modern web
+APIs and the provider's CORS policy. TypeScript declaration synchronization needs
+its own tests. A CommonJS entry point is not claimed.
+
+## Provenance is part of the result
+
+Native versus elicited probabilities are tagged. Native codecs preserve reported
+probabilities, confidence, and scores. Generative strategies derive choice/score
+from their elicited distributions and do not supply native confidence;
+unreported token counts are null. Consequence: applications must handle optional
+confidence/usage, and identical output schemas do not imply interchangeable
+calibration or correctness.
+
+## Fail explicitly instead of silently repairing or falling back
+
+Reject invalid JSON, extra fields, wrong labels, distributions outside the provider
+precision allowance, explicit output truncation, and refusals. Require explicit
+output modes and models. Services may truncate input without reporting it; local
+byte limits do not guarantee token fit. Consequence:
+some calls fail that a permissive wrapper might guess at, but failures remain
+observable and cannot silently change budgets or decision policies.
+
+## Trusted extensions and explicit configuration
+
+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.
+
+## Conservative retries and independent observations
+
+Retry selected explicit transient HTTP statuses within a deadline. Do not retry
+ambiguous network failures, malformed decisions, or observer failures. Consequence:
+users can choose manual retry policies, but exactly-once billing cannot be promised.
+
+## MIT licensing and coordinated distribution
+
+Publish the maintained source under the MIT License, with the copyright notice
+in `LICENSE` and matching SPDX identifiers in package metadata. Release the source
+repository and npm package together. Consequence: source and package recipients
+have the same MIT permissions and obligations; building an archive alone does not
+publish a release.
+
+## Verified npm package artifact
+
+Build a versioned npm tarball from the source package and retain it only after an
+offline installation check of the exact archive. Publish that verified artifact
+to the public npm registry as part of the coordinated source and package release;
+building alone never publishes it. Consequence: consumers install the release from
+npm, while maintainers verify the exact archive before publication.

package/docs/development/README.md

@@ -0,0 +1,12 @@
+# Contributor documentation
+
+This directory contains maintained documentation for contributors to the public
+repository. Start with [CONTRIBUTING.md](../../CONTRIBUTING.md).
+
+| Document | Purpose |
+| --- | --- |
+| [Architecture](ARCHITECTURE.md) | Runtime ownership, evaluation flow, and boundaries |
+| [Design rationale](DESIGN.md) | Public contract choices and their consequences |
+| [Testing](TESTING.md) | Local tests, type checks, packaging checks, and live smoke tests |
+| [Packaging and release](RELEASING.md) | Source/package verification and separate publication instructions |
+| [Repository layout](REPOSITORY_LAYOUT.md) | Source and package boundaries |

package/docs/development/RELEASING.md

@@ -0,0 +1,100 @@
+# Packaging and release
+
+The npm package build archives ESM source without compilation. The versioned
+tarball contains the runtime, TypeScript declarations, examples, and maintained
+docs. Tests and development scripts remain in the source repository.
+
+## Verify source and package contents
+
+From a clean source checkout, verify the code and build the installable artifact:
+
+```text
+npm run check
+npm run test:coverage
+npm run typecheck
+npm run build
+```
+
+`npm run build` packs the source with lifecycle scripts disabled, installs and
+checks that exact tarball in a clean offline consumer, and retains it at
+`release/fayegram-ai-decision-bridge-VERSION.tgz`. The `release/` directory is Git-ignored.
+Packing and individual verification commands have 120-second bounds; the combined
+installed-consumer verification stage has a separate 600-second bound and streams
+its progress. This accommodates CLI startup across multiple verification commands.
+To check that archive again, run:
+
+```text
+node scripts/package-smoke.mjs --tarball release/fayegram-ai-decision-bridge-VERSION.tgz
+```
+
+Check public documentation against the implementation, including supported API
+shapes, examples, limits, errors, and service compatibility notes. Inspect the MIT
+copyright notice and package contents. Complete hosted checks relevant to changed
+features using an authorized account/runtime;
+fixture and declaration checks do not establish hosted binding/Gateway behavior.
+Keep completed verification evidence separate from maintained consumer guidance.
+These content and verification checks do not depend on publication account setup.
+
+## Confirm publication prerequisites
+
+Before publication, confirm the repository exists at the metadata destination and
+inspect CI results for the exact release commit. Make sure the hosted repository
+has a private vulnerability-reporting route as described in
+[SECURITY.md](../../SECURITY.md). Confirm that the npm login can publish under
+`@fayegram-ai`. Direct publication requires account 2FA or a granular token
+permitted to bypass it; see [npm's requirements](https://docs.npmjs.com/creating-and-publishing-scoped-public-packages/).
+
+Building only creates and checks the artifact; it does not publish it. The package
+name and registry are `@fayegram-ai/decision-bridge` and the public npm registry.
+Coordinate the GitHub source release and publication of the verified tarball to
+npm as one release. The source release commit and archive must contain the same
+intended files, including README and documentation. A packed or uploaded archive
+is a snapshot: subsequent source edits do not change its contents.
+
+The tracked `.npmrc` routes this scope to npm in this checkout without changing
+the user's npm configuration. Keep credentials in the user configuration, never
+in the repository. Verify the target with `npm config get @fayegram-ai:registry`
+before staging or publishing. Replace `VERSION` and `STAGE_ID` below with the
+package version and the returned stage identifier. The `./` prefix identifies a
+local archive path to npm.
+
+## Stage, inspect, and approve an archive
+
+With npm CLI 11.15.0+ and package write access, stage the verified archive:
+
+```text
+npm stage publish ./release/fayegram-ai-decision-bridge-VERSION.tgz --access public --tag latest
+npm stage view STAGE_ID --json
+npm stage download STAGE_ID
+```
+
+Compare the downloaded archive's checksum with the retained artifact, then verify
+that exact download using `node scripts/package-smoke.mjs --tarball PATH_TO_DOWNLOAD`.
+The staged version becomes publicly installable when a maintainer approves it
+with 2FA:
+
+```text
+npm stage approve STAGE_ID
+```
+
+Approval publishes that version; no additional `npm publish` is needed. A first
+stage for a new package creates a public `0.0.0-stage` placeholder, which is not
+the staged SDK. See [npm's staged publishing guide](https://docs.npmjs.com/staged-publishing/).
+
+If packaged files change before approval, build and verify a fresh archive.
+Reject the old stage with `npm stage reject STAGE_ID` (requires 2FA), then stage
+the new archive and repeat inspection. A pending stage reserves its version, so
+remove it before staging a replacement with the same unpublished version. See
+the [npm stage reference](https://docs.npmjs.com/cli/v12/commands/npm-stage/).
+
+## Direct publication alternative
+
+For a version without a pending stage, publish the verified archive directly:
+
+```text
+npm publish ./release/fayegram-ai-decision-bridge-VERSION.tgz --access public --tag latest
+```
+
+After the coordinated release, confirm that the package page
+links to the source repository and `npm install @fayegram-ai/decision-bridge` works.
+Keep generated archives and verification logs outside tracked source.

package/docs/development/REPOSITORY_LAYOUT.md

@@ -0,0 +1,33 @@
+# Repository layout
+
+The source repository contains the SDK, CLI, examples, functional tests, CI, and
+maintained documentation. The installable npm tarball contains the SDK and CLI
+with declarations, examples, and docs; it excludes tests and development scripts.
+
+```text
+README.md                  Product overview and quick start
+CONTRIBUTING.md             Contributor entry point
+CHANGELOG.md                User-visible changes
+SECURITY.md                 Security boundaries and reporting guidance
+LICENSE                    MIT license
+package.json               Package identity, exports, commands, and file allowlist
+package-lock.json          Pinned development dependency metadata
+.env.example               Provider credential placeholders
+src/                       Common SDK, native providers, CLI, declarations
+src/custom/                Explicit decision definitions and generative presets
+bin/                       Node.js CLI entry point
+examples/                  Native SDK examples and request profiles
+examples/custom/           Opt-in generative and native delegation examples
+schemas/                   Packaged CLI configuration JSON Schema
+docs/guides/               User guides
+docs/reference/            SDK, CLI, configuration, and provider contracts
+docs/development/          Architecture, tests, and packaging guidance
+test/                      Functional and type-contract tests
+scripts/                   Source, type, and package checks
+.github/                   CI and dependency update configuration
+```
+
+The `package.json` `files` allowlist defines the npm tarball.
+`npm run test:package` verifies the installed files and offline CLI commands. `npm run build`
+retains its verified tarball under the ignored `release/` directory. Credentials
+belong in local environment files, not in source or package contents.

package/docs/development/TESTING.md

@@ -0,0 +1,131 @@
+# Testing
+
+Run these commands from a source checkout. An installed npm package contains
+runtime code and documentation, but does not contain tests or development scripts.
+
+## Automated code and package checks
+
+Use Node.js 22.16 or newer. Runtime code has zero npm dependencies. Run
+`npm ci --ignore-scripts` to install the pinned development tools: TypeScript
+5.8.3, the official Workers declarations, and the configuration-schema validator.
+Source and installed-consumer type checks use the same local compiler.
+
+| Command | Verification |
+| --- | --- |
+| `npm run check` | Public-source layout, JavaScript syntax, JSON, formatting, local doc links, versions |
+| `npm test` | SDK, CLI, provider, and file/transport behavior using fixtures and loopback servers |
+| `npm run test:coverage` | The functional suite with production source/bin coverage floors |
+| `npm run typecheck` | Positive and expected-negative TypeScript API contracts |
+| `npm run test:package` | Pack, offline install, root/custom exports and types, browser-safe imports, presets/modules, contents and docs |
+| `npm run build` | Retain a versioned npm tarball after checking its offline installation |
+| `npm run verify` | Source checks, tests, type contracts, and package smoke check |
+
+`verify` is a convenience command for routine changes. It already runs `npm test`
+and `test:package`; running coverage and build immediately after it repeats
+those checks. CI and the release guide run `check`, `test:coverage`,
+`typecheck`, and `build` once each.
+
+These commands validate code behavior and package integrity. Model-quality
+evaluation is a separate activity, not part of the test suite: these commands do
+not score model answers, measure provider speed, or use paid inference. Coverage
+floors are 90% lines, 80% branches, and 85% functions. Coverage does not establish model
+quality, correctness of every path, or current hosted compatibility.
+The CI configuration targets Linux, Windows, and macOS on Node 22.16 and Node 24;
+consult actual run results for a particular commit instead of treating the matrix
+as evidence that every environment passed.
+
+## Suite ownership
+
+- `contract.test.mjs`: request/result contracts, builders, decision policy, and JSON safety.
+- `bridge.test.mjs`: SDK evaluation, extensions, observers, deadlines, and batches.
+- `providers.test.mjs`: provider wire formats, response parsing, model listing, and configuration.
+- `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.
+- `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.
+- `config.test.mjs`: file/environment/flag precedence and provider transitions.
+- `cli.test.mjs`: commands, streams, exit codes, modules, and signals.
+- `io.test.mjs`: atomic output, file aliases, and cancellation.
+- `ordered.test.mjs`: ordered streaming and bounded concurrency.
+- `support.mjs` and `fixtures.mjs`: local test setup and synthetic domain data.
+- `types.mts`, `providers.types.mts`, `custom.types.mts`: public type inference and rejected API usage.
+- `decisions.types.mts`, `cloudflare.types.mts`: richer questions, native APIs, and precision settings.
+- `cloudflare-worker.types.mts`: compatibility with official Workers binding declarations.
+
+Node's reported test count includes each row of a parameterized input table. It
+is not a count of independent features; retain separate rows when they protect
+different contract or protocol paths.
+
+All model responses used by ordinary tests are synthetic. HTTP integration servers
+listen on loopback. Tests do not require account keys or make paid model calls.
+Test workspaces are temporary.
+
+## Optional authenticated provider smoke check
+
+Live inference is explicitly opted in and can incur charges. Configure credentials
+locally, then on POSIX shells:
+
+```bash
+RUN_LIVE_TESTS=1 npm run smoke:live -- --env-file .env
+```
+
+On PowerShell:
+
+```powershell
+$env:RUN_LIVE_TESTS = '1'
+npm run smoke:live -- --env-file .env
+Remove-Item Env:RUN_LIVE_TESTS
+```
+
+Forward provider/model/config options for the selected account. The helper refuses
+to infer without the opt-in flag and returns real results or errors. It checks a
+configured inference path, not model quality or throughput. For model listing
+alone, use `node bin/decision.mjs models --env-file .env`.
+Model listing is unsupported for OpenAI Decisions and Cloudflare Clef.
+
+The OpenAI Decisions helper performs four bounded common/native requests when
+invoked with `--decisions`. It includes a valid embedded PNG, typed choices, and
+labelled scores. For example, after setting the same opt-in variable:
+
+```text
+npm run smoke:live -- --decisions --env-file .env
+```
+
+Cloudflare REST can use the ordinary smoke command with
+`--provider cloudflare-decisions --model clef`, `--model clef-flash`, or
+`--model clef-omni`, loading its
+account/token environment explicitly. These invocations each check one common
+request. Native, image, large-distribution, binding, and Gateway checks require
+separate bounded cases; test the latter two in the intended existing runtime and
+Gateway. REST busy rejection has a documented
+[service limitation](../guides/CLOUDFLARE_DECISIONS.md#capacity-rejection-and-ai-gateway).
+Test all three models and both access shapes when changing those paths. Include typed
+string/boolean identity, labelled scores, reported confidence/usage, and distinct
+request/Gateway IDs from concurrent calls. Enabling binding busy mode verifies
+option acceptance; it does not establish behavior under exhausted capacity.
+Header/dimension preflight does not fully decode images, so live image fixtures
+must also contain valid encoded image data.
+Omni fixtures must contain genuinely decodable WAV/MP3 and MP4/WebM media for
+hosted tests. Local authored container fixtures verify inspection and protocol
+behavior without claiming codec validity. Include grouped modalities, duration
+and size boundaries, effective-model overrides, request bodies above 13 MiB,
+and explicit smaller ceilings. Gateway caching/logging should be disabled for
+test payloads, and each bounded run should have a request and total time budget.
+
+The SDK, CLI, and ordinary checks do not create Workers or Gateways. Provisioning
+and cleanup belong to the application's separately authorized environment setup.
+
+## Package verification
+
+To test a specific local tarball against this source checkout:
+
+```text
+node scripts/package-smoke.mjs --tarball /path/to/fayegram-ai-decision-bridge-VERSION.tgz
+```
+
+The check installs the specified archive offline and compares installed bytes,
+documentation links, exports, CLI shims, and the bundled sample. It also rejects
+local archives and development-only files leaking into the runtime package.

package/docs/guides/BROWSER.md

@@ -0,0 +1,43 @@
+# Browser integration
+
+The SDK exports browser-compatible ESM. Follow the
+[installation guide](GETTING_STARTED.md#install-into-your-application), then import
+`@fayegram-ai/decision-bridge` through your browser application's module bundler. The
+optional `decision-bridge` command still requires Node.js.
+Omni's embedded audio/video validation is browser-safe and adds no runtime media
+library. Build data URLs in the application; the SDK does not fetch remote media.
+
+Built-in REST providers need explicitly supplied credentials in browser code;
+Node environment-variable defaults and `.env` files are not available. Cloudflare
+REST also needs `accountId`; its Workers AI binding is configured inside a Worker,
+as described in the [Cloudflare guide](CLOUDFLARE_DECISIONS.md#workers-ai-binding).
+A compatible loopback endpoint can explicitly use `apiKey: null`.
+The following example requires TypeSafe to permit your application's origin and
+provide a credential suitable for client exposure. `browserCredential` is supplied
+by your application's credential flow:
+
+```javascript
+import { createBridge, JevProvider, noul } from '@fayegram-ai/decision-bridge';
+
+const bridge = createBridge({
+    provider: new JevProvider({ apiKey: browserCredential }),
+});
+const result = await bridge.evaluate({
+    state: 'A user-supplied statement',
+    questions: { relevant: noul('Is this relevant?') },
+});
+console.log(result.answers.relevant.noul);
+```
+
+This sends the request **directly from the browser**. The provider's server must
+accept the page's origin in its CORS preflight response and allow the method and
+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.
+
+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
+account key must remain private, keep the provider call in your own backend and
+invoke that backend from the browser. This is a credential boundary, separate
+from whether the SDK's modules can run in a browser.