@takk/bayesoutputgate 1.0.0

package/SPEC.md

@@ -0,0 +1,467 @@
+# @takk/bayesoutputgate - Technical Specification
+
+**Version:** 1.0.0
+**Status:** Stable
+**License:** Apache-2.0
+
+This document is the binding contract between `@takk/bayesoutputgate` and its consumers. Behavior described here is covered by SemVer: breaking changes require a major version bump and a deprecation cycle (see [SEMVER POLICY](#52-semver-policy)).
+
+---
+
+## 1. Purpose
+
+BayesOutputGate is a universal, zero-runtime-dependency library and CLI that turns the quality scores of an output into a calibrated pass, fail, or escalate decision. You feed in the per-dimension scores of an output, from any scorer (an LLM-as-judge, a classifier, a regex), and the engine answers the question a reviewer actually asks, transparently:
+
+- **Calibrating** two hypotheses from labeled history: a Beta model of the scores of known-high-quality outputs and a Beta model of the scores of known-low-quality outputs, per dimension, regularized by a prior and updatable online.
+- **Weighing** a new output's scores with a Bayes Factor: the ratio of the likelihood under the high-quality hypothesis to the likelihood under the low-quality one, summed in log space across weighted dimensions.
+- **Interpreting** the combined Bayes Factor on the Jeffreys scale, whose symmetric boundaries at 3, 10, and 100 separate inconclusive, substantial, strong, and decisive evidence.
+- **Deciding** pass, fail, or escalate, by a pure Bayes Factor policy on that scale, or by a decision-theoretic policy that minimizes expected loss under an asymmetric cost of the two error types.
+- **Diagnosing** trust: a goodness-of-fit test of the Beta assumption, a dependence diagnostic over the dimensions, and measured decision calibration (Brier score, expected calibration error, reliability diagram).
+- **Proving** the decision trail with a tamper-evident hash-chained audit log.
+
+It is library-shaped, not service-shaped. There is no central server, no SaaS dependency, no SDK lock-in. The core is node-free; it runs in Node, edge runtimes, and the browser. It is an output-validation engine for Massive Intelligence (IM) systems and for any setting where a stream of quality scores must be turned into calibrated accept or reject decisions.
+
+---
+
+## 2. Public surface
+
+### 2.1 Entry points
+
+The package ships thirteen functional subpath exports plus `./package.json`, each with separate `import` (ESM) and `require` (CJS) conditions and matching `.d.ts` / `.d.cts` files:
+
+| Subpath | Use |
+|---|---|
+| `.` | The `evaluate` gate, `OutputGate`, `OutputGateMonitor`, plus the full toolkit and types |
+| `./beta` | `BetaModel`, the calibrated, online-updatable Beta model both hypotheses share |
+| `./hypothesis` | `HypothesisManager`, per-dimension high and low score models from labeled history |
+| `./likelihood` | `logScoreLikelihood`, `logBinaryMarginalLikelihood`, `logVectorLikelihood`, `toScoreMap` |
+| `./bayesfactor` | `bayesFactor`, `jeffreysStrength`, the combined Bayes Factor and its interpretation |
+| `./dimensions` | `dependenceDiagnostic`, pairwise correlation between dimensions |
+| `./policy` | `decide`, `posteriorHighQuality`, the Bayes Factor and decision-theoretic policies |
+| `./calibration` | `goodnessOfFit`, `brierScore`, `expectedCalibrationError`, `reliability` |
+| `./gate` | `evaluate`, `OutputGate`, `OutputGateMonitor` |
+| `./audit` | `AuditChain`, `verifyChain`, `sha256Hex`, an append-only SHA-256 hash chain over Web Crypto |
+| `./adapter` | `bayesOutputGateTool`, `runTool`, `describeTool`, the framework-agnostic MCP and LLM tool |
+| `./node` | File loaders for JSON and CSV score history (the only Node-only entry) |
+| `./edge` | The node-free core, re-exported for edge runtimes and the browser |
+| `./package.json` | Manifest access for tooling |
+
+A `bayesoutputgate` binary is exposed via `package.json#bin -> ./dist/cli/index.js`.
+
+### 2.2 Core types
+
+```ts
+type HypothesisKind = "high" | "low";
+type GateAction = "pass" | "fail" | "escalate";
+
+interface QualityScore {
+  readonly dimension: string;  // the axis this score measures, for example "factuality"
+  readonly value: number;      // the score in [0, 1], higher is better
+}
+type ScoreVector = readonly QualityScore[];
+
+interface BetaParams {
+  readonly a: number;          // positive
+  readonly b: number;          // positive
+}
+
+interface DimensionModel {
+  readonly dimension: string;
+  readonly high: BetaParams;   // Beta over the scores of known-high-quality outputs
+  readonly low: BetaParams;    // Beta over the scores of known-low-quality outputs
+  readonly weight: number;     // non-negative weight on this dimension's log-Bayes-Factor
+}
+
+interface LabeledObservation {
+  readonly scores: ScoreVector;
+  readonly label: HypothesisKind;  // the known ground-truth quality of this output
+}
+```
+
+### 2.3 Core API
+
+#### `evaluate(scores, models, policy, guards?): GateDecision`
+
+Weighs one output's scores against the dimension models under a policy, in a single call: it computes the Bayes Factor, applies the policy, and, when guards with a precomputed assumption report are supplied, escalates instead of trusting a Bayes Factor from a misspecified model.
+
+```ts
+function evaluate(
+  scores: ScoreVector,
+  models: readonly DimensionModel[],
+  policy: PolicyConfig,
+  guards?: GateGuards,
+): GateDecision;
+
+interface GateDecision {
+  readonly action: GateAction;
+  readonly bayesFactor: number;
+  readonly logBayesFactor: number;
+  readonly strength: EvidenceStrength;
+  readonly rationale: "bayes-factor" | "expected-loss" | "assumption-violated";
+  readonly posteriorHighQuality?: number;        // present under a decision-theoretic policy
+  readonly expectedLoss?: ExpectedLoss;          // present under a decision-theoretic policy
+  readonly assumptions?: AssumptionReport;       // present when guards supplied a report
+  readonly contributions: readonly DimensionContribution[];
+}
+
+interface GateGuards {
+  assumptions?: AssumptionReport;   // a precomputed report; see assessAssumptions
+  requireGoodnessOfFit?: boolean;   // escalate if goodness-of-fit is inadequate
+  requireIndependence?: boolean;    // escalate if the independence assumption is unsafe
+}
+
+interface AssumptionReport {
+  readonly goodnessOfFitAdequate: boolean;
+  readonly independenceAssumptionSafe: boolean;
+  readonly inadequateDimensions: readonly string[];
+  readonly dependentPairs: readonly string[];     // each "a~b"
+}
+```
+
+When a `require` flag is set and the matching assumption fails, the decision's action becomes `escalate` and its rationale `"assumption-violated"`, while the Bayes Factor, strength, and contributions are preserved for the reviewer. `OutputGate` and `OutputGateMonitor` accept guards in their options; the monitor reassesses the report from the history on every batch `fit`.
+
+#### `bayesFactor(scores, models): BayesFactorResult`
+
+Computes the combined natural-log Bayes Factor in favor of high quality as the weighted sum of per-dimension Beta log-density differences, over the dimensions that have both a score and a model, and interprets it on the Jeffreys scale.
+
+```ts
+type EvidenceStrength =
+  | "decisive-low" | "strong-low" | "substantial-low"
+  | "inconclusive"
+  | "substantial-high" | "strong-high" | "decisive-high";
+
+interface DimensionContribution {
+  readonly dimension: string;
+  readonly score: number;
+  readonly logBayesFactor: number;
+  readonly weight: number;
+}
+
+interface BayesFactorResult {
+  readonly logBayesFactor: number;
+  readonly bayesFactor: number;                  // exp(logBayesFactor), may be Infinity
+  readonly favored: "high" | "low" | "inconclusive";
+  readonly strength: EvidenceStrength;
+  readonly contributions: readonly DimensionContribution[];
+}
+```
+
+#### `HypothesisManager` (`./hypothesis`)
+
+Keeps two calibrated `BetaModel`s per dimension, one for known-high and one for known-low outputs, fit from labeled history and updatable online, and produces the `DimensionModel[]` the Bayes Factor consumes.
+
+```ts
+new HypothesisManager(options?: {
+  dimensions?: ReadonlyArray<{ dimension: string; weight?: number; priorHigh?: BetaParams; priorLow?: BetaParams }>;
+  defaultWeight?: number;        // default 1
+  defaultPriorHigh?: BetaParams; // default Beta(2, 1)
+  defaultPriorLow?: BetaParams;  // default Beta(1, 2)
+});
+
+manager.observe(observation: LabeledObservation): this;   // fold one labeled output
+manager.fit(observations: Iterable<LabeledObservation>): this;
+manager.models(): DimensionModel[];                       // snapshot for the Bayes Factor
+manager.dimensions: string[];
+manager.observationCount(dimension: string, kind: HypothesisKind): number;
+```
+
+#### Policy (`./policy`)
+
+```ts
+type PolicyConfig = BayesFactorPolicy | DecisionTheoreticPolicy;
+
+interface BayesFactorPolicy {
+  kind: "bayes-factor";
+  passAbove: number;   // pass at or above this Bayes Factor; must be >= 1
+  failBelow: number;   // fail at or below this Bayes Factor; must be in (0, 1]
+}
+
+interface DecisionTheoreticPolicy {
+  kind: "decision-theoretic";
+  priorHighQuality: number;  // base rate of high quality, in (0, 1)
+  lossFalsePass: number;     // cost of passing a low-quality output, >= 0
+  lossFalseFail: number;     // cost of failing a high-quality output, >= 0
+  escalationCost: number;    // fixed cost of escalating to review, >= 0
+}
+
+decide(logBayesFactor: number, policy: PolicyConfig): PolicyDecision;
+posteriorHighQuality(logBayesFactor: number, priorHighQuality: number): number;
+```
+
+#### Calibration (`./calibration`)
+
+```ts
+goodnessOfFit(samples: readonly number[], params: BetaParams, alpha?: number): GoodnessOfFit;
+brierScore(predictions: readonly Prediction[]): number;
+expectedCalibrationError(predictions: readonly Prediction[], bins?: number): number;
+reliability(predictions: readonly Prediction[], bins?: number): ReliabilityBin[];
+assessAssumptions(history, models, options?): AssumptionReport; // per-dimension fit + dependence, for the gate guards
+
+interface GoodnessOfFit {
+  readonly ksStatistic: number;
+  readonly criticalValue: number;
+  readonly adequate: boolean;   // true when the Beta assumption is reasonable
+  readonly samples: number;
+}
+interface Prediction { readonly probability: number; readonly outcome: number; } // outcome 0 or 1
+```
+
+#### Dependence (`./dimensions`)
+
+```ts
+dependenceDiagnostic(history: readonly ScoreVector[], options?: { threshold?: number }): DependenceDiagnostic;
+
+interface DependenceDiagnostic {
+  readonly dimensions: readonly string[];
+  readonly pairs: readonly DimensionCorrelation[];        // all pairs, by absolute correlation desc
+  readonly flagged: readonly DimensionCorrelation[];      // pairs at or above the threshold
+  readonly maxAbsCorrelation: number;
+  readonly independenceAssumptionSafe: boolean;           // true when no pair crosses the threshold
+}
+```
+
+### 2.4 Error model
+
+A single error type carries a stable, machine-readable code. Callers branch on `error.code`, never on message text.
+
+```
+Error
+ └─ BayesOutputGateError  { code: BayesOutputGateErrorCode }
+```
+
+| Code | Raised when |
+|---|---|
+| `INVALID_CONFIG` | A malformed option (a bad policy kind, a negative weight, a CLI flag without a numeric value, an unreadable file) |
+| `INVALID_SCORE` | A score outside [0, 1], a non-finite score, a duplicate dimension, a malformed score row |
+| `INVALID_DIMENSION` | An operation referenced an unknown or invalid dimension |
+| `INVALID_HYPOTHESIS` | An invalid hypothesis label where `high` or `low` was required |
+| `INVALID_OBSERVATION` | A malformed labeled observation, too few samples for a diagnostic, a missing label |
+| `INVALID_STATE` | An operation invalid for the current state, or Web Crypto unavailable |
+| `INVALID_SNAPSHOT` | A malformed model snapshot or audit chain |
+| `NUMERIC` | A numeric domain error, for example a Beta fit producing non-finite parameters |
+
+### 2.5 Audit events
+
+Each entry has `index`, `payload`, an optional caller-supplied `timestamp`, `previousHash`, and `hash`. `append` chains a SHA-256 hash over the canonicalized entry via the Web Crypto API; `verifyChain` recomputes the chain and returns `{ valid, brokenAt? }`. The seal is an integrity seal, not a digital signature: it proves a log was not altered after sealing, not who produced it. The log is tamper-evident, meaning alteration is detectable, not unalterable. Time is never read inside the library; timestamps are caller-supplied so hashing stays deterministic.
+
+---
+
+## 3. Architecture
+
+```
++-------------------------------------------------+
+| Caller code                                     |
+| const d = evaluate(scores, models, policy)      |
+| d.action            // pass | fail | escalate    |
+| d.bayesFactor       // the evidence ratio        |
+| d.contributions     // per-dimension breakdown   |
++-----------------------+-------------------------+
+                        | per-dimension quality scores
+                        v
++-------------------------------------------------+
+| Gate orchestrator (gate)                        |
+| - Calibrated Beta models (beta)                  |
+| - Hypothesis manager (hypothesis)                |
+| - Likelihoods (likelihood)                       |
+| - Bayes Factor + Jeffreys scale (bayesfactor)    |
+| - Decision policy (policy)                        |
+| - Dependence diagnostic (dimensions)             |
+| - Calibration measurement (calibration)          |
+| - Tool adapter (adapter)                          |
+| - Audit trail (audit)                             |
++-----------------------+-------------------------+
+                        | GateDecision
+                        v
+                  Caller acts
+```
+
+### 3.1 The calibrated Beta model
+
+The computational primitive is `BetaModel` (`./beta`), a Beta distribution over a score in [0, 1]. It is fit from labeled scores by method of moments, regularized by a prior Beta treated as `priorA + priorB` pseudo-observations carrying the prior's own mean and variance, and updated online from sufficient statistics (count, sum, sum of squares) so a cold model returns its prior and a warm model is data-driven. Both Bayes Factor modes reduce to this engine. A `snapshot` and `fromSnapshot` make a model serializable across processes.
+
+### 3.2 The hypothesis manager
+
+`HypothesisManager` (`./hypothesis`) keeps a high and a low `BetaModel` per dimension plus a weight, calibrated from `LabeledObservation`s. The weakly-informative defaults, Beta(2, 1) for high and Beta(1, 2) for low with only three pseudo-observations of concentration, let labeled data dominate quickly. `models()` snapshots the current calibration as the `DimensionModel[]` the Bayes Factor consumes.
+
+### 3.3 Likelihoods
+
+`./likelihood` provides both closed-form modes: the calibrated Beta log-density of a continuous score under a hypothesis (`logScoreLikelihood`), and the Beta-Binomial marginal likelihood of binary pass/fail outcomes under a hypothesis's Beta prior (`logBinaryMarginalLikelihood`). `logVectorLikelihood` sums the weighted per-dimension log-density of a score vector under one hypothesis and reports how many dimensions matched, so a caller can detect an output that scored no modeled dimension.
+
+### 3.4 The Bayes Factor
+
+`bayesFactor` (`./bayesfactor`) computes the combined natural-log Bayes Factor as the weighted sum of per-dimension differences between the high-hypothesis and low-hypothesis Beta log-densities, over the dimensions that have both a score and a model. Boundary scores are clamped inward by a small epsilon so a 0 or 1 never produces a non-finite log-density. `jeffreysStrength` maps the log-Bayes-Factor to the seven-way Jeffreys-scale category using the symmetric boundaries 3, 10, and 100.
+
+### 3.5 The decision policy
+
+`decide` (`./policy`) applies a policy to the log-Bayes-Factor. The Bayes Factor policy passes at or above `passAbove`, fails at or below `failBelow`, and escalates in between. The decision-theoretic policy converts the log-Bayes-Factor to a posterior probability of high quality through an explicit prior (`posteriorHighQuality`, via posterior log-odds equal log-Bayes-Factor plus prior log-odds, with a numerically stable logistic), then chooses the action minimizing expected loss under the asymmetric costs of a false pass, a false fail, and escalation.
+
+### 3.6 The dependence diagnostic
+
+`dependenceDiagnostic` (`./dimensions`) measures pairwise Pearson correlation between dimensions across a history of score vectors, over the rows where both dimensions are present, and flags pairs at or above a threshold (default 0.5). The combined Bayes Factor assumes the dimensions are conditionally independent given the hypothesis; a flagged pair warns that correlated dimensions will double-count evidence and inflate the Bayes Factor. The diagnostic is informational; the caller decides whether to drop, merge, or down-weight a flagged dimension.
+
+### 3.7 Calibration measurement
+
+`./calibration` measures trust in two layers, in order. First, `goodnessOfFit` tests whether the per-dimension Beta assumption holds, by the Kolmogorov-Smirnov statistic against the fitted Beta with an asymptotic critical value; when it fails, the density-ratio likelihood should not be trusted for those scores. Second, once the gate emits posterior probabilities, `brierScore`, `expectedCalibrationError`, and `reliability` measure whether those probabilities match realized outcomes. Calibration is measured, never asserted.
+
+### 3.8 The gate orchestrator
+
+`evaluate` (`./gate`) ties the calibrated models, the Bayes Factor, and the policy into one call. `OutputGate` wraps fixed models and a fixed policy. `OutputGateMonitor` wraps the same pipeline with a tamper-evident audit chain and online recalibration: `record` evaluates and seals each decision, `observe` and `fit` fold labeled outcomes back into the calibration, and `auditTrail` returns the sealed chain.
+
+### 3.9 The tool adapter
+
+`bayesOutputGateTool` (`./adapter`) exposes the whole gate as a framework-agnostic tool: a name (`bayes_output_gate`), a description, a JSON Schema for the input (scores, models, optional policy), and a handler. The shape matches what MCP servers and LLM tool-calling APIs expect. Input arriving from a model is validated defensively, and the output is made JSON-safe (non-finite numbers become null) so it survives serialization across a tool boundary.
+
+### 3.10 Audit trail
+
+`AuditChain` (`./audit`) records decisions append-only. `append` chains a SHA-256 hash over the canonicalized entry via the Web Crypto API; `verifyChain` recomputes and reports the first broken index; `sha256Hex` is the underlying digest. Canonical JSON serialization (key-sorted) makes the chain reproducible across runtimes. The log is tamper-evident: any alteration of a past entry breaks the chain and is detected.
+
+---
+
+## 4. Operational SLOs
+
+The library is small; targets here are runtime characteristics, not service SLOs.
+
+| Target | Budget |
+|---|---|
+| Runtime dependencies (required) | 0 |
+| ESM core facade (`import { evaluate }`) | <= 8 KB brotli |
+| Bayes Factor | exact closed-form Beta log-density ratio, summed in log space |
+| Calibration | measured by goodness-of-fit, Brier score, and ECE, not asserted |
+| Engines | Node >= 20.0.0, tested on 20, 22, and 24 |
+| Node-free core | the audit seal uses Web Crypto, not node:crypto |
+
+Bundle budgets are enforced by `size-limit` in CI.
+
+Optional peers `@takk/keymesh` and `@takk/modelchain` are not required to run; they are integration points and the core takes no dependency on them.
+
+---
+
+## 5. Stability promise
+
+### 5.1 What counts as the public API
+
+For 1.0.0 onward:
+
+- Every name exported from the root and from each subpath export.
+- Every type, interface, class shape, function signature, and discriminated-union variant reachable from those exports.
+- The shape of `QualityScore`, `ScoreVector`, `DimensionModel`, `LabeledObservation`, `BayesFactorResult`, `GateDecision`, `PolicyConfig`, the calibration types, and every audit type.
+- The CLI flags and subcommands of `bayesoutputgate` and its exit codes.
+- The JSON schema of the tool input and of an audit chain.
+
+Not part of the public API:
+
+- Anything inside `src/` that is not re-exported from a public entry point.
+- The internal numerics of the models (the special functions, the Beta fit regularization constants).
+- The format of any debug output.
+
+The adapter tool (`bayesOutputGateTool`) and its JSON Schema are stable, but the integration with a specific external runtime is the consumer's responsibility; the gate returns a recommendation and does not act.
+
+### 5.2 SemVer policy
+
+First cut is 1.0.0.
+
+| Change | Bump |
+|---|---|
+| Bug fix, internal refactor, doc-only | patch (`1.0.0 -> 1.0.1`) |
+| New optional export, new optional field, new policy, new entry point | minor (`1.0.0 -> 1.1.0`) |
+| Removing or renaming an export, a signature change, an audit-chain schema change, a CLI flag removal | major (`1.0.0 -> 2.0.0`), only after a deprecation cycle |
+
+Prerelease channels are `alpha`, `beta`, and `rc`, published under the matching npm dist-tag.
+
+### 5.3 Deprecation policy
+
+Breaking a public API requires:
+
+1. **Announce** the deprecation in a minor release of the current major: add `@deprecated` JSDoc on the export.
+2. **Ship** the deprecated API for at least one further minor of the same major. Consumers must always have a non-deprecated path.
+3. **Remove** only in the next major release, accompanied by a `MIGRATING.md` with a migration recipe.
+
+Security-driven exceptions ship in the next patch across all supported majors with a `### Security` CHANGELOG entry. Report security issues to davcavalcante@proton.me.
+
+### 5.4 License and provenance invariants
+
+- License stays Apache-2.0 within a major.
+- `NOTICE` is preserved verbatim in the tarball.
+- Every release is published with npm provenance (`--provenance`, an OIDC SLSA attestation by GitHub Actions). Consumers can verify via `npm view @takk/bayesoutputgate@<version> --json | jq .dist.attestations`.
+
+---
+
+## 6. CLI
+
+The `bayesoutputgate` binary exposes four subcommands. History is a JSON array of labeled observations (`{ scores, label }`); scores is a JSON array of score vectors (each an array of `{ dimension, value }` or an object map), or a CSV with a header row of dimension names and one row of values per output.
+
+### 6.1 `gate <history.json> <scores.json>`
+
+Fits the two hypotheses from labeled history, then decides each output's scores under a Bayes Factor policy, printing the action, the Bayes Factor, and the strength per output.
+
+### 6.2 `bayes-factor <models.json> <scores.json>`
+
+Computes the Bayes Factor for each output against an explicit array of dimension models, printing the Bayes Factor, the strength, and the favored hypothesis per output.
+
+### 6.3 `calibrate <history.json>`
+
+Fits from labeled history, then reports the goodness-of-fit per dimension for both hypotheses and the dependence diagnostic across dimensions.
+
+### 6.4 `audit-verify <chain.json>`
+
+Verifies the integrity of a sealed decision audit-chain JSON file.
+
+| Flag | Meaning |
+|---|---|
+| `--pass-above` | Bayes Factor pass threshold for `gate` (default 10) |
+| `--fail-below` | Bayes Factor fail threshold for `gate` (default 0.1) |
+| `--json` | Emit machine-readable JSON instead of text |
+| `--help`, `-h` | Show help |
+| `--version`, `-v` | Show the version |
+
+### 6.5 Exit codes
+
+| Code | Meaning |
+|---|---|
+| `0` | Success (all outputs passed, or an informational command) |
+| `2` | Usage or input error (bad flags, missing file, malformed input) |
+| `20` | A broken audit chain (`audit-verify`) |
+| `30` | A fail decision (`gate`) |
+| `40` | An escalate decision (`gate`) |
+
+---
+
+## 7. Runtime expectations
+
+- BayesOutputGate is a library; it does not call out to any service at import time and makes no outbound network calls of its own.
+- The Bayes Factor is exact in closed form given the calibrated Beta models. The fit is deterministic given the same data.
+- All stochastic routines (the posterior-predictive sample helpers) are driven by a seedable generator, so any sampling is reproducible and therefore auditable.
+- The gate produces a pass, fail, or escalate recommendation; it does not act on your outputs. Your orchestrator consumes the decision and acts.
+- Decisions are calibrated GIVEN the model. The numbers are exactly as trustworthy as the Beta family fits the true score distribution; goodness-of-fit and the dependence diagnostic are provided so the caller can detect when the assumptions break, and decision calibration is measured rather than assumed.
+- The only asynchronous surfaces are the audit append and verify, which await the Web Crypto digest, and the file loaders, which await disk reads.
+
+---
+
+## 8. Test surface
+
+- Unit tests for every module: the special functions, the random generators, the canonical serializer, the calibrated Beta model, the hypothesis manager, the likelihoods, the Bayes Factor, the dependence diagnostic, the decision policy, the calibration measurement, the gate, the audit chain, the tool adapter, the node loaders, and the CLI.
+- Oracle tests that verify the Beta log-density and Beta-Binomial marginal against closed forms, the Bayes Factor against the Jeffreys boundaries, and the decision-theoretic policy against expected loss.
+- Audit tests that confirm a known SHA-256 digest, that chains link, and that tampering and broken links are detected.
+- Assumption-guard tests that confirm the gate escalates on an inadequate goodness-of-fit or an unsafe dependence and attaches the report to the decision.
+- A distribution smoke test that exercises the compiled ESM and CJS artifacts and spawns the compiled CLI as a single Node process.
+- Five runnable examples and a value benchmark under `examples/` and `benchmarks/`, executed against the compiled `dist`; every number in the docs comes from real execution.
+
+Coverage thresholds enforced via `vitest.config.ts`: `lines >= 80`, `functions >= 80`, `statements >= 80`, `branches >= 80`. The measured coverage of 1.0.0 is statements 94.64%, branches 87.58%, functions 96.24%, lines 95.91%, over 90 tests in 15 suites.
+
+---
+
+## 9. Non-goals (in 1.0)
+
+- Per-output, per-dimension automatic gating (1.0 assesses goodness-of-fit and dependence over the calibration history and escalates the whole gate via opt-in guards; a finer-grained per-output adequacy signal is a planned addition).
+- A built-in scorer or judge (1.0 consumes scores from any scorer you already run; it does not produce them).
+- Streaming, multi-rater aggregation, or inter-annotator agreement (planned for a later release).
+- Drift and change-point detection on the calibrated models (planned for a later release).
+- Non-Beta score families, for example a calibrated mixture or a nonparametric density (the 1.0 likelihood is Beta; planned for a later release).
+- Turnkey runtime integrations that act on the decision (the 1.0 gate recommends; your orchestrator acts; bindings planned for a later release).
+- Signed and timestamped audit seals (the current seal is integrity-only and tamper-evident, not a signature).
+- A hosted validation dashboard and federated calibration sharing (separate products).
+
+---
+
+**Owner:** David C Cavalcante, davcavalcante@proton.me, Takk Innovate Studio, https://takk.ag
+**Repository:** github.com/davccavalcante/bayesoutputgate