[PUBLISHED ON NPMJS] @takk/bayescausal@1.0.0

STATUS: PUBLISHED ON NPMJS. This version was published to the npm registry on 2026-06-23T12:08:53Z with provenance attestation. View on npm: https://www.npmjs.com/package/@takk/bayescausal/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-23T09:40:45Z

Initial stable release. A universal, zero-runtime-dependency NPM library and CLI for declarative Bayesian networks and calibrated incident root cause inference, the diagnostic layer for Massive Intelligence (IM) systems and non-human entities. You declare the causal graph between your components once, feed the symptoms observed during an incident as evidence, and BayesCausal returns a ranked list of probable root causes with calibrated posteriors, a most probable joint explanation, and a human-readable report, the calibrated answer to "what most probably broke" instead of hours of manual forensics.

Added

Graph, conditional probability tables, and evidence

• Factor algebra (@takk/bayescausal/factor): a dense, row-major Factor with product, sum-marginalization, max-marginalization with an argmax traceback, reduction by evidence, and normalization, the four operations every exact engine needs, implemented as pure arithmetic over integer state indices with zero dependencies.
• Conditional probability tables (@takk/bayescausal/cpt): validateCpt, prior, cptFrom, uniformCpt, and noisyOr, the canonical compact model where several independent causes each have a chance to trigger a symptom, so a large diagnostic graph is authorable without hundreds of hand numbers.
• The directed acyclic graph (@takk/bayescausal/network): BayesNetwork and buildNetwork validate that every parent exists, that no variable depends on itself, that the tables have the right shape, and that the graph is acyclic, then fix a topological order. Exposes the moral graph, per-node factors, roles, and fault states.
• Evidence (@takk/bayescausal/evidence): hard evidence that pins a variable to a state, plus virtual (likelihood) evidence for noisy detectors, both reduced to factors the engines understand.

Exact inference

• Variable elimination (@takk/bayescausal/inference): the exact engine, with a min-degree elimination order, single-variable and all-variable marginals, and the probability of the evidence (the normalizing constant, a near-zero value flags a model that finds the evidence almost impossible).
• Junction-tree belief propagation (@takk/bayescausal/junction): every variable's posterior in a single two-pass Shafer-Shenoy sweep over a clique tree built from a triangulation, a maximum-weight spanning tree that guarantees the running-intersection property. Exact, and verified equal to variable elimination in the test suite.
• Most probable explanation (@takk/bayescausal/mpe): the single joint assignment of every unobserved variable that maximizes the joint probability with the evidence, by max-product elimination plus traceback, the internally consistent incident narrative.

Approximate inference, honest about its error

• Loopy belief propagation (@takk/bayescausal/loopy): sum-product message passing directly on the factor graph for graphs too dense for exact inference. Exact on a tree, an approximation on a loopy graph, and it reports whether it converged, the iteration count, and the final message change rather than silently returning a non-converged result as if it were exact.
• Likelihood weighting and Gibbs sampling (@takk/bayescausal/sampling): Monte Carlo engines for very large graphs and an independent cross-check on the exact engines, each reporting a Jeffreys credible interval per state and, for likelihood weighting, the effective sample size, so the Monte Carlo error and the degradation under unlikely evidence are visible rather than hidden.

The do-operator, the move from association to causation

• Interventions (@takk/bayescausal/intervene): intervene mutilates the network by the do-operator, each intervened variable becomes a root fixed to its set value with its parents severed, so P(Y | do(X = x)) answers "if we force this config back to known-good, what happens", the question incident response actually asks. interventionalMarginal runs any inference engine on the mutilated graph; causalEffect reports the interventional and the observational effect side by side and flags confounded when they disagree, the signature of confounding the declared structure encodes. Counterfactual queries (abduction over exogenous noise) need a structural model beyond conditional probability tables and are on the roadmap, not in this release; this layer is interventional, and says so.

Diagnosis and explanation

• Root cause ranking (@takk/bayescausal/diagnose): ranks each cause by its posterior probability of being in a fault state, with the prior and the lift (posterior over prior) for context, so an operator sees not just which cause is most likely now but how much the evidence moved it. Causes are declared by role, by explicit fault states, or fall back to the rarest state under the prior.
• Explanation generator (@takk/bayescausal/explain): turns a diagnosis and an optional most probable explanation into a short, deterministic, templated report, no Massive Intelligence (IM) model is called, with a closing line that the posteriors are only as good as the declared causal model.

Online parameter learning

• Dirichlet learner (@takk/bayescausal/learn): online parameter learning by the Dirichlet-multinomial conjugate update. The structure stays declared by the engineer; the numbers in the tables are learned from observed cases in closed form with no retraining, with a credible interval per cell. Structure learning, discovering the edges themselves, is deliberately out of scope for this release.

Templates, evaluation, and the observability adapter

• Prebuilt incident graphs (@takk/bayescausal/templates): a ready noisy-OR causal graph for a Massive Intelligence (IM) serving stack (provider degradation, traffic spike, model deprecation, configuration drift as causes; latency, error rate, output quality, and cost as symptoms), a starting point to adapt rather than a universal truth.
• Diagnosis evaluation (@takk/bayescausal/calculator): evaluateDiagnosis runs the real engine over many incidents drawn by ancestral sampling from the network and reports top-1 accuracy, mean reciprocal rank, and the Brier score (are the posteriors calibrated, not just ordered correctly). Every number comes from real execution.
• Observability adapter (@takk/bayescausal/adapter): createDiagnoser binds a network to a diagnosis with no vendor SDK, an evidence mapper is injected, and thresholdMapper turns numeric metrics into observed states by simple bins, the dependency-free way for a non-human entity (NHE) to diagnose itself from its own telemetry.

Audit and facade

• Tamper-evident audit trail (@takk/bayescausal/audit): an append-only AuditLog of evidence, diagnosis, and decision events with a SHA-256 hash chain you append to and verify, plus sha256Hex. It uses the Web Crypto API, not node:crypto, so the surface stays node-free. It is tamper-evident, any later edit is detectable, not an unalterable record.
• Facade: createNetwork / CausalNetwork wires the graph, the engines, the diagnosis, the explanation, and the do-operator into one object. Methods: observe, clear, reset, posterior, marginals, mpe, probabilityOfEvidence, diagnose, explain, intervene (returns a new mutilated network), causalEffect, snapshot, load, plus variables, evidence, and structure. Config: nodes, method (exact, junction-tree, loopy, likelihood-weighting, gibbs), evidence, seed, samples, and an observer seam for telemetry and governance.

Persistence and CLI

• @takk/bayescausal/node ships createFileStore, a durable file-backed snapshot store using node:fs and node:path with atomic writes (write to a temporary file, then rename), so a learned network survives a restart with no database. It is the only entry point that touches a Node built-in.
• Binary bayescausal exposed via package.json#bin. bayescausal demo diagnoses a built-in serving incident; bayescausal diagnose reads a JSON network from a file or stdin and prints the ranked root causes and the explanation; bayescausal evaluate measures top-1 accuracy, mean reciprocal rank, and the Brier score over simulated incidents. Standard sysexits-style exit codes: 0 ok, 64 usage, 65 data error, 66 missing input.

Distribution

• Twenty entry points, each a subpath export with split import/require conditions: the root facade plus factor, cpt, network, evidence, inference, junction, loopy, sampling, mpe, intervene, diagnose, explain, learn, templates, calculator, adapter, audit, node, and edge.
• Dual ESM + CJS bundles built with tsup 8, with separate .d.ts and .d.cts type files per entry point.
• Node-free, platform-neutral core importable in Node, edge runtimes, and the browser; @takk/bayescausal/edge re-exports it verbatim alongside the audit trail.
• Zero required runtime dependencies. @takk/keymesh and @takk/modelchain are optional peer dependencies.

Documentation and examples

• A complete project site (index.html, 404.html) and documentation set (README.md, SPEC.md, SECURITY.md, PRIVACY.md, CONTRIBUTING.md, RELEASING.md, CLA.md, CODE_OF_CONDUCT.md), with five JSON-LD structured-data blocks, an Open Graph card, a bespoke hero diagram, and a robots and sitemap pair.
• Seven runnable, offline, deterministic examples: quickstart, the...