BitGraph Player

A Programmable Layer for BitGraph

BitGraph records. Player evaluates.

A BitGraph recording establishes that particular bytes occupied a particular causal position. Player takes a set of those recordings, applies a rule to them, and produces a verdict:
TRUE, FALSE, or UNDETERMINED.

Anyone with the same rule and the same evidence can reproduce that verdict themselves, on their own machine, offline. No network, no clock, no account, and no trust in whoever ran Player first.

A purchase order was recorded. Later, a delivery was recorded. Later still, an approval was recorded. No declared cancellation was recorded before the approval.

A Player rule can express exactly that claim and determine whether the BitGraph evidence supports it.

What a Player is

A rule names the artifacts it cares about and states a claim about their causal order:

• the delivery was recorded after the purchase order
• the approval was recorded after the delivery
• no declared cancellation occurred before the approval

Player evaluates that claim against the recordings in a proof bundle and writes a verdict that shows its work, step by step, including the evidence each answer rests on.

Player evaluates; it does not enforce. No field in a rule can cause an external action. If a system pays an invoice after a TRUE verdict, that system sits above Player. Player only determines what follows from the rule and the evidence it was given.

A rule

{
  "rule": "bitgraph-player/1",
  "id": "po-release-payment",
  "cast": {
    "purchase_order": { "digest": "sha256:…", "means": "PO-4471" },
    "delivery":       { "digest": "sha256:…" },
    "approval":       { "digest": "sha256:…" },
    "cancellation":   { "digest": "sha256:…", "optional": true }
  },
  "world": "closed",
  "requires": { "ordering": "assumption-dependent" },
  "claim": { "all": [
    { "exists": "purchase_order" },
    { "after":  ["delivery", "purchase_order"] },
    { "after":  ["approval", "delivery"] },
    { "not": { "before": ["cancellation", "approval"] } }
  ]},
  "then": { "label": "release_payment" }
}

What Player can prove

Every rule separates two kinds of facts.

cast contains facts supplied by the rule author: which digest represents the purchase order, which digest represents the delivery, which occurrence is intended, or who a signer is said to represent.

claim contains only what Player is allowed to derive from BitGraph evidence: whether a recording exists, whether one recording came before or after another, or whether the available evidence fails to establish an answer.

The verdict never mixes the two. A reader can always see which facts came from BitGraph and which were asserted by the person who wrote the rule. That separation is the trust boundary.

The rule's security floor

Every rule must declare the limits under which its claim is allowed to be evaluated.

world: "closed" scopes negative claims to the artifacts declared in the rule. For example, this rule does not claim that no cancellation exists anywhere. It claims only that no cancellation represented by the declared cancellation role was established before the approval. Negative claims never extend beyond the evidence the rule declares.

requires.ordering is the rule's security floor. It specifies what kind of ordering evidence the author is willing to accept. hash-linked accepts conclusions supported by hash-linked ordering evidence alone. assumption-dependent also permits ordering conclusions that rely on accepted BitGraph assumptions, including counter order and Ethereum anchor bounds.

There is no default. A rule that does not declare its ordering floor does not parse, because that floor is part of the rule's own security policy. The tool must not choose it for the author.

Three answers, not two

Every claim evaluates to:

TRUE
The evidence supports the claim at or above the rule's declared security floor.

FALSE
The evidence refutes the claim.

UNDETERMINED
The available evidence does not decide.

UNDETERMINED is the correct answer when, for example:

• the evidence does not establish the order of two recordings
• the same digest was recorded more than once and nothing selects the intended occurrence
• the available ordering evidence falls below the rule's declared security floor

A two-valued evaluator would have to launder those cases into TRUE or FALSE and would therefore be wrong on some inputs. Player refuses to invent certainty. When the evidence cannot decide the claim, the verdict is UNDETERMINED and states why.

Run it

With Node.js installed, evaluate a rule against a BitGraph proof bundle. A bundle may be a directory, .tar, or .tar.gz containing BitGraph exports, including the folders written by BitGraph Folder.

npx @mikeargento/bitgraph-player rule.json bundle/ > verdict.json

To begin a rule from the files themselves, init hashes the files and writes a skeleton with the cast filled in:

npx @mikeargento/bitgraph-player init po.pdf delivery.jpg approval.pdf --out rule.json

It deliberately leaves requires.ordering unset. The security floor belongs to the rule author. Player will not choose it.

The process exit code is the verdict summary, so another program can gate on it directly:

Same evidence. Same verdict.

Two runs of the same rule bytes over the same bundle contents produce byte-identical verdicts, on any machine, at any later time. The verdict carries no timestamp, filesystem path, or machine-local state. Every ordering conclusion identifies the evidence it rests on and whether that conclusion depends on an assumption.

Auditing a decision stops being a matter of reading a report someone wrote and becomes replaying the decision yourself.

There is a loose architectural analogy to Ethereum: BitGraph provides the recorded substrate, while Player provides deterministic evaluation over it. The difference is deliberate. The EVM's value is that participants agree on execution. Player's value is that anyone can independently reproduce the evaluation. Player does not make BitGraph an authority. It makes claims over BitGraph evidence reproducible.

Specification

The semantics are specified precisely enough to reimplement. SPEC.md is normative. The published package is the MIT-licensed reference implementation, built on the same audit pipeline used to inspect a BitGraph bundle by hand. A conforming Player in any language must reach the same verdict from the same rule and the same evidence.