@mikeargento/bitgraph-player 0.1.0

package/src/cast.ts

@@ -0,0 +1,120 @@
+// Copyright (c) 2024-2026 Mike Argento. Licensed under the MIT License. See LICENSE.
+
+/**
+ * Cast resolution: digest -> recording.
+ *
+ * A digest identifies bits; a BitGraph recording identifies an OCCURRENCE
+ * of those bits at a causal position. The same bits can hold many
+ * positions by design (the ledger's by-digest index is one entry per
+ * causal position), so a role must resolve to exactly one recording:
+ *
+ *   exactly 1 verified match          -> resolved
+ *   0 matches, optional               -> absent (a definite fact under the closed world)
+ *   0 matches, required               -> absent (evaluates to UNDETERMINED)
+ *   2+ matches, no pin                -> ambiguous (UNDETERMINED, never a silent pick)
+ *   2+ matches, pin selects exactly 1 -> resolved
+ *
+ * Only proofs whose canonical verification passed (status "verified", at
+ * either tier) count as recordings. A file shaped like a proof that fails
+ * verification is noise, not evidence — but if matches exist and ALL fail
+ * verification, that is surfaced as invalid rather than silently treated
+ * as absence, because "the bundle contains only broken recordings of this
+ * digest" and "the bundle contains no recordings of this digest" are
+ * different situations and only one of them supports a closed-world
+ * absence claim.
+ */
+
+import type { AuditResult, ObservedProof } from "@mikeargento/bitgraph-audit";
+import { decodeDigestBytes, normalizeDigest } from "./rule.js";
+import type { CastEntry, Resolution } from "./types.js";
+
+function matchesPin(proof: ObservedProof, pin: NonNullable<CastEntry["at"]>): boolean {
+  if ("proofHash" in pin) return proof.proofHash === pin.proofHash;
+  return proof.epochId === pin.epochId && proof.counter === pin.counter;
+}
+
+/**
+ * A recording counts when its canonical verification PASSED at either
+ * tier: "verified" is the full-tier pass (artifact bytes present and
+ * matching), "artifact-unavailable" is the integrity-tier pass (the proof
+ * verifies bytes-free; the digest is inside the signed body either way).
+ */
+function verificationPassed(proof: ObservedProof): boolean {
+  const status = proof.verification?.status;
+  return status === "verified" || status === "artifact-unavailable";
+}
+
+export function resolveRole(role: string, entry: CastEntry, audit: AuditResult): Resolution {
+  const digestB64 = normalizeDigest(entry.digest);
+  if (digestB64 === undefined) {
+    // parseRule already rejects malformed digests; this guards direct API use.
+    return { kind: "invalid", role, reason: "digest is not a well-formed 32-byte SHA-256" };
+  }
+  const targetBytes = decodeDigestBytes(digestB64) as Buffer;
+
+  const anyMatch: ObservedProof[] = [];
+  const verified: ObservedProof[] = [];
+  for (const proof of audit.ingest.proofs) {
+    // Byte-level match: a hostile file may spell its digest any way it
+    // likes, and "only broken recordings exist" must not masquerade as
+    // "no recordings exist".
+    const proofDigest = decodeDigestBytes(proof.proof.artifact.digestB64);
+    if (proofDigest === undefined || !proofDigest.equals(targetBytes)) continue;
+    anyMatch.push(proof);
+    if (verificationPassed(proof)) verified.push(proof);
+  }
+
+  if (verified.length === 0) {
+    if (anyMatch.length > 0) {
+      return {
+        kind: "invalid",
+        role,
+        reason: `${anyMatch.length} recording(s) of this digest are present but none passed verification`,
+      };
+    }
+    return { kind: "absent", role, optional: entry.optional === true };
+  }
+
+  let candidates = verified;
+  if (entry.at !== undefined) {
+    const pin = entry.at;
+    candidates = verified.filter((p) => matchesPin(p, pin));
+    if (candidates.length === 0) {
+      return {
+        kind: "invalid",
+        role,
+        reason: `"at" pin matches none of the ${verified.length} verified recording(s) of this digest`,
+      };
+    }
+  }
+
+  if (candidates.length > 1) {
+    return {
+      kind: "ambiguous",
+      role,
+      matchCount: candidates.length,
+      candidates: candidates.map((p) => p.proofHash).sort(),
+    };
+  }
+
+  const proof = candidates[0] as ObservedProof;
+  return {
+    kind: "resolved",
+    role,
+    proof,
+    verificationTier: proof.verification?.tier ?? "integrity",
+    matchCount: verified.length,
+  };
+}
+
+/** Resolve every declared role. Deterministic: iterates the cast in declaration order. */
+export function resolveCast(
+  cast: Record<string, CastEntry>,
+  audit: AuditResult
+): Map<string, Resolution> {
+  const out = new Map<string, Resolution>();
+  for (const [role, entry] of Object.entries(cast)) {
+    out.set(role, resolveRole(role, entry, audit));
+  }
+  return out;
+}

package/src/cli.ts

@@ -0,0 +1,143 @@
+#!/usr/bin/env node
+// Copyright (c) 2024-2026 Mike Argento. Licensed under the MIT License. See LICENSE.
+
+/**
+ * bitgraph-play <rule.json> <bundle> [--out <file>] [--summary]
+ *
+ * Evaluates a bitgraph-player/1 rule against a proof bundle (directory,
+ * .tar, .tar.gz, or .tgz) and writes the verdict JSON to stdout (or
+ * --out). Offline: the audit pipeline and the evaluator make no network
+ * requests of any kind.
+ *
+ * Exit codes: 0 TRUE, 1 FALSE, 2 UNDETERMINED, 3 error.
+ * Diagnostics go to stderr; stdout carries verdict bytes only.
+ *
+ * The process exits by setting process.exitCode and returning, never by
+ * process.exit(): exiting early would truncate a verdict still draining
+ * to a pipe.
+ */
+
+import { createHash } from "node:crypto";
+import { readFileSync, writeFileSync } from "node:fs";
+import { runAudit } from "@mikeargento/bitgraph-audit";
+import type { AuditResult } from "@mikeargento/bitgraph-audit";
+import { resolveCast } from "./cast.js";
+import { evaluate } from "./evaluate.js";
+import { parseRule, RuleError } from "./rule.js";
+import { buildVerdict, serializeVerdict } from "./verdict.js";
+
+function usage(): number {
+  process.stderr.write(
+    "usage: bitgraph-play <rule.json> <bundle> [--out <file>] [--summary]\n" +
+      "  exit codes: 0 TRUE, 1 FALSE, 2 UNDETERMINED, 3 error\n"
+  );
+  return 3;
+}
+
+function printSummary(audit: AuditResult): void {
+  const lines: string[] = [];
+  const c = audit.ingest.counts;
+  lines.push(
+    `bundle: ${c.observed} observed proof(s), ${c.artifacts} artifact(s), ${c.witnesses} witness file(s)`
+  );
+  for (const partition of audit.reconstruction.partitions) {
+    const key = partition.key;
+    lines.push(
+      `partition epoch=${key.epochId ?? "(none)"} chain=${key.chainId} key=${key.publicKeyB64.slice(0, 12)}…: ` +
+        `${partition.memberProofHashes.length} proof(s) in ${partition.components.length} component(s)`
+    );
+  }
+  const rel = audit.reconstruction.epochRelationships;
+  lines.push(
+    `epochs: ${rel.epochs.length} observed, ${rel.orderedPairs.length} lineage-ordered pair(s), ` +
+      `${audit.temporal.anchorOrderedPairs.length} anchor-ordered pair(s)`
+  );
+  lines.push(
+    `unchained: ${audit.reconstruction.unchainedProofHashes.length}, unpartitioned: ${audit.reconstruction.unpartitionedProofHashes.length}`
+  );
+  process.stderr.write(lines.join("\n") + "\n");
+}
+
+async function main(): Promise<number> {
+  const args = process.argv.slice(2);
+  const positional: string[] = [];
+  let outFile: string | undefined;
+  let summary = false;
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i] as string;
+    if (arg === "--out") {
+      const next = args[++i];
+      if (next === undefined || next.startsWith("-")) return usage();
+      outFile = next;
+    } else if (arg === "--summary") {
+      summary = true;
+    } else if (arg.startsWith("-")) {
+      return usage();
+    } else {
+      positional.push(arg);
+    }
+  }
+  if (positional.length !== 2) return usage();
+  const [rulePath, bundlePath] = positional as [string, string];
+
+  let ruleBytes: Buffer;
+  try {
+    ruleBytes = readFileSync(rulePath);
+  } catch (err) {
+    process.stderr.write(`error: cannot read rule file: ${(err as Error).message}\n`);
+    return 3;
+  }
+  const ruleSha256Hex = createHash("sha256").update(ruleBytes).digest("hex");
+
+  let rule;
+  try {
+    rule = parseRule(ruleBytes.toString("utf8"));
+  } catch (err) {
+    if (err instanceof RuleError) {
+      process.stderr.write("error: invalid rule\n");
+      for (const issue of err.issues) process.stderr.write(`  - ${issue}\n`);
+    } else {
+      process.stderr.write(`error: ${(err as Error).message}\n`);
+    }
+    return 3;
+  }
+
+  let audit: AuditResult;
+  try {
+    audit = await runAudit(bundlePath);
+  } catch (err) {
+    process.stderr.write(`error: bundle audit failed: ${(err as Error).message}\n`);
+    return 3;
+  }
+
+  const resolutions = resolveCast(rule.cast, audit);
+  const evaluation = evaluate(rule, resolutions, audit);
+  const verdict = buildVerdict(rule, ruleSha256Hex, resolutions, evaluation, audit);
+  const bytes = serializeVerdict(verdict);
+
+  if (outFile !== undefined) {
+    writeFileSync(outFile, bytes);
+  } else {
+    process.stdout.write(bytes);
+  }
+  if (summary) printSummary(audit);
+
+  switch (evaluation.result) {
+    case "TRUE":
+      return 0;
+    case "FALSE":
+      return 1;
+    case "UNDETERMINED":
+      return 2;
+  }
+}
+
+main().then(
+  (code) => {
+    process.exitCode = code;
+  },
+  (err: unknown) => {
+    process.stderr.write(`error: ${(err as Error).message}\n`);
+    process.exitCode = 3;
+  }
+);

package/src/evaluate.ts

@@ -0,0 +1,238 @@
+// Copyright (c) 2024-2026 Mike Argento. Licensed under the MIT License. See LICENSE.
+
+/**
+ * The evaluator: walks the claim tree over resolved recordings and the
+ * ordering adapter, under strong Kleene semantics.
+ *
+ * Deliberate properties:
+ *
+ * - FULL WALK, no short-circuit. Every sub-claim is evaluated and recorded
+ *   so the verdict is a complete replayable trace, not just an outcome.
+ *
+ * - CLOSED WORLD, scoped to the cast. An absent OPTIONAL role is a
+ *   definite absence within the declared universe: positive claims about
+ *   it are FALSE, so negatives over it hold. An absent REQUIRED role, an
+ *   ambiguous role, and a role the cast never declared are UNDETERMINED —
+ *   the evidence does not decide, and saying FALSE would be a lie.
+ *
+ * - THE FLOOR GATES EVIDENCE, NOT POLARITY. When an ordering answer rests
+ *   on a tier below requires.ordering, the answer is UNDETERMINED whether
+ *   it would have been TRUE or FALSE: the rule author said not to trust
+ *   that evidence in either direction.
+ */
+
+import type { AuditResult, ObservedProof } from "@mikeargento/bitgraph-audit";
+import { kleeneAll, kleeneAny, kleeneNot } from "./logic.js";
+import { compare } from "./order.js";
+import { basisTier, meetsFloor } from "./types.js";
+import type {
+  Claim,
+  DerivedStep,
+  EvidenceTier,
+  Resolution,
+  Rule,
+  ThreeValued,
+} from "./types.js";
+
+export interface Evaluation {
+  result: ThreeValued;
+  steps: DerivedStep[];
+  /** Weakest tier among ordering answers that actually decided a step. */
+  weakestEvidence?: EvidenceTier;
+}
+
+interface Ctx {
+  rule: Rule;
+  resolutions: Map<string, Resolution>;
+  audit: AuditResult;
+  steps: DerivedStep[];
+  usedTiers: Set<EvidenceTier>;
+}
+
+function positionOf(proof: ObservedProof): Record<string, unknown> {
+  const out: Record<string, unknown> = { proofHash: proof.proofHash };
+  if (proof.epochId !== undefined) out["epochId"] = proof.epochId;
+  out["chainId"] = proof.chainId;
+  if (proof.counter !== undefined) out["counter"] = proof.counter;
+  if (proof.slotCounter !== undefined) out["slotCounter"] = proof.slotCounter;
+  return out;
+}
+
+/**
+ * Classify a role for predicate purposes.
+ *   resolved          -> use the recording
+ *   definitely-absent -> optional and absent: closed-world FALSE material
+ *   undetermined      -> everything else, with the reason
+ */
+function classify(
+  ctx: Ctx,
+  role: string
+):
+  | { kind: "resolved"; proof: ObservedProof }
+  | { kind: "definitely-absent" }
+  | { kind: "undetermined"; reason: string } {
+  const res = ctx.resolutions.get(role);
+  if (res === undefined) {
+    return { kind: "undetermined", reason: `role "${role}" is not declared in the cast` };
+  }
+  switch (res.kind) {
+    case "resolved":
+      return { kind: "resolved", proof: res.proof };
+    case "absent":
+      return res.optional
+        ? { kind: "definitely-absent" }
+        : {
+            kind: "undetermined",
+            reason: `required role "${role}" has no verified recording in the bundle`,
+          };
+    case "ambiguous":
+      return {
+        kind: "undetermined",
+        reason: `role "${role}" matches ${res.matchCount} recordings and no "at" pin selects one`,
+      };
+    case "invalid":
+      return { kind: "undetermined", reason: `role "${role}": ${res.reason}` };
+  }
+}
+
+function record(ctx: Ctx, step: DerivedStep): ThreeValued {
+  ctx.steps.push(step);
+  return step.result;
+}
+
+function evalExists(ctx: Ctx, role: string): ThreeValued {
+  const c = classify(ctx, role);
+  const claim = `exists(${role})`;
+  if (c.kind === "resolved") {
+    return record(ctx, {
+      claim,
+      result: "TRUE",
+      because: { recording: positionOf(c.proof) },
+    });
+  }
+  if (c.kind === "definitely-absent") {
+    return record(ctx, {
+      claim,
+      result: "FALSE",
+      because: {
+        reason: `no verified recording of the declared digest is in the bundle; definite absence within the declared closed world`,
+      },
+    });
+  }
+  return record(ctx, { claim, result: "UNDETERMINED", because: { reason: c.reason } });
+}
+
+/** Shared body of before/after: asks whether `x` precedes `y`. */
+function evalPrecedes(ctx: Ctx, claim: string, x: string, y: string): ThreeValued {
+  const cx = classify(ctx, x);
+  const cy = classify(ctx, y);
+
+  for (const [role, c] of [
+    [x, cx],
+    [y, cy],
+  ] as const) {
+    if (c.kind === "undetermined") {
+      return record(ctx, {
+        claim,
+        result: "UNDETERMINED",
+        because: { reason: c.reason, role },
+      });
+    }
+  }
+  if (cx.kind === "definitely-absent" || cy.kind === "definitely-absent") {
+    const absent = cx.kind === "definitely-absent" ? x : y;
+    return record(ctx, {
+      claim,
+      result: "FALSE",
+      because: {
+        reason: `role "${absent}" is definitely absent within the declared closed world; no ordering claim about it can hold`,
+      },
+    });
+  }
+
+  const a = (cx as { kind: "resolved"; proof: ObservedProof }).proof;
+  const b = (cy as { kind: "resolved"; proof: ObservedProof }).proof;
+  const order = compare(a, b, ctx.audit);
+  const because: Record<string, unknown> = {
+    a: positionOf(a),
+    b: positionOf(b),
+    relation: order.relation,
+    detail: order.detail,
+  };
+
+  if (order.relation === "same") {
+    return record(ctx, { claim, result: "FALSE", because });
+  }
+  if (order.relation === "unordered") {
+    return record(ctx, { claim, result: "UNDETERMINED", because });
+  }
+
+  const basis = order.basis as NonNullable<typeof order.basis>;
+  // The tier the specific answer rests on — carried by the adapter, not
+  // recomputed from the basis family (lineage coverage can downgrade it).
+  const tier = order.tier ?? basisTier(basis);
+  because["weaker"] = order.weaker;
+  because["assumptionDependent"] = order.assumptionDependent;
+
+  if (!meetsFloor(tier, ctx.rule.requires.ordering)) {
+    because["floor"] = ctx.rule.requires.ordering;
+    return record(ctx, {
+      claim,
+      result: "UNDETERMINED",
+      basis,
+      evidenceTier: tier,
+      because: {
+        ...because,
+        reason: `ordering evidence ("${basis}", tier "${tier}") is below the rule's declared floor ("${ctx.rule.requires.ordering}")`,
+      },
+    });
+  }
+
+  ctx.usedTiers.add(tier);
+  return record(ctx, {
+    claim,
+    result: order.relation === "before" ? "TRUE" : "FALSE",
+    basis,
+    evidenceTier: tier,
+    because,
+  });
+}
+
+function evalClaim(ctx: Ctx, claim: Claim): ThreeValued {
+  if ("exists" in claim) return evalExists(ctx, claim.exists);
+  if ("before" in claim) {
+    const [x, y] = claim.before;
+    return evalPrecedes(ctx, `before(${x}, ${y})`, x, y);
+  }
+  if ("after" in claim) {
+    const [x, y] = claim.after;
+    // after(x, y) holds exactly when y precedes x.
+    return evalPrecedes(ctx, `after(${x}, ${y})`, y, x);
+  }
+  if ("between" in claim) {
+    const [subject, lower, upper] = claim.between;
+    // between(x, a, b) := after(x, a) AND before(x, b), recorded as two steps.
+    const afterPart = evalPrecedes(ctx, `between(${subject}, ${lower}, ${upper}): after(${subject}, ${lower})`, lower, subject);
+    const beforePart = evalPrecedes(ctx, `between(${subject}, ${lower}, ${upper}): before(${subject}, ${upper})`, subject, upper);
+    return kleeneAll([afterPart, beforePart]);
+  }
+  if ("all" in claim) return kleeneAll(claim.all.map((c) => evalClaim(ctx, c)));
+  if ("any" in claim) return kleeneAny(claim.any.map((c) => evalClaim(ctx, c)));
+  return kleeneNot(evalClaim(ctx, claim.not));
+}
+
+export function evaluate(
+  rule: Rule,
+  resolutions: Map<string, Resolution>,
+  audit: AuditResult
+): Evaluation {
+  const ctx: Ctx = { rule, resolutions, audit, steps: [], usedTiers: new Set() };
+  const result = evalClaim(ctx, rule.claim);
+  const evaluation: Evaluation = { result, steps: ctx.steps };
+  if (ctx.usedTiers.has("assumption-dependent")) {
+    evaluation.weakestEvidence = "assumption-dependent";
+  } else if (ctx.usedTiers.has("hash-linked")) {
+    evaluation.weakestEvidence = "hash-linked";
+  }
+  return evaluation;
+}

package/src/index.ts

@@ -0,0 +1,38 @@
+// Copyright (c) 2024-2026 Mike Argento. Licensed under the MIT License. See LICENSE.
+
+/**
+ * @mikeargento/bitgraph-player
+ *
+ * Deterministic evaluation of causal rules over BitGraph proof bundles.
+ *
+ *   BitGraph records. Player executes.
+ *
+ * Player is a pure function over `runAudit()`'s output: same rule, same
+ * bundle, same verdict, on anyone's machine, with no network access at
+ * evaluation time. It decides; it does not enforce — no field in the rule
+ * format is capable of causing an action.
+ */
+
+export type {
+  CastEntry,
+  CastPin,
+  Claim,
+  DeclaredEntry,
+  DerivedStep,
+  EvidenceTier,
+  OrderBasis,
+  OrderResult,
+  Resolution,
+  Rule,
+  ThreeValued,
+  Verdict,
+} from "./types.js";
+export { basisTier, meetsFloor } from "./types.js";
+
+export { parseRule, normalizeDigest, RuleError } from "./rule.js";
+export { resolveCast, resolveRole } from "./cast.js";
+export { compare } from "./order.js";
+export { kleeneAll, kleeneAny, kleeneNot } from "./logic.js";
+export { evaluate } from "./evaluate.js";
+export type { Evaluation } from "./evaluate.js";
+export { buildVerdict, serializeVerdict, playerVersion } from "./verdict.js";

package/src/logic.ts

@@ -0,0 +1,39 @@
+// Copyright (c) 2024-2026 Mike Argento. Licensed under the MIT License. See LICENSE.
+
+/**
+ * Strong Kleene three-valued connectives.
+ *
+ *   all: FALSE if any FALSE; else UNDETERMINED if any UNDETERMINED; else TRUE
+ *   any: TRUE  if any TRUE;  else UNDETERMINED if any UNDETERMINED; else FALSE
+ *   not: TRUE <-> FALSE; UNDETERMINED stays UNDETERMINED
+ *
+ * UNDETERMINED is not a nuisance value: it is the honest answer wherever
+ * the evidence does not decide, and these tables are what keep it from
+ * being laundered into FALSE by composition.
+ */
+
+import type { ThreeValued } from "./types.js";
+
+export function kleeneNot(v: ThreeValued): ThreeValued {
+  if (v === "TRUE") return "FALSE";
+  if (v === "FALSE") return "TRUE";
+  return "UNDETERMINED";
+}
+
+export function kleeneAll(values: readonly ThreeValued[]): ThreeValued {
+  let sawUndetermined = false;
+  for (const v of values) {
+    if (v === "FALSE") return "FALSE";
+    if (v === "UNDETERMINED") sawUndetermined = true;
+  }
+  return sawUndetermined ? "UNDETERMINED" : "TRUE";
+}
+
+export function kleeneAny(values: readonly ThreeValued[]): ThreeValued {
+  let sawUndetermined = false;
+  for (const v of values) {
+    if (v === "TRUE") return "TRUE";
+    if (v === "UNDETERMINED") sawUndetermined = true;
+  }
+  return sawUndetermined ? "UNDETERMINED" : "FALSE";
+}