[PUBLISHED ON NPMJS] @takk/bayesoutputgate@1.0.0

STATUS: PUBLISHED ON NPMJS. This version was published to the npm registry on 2026-06-24T00:31:32Z with provenance attestation. View on npm: https://www.npmjs.com/package/@takk/bayesoutputgate/v/1.0.0

STATUS: REVIEW REQUIRED, NOT YET ON NPMJS. This GitHub Release was created by the release.yml workflow. The Creator must review the contents (tag, changelog, attached commit, pack-smoke result in the workflow logs) and then explicitly run npm-publish.yml to publish this version to the npm registry.

[1.0.0] - 2026-06-23T22:58:26Z

Initial stable release. A universal, zero-runtime-dependency NPM library and CLI for calibrated output validation with the Bayes Factor, the validation layer for Massive Intelligence (IM) systems and non-human entities (NHEs). Feed the per-dimension quality scores of an output, from an LLM-as-judge, a classifier, or a regex; BayesOutputGate weighs a high-quality hypothesis against a low-quality one, computes the Bayes Factor between them, interprets it on the Jeffreys scale, and returns a calibrated pass, fail, or escalate decision, the principled answer to "is this output good enough to ship" instead of an arbitrary threshold.

Added

The calibrated Beta engine

• Beta model (@takk/bayesoutputgate/beta): BetaModel, a calibrated Beta distribution over a quality score in [0, 1] that both Bayes Factor modes are built on. It is fit from labeled scores by method of moments, regularized by a prior Beta treated as pseudo-observations carrying the prior's own mean and variance, and updated online from sufficient statistics, so a cold model returns its prior and a warm model is data-driven. fromSamples, fromSnapshot, observe, params, mean, logDensity, and snapshot make it serializable across processes.

Hypotheses and likelihoods

• Hypothesis manager (@takk/bayesoutputgate/hypothesis): HypothesisManager keeps a high-quality and a low-quality BetaModel per dimension plus a weight, calibrated from labeled observations and updatable online. The weakly-informative defaults, Beta(2, 1) for high and Beta(1, 2) for low with only a few pseudo-observations of concentration, let labeled data dominate quickly. models() snapshots the calibration as the dimension models the Bayes Factor consumes.
• Likelihoods (@takk/bayesoutputgate/likelihood): logScoreLikelihood (the Beta log-density of a continuous score), logBinaryMarginalLikelihood (the Beta-Binomial marginal for binary pass/fail outcomes), toScoreMap, and logVectorLikelihood (the weighted per-dimension log-likelihood of a score vector under one hypothesis, with a matched-dimension count).

The Bayes Factor and the decision policy

• Bayes Factor (@takk/bayesoutputgate/bayesfactor): bayesFactor 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, with boundary scores clamped inward so a 0 or 1 never produces a non-finite density. jeffreysStrength maps the log-Bayes-Factor to a seven-way Jeffreys-scale category using the symmetric boundaries 3, 10, and 100 (Kass and Raftery, 1995).
• Decision policy (@takk/bayesoutputgate/policy): decide and posteriorHighQuality. The Bayes Factor policy passes at or above passAbove, fails at or below failBelow, and escalates in between. The decision-theoretic policy converts the Bayes Factor to a posterior probability of high quality through an explicit prior (posterior log-odds equal log-Bayes-Factor plus prior log-odds, via a numerically stable logistic), then chooses the action that minimizes expected loss under the asymmetric costs of a false pass, a false fail, and escalation, which makes the gate utility-aware rather than a re-skinned threshold.

Trust diagnostics

• Dependence diagnostic (@takk/bayesoutputgate/dimensions): dependenceDiagnostic measures pairwise Pearson correlation between dimensions across a history of score vectors and flags pairs at or above a threshold, because correlated dimensions double-count evidence and inflate the Bayes Factor. It surfaces whether the conditional-independence assumption behind the summed log-Bayes-Factors is safe.
• Calibration measurement (@takk/bayesoutputgate/calibration): goodnessOfFit (the Kolmogorov-Smirnov statistic of observed scores against a fitted Beta, with an asymptotic critical value), brierScore, expectedCalibrationError, reliability, and assessAssumptions (the per-dimension fit and the dependence diagnostic combined into one report the gate guards consult). Goodness-of-fit comes first, because if the Beta assumption fails the Bayes Factor is optimizing the wrong model; decision calibration then measures whether the posterior probabilities match realized outcomes. Calibration is measured, never asserted.

The gate, the audit trail, and the tool

• Gate orchestrator (@takk/bayesoutputgate/gate): evaluate ties the calibrated models, the Bayes Factor, and the policy into one call returning a GateDecision. OutputGate wraps fixed models and a fixed policy. OutputGateMonitor wraps the same pipeline with a tamper-evident audit chain and online recalibration: it seals each decision, folds labeled outcomes back into the calibration, and returns the sealed chain.
• Assumption guards (GateGuards, AssumptionReport): evaluate, OutputGate, and OutputGateMonitor accept guards that escalate to human review rather than trusting a Bayes Factor from a misspecified model. With requireGoodnessOfFit or requireIndependence, a violated assumption forces the action to escalate with rationale "assumption-violated", and the report is attached to every GateDecision. The monitor reassesses the report from the history on each batch fit.
• Tamper-evident audit trail (@takk/bayesoutputgate/audit): an append-only AuditChain with a SHA-256 hash chain you append to and verifyChain, plus sha256Hex and GENESIS_HASH. Each entry hashes its canonical JSON with the previous entry's hash, so any later edit breaks every link after it. It uses the Web Crypto API, not node:crypto, so the surface stays node-free, and timestamps are caller-supplied so hashing is deterministic.
• Tool adapter (@takk/bayesoutputgate/adapter): bayesOutputGateTool, runTool, and describeTool, a framework-agnostic tool definition (name bayes_output_gate, description, JSON Schema, handler) matching what MCP servers and LLM tool-calling APIs expect, so a non-human entity (NHE) can validate its own output before acting. Input arriving from a model is parsed defensively and the output is made JSON-safe.

Persistence and CLI

• @takk/bayesoutputgate/node ships readJsonFile, loadLabeledObservations, parseCsvScores, and loadScores over node:fs, defensively validated, and re-exports the full core. It is the only entry point that touches a Node built-in.
• Binary bayesoutputgate exposed via package.json#bin. bayesoutputgate gate fits from labeled history and decides each output, bayes-factor computes the Bayes Factor against explicit dimension models, calibrate reports goodness-of-fit per dimension and the dependence diagnostic, and audit-verify checks a sealed decision chain. Flags --pass-above, --fail-below, and --json. Single-process exit codes: 0 ok, 2 usage or input error, 30 a fail decision, 40 an escalate decision, 20 a broken audit chain.

Distribution

• Thirteen entry points, each a subpath export with split import/require conditions: the root facade plus beta, hypothesis, likelihood, bayesfactor, dimensions, policy, calibration, gate, audit, adapter, node, and edge.
• Dual ESM + CJS bundles built with tsup 8 in a single neutral-platform pass, with separate .d.ts and .d.cts type files per entry point, and the CLI shebang preserved from source.
• Node-free, platform-neutral core importable in Node, edge runtimes, and the browser; @takk/bayesoutputgate/edge re-exports it verbatim, audit trail included, since Web Crypto is present there too.
• Zero required runtime dependencies. @takk/keymesh and @takk/modelchain are optional peer dependencies, integration points the core takes no dependency on.

Documentation and project site

• A complete project site (index.html, 404.html) and documentation set (README.md, SPEC.md, SECURITY.md, PRIVACY.md, CLA.md, CODE_OF_CONDUCT.md, .github/CONTRIBUTING.md, .github/RELEASING.md), with five JSON-LD structured-data blocks, an Open Graph card, a bespoke hero diagram that traces the flow from per-dimension scores through the Bayes Factor and the Jeffreys scale to a pass, fail, or escalate decision sealed in the audit trail, and a robots and sitemap pair. Every claim is phrased honestly: the Bayes Factor is calibrated from the user's own labeled data, the goodness-of-fit and dependence checks are diagnostics the caller inspects, the gate returns a recommendation an orchestrator consumes rather than acting itself, and "calibrated" is backed by the metrics the library measures.

Examples and benchmark

• Five runnable, offline, deterministic examples under examples/, executed end-to-end against the compiled dist: the basic gate, the decision-theoretic policy, the assumption guards, the MCP tool adapter, and node-free edge usage with a verifiable audit chain.
• A value benchmark (benchmarks/value.ts) executed against the compiled dist, scoring the gate against fairly-tuned fixed thresholds (on the mean and on the min of two dimensions) on a held-out test set the gate never calibrates on, under an asymmetric loss (false pass 10, false fail 2, escalation 1), with a "masking" low-quality output that scores high on factuality but low on safety. When the Beta assumption holds, the calibrated multi-dimension gate cuts average loss to 0.456 against the best tuned threshold's 0.619 (accuracy 93.7% against 78.6%), escalating the ambiguous 23.7% to review. When the assumption is violated (a strongly bimodal score distribution), goodness-of-fit detects it, the gate keeps the lowest loss (0.869 against about 0.986) with zero false passes, and the goodness-of-fit guard escalates every output rather than acting on a model it knows is misspecified. The gate sustains roughly 2.7 million two-dimension decisions per second. Every number is from real execution, never invented.

Quality

• 90 tests across 15 suites passing under Vitest 4, including the special functions verified against closed forms, the Beta-Binomial marginal verified against its uniform-prior identity, the calibrated Beta fit and online update, the Bayes Factor verified against the Jeffreys boundaries, the decision-theoretic policy verified against expected loss, the goodness-of-fit and dependence diagnostics, the assumption guards that escalate on a violated assumption, and the audit chain verified against a known SHA-256 digest and to detect tampering and broken links.
• Coverage: statements 94.64%, branches 87.58%, functions 96.24%, lines 95.91%.
• Lint clean under Biome 2.5. Typecheck clean under TypeScript 6 in maximum strict mode (exactOptionalPropertyTypes, noUncheckedIndexedAccess, verbatimModuleSyntax, noPropertyAccessFromIndexSignature, isolatedModules).
• publint clean and @arethetypeswrong/cli green across all thirteen subpaths and package.json.
• size-limit under budget on every bundle (brotli core facade 5.29 kB against an 8 kB limit, bayes factor 1.03 kB, gate 3.01 kB, edge barrel 5.29 kB, node entry 5.95 kB).
• Distribution smoke test exercising the compiled ESM and CJS artifacts and every subpath, with the compiled CLI spawned as a single Node process. The full suite, the smoke test, and the CLI are re-verified on Node 24.

Security

• Every release is published to the npm registry with npm publish --provenance, carrying a SLSA provenance attestation generated by GitHub Actions over OIDC. Consumers can verify with npm view @takk/bayesoutputgate --json | jq .dist.attestations.
• Tamper-evident audit trail backed by a SHA-256 hash chain, suitable as compliance evidence (EU AI Act) that the recorded decisions were not altered after sealing. It is an integrity seal, not a signature.
• Zero runtime dependencies, the smallest possible supply-chain surface. The node-free core uses the Web Crypto API, not node:crypto.

Licensing

• Licensed under the Apache License, Version 2.0. The NOTICE file ships in the tarball alongside LICENSE.

Engines

• Node >=20.0.0. Verified locally on Node 22 and Node 24; the continuous integration matrix covers Node 20, 22, and 24.