Skip to content
backprop-trace

Getting Started

backprop-trace is a CLI + library. You can do everything from the bp command, or pull the public API in TypeScript. This page covers the three commands that prove the system works.

Prerequisites

Section titled “Prerequisites”
  • Node.js 22.x (pinned — V8 fdlibm Math.exp determinism is load-bearing; see Architecture for why)
  • A package manager: pnpm (preferred), npm, or yarn

Install

Section titled “Install”
Terminal window
pnpm add @mcptoolshop/backprop-trace
# or:
npm install @mcptoolshop/backprop-trace

Or globally (for bp in any shell):

Terminal window
npm install -g @mcptoolshop/backprop-trace

The three commands

Section titled “The three commands”

These are the same three blocks from the README’s 30-second quickstart, expanded.

1. Accept a good receipt

Section titled “1. Accept a good receipt”
Terminal window
npx bp verify mazur
# exit 0 — schema + reconcile + engine-reproduce + byte-equal-vs-golden

This runs the full Mazur gate on the bundled fixture (fixtures/mazur.golden.jsonl):

  1. Schema validate the receipt (Ajv against schemas/receipt.v0.1.0.json)
  2. Reconcile — all 26 rules pass within hybrid tolerance (atol=1e-12, rtol=1e-9 for this engine-authored receipt; the verifier clamps any requested tolerance to a fixed ceiling first, so a receipt can never loosen its own pass band — see Architecture)
  3. Engine-reproduce — re-run runMazurStep(MAZUR_INPUT) and compare bytewise
  4. Byte-equal vs golden — the canonical bytes match the committed fixture
  5. Fixture status enum sanity
  6. Published-anchor drift — post_update_loss.total = 0.29102777369359933 matches the Mazur 2015 walkthrough

The Mazur 2-2-2 is the most-cited single-step backprop example on the open web. Every number in it is derivable by hand.

A recognizable receipt: the hero classifier (v1.0.0)

Section titled “A recognizable receipt: the hero classifier (v1.0.0)”

The Mazur 2-2-2 is the textbook toy; v1.0.0 also ships a receipt you can picture. fixtures/hero-classifier.golden.jsonl is a 9-pixel → 16-ReLU → 4-class softmax glyph classifier — a step that looks like a real (if tiny) network — byte-reproducible on CPU, single and multi-step:

Terminal window
npx bp verify general \
  node_modules/@mcptoolshop/backprop-trace/fixtures/hero-classifier.golden.jsonl --json
# exit 0 — schema + reconcile (26 rules) + engine-reproduce byte-equal

The --json envelope carries rules_evaluated and gated_off, so the PASS is auditable — you see which substantive rules actually fired (e.g. softmax + cross-entropy rules) versus which were gated off because their feature block was absent (e.g. the Adam-family or batch rules). This is the receipt the compliance bundle worked example uses.

2. Reject a deliberately-broken receipt

Section titled “2. Reject a deliberately-broken receipt”
Terminal window
npx bp reconcile receipt \
  node_modules/@mcptoolshop/backprop-trace/fixtures/bad/mazur.bad-gradient.jsonl
# exit 1 — Rule 4: update.gradient mismatch on w5

The bad fixture has the gradient field of one update mutated. Rule 4 (update gradient consistency) recomputes the gradient from named factors (output error signal × upstream activation), compares to the stored value, finds disagreement within none-of-tolerance, exits 1.

The load-bearing detail: the verifier rejects BEFORE consulting fixture_status.authoring_state = "deliberately_broken". If the reconciler used metadata to decide whether to fail, the oracle would be consulting the artifact it judges — that’s the Csmith/CompCert anti-circularity violation. Every bad fixture must be reject-by-math, not reject-by-label.

The test plate at test/reconcile.bad-*.test.ts formalizes this — it loads the bad fixture as raw JSONL, runs reconcileReceipt() first, captures the failure, THEN reads meta.json to assert the right rule fired. Reading meta.json before reconcile would invalidate the test.

3. Emit canonical bytes (the attestation seam)

Section titled “3. Emit canonical bytes (the attestation seam)”
Terminal window
npx bp generate mazur | sha256sum
# 9-sig-fig canonical bytes (V8/Node 22.x) — in-toto v1 attestation seam

bp generate mazur re-runs the engine and emits the canonical JSONL receipt to stdout. The bytes are deterministic on Node 22.x (see Architecture for the determinism scope). Pipe them to sha256sum (or shasum -a 256) to get the bytes hash — that’s what an in-toto v1 attestation envelope would wrap as its subject digest.

This is the seam where backprop-trace plugs into supply-chain attestation: an in-toto subject.digest.sha256 equals the receipt-bytes hash; the predicate is the receipt itself plus a producer signature. backprop-trace doesn’t ship the signing layer; it produces deterministic bytes that the signing layer can wrap.

Next steps

Section titled “Next steps”