@takk/bayesoutputgate 1.0.0

package/dist/cli/index.cjs

@@ -0,0 +1,968 @@
+#!/usr/bin/env node
+'use strict';
+
+var fs = require('fs');
+var path = require('path');
+
+// src/canonical.ts
+function canonicalize(value) {
+  return serialize(value);
+}
+function serialize(value) {
+  if (value === null) {
+    return "null";
+  }
+  const kind = typeof value;
+  if (kind === "number") {
+    return Number.isFinite(value) ? String(value) : "null";
+  }
+  if (kind === "boolean") {
+    return value ? "true" : "false";
+  }
+  if (kind === "string") {
+    return JSON.stringify(value);
+  }
+  if (Array.isArray(value)) {
+    return `[${value.map((item) => serialize(item)).join(",")}]`;
+  }
+  if (kind === "object") {
+    const entries = Object.entries(value).filter(([, v]) => v !== void 0).sort(([left], [right]) => left < right ? -1 : left > right ? 1 : 0);
+    const body = entries.map(([key, v]) => `${JSON.stringify(key)}:${serialize(v)}`).join(",");
+    return `{${body}}`;
+  }
+  return "null";
+}
+
+// src/audit/index.ts
+var GENESIS_HASH = "0".repeat(64);
+async function sha256Hex(input) {
+  const bytes = new TextEncoder().encode(input);
+  const digest = await crypto.subtle.digest("SHA-256", bytes);
+  return Array.from(new Uint8Array(digest)).map((byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+function recordOf(index, payload, previousHash, timestamp) {
+  return timestamp !== void 0 ? { index, timestamp, payload, previousHash } : { index, payload, previousHash };
+}
+async function verifyChain(entries) {
+  for (let i = 0; i < entries.length; i++) {
+    const entry = entries[i];
+    const expectedPrevious = i === 0 ? GENESIS_HASH : entries[i - 1].hash;
+    if (entry.index !== i || entry.previousHash !== expectedPrevious) {
+      return { valid: false, brokenAt: i };
+    }
+    const record = recordOf(entry.index, entry.payload, entry.previousHash, entry.timestamp);
+    const recomputed = await sha256Hex(canonicalize(record));
+    if (recomputed !== entry.hash) {
+      return { valid: false, brokenAt: i };
+    }
+  }
+  return { valid: true };
+}
+
+// src/errors.ts
+var BayesOutputGateError = class _BayesOutputGateError extends Error {
+  code;
+  constructor(code, message) {
+    super(message);
+    this.name = "BayesOutputGateError";
+    this.code = code;
+    Object.setPrototypeOf(this, _BayesOutputGateError.prototype);
+  }
+};
+function invariant(condition, code, message) {
+  if (!condition) {
+    throw new BayesOutputGateError(code, message);
+  }
+}
+
+// src/mathspecial.ts
+var LN_SQRT_2PI = 0.9189385332046728;
+var LANCZOS_G = 7;
+var LANCZOS_COEFFICIENTS = [
+  0.9999999999998099,
+  676.5203681218851,
+  -1259.1392167224028,
+  771.3234287776531,
+  -176.6150291621406,
+  12.507343278686905,
+  -0.13857109526572012,
+  9984369578019572e-21,
+  15056327351493116e-23
+];
+function lgamma(x) {
+  if (!Number.isFinite(x) || x <= 0) {
+    throw new BayesOutputGateError(
+      "NUMERIC",
+      `lgamma requires a positive finite argument, got ${x}`
+    );
+  }
+  const z = x - 1;
+  let acc = LANCZOS_COEFFICIENTS[0];
+  for (let i = 1; i < LANCZOS_COEFFICIENTS.length; i++) {
+    acc += LANCZOS_COEFFICIENTS[i] / (z + i);
+  }
+  const t = z + LANCZOS_G + 0.5;
+  return LN_SQRT_2PI + (z + 0.5) * Math.log(t) - t + Math.log(acc);
+}
+function lbeta(a, b) {
+  return lgamma(a) + lgamma(b) - lgamma(a + b);
+}
+function betaLogDensity(x, a, b) {
+  if (a <= 0 || b <= 0) {
+    throw new BayesOutputGateError(
+      "NUMERIC",
+      `Beta shape parameters must be positive, got a=${a}, b=${b}`
+    );
+  }
+  if (x < 0 || x > 1 || !Number.isFinite(x)) {
+    return Number.NEGATIVE_INFINITY;
+  }
+  if (x === 0) {
+    if (a < 1) return Number.POSITIVE_INFINITY;
+    if (a > 1) return Number.NEGATIVE_INFINITY;
+    return -lbeta(a, b) + (b - 1) * Math.log(1);
+  }
+  if (x === 1) {
+    if (b < 1) return Number.POSITIVE_INFINITY;
+    if (b > 1) return Number.NEGATIVE_INFINITY;
+    return -lbeta(a, b);
+  }
+  return (a - 1) * Math.log(x) + (b - 1) * Math.log1p(-x) - lbeta(a, b);
+}
+function clamp(x, lo, hi) {
+  if (x < lo) return lo;
+  if (x > hi) return hi;
+  return x;
+}
+function regularizedIncompleteBeta(x, a, b) {
+  if (a <= 0 || b <= 0) {
+    throw new BayesOutputGateError(
+      "NUMERIC",
+      `incomplete beta requires positive shapes, got a=${a}, b=${b}`
+    );
+  }
+  if (x <= 0) return 0;
+  if (x >= 1) return 1;
+  const logFront = lgamma(a + b) - lgamma(a) - lgamma(b) + a * Math.log(x) + b * Math.log1p(-x);
+  const front = Math.exp(logFront);
+  if (x < (a + 1) / (a + b + 2)) {
+    return front * betaContinuedFraction(x, a, b) / a;
+  }
+  return 1 - front * betaContinuedFraction(1 - x, b, a) / b;
+}
+function betaCdf(x, a, b) {
+  return regularizedIncompleteBeta(x, a, b);
+}
+function betaContinuedFraction(x, a, b) {
+  const maxIterations = 200;
+  const epsilon = 3e-12;
+  const tiny = 1e-300;
+  const qab = a + b;
+  const qap = a + 1;
+  const qam = a - 1;
+  let c = 1;
+  let d = 1 - qab * x / qap;
+  if (Math.abs(d) < tiny) d = tiny;
+  d = 1 / d;
+  let h = d;
+  for (let m = 1; m <= maxIterations; m++) {
+    const m2 = 2 * m;
+    let aa = m * (b - m) * x / ((qam + m2) * (a + m2));
+    d = 1 + aa * d;
+    if (Math.abs(d) < tiny) d = tiny;
+    c = 1 + aa / c;
+    if (Math.abs(c) < tiny) c = tiny;
+    d = 1 / d;
+    h *= d * c;
+    aa = -(a + m) * (qab + m) * x / ((a + m2) * (qap + m2));
+    d = 1 + aa * d;
+    if (Math.abs(d) < tiny) d = tiny;
+    c = 1 + aa / c;
+    if (Math.abs(c) < tiny) c = tiny;
+    d = 1 / d;
+    const delta = d * c;
+    h *= delta;
+    if (Math.abs(delta - 1) < epsilon) {
+      break;
+    }
+  }
+  return h;
+}
+
+// src/bayesfactor/index.ts
+var LN_3 = Math.log(3);
+var LN_10 = Math.log(10);
+var LN_100 = Math.log(100);
+var DENSITY_EPSILON = 1e-6;
+function jeffreysStrength(logBayesFactor) {
+  const x = logBayesFactor;
+  if (x >= LN_100) return "decisive-high";
+  if (x >= LN_10) return "strong-high";
+  if (x >= LN_3) return "substantial-high";
+  if (x > -LN_3) return "inconclusive";
+  if (x > -LN_10) return "substantial-low";
+  if (x > -LN_100) return "strong-low";
+  return "decisive-low";
+}
+function bayesFactor(scores, models) {
+  invariant(models.length > 0, "INVALID_CONFIG", "at least one dimension model is required");
+  const map = /* @__PURE__ */ new Map();
+  for (const s of scores) {
+    invariant(
+      Number.isFinite(s.value) && s.value >= 0 && s.value <= 1,
+      "INVALID_SCORE",
+      `score for "${s.dimension}" must be a finite number in [0, 1], got ${s.value}`
+    );
+    invariant(
+      !map.has(s.dimension),
+      "INVALID_SCORE",
+      `duplicate score for dimension "${s.dimension}"`
+    );
+    map.set(s.dimension, s.value);
+  }
+  const contributions = [];
+  let logBayesFactor = 0;
+  for (const model of models) {
+    const value = map.get(model.dimension);
+    if (value === void 0) {
+      continue;
+    }
+    invariant(
+      Number.isFinite(model.weight) && model.weight >= 0,
+      "INVALID_CONFIG",
+      `weight for "${model.dimension}" must be a non-negative finite number, got ${model.weight}`
+    );
+    const x = clamp(value, DENSITY_EPSILON, 1 - DENSITY_EPSILON);
+    const logHigh = betaLogDensity(x, model.high.a, model.high.b);
+    const logLow = betaLogDensity(x, model.low.a, model.low.b);
+    const weighted = model.weight * (logHigh - logLow);
+    logBayesFactor += weighted;
+    contributions.push({
+      dimension: model.dimension,
+      score: value,
+      logBayesFactor: weighted,
+      weight: model.weight
+    });
+  }
+  invariant(
+    contributions.length > 0,
+    "INVALID_SCORE",
+    "no scored dimension matched a configured dimension model"
+  );
+  invariant(Number.isFinite(logBayesFactor), "NUMERIC", "combined log-Bayes-Factor is not finite");
+  const strength = jeffreysStrength(logBayesFactor);
+  const favored = strength.endsWith("high") ? "high" : strength.endsWith("low") ? "low" : "inconclusive";
+  return {
+    logBayesFactor,
+    bayesFactor: Math.exp(logBayesFactor),
+    favored,
+    strength,
+    contributions
+  };
+}
+
+// src/dimensions/index.ts
+function dependenceDiagnostic(history, options = {}) {
+  const threshold = options.threshold ?? 0.5;
+  invariant(
+    Number.isFinite(threshold) && threshold >= 0 && threshold <= 1,
+    "INVALID_CONFIG",
+    `threshold must be in [0, 1], got ${threshold}`
+  );
+  invariant(
+    history.length >= 2,
+    "INVALID_OBSERVATION",
+    "dependence diagnostic needs at least two score vectors"
+  );
+  const dimensionSet = /* @__PURE__ */ new Set();
+  for (const vector of history) {
+    for (const score of vector) {
+      dimensionSet.add(score.dimension);
+    }
+  }
+  const dimensions = [...dimensionSet].sort();
+  const rows = history.map((vector) => {
+    const map = /* @__PURE__ */ new Map();
+    for (const score of vector) {
+      map.set(score.dimension, score.value);
+    }
+    return map;
+  });
+  const pairs = [];
+  for (let i = 0; i < dimensions.length; i++) {
+    for (let j = i + 1; j < dimensions.length; j++) {
+      const a = dimensions[i];
+      const b = dimensions[j];
+      const xs = [];
+      const ys = [];
+      for (const row of rows) {
+        const x = row.get(a);
+        const y = row.get(b);
+        if (x !== void 0 && y !== void 0) {
+          xs.push(x);
+          ys.push(y);
+        }
+      }
+      if (xs.length >= 2) {
+        const correlation = pearson(xs, ys);
+        if (Number.isFinite(correlation)) {
+          pairs.push({ a, b, correlation, samples: xs.length });
+        }
+      }
+    }
+  }
+  pairs.sort((left, right) => Math.abs(right.correlation) - Math.abs(left.correlation));
+  const maxAbsCorrelation = pairs.length > 0 ? Math.abs(pairs[0].correlation) : 0;
+  const flagged = pairs.filter((pair) => Math.abs(pair.correlation) >= threshold);
+  return {
+    dimensions,
+    pairs,
+    flagged,
+    maxAbsCorrelation,
+    independenceAssumptionSafe: flagged.length === 0
+  };
+}
+function pearson(xs, ys) {
+  const n = xs.length;
+  let sumX = 0;
+  let sumY = 0;
+  for (let i = 0; i < n; i++) {
+    sumX += xs[i];
+    sumY += ys[i];
+  }
+  const meanX = sumX / n;
+  const meanY = sumY / n;
+  let covariance = 0;
+  let varianceX = 0;
+  let varianceY = 0;
+  for (let i = 0; i < n; i++) {
+    const dx = xs[i] - meanX;
+    const dy = ys[i] - meanY;
+    covariance += dx * dy;
+    varianceX += dx * dx;
+    varianceY += dy * dy;
+  }
+  if (varianceX === 0 || varianceY === 0) {
+    return 0;
+  }
+  return covariance / Math.sqrt(varianceX * varianceY);
+}
+
+// src/calibration/index.ts
+function goodnessOfFit(samples, params, alpha = 0.05) {
+  invariant(
+    samples.length >= 5,
+    "INVALID_OBSERVATION",
+    "goodnessOfFit needs at least five samples"
+  );
+  invariant(params.a > 0 && params.b > 0, "INVALID_CONFIG", "Beta parameters must be positive");
+  const sorted = [...samples].sort((left, right) => left - right);
+  const n = sorted.length;
+  let ks = 0;
+  for (let i = 0; i < n; i++) {
+    const value = sorted[i];
+    invariant(
+      Number.isFinite(value) && value >= 0 && value <= 1,
+      "INVALID_SCORE",
+      `samples must be finite and in [0, 1], got ${value}`
+    );
+    const cdf = betaCdf(value, params.a, params.b);
+    const upper = (i + 1) / n - cdf;
+    const lower = cdf - i / n;
+    ks = Math.max(ks, upper, lower);
+  }
+  const coefficient = alpha <= 0.01 ? 1.628 : alpha <= 0.05 ? 1.358 : 1.224;
+  const criticalValue = coefficient / Math.sqrt(n);
+  return { ksStatistic: ks, criticalValue, adequate: ks <= criticalValue, samples: n };
+}
+
+// src/beta/index.ts
+var VARIANCE_FLOOR = 1e-9;
+var CONCENTRATION_FLOOR = 1e-3;
+var BetaModel = class _BetaModel {
+  priorA;
+  priorB;
+  count = 0;
+  sum = 0;
+  sumSquares = 0;
+  constructor(options = {}) {
+    const prior = options.prior ?? { a: 1, b: 1 };
+    invariant(
+      prior.a > 0 && prior.b > 0 && Number.isFinite(prior.a) && Number.isFinite(prior.b),
+      "INVALID_CONFIG",
+      `prior Beta parameters must be positive and finite, got a=${prior.a}, b=${prior.b}`
+    );
+    this.priorA = prior.a;
+    this.priorB = prior.b;
+  }
+  /** Build a model from labeled scores in one pass. */
+  static fromSamples(samples, options = {}) {
+    const model = new _BetaModel(options);
+    for (const s of samples) {
+      model.observe(s);
+    }
+    return model;
+  }
+  /** Restore a model from a snapshot. */
+  static fromSnapshot(snapshot) {
+    const model = new _BetaModel({ prior: snapshot.prior });
+    invariant(
+      snapshot.count >= 0 && Number.isFinite(snapshot.sum) && Number.isFinite(snapshot.sumSquares),
+      "INVALID_SNAPSHOT",
+      "snapshot fields must be finite and non-negative"
+    );
+    model.count = snapshot.count;
+    model.sum = snapshot.sum;
+    model.sumSquares = snapshot.sumSquares;
+    return model;
+  }
+  /** Number of real observations folded into this model so far. */
+  get observations() {
+    return this.count;
+  }
+  /** Fold a single score in [0, 1] into the model, updating its calibration online. */
+  observe(score) {
+    invariant(
+      Number.isFinite(score) && score >= 0 && score <= 1,
+      "INVALID_SCORE",
+      `score must be a finite number in [0, 1], got ${score}`
+    );
+    this.count += 1;
+    this.sum += score;
+    this.sumSquares += score * score;
+    return this;
+  }
+  /**
+   * The fitted Beta parameters. The prior is mixed in as `priorA + priorB` pseudo-observations with
+   * the prior's own mean and variance, then a and b come from method of moments on the blend, so a
+   * cold model returns its prior and a warm model is data-driven.
+   */
+  params() {
+    const priorStrength = this.priorA + this.priorB;
+    const priorMean = this.priorA / priorStrength;
+    const priorVariance = priorMean * (1 - priorMean) / (priorStrength + 1);
+    const totalCount = this.count + priorStrength;
+    const totalSum = this.sum + priorStrength * priorMean;
+    const totalSumSquares = this.sumSquares + priorStrength * (priorVariance + priorMean * priorMean);
+    const mean = clamp(totalSum / totalCount, VARIANCE_FLOOR, 1 - VARIANCE_FLOOR);
+    const rawVariance = totalSumSquares / totalCount - mean * mean;
+    const maxVariance = mean * (1 - mean);
+    const variance = clamp(rawVariance, VARIANCE_FLOOR, maxVariance * (1 - VARIANCE_FLOOR));
+    const concentration = Math.max(mean * (1 - mean) / variance - 1, CONCENTRATION_FLOOR);
+    const a = Math.max(mean * concentration, CONCENTRATION_FLOOR);
+    const b = Math.max((1 - mean) * concentration, CONCENTRATION_FLOOR);
+    if (!Number.isFinite(a) || !Number.isFinite(b)) {
+      throw new BayesOutputGateError("NUMERIC", "Beta fit produced non-finite parameters");
+    }
+    return { a, b };
+  }
+  /** Mean of the fitted Beta. */
+  mean() {
+    const { a, b } = this.params();
+    return a / (a + b);
+  }
+  /** Log-density of an observed score under the fitted Beta. */
+  logDensity(score) {
+    const { a, b } = this.params();
+    return betaLogDensity(score, a, b);
+  }
+  /** A serializable snapshot of the current state. */
+  snapshot() {
+    return {
+      count: this.count,
+      sum: this.sum,
+      sumSquares: this.sumSquares,
+      prior: { a: this.priorA, b: this.priorB }
+    };
+  }
+};
+
+// src/hypothesis/index.ts
+var HypothesisManager = class {
+  entries = /* @__PURE__ */ new Map();
+  defaultWeight;
+  defaultPriorHigh;
+  defaultPriorLow;
+  configured = /* @__PURE__ */ new Map();
+  constructor(options = {}) {
+    this.defaultWeight = options.defaultWeight ?? 1;
+    this.defaultPriorHigh = options.defaultPriorHigh ?? { a: 2, b: 1 };
+    this.defaultPriorLow = options.defaultPriorLow ?? { a: 1, b: 2 };
+    invariant(
+      Number.isFinite(this.defaultWeight) && this.defaultWeight >= 0,
+      "INVALID_CONFIG",
+      `defaultWeight must be a non-negative finite number, got ${this.defaultWeight}`
+    );
+    for (const config of options.dimensions ?? []) {
+      this.configured.set(config.dimension, config);
+      this.ensure(config.dimension);
+    }
+  }
+  ensure(dimension) {
+    const existing = this.entries.get(dimension);
+    if (existing) {
+      return existing;
+    }
+    const config = this.configured.get(dimension);
+    const entry = {
+      high: new BetaModel({ prior: config?.priorHigh ?? this.defaultPriorHigh }),
+      low: new BetaModel({ prior: config?.priorLow ?? this.defaultPriorLow }),
+      weight: config?.weight ?? this.defaultWeight
+    };
+    invariant(
+      Number.isFinite(entry.weight) && entry.weight >= 0,
+      "INVALID_CONFIG",
+      `weight for "${dimension}" must be a non-negative finite number, got ${entry.weight}`
+    );
+    this.entries.set(dimension, entry);
+    return entry;
+  }
+  /** Fold one labeled output into the high or low model of each scored dimension. */
+  observe(observation) {
+    invariant(
+      observation.label === "high" || observation.label === "low",
+      "INVALID_OBSERVATION",
+      `observation label must be "high" or "low", got ${String(observation.label)}`
+    );
+    for (const score of observation.scores) {
+      const entry = this.ensure(score.dimension);
+      const model = observation.label === "high" ? entry.high : entry.low;
+      model.observe(score.value);
+    }
+    return this;
+  }
+  /** Fold a batch of labeled observations. */
+  fit(observations) {
+    for (const observation of observations) {
+      this.observe(observation);
+    }
+    return this;
+  }
+  /** The dimension names this manager currently tracks. */
+  get dimensions() {
+    return [...this.entries.keys()];
+  }
+  /** Snapshot the current calibrated models as the dimension models the Bayes Factor consumes. */
+  models() {
+    const out = [];
+    for (const [dimension, entry] of this.entries) {
+      out.push({
+        dimension,
+        high: entry.high.params(),
+        low: entry.low.params(),
+        weight: entry.weight
+      });
+    }
+    return out;
+  }
+  /** Number of labeled observations folded into a dimension under one hypothesis. */
+  observationCount(dimension, kind) {
+    const entry = this.entries.get(dimension);
+    if (!entry) {
+      return 0;
+    }
+    return (kind === "high" ? entry.high : entry.low).observations;
+  }
+};
+function decide(logBayesFactor, policy) {
+  {
+    invariant(
+      policy.passAbove >= 1,
+      "INVALID_CONFIG",
+      `passAbove must be >= 1, got ${policy.passAbove}`
+    );
+    invariant(
+      policy.failBelow > 0 && policy.failBelow <= 1,
+      "INVALID_CONFIG",
+      `failBelow must be in (0, 1], got ${policy.failBelow}`
+    );
+    invariant(
+      policy.passAbove > policy.failBelow,
+      "INVALID_CONFIG",
+      "passAbove must be greater than failBelow"
+    );
+    const bayesFactor2 = Math.exp(logBayesFactor);
+    const action2 = bayesFactor2 >= policy.passAbove ? "pass" : bayesFactor2 <= policy.failBelow ? "fail" : "escalate";
+    return { action: action2, rationale: "bayes-factor" };
+  }
+}
+
+// src/gate/index.ts
+function toDecision(factor, policy, guards) {
+  const base = {
+    action: policy.action,
+    bayesFactor: factor.bayesFactor,
+    logBayesFactor: factor.logBayesFactor,
+    strength: factor.strength,
+    rationale: policy.rationale,
+    contributions: factor.contributions,
+    ...policy.posteriorHighQuality !== void 0 ? { posteriorHighQuality: policy.posteriorHighQuality } : {},
+    ...policy.expectedLoss !== void 0 ? { expectedLoss: policy.expectedLoss } : {}
+  };
+  {
+    return base;
+  }
+}
+function evaluate(scores, models, policy, guards) {
+  const factor = bayesFactor(scores, models);
+  const decision = decide(factor.logBayesFactor, policy);
+  return toDecision(factor, decision);
+}
+function readTextFile(path) {
+  try {
+    return fs.readFileSync(path, "utf8");
+  } catch (error) {
+    throw new BayesOutputGateError(
+      "INVALID_CONFIG",
+      `cannot read file ${path}: ${error.message}`
+    );
+  }
+}
+function readJsonFile(path) {
+  const text = readTextFile(path);
+  try {
+    return JSON.parse(text);
+  } catch {
+    throw new BayesOutputGateError("INVALID_CONFIG", `invalid JSON in ${path}`);
+  }
+}
+function parseScoreRow(value, where) {
+  invariant(
+    typeof value === "object" && value !== null && !Array.isArray(value),
+    "INVALID_SCORE",
+    `${where} must be an object`
+  );
+  const row = value;
+  const dimension = row["dimension"];
+  const score = row["value"];
+  invariant(
+    typeof dimension === "string" && dimension.length > 0,
+    "INVALID_SCORE",
+    `${where} dimension must be a non-empty string`
+  );
+  invariant(
+    typeof score === "number" && Number.isFinite(score) && score >= 0 && score <= 1,
+    "INVALID_SCORE",
+    `${where} value must be a finite number in [0, 1]`
+  );
+  return { dimension, value: score };
+}
+function parseScoreVector(row, where) {
+  if (Array.isArray(row)) {
+    return row.map((score, j) => parseScoreRow(score, `${where} score ${j}`));
+  }
+  invariant(
+    typeof row === "object" && row !== null,
+    "INVALID_SCORE",
+    `${where} must be an array or an object map`
+  );
+  return Object.entries(row).map(([dimension, value]) => {
+    invariant(
+      typeof value === "number" && Number.isFinite(value) && value >= 0 && value <= 1,
+      "INVALID_SCORE",
+      `${where} value for "${dimension}" must be a finite number in [0, 1]`
+    );
+    return { dimension, value };
+  });
+}
+function loadLabeledObservations(path) {
+  const data = readJsonFile(path);
+  invariant(
+    Array.isArray(data),
+    "INVALID_OBSERVATION",
+    `${path} must contain a JSON array of labeled observations`
+  );
+  return data.map((row, i) => {
+    invariant(
+      typeof row === "object" && row !== null,
+      "INVALID_OBSERVATION",
+      `observation ${i} must be an object`
+    );
+    const record = row;
+    const label = record["label"];
+    invariant(
+      label === "high" || label === "low",
+      "INVALID_OBSERVATION",
+      `observation ${i} label must be "high" or "low"`
+    );
+    invariant(
+      Array.isArray(record["scores"]),
+      "INVALID_SCORE",
+      `observation ${i} scores must be an array`
+    );
+    const scores = record["scores"].map(
+      (score, j) => parseScoreRow(score, `observation ${i} score ${j}`)
+    );
+    return { scores, label };
+  });
+}
+function parseCsvScores(text) {
+  const lines = text.split(/\r?\n/).map((line) => line.trim()).filter((line) => line.length > 0);
+  invariant(lines.length >= 2, "INVALID_SCORE", "CSV needs a header row and at least one data row");
+  const header = lines[0].split(",").map((cell) => cell.trim());
+  invariant(
+    header.every((name) => name.length > 0),
+    "INVALID_SCORE",
+    "CSV header dimensions must be non-empty"
+  );
+  const out = [];
+  for (let i = 1; i < lines.length; i++) {
+    const cells = lines[i].split(",").map((cell) => cell.trim());
+    invariant(
+      cells.length === header.length,
+      "INVALID_SCORE",
+      `CSV row ${i} has ${cells.length} cells, expected ${header.length}`
+    );
+    const vector = header.map((dimension, k) => {
+      const value = Number(cells[k]);
+      invariant(
+        Number.isFinite(value) && value >= 0 && value <= 1,
+        "INVALID_SCORE",
+        `CSV row ${i} value for "${dimension}" must be a finite number in [0, 1]`
+      );
+      return { dimension, value };
+    });
+    out.push(vector);
+  }
+  return out;
+}
+function loadScores(path$1) {
+  if (path.extname(path$1).toLowerCase() === ".csv") {
+    return parseCsvScores(readTextFile(path$1));
+  }
+  const data = readJsonFile(path$1);
+  invariant(
+    Array.isArray(data),
+    "INVALID_SCORE",
+    `${path$1} must contain a JSON array of score vectors`
+  );
+  return data.map((row, i) => parseScoreVector(row, `entry ${i}`));
+}
+
+// src/cli/commands.ts
+var VERSION = "1.0.0";
+var HELP = `bayesoutputgate <command> [options]
+
+Commands:
+  gate <history.json> <scores.json>         fit from labeled history, decide each output
+  bayes-factor <models.json> <scores.json>  compute the Bayes Factor for each output
+  calibrate <history.json>                  fit, then report goodness-of-fit and dependence
+  audit-verify <chain.json>                 verify a sealed decision audit chain
+
+Options:
+  --pass-above <n>   Bayes Factor pass threshold for gate (default 10)
+  --fail-below <n>   Bayes Factor fail threshold for gate (default 0.1)
+  --json             print machine-readable JSON
+  --help, -h         show this help
+  --version, -v      show the version
+
+Exit codes: 0 ok, 2 usage or input error, 30 fail decision, 40 escalate decision, 20 broken chain`;
+function parseArgs(argv) {
+  const flags = /* @__PURE__ */ new Map();
+  const positionals = [];
+  const valued = /* @__PURE__ */ new Set(["pass-above", "fail-below"]);
+  for (let i = 0; i < argv.length; i++) {
+    const token = argv[i];
+    if (token.startsWith("--")) {
+      const key = token.slice(2);
+      const next = argv[i + 1];
+      if (valued.has(key) && next !== void 0 && !next.startsWith("--")) {
+        flags.set(key, next);
+        i++;
+      } else {
+        flags.set(key, true);
+      }
+    } else if (token.startsWith("-")) {
+      flags.set(token.slice(1), true);
+    } else {
+      positionals.push(token);
+    }
+  }
+  return { command: positionals[0], positionals: positionals.slice(1), flags };
+}
+function numberFlag(flags, key, fallback) {
+  const raw = flags.get(key);
+  if (raw === void 0 || raw === true) {
+    return fallback;
+  }
+  const value = Number(raw);
+  if (!Number.isFinite(value)) {
+    throw new BayesOutputGateError("INVALID_CONFIG", `--${key} must be a number, got ${raw}`);
+  }
+  return value;
+}
+function worstAction(actions) {
+  if (actions.includes("fail")) return "fail";
+  if (actions.includes("escalate")) return "escalate";
+  return "pass";
+}
+function exitForAction(action) {
+  return action === "fail" ? 30 : action === "escalate" ? 40 : 0;
+}
+async function run(argv, io2) {
+  const { command, positionals, flags } = parseArgs(argv);
+  if (flags.has("version") || flags.has("v")) {
+    io2.write(VERSION);
+    return 0;
+  }
+  if (flags.has("help") || flags.has("h") || command === void 0) {
+    io2.write(HELP);
+    return 0;
+  }
+  const json = flags.has("json");
+  try {
+    switch (command) {
+      case "gate":
+        return gateCommand(positionals, flags, json, io2);
+      case "bayes-factor":
+        return bayesFactorCommand(positionals, json, io2);
+      case "calibrate":
+        return calibrateCommand(positionals, json, io2);
+      case "audit-verify":
+        return await auditVerifyCommand(positionals, json, io2);
+      default:
+        io2.error(`unknown command: ${command}`);
+        io2.write(HELP);
+        return 2;
+    }
+  } catch (error) {
+    if (error instanceof BayesOutputGateError) {
+      io2.error(`${error.code}: ${error.message}`);
+    } else {
+      io2.error(`error: ${error.message ?? String(error)}`);
+    }
+    return 2;
+  }
+}
+function requirePositionals(positionals, n, usage) {
+  if (positionals.length < n) {
+    throw new BayesOutputGateError("INVALID_CONFIG", `missing argument, usage: ${usage}`);
+  }
+}
+function gateCommand(positionals, flags, json, io2) {
+  requirePositionals(positionals, 2, "bayesoutputgate gate <history.json> <scores.json>");
+  const policy = {
+    passAbove: numberFlag(flags, "pass-above", 10),
+    failBelow: numberFlag(flags, "fail-below", 0.1)
+  };
+  const manager = new HypothesisManager();
+  manager.fit(loadLabeledObservations(positionals[0]));
+  const models = manager.models();
+  const vectors = loadScores(positionals[1]);
+  const decisions = vectors.map((vector) => evaluate(vector, models, policy));
+  if (json) {
+    io2.write(JSON.stringify(decisions, null, 2));
+  } else {
+    decisions.forEach((decision, i) => {
+      io2.write(
+        `output ${i}: ${decision.action.toUpperCase()} (Bayes Factor ${decision.bayesFactor.toFixed(3)}, ${decision.strength})`
+      );
+    });
+  }
+  return exitForAction(worstAction(decisions.map((decision) => decision.action)));
+}
+function bayesFactorCommand(positionals, json, io2) {
+  requirePositionals(positionals, 2, "bayesoutputgate bayes-factor <models.json> <scores.json>");
+  const models = readJsonFile(positionals[0]);
+  if (!Array.isArray(models)) {
+    throw new BayesOutputGateError(
+      "INVALID_CONFIG",
+      "models file must be a JSON array of dimension models"
+    );
+  }
+  const vectors = loadScores(positionals[1]);
+  const results = vectors.map((vector) => bayesFactor(vector, models));
+  if (json) {
+    io2.write(JSON.stringify(results, null, 2));
+  } else {
+    results.forEach((result, i) => {
+      io2.write(
+        `output ${i}: Bayes Factor ${result.bayesFactor.toFixed(3)} (${result.strength}, favors ${result.favored})`
+      );
+    });
+  }
+  return 0;
+}
+function calibrateCommand(positionals, json, io2) {
+  requirePositionals(positionals, 1, "bayesoutputgate calibrate <history.json>");
+  const observations = loadLabeledObservations(positionals[0]);
+  const manager = new HypothesisManager();
+  manager.fit(observations);
+  const models = manager.models();
+  const report = models.map((model) => {
+    const highScores = scoresFor(observations, model.dimension, "high");
+    const lowScores = scoresFor(observations, model.dimension, "low");
+    return {
+      dimension: model.dimension,
+      high: highScores.length >= 5 ? goodnessOfFit(highScores, model.high) : null,
+      low: lowScores.length >= 5 ? goodnessOfFit(lowScores, model.low) : null
+    };
+  });
+  const vectors = observations.map((observation) => observation.scores);
+  const dependence = vectors.length >= 2 ? dependenceDiagnostic(vectors) : null;
+  if (json) {
+    io2.write(JSON.stringify({ goodnessOfFit: report, dependence }, null, 2));
+  } else {
+    for (const row of report) {
+      const highTag = row.high ? row.high.adequate ? "adequate" : "INADEQUATE" : "insufficient";
+      const lowTag = row.low ? row.low.adequate ? "adequate" : "INADEQUATE" : "insufficient";
+      io2.write(`dimension ${row.dimension}: high fit ${highTag}, low fit ${lowTag}`);
+    }
+    if (dependence) {
+      io2.write(
+        `dimension independence: ${dependence.independenceAssumptionSafe ? "safe" : "AT RISK"} (max abs correlation ${dependence.maxAbsCorrelation.toFixed(3)})`
+      );
+    }
+  }
+  return 0;
+}
+async function auditVerifyCommand(positionals, json, io2) {
+  requirePositionals(positionals, 1, "bayesoutputgate audit-verify <chain.json>");
+  const data = readJsonFile(positionals[0]);
+  if (!Array.isArray(data)) {
+    throw new BayesOutputGateError(
+      "INVALID_SNAPSHOT",
+      "audit chain file must be a JSON array of entries"
+    );
+  }
+  const result = await verifyChain(data);
+  if (json) {
+    io2.write(JSON.stringify(result, null, 2));
+  } else {
+    io2.write(result.valid ? "audit chain valid" : `audit chain BROKEN at entry ${result.brokenAt}`);
+  }
+  return result.valid ? 0 : 20;
+}
+function scoresFor(observations, dimension, label) {
+  const out = [];
+  for (const observation of observations) {
+    if (observation.label !== label) {
+      continue;
+    }
+    for (const score of observation.scores) {
+      if (score.dimension === dimension) {
+        out.push(score.value);
+      }
+    }
+  }
+  return out;
+}
+
+// src/cli/index.ts
+var io = {
+  write: (line) => {
+    process.stdout.write(`${line}
+`);
+  },
+  error: (line) => {
+    process.stderr.write(`${line}
+`);
+  }
+};
+run(process.argv.slice(2), io).then((code) => {
+  process.exitCode = code;
+}).catch((error) => {
+  process.stderr.write(`${error.message ?? String(error)}
+`);
+  process.exitCode = 2;
+});