@takk/bayesoutputgate 1.0.0

package/dist/adapter/index.js

@@ -0,0 +1,404 @@
+// 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;
+}
+
+// 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/policy/index.ts
+function posteriorHighQuality(logBayesFactor, priorHighQuality) {
+  invariant(
+    priorHighQuality > 0 && priorHighQuality < 1,
+    "INVALID_CONFIG",
+    `priorHighQuality must be in (0, 1), got ${priorHighQuality}`
+  );
+  invariant(
+    Number.isFinite(logBayesFactor),
+    "NUMERIC",
+    `logBayesFactor must be finite, got ${logBayesFactor}`
+  );
+  const logPosteriorOdds = logBayesFactor + Math.log(priorHighQuality / (1 - priorHighQuality));
+  if (logPosteriorOdds >= 0) {
+    return 1 / (1 + Math.exp(-logPosteriorOdds));
+  }
+  const odds = Math.exp(logPosteriorOdds);
+  return odds / (1 + odds);
+}
+function decide(logBayesFactor, policy) {
+  if (policy.kind === "bayes-factor") {
+    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" };
+  }
+  invariant(
+    policy.lossFalsePass >= 0 && policy.lossFalseFail >= 0 && policy.escalationCost >= 0,
+    "INVALID_CONFIG",
+    "decision-theoretic losses must be non-negative"
+  );
+  invariant(
+    Number.isFinite(policy.lossFalsePass) && Number.isFinite(policy.lossFalseFail) && Number.isFinite(policy.escalationCost),
+    "INVALID_CONFIG",
+    "decision-theoretic losses must be finite"
+  );
+  const posterior = posteriorHighQuality(logBayesFactor, policy.priorHighQuality);
+  const expectedLoss = {
+    pass: (1 - posterior) * policy.lossFalsePass,
+    fail: posterior * policy.lossFalseFail,
+    escalate: policy.escalationCost
+  };
+  let action = "pass";
+  let best = expectedLoss.pass;
+  if (expectedLoss.fail < best) {
+    action = "fail";
+    best = expectedLoss.fail;
+  }
+  if (expectedLoss.escalate < best) {
+    action = "escalate";
+  }
+  return { action, rationale: "expected-loss", posteriorHighQuality: posterior, expectedLoss };
+}
+
+// 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);
+}
+
+// src/adapter/index.ts
+var TOOL_NAME = "bayes_output_gate";
+var DEFAULT_POLICY = { kind: "bayes-factor", passAbove: 10, failBelow: 0.1 };
+function toJsonSafe(value) {
+  if (typeof value === "number") {
+    return Number.isFinite(value) ? value : null;
+  }
+  if (Array.isArray(value)) {
+    return value.map((item) => toJsonSafe(item));
+  }
+  if (value !== null && typeof value === "object") {
+    const out = {};
+    for (const [key, item] of Object.entries(value)) {
+      out[key] = toJsonSafe(item);
+    }
+    return out;
+  }
+  return value;
+}
+function asObject(value, message) {
+  invariant(
+    typeof value === "object" && value !== null && !Array.isArray(value),
+    "INVALID_CONFIG",
+    message
+  );
+  return value;
+}
+function parseBeta(value, where) {
+  const obj = asObject(value, `${where} must be an object with positive a and b`);
+  const a = obj["a"];
+  const b = obj["b"];
+  invariant(
+    typeof a === "number" && typeof b === "number" && a > 0 && b > 0,
+    "INVALID_CONFIG",
+    `${where} must have positive numeric a and b`
+  );
+  return { a, b };
+}
+function parseScore(value) {
+  const obj = asObject(value, "each score must be an object with dimension and value");
+  const dimension = obj["dimension"];
+  const score = obj["value"];
+  invariant(
+    typeof dimension === "string" && dimension.length > 0,
+    "INVALID_SCORE",
+    "score dimension must be a non-empty string"
+  );
+  invariant(
+    typeof score === "number" && Number.isFinite(score) && score >= 0 && score <= 1,
+    "INVALID_SCORE",
+    `score value for "${dimension}" must be a finite number in [0, 1]`
+  );
+  return { dimension, value: score };
+}
+function parseModel(value) {
+  const obj = asObject(value, "each model must be an object");
+  const dimension = obj["dimension"];
+  invariant(
+    typeof dimension === "string" && dimension.length > 0,
+    "INVALID_CONFIG",
+    "model dimension must be a non-empty string"
+  );
+  const rawWeight = obj["weight"];
+  const weight = rawWeight === void 0 ? 1 : rawWeight;
+  invariant(
+    typeof weight === "number" && Number.isFinite(weight) && weight >= 0,
+    "INVALID_CONFIG",
+    `model weight for "${dimension}" must be a non-negative number`
+  );
+  return {
+    dimension,
+    high: parseBeta(obj["high"], `model "${dimension}" high`),
+    low: parseBeta(obj["low"], `model "${dimension}" low`),
+    weight
+  };
+}
+function parsePolicy(value) {
+  if (value === void 0) {
+    return DEFAULT_POLICY;
+  }
+  const obj = asObject(value, "policy must be an object");
+  const kind = obj["kind"];
+  if (kind === "decision-theoretic") {
+    const prior = obj["priorHighQuality"];
+    const lossFalsePass = obj["lossFalsePass"];
+    const lossFalseFail = obj["lossFalseFail"];
+    const escalationCost = obj["escalationCost"];
+    invariant(
+      typeof prior === "number" && typeof lossFalsePass === "number" && typeof lossFalseFail === "number" && typeof escalationCost === "number",
+      "INVALID_CONFIG",
+      "decision-theoretic policy requires numeric priorHighQuality, lossFalsePass, lossFalseFail, escalationCost"
+    );
+    return {
+      kind: "decision-theoretic",
+      priorHighQuality: prior,
+      lossFalsePass,
+      lossFalseFail,
+      escalationCost
+    };
+  }
+  invariant(kind === "bayes-factor", "INVALID_CONFIG", `unknown policy kind ${String(kind)}`);
+  const passAbove = obj["passAbove"];
+  const failBelow = obj["failBelow"];
+  invariant(
+    typeof passAbove === "number" && typeof failBelow === "number",
+    "INVALID_CONFIG",
+    "bayes-factor policy requires numeric passAbove and failBelow"
+  );
+  return { kind: "bayes-factor", passAbove, failBelow };
+}
+function parseGateInput(input) {
+  const obj = asObject(input, "tool input must be an object");
+  invariant(Array.isArray(obj["scores"]), "INVALID_SCORE", "scores must be an array");
+  invariant(Array.isArray(obj["models"]), "INVALID_CONFIG", "models must be an array");
+  const scores = obj["scores"].map(parseScore);
+  const models = obj["models"].map(parseModel);
+  invariant(models.length > 0, "INVALID_CONFIG", "at least one model is required");
+  return { scores, models, policy: parsePolicy(obj["policy"]) };
+}
+function runTool(input) {
+  const { scores, models, policy } = parseGateInput(input);
+  return evaluate(scores, models, policy);
+}
+function describeTool() {
+  return {
+    name: TOOL_NAME,
+    description: "Weigh an output's per-dimension quality scores against a high-quality and a low-quality hypothesis with a calibrated Bayes Factor, and return a pass, fail, or escalate decision on the Jeffreys scale.",
+    inputSchema: {
+      type: "object",
+      required: ["scores", "models"],
+      properties: {
+        scores: {
+          type: "array",
+          items: {
+            type: "object",
+            required: ["dimension", "value"],
+            properties: {
+              dimension: { type: "string" },
+              value: { type: "number", minimum: 0, maximum: 1 }
+            }
+          }
+        },
+        models: {
+          type: "array",
+          items: {
+            type: "object",
+            required: ["dimension", "high", "low"],
+            properties: {
+              dimension: { type: "string" },
+              high: { type: "object", required: ["a", "b"] },
+              low: { type: "object", required: ["a", "b"] },
+              weight: { type: "number", minimum: 0 }
+            }
+          }
+        },
+        policy: { type: "object" }
+      }
+    }
+  };
+}
+var bayesOutputGateTool = {
+  ...describeTool(),
+  handler: (input) => toJsonSafe(runTool(input))
+};
+
+export { TOOL_NAME, bayesOutputGateTool, describeTool, parseGateInput, runTool, toJsonSafe };

package/dist/audit/index.cjs

@@ -0,0 +1,82 @@
+'use strict';
+
+// 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 };
+}
+var AuditChain = class {
+  entries = [];
+  /** Append a payload, sealing it against the previous entry's hash. */
+  async append(payload, meta = {}) {
+    const index = this.entries.length;
+    const previousHash = index === 0 ? GENESIS_HASH : this.entries[index - 1].hash;
+    const record = recordOf(index, payload, previousHash, meta.timestamp);
+    const hash = await sha256Hex(canonicalize(record));
+    const entry = meta.timestamp !== void 0 ? { index, timestamp: meta.timestamp, payload, previousHash, hash } : { index, payload, previousHash, hash };
+    this.entries.push(entry);
+    return entry;
+  }
+  /** A copy of the chain's entries in order. */
+  toArray() {
+    return [...this.entries];
+  }
+  /** Number of entries in the chain. */
+  get length() {
+    return this.entries.length;
+  }
+};
+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 };
+}
+
+exports.AuditChain = AuditChain;
+exports.GENESIS_HASH = GENESIS_HASH;
+exports.sha256Hex = sha256Hex;
+exports.verifyChain = verifyChain;

package/dist/audit/index.d.cts

@@ -0,0 +1,40 @@
+/** The hash that precedes the first entry of a chain. */
+declare const GENESIS_HASH: string;
+/** Compute the lowercase hexadecimal SHA-256 digest of a string via the Web Crypto API. */
+declare function sha256Hex(input: string): Promise<string>;
+/** One sealed record in an audit chain. */
+interface AuditEntry {
+    readonly index: number;
+    readonly timestamp?: string;
+    readonly payload: unknown;
+    readonly previousHash: string;
+    readonly hash: string;
+}
+/** Metadata a caller may attach when appending. */
+interface AuditMeta {
+    readonly timestamp?: string;
+}
+/** An append-only, hash-chained log of gate decisions. */
+declare class AuditChain {
+    private readonly entries;
+    /** Append a payload, sealing it against the previous entry's hash. */
+    append(payload: unknown, meta?: AuditMeta): Promise<AuditEntry>;
+    /** A copy of the chain's entries in order. */
+    toArray(): AuditEntry[];
+    /** Number of entries in the chain. */
+    get length(): number;
+}
+/** The result of verifying an audit chain. */
+interface ChainVerification {
+    readonly valid: boolean;
+    /** Index of the first broken entry, present when the chain is invalid. */
+    readonly brokenAt?: number;
+}
+/**
+ * Verify that an audit chain is intact: every entry's index is sequential, every link points at the
+ * prior hash, and every hash recomputes from the entry's canonical content. Returns the index of the
+ * first tampered or broken entry when invalid.
+ */
+declare function verifyChain(entries: readonly AuditEntry[]): Promise<ChainVerification>;
+
+export { AuditChain, type AuditEntry, type AuditMeta, type ChainVerification, GENESIS_HASH, sha256Hex, verifyChain };

package/dist/audit/index.d.ts

@@ -0,0 +1,40 @@
+/** The hash that precedes the first entry of a chain. */
+declare const GENESIS_HASH: string;
+/** Compute the lowercase hexadecimal SHA-256 digest of a string via the Web Crypto API. */
+declare function sha256Hex(input: string): Promise<string>;
+/** One sealed record in an audit chain. */
+interface AuditEntry {
+    readonly index: number;
+    readonly timestamp?: string;
+    readonly payload: unknown;
+    readonly previousHash: string;
+    readonly hash: string;
+}
+/** Metadata a caller may attach when appending. */
+interface AuditMeta {
+    readonly timestamp?: string;
+}
+/** An append-only, hash-chained log of gate decisions. */
+declare class AuditChain {
+    private readonly entries;
+    /** Append a payload, sealing it against the previous entry's hash. */
+    append(payload: unknown, meta?: AuditMeta): Promise<AuditEntry>;
+    /** A copy of the chain's entries in order. */
+    toArray(): AuditEntry[];
+    /** Number of entries in the chain. */
+    get length(): number;
+}
+/** The result of verifying an audit chain. */
+interface ChainVerification {
+    readonly valid: boolean;
+    /** Index of the first broken entry, present when the chain is invalid. */
+    readonly brokenAt?: number;
+}
+/**
+ * Verify that an audit chain is intact: every entry's index is sequential, every link points at the
+ * prior hash, and every hash recomputes from the entry's canonical content. Returns the index of the
+ * first tampered or broken entry when invalid.
+ */
+declare function verifyChain(entries: readonly AuditEntry[]): Promise<ChainVerification>;
+
+export { AuditChain, type AuditEntry, type AuditMeta, type ChainVerification, GENESIS_HASH, sha256Hex, verifyChain };

package/dist/audit/index.js

@@ -0,0 +1,77 @@
+// 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 };
+}
+var AuditChain = class {
+  entries = [];
+  /** Append a payload, sealing it against the previous entry's hash. */
+  async append(payload, meta = {}) {
+    const index = this.entries.length;
+    const previousHash = index === 0 ? GENESIS_HASH : this.entries[index - 1].hash;
+    const record = recordOf(index, payload, previousHash, meta.timestamp);
+    const hash = await sha256Hex(canonicalize(record));
+    const entry = meta.timestamp !== void 0 ? { index, timestamp: meta.timestamp, payload, previousHash, hash } : { index, payload, previousHash, hash };
+    this.entries.push(entry);
+    return entry;
+  }
+  /** A copy of the chain's entries in order. */
+  toArray() {
+    return [...this.entries];
+  }
+  /** Number of entries in the chain. */
+  get length() {
+    return this.entries.length;
+  }
+};
+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 };
+}
+
+export { AuditChain, GENESIS_HASH, sha256Hex, verifyChain };