Hands-on · zero to full loop
The guide: run the whole thing
Three levels: L1 the Node-only Counter tutorial, L2 the bank generation path and its separate formal workshop prerequisites, and L3 graph queries through MCP. A local generation command is not a formal service acceptance run. The bank’s newer technical pass and the still-open independent experience are described separately below.
Environment — choose the scope first
The Node-only tutorial and bank source scope need Node ≥ 22.13.0 (node:sqlite) F-13. Compiling generated Scala needs a JVM and sbt. Formal anchors/code/service verification additionally needs explicit matched materials; formal code/service is scoped to native Darwin x64 / JDK11 F-28. Read the prerequisites before treating any command as an acceptance path.
Path A · native Node
# macOS (Homebrew)
brew install node@22
# or with nvm
nvm install 22
node --version # must print v22.13.0 or newer
Path B · Docker for Node-only work
docker run --rm -it -v "$PWD":/work -w /work node:22 bash
This container is an option for Node work, not a substitute for the accepted native bank code/service environment.
Convenience Scala compilation · JVM + sbt
# macOS
brew install openjdk@11 sbt
# or the Docker variant for JVM work
docker run --rm -it -v "$PWD":/work -w /work sbtscala/scala-sbt:eclipse-temurin-11.0.24_9_1.10.11_2.13.14 bash
Get the toolchain
npm publication is still pending (DEF-03); a source checkout is the entry point shown here. Zero npm runtime dependencies does not include the bank workshop’s frozen compiler, third-party dependencies or runtime supply. A checkout alone is not the complete paired acceptance candidate (DEF-15).
Separately reviewed on 2026-11-12: the matched CLI package 0.5.0 passed package-pin verification, functional offline installation, actual prefix relocation and the Counter 0→2 update, with 40 command observations F-29. This is distinct from engines 0.3.0 F-23, public package delivery and human newcomer acceptance. Repeated update’s zero writes means generated-source files only, not graph/evidence writes. See the evidence summary.
export TRUTHSRC_WORKSPACE="$PWD"
git clone https://github.com/co-arising/metarch-truthsrc.git
export TRUTHSRC_CLI="$TRUTHSRC_WORKSPACE/metarch-truthsrc/bin/truthsrc.js"
node "$TRUTHSRC_CLI" --help
Run from your own exercise parent directory; the checkout directory must not exist. Keep the same shell: the absolute CLI path survives directory changes. No npm runtime installation is needed.
L1 · Counter: generate once, then change once
After preparing the tool above, remain in the exercise parent directory. counter-lab must not exist. Every command names its project and a separate generated-output directory.
node "$TRUTHSRC_CLI" init counter-lab --format human
cd counter-lab
node "$TRUTHSRC_CLI" generate-project --project truthsrc.project.json --out generated --plan --format human
node "$TRUTHSRC_CLI" generate-project --project truthsrc.project.json --out generated --format human
node "$TRUTHSRC_CLI" status-project --project truthsrc.project.json --out generated --format human
node "$TRUTHSRC_CLI" query-project --project truthsrc.project.json --out generated --knowledge SetCount --format human
The preview lists update actions, not a textual diff. After generation, expect inputs=current, evidence=verified and synchronized=true. These describe source and byte freshness, not Scala or bank behavior execution.
Reverse-query a real location, not a guessed file or line
The Explorer Code view is the no-install browsing surface for a published matching snapshot. Its bank source/anchor snapshot is fully verified (F-30); the local procedure below remains the way to verify your own current files.
A span is a half-open UTF-8 byte range, not a line number. This script derives a line from currently verified source and queries it back; it stops rather than inventing a missing location.
node --input-type=module <<'NODE'
import { execFileSync } from 'node:child_process';
import { readFileSync } from 'node:fs';
import { join } from 'node:path';
const cli = process.env.TRUTHSRC_CLI;
if (!cli) throw new Error('TRUTHSRC_CLI is required');
const base = ['--project', 'truthsrc.project.json', '--out', 'generated'];
const forward = JSON.parse(execFileSync(process.execPath, [cli, 'query-project', ...base,
'--knowledge', 'SetCount', '--format', 'json'], { encoding: 'utf8' }));
const loc = forward.result.flatMap(row => row.locations).find(item =>
item.file.endsWith('CounterRules.scala') && item.verification.spanVerified &&
item.freshness === 'current-bytes' && item.span.text.startsWith(' def SetCount('));
if (!loc) throw new Error('No verified current SetCount span; inspect status first');
const bytes = readFileSync(join('generated', loc.file));
const line = bytes.subarray(0, loc.span.start).toString('utf8').split('\n').length;
process.stdout.write(execFileSync(process.execPath, [cli, 'query-project', ...base,
'--file', loc.file, '--line', String(line), '--format', 'human'], { encoding: 'utf8' }));
NODE
Verify and export an offline snapshot
node "$TRUTHSRC_CLI" verify-project --project truthsrc.project.json --out generated --format human
node "$TRUTHSRC_CLI" view-project --project truthsrc.project.json --out generated --html counter-map.html --knowledge SetCount --format human
Open the newly created counter-map.html. It is a fixed read-only snapshot, not a live view of disk changes.
Change the initial value, see staleness, then synchronize
In truth/example/contexts/example/aggregates/counter/aggregate.yaml, change only count’s "default": "0" to "default": "2". Still inside counter-lab, run:
node "$TRUTHSRC_CLI" status-project --project truthsrc.project.json --out generated --format human
node "$TRUTHSRC_CLI" generate-project --project truthsrc.project.json --out generated --update --plan --format human
node "$TRUTHSRC_CLI" generate-project --project truthsrc.project.json --out generated --update --format human
node "$TRUTHSRC_CLI" verify-project --project truthsrc.project.json --out generated --format human
node "$TRUTHSRC_CLI" generate-project --project truthsrc.project.json --out generated --update --format human
Before update, inputs should be changed while existing files may remain unchanged: their bytes still match the last generation. After update, verification passes. The final repeat should report written=0 for generated source files, not all evidence writes. Keep old snapshots; use a new filename for a later export.
On an existing directory or output conflict, preserve it and inspect ownership and inputs. Do not delete directories or hand-edit ledgers to force success. See the tool’s TUTORIAL.md for the full CLI contract.
Optional · change a business rule, not just a default
Continue inside your own counter-lab after the 0→2 loop. No bank edits, original scaffold edits, JVM, database or MCP are needed. The approved toy requirement is: SetCount accepts 0 through 100 inclusive, with a nonempty id. Changing the initial default does not impose this command limit.
Agree on the boundary before changing the rule
Write these independent cases first; do not generate expected answers from the new predicate. Use id toy-counter and old count 2 for all four. A human approves the business expectation and scope; a test cannot grant that approval.
| Requested count | Expected decision | Expected event / state |
|---|---|---|
| -1 | reject · NEGATIVE_COUNT | No event; old state unchanged. |
| 0 | continue | CountSet(count=0); next count 0. |
| 100 | continue | CountSet(count=100); next count 100. |
| 101 | reject · NEGATIVE_COUNT | No event; old state unchanged. |
Save the Node-only Counter check outside the author tree. Set COUNTER_CHECK to that file’s absolute path; keep TRUTHSRC_CLI from setup. It needs the complete package’s documented lib/domain-products oracles. Run it before the edit: the original rule should fail the new 101 expectation.
: "${COUNTER_CHECK:?Set COUNTER_CHECK to the saved verify-counter-change.mjs absolute path}"
: "${TRUTHSRC_CLI:?Complete the CLI setup first}"
node "$COUNTER_CHECK" --project "$PWD/truthsrc.project.json"
Edit the existing guard, preserving its identity
In truth/example/contexts/example/aggregates/counter/slices/set-count.slice.yaml, find payload.guards’ existing ref: nonnegative-count row. Change only its cond from param.count >= 0 to the condition below. Keep the preceding nonempty-id guard, order, ref, errCode and onFail. Do not append a competing second range rule or patch generated Scala.
This is the replacement JSON member fragment, not a complete slice/YAML file.
{
"kind": "invariantRef",
"ref": "nonnegative-count",
"errCode": "NEGATIVE_COUNT",
"cond": "param.count >= 0 && param.count <= 100",
"onFail": "reject"
}
Reusing this guard deliberately reuses NEGATIVE_COUNT for both -1 and 101, despite its historical name. That is this toy exercise’s error policy, not a recommendation for production API wording. Changing identity/error policy needs its own explicit decision. Zero remains valid.
Check the author inputs, preview, update, then fully verify
All commands below run in counter-lab. Only the toy author edit is manual; generation writes generated/ and the project’s derived knowledge/evidence. The update plan lists actions, not a text diff.
node "$TRUTHSRC_CLI" validate --tree truth/example
node "$TRUTHSRC_CLI" roundtrip --tree truth/example
node "$TRUTHSRC_CLI" status-project --project truthsrc.project.json --out generated --format human
node "$TRUTHSRC_CLI" generate-project --project truthsrc.project.json --out generated --update --plan --format human
node "$TRUTHSRC_CLI" generate-project --project truthsrc.project.json --out generated --update --format human
node "$TRUTHSRC_CLI" verify-project --project truthsrc.project.json --out generated --format human
node "$TRUTHSRC_CLI" query-project --project truthsrc.project.json --out generated --knowledge SetCount --format human
node "$COUNTER_CHECK" --project "$PWD/truthsrc.project.json"
Now all four cases should pass. The script calls the public compile-project CLI to freshly admit the actual modified rule (that command takes --project, not --out). It evaluates those products using the same installed package’s decision, binding and fold oracles, with fixed expected answers. It is not a separately rewritten JavaScript range test. Replay deliberately gets state/event only, not command inputs.
Supported here: Counter decision @4 and dependencies/folds @6 at tool cb860b5c, package 0.5.0. Missing package modules, rejected syntax or different profiles must stop the exercise; no fallback arithmetic or fake success. The result is admitted-product behavior only, not execution of generated Scala, an HTTP service or bank acceptance. Generated verification cases are not automatically independent business tests.
Close the loop in both directions, and read the real code
Follow the forward SetCount query above to current verified locations. Open the actual generated rule and event handler: review the inclusive comparisons, retained reject code, payload binding and event-only assignment. Repeat the earlier byte-span-to-line reverse query against the new verified bytes, back to the author declaration. Never reuse an old guessed line number. verify-project checks source/anchor consistency, not execution; target-runtime claims still require separately run generated-code behavioral tests with independently approved expectations.
After review, repeat update if desired: zero generated-source writes indicates idempotent synchronization, not zero evidence writes. If ownership, MANUAL boundaries, inputs or output bytes conflict, stop and preserve them. Inspect status and the real diff; use a new explicitly owned exercise directory if needed, never delete output/SQLite/ledgers to force green.
L2 · Bank generation and formal workshop scopes
Node-only source checks, convenience generation and formal workshop acceptance are different entry points. The convenient npm run project may obtain engines, but formal anchors/code/service requires both an explicit clean1134 archive and an already prepared runtime-supply directory. The matched CLI, complete paired source materials and archive have no confirmed public delivery channel (DEF-15). Do not treat this page as a one-command public reproduction.
| Formal scope | Required inputs and environment |
|---|---|
| source | Your bank checkout, the complete adjacent matched tool checkout and Node. No JVM, database or browser. Rejects unused --archive and --runtime-supply flags. |
| anchors | Source inputs plus --archive: an absolute path to the existing clean1134 archive (frozen compiler/toolchain and third-party dependencies), and --runtime-supply: an absolute path to the existing prepared 0.3.0 receipt.json + maven/ directory, matching the project F-23. Neither is optional. |
| code | Both supplies above, plus native Darwin x64, an installed x64 JDK11 selected by --java-home, and the sandbox/Python prerequisites F-28. |
| service | All code prerequisites, plus a new exclusive resource lease, available Docker/socket and pinned database images, and explicit Playwright module and chrome-headless-shell paths. Service scope cannot omit the browser. |
Formal verification does not implicitly download, prepare or fall back to P23. The composed supply excludes the archive’s old engines and selects the separately locked runtime supply; the archive is not re-signed. The legacy offline-bundle migration remains separate (DEF-20). See the accepted scope and material contract.
Preflight only — set your own real paths first
Run from your own bank checkout root with its matched adjacent tool checkout. Set BANK to that checkout’s absolute path. For code scope, also set ARCHIVE, RUNTIME_SUPPLY and JAVA_HOME_BANK to existing, absolute local paths described above. These are required variables, not download locations or supplied files.
Source preflight has no archive/runtime flags.
: "${BANK:?Set BANK to your own bank checkout absolute path}"
node "$BANK/tools/bank-workshop.mjs" doctor --through source --format human
Code preflight explicitly selects both supplies and the installed JDK.
: "${BANK:?Set BANK to your own bank checkout absolute path}"
: "${ARCHIVE:?Set ARCHIVE to the existing clean1134 archive absolute path}"
: "${RUNTIME_SUPPLY:?Set RUNTIME_SUPPLY to the prepared 0.3.0 supply directory absolute path}"
: "${JAVA_HOME_BANK:?Set JAVA_HOME_BANK to the installed x64 JDK11 absolute path}"
node "$BANK/tools/bank-workshop.mjs" doctor --through code \
--archive "$ARCHIVE" --runtime-supply "$RUNTIME_SUPPLY" \
--java-home "$JAVA_HOME_BANK" --format human
Doctor is preflight, not acceptance. A subsequent verify must create a fresh run in a never-used direct child of the bank’s target/, with an existing parent and a canonical absolute path. Do not reuse an old run. Doctor without --run does not check that parent. Report/view and independent session start/status/stop use the run’s sealed supply; session commands reject archive/runtime-supply overrides. A later fix needs new execution evidence, not a relabelled report.
Convenience generation — not the workshop recipe
The existing local path validates, generates into generated/current/, compiles handwritten production sources with the generated project, and verifies anchors. Its first generation may fetch SHA-256-pinned engines from Maven Central. It does not establish that the formal supplies above are present, and it does not start or accept the service.
: "${TRUTHSRC_WORKSPACE:?Complete the source setup first}"
cd "$TRUTHSRC_WORKSPACE"
git clone https://github.com/co-arising/bank-wealth-demo.git
cd bank-wealth-demo
npm run validate
npm run compile
node "$TRUTHSRC_CLI" graph --tree truth/bank-wealth --out bank.graph.sqlite
npm run project
cd generated/current && sbt compile
sbt test
cd ../.. && node "$TRUTHSRC_CLI" verify-project \
--project truthsrc.project.json --out generated/current
Historical capture, 2026-11-11: 0 hard findings and 157 byte-identical roundtrip atoms F-01 F-02; 235 generated files F-04; 0 compile errors across 534 sources F-06; 23/23 generated unit tests, not independent handwritten tests F-07; 792 verified anchors F-05. These counts are not asserted for the newer service candidate.
bank030-relocated-20261112-02 passed and rechecked source / anchors / code / service on 2026-11-12 F-24, including real database/HTTP and automated browser observations F-26. The old P23/service02 failure stays historical (DEF-06). Independent experience remains open: session03 did not reach readiness, cleanup was not a pass, and the later fix candidate is unexecuted (DEF-07). Public materials (DEF-15) and human acceptance (DEF-16) are not signed off by that technical result. See the bank’s scoped results and remaining boundaries.
L3 · Optional graph collaboration through MCP
MCP is optional, not a prerequisite for the Counter CLI loop or rule-change exercise. It lets an agent use the declared graph alongside source inspection when planning a change. The server ships 26 read-oriented tools verified.
Register the server
# from any directory (path to your metarch-truthsrc checkout)
claude mcp add truthsrc -- node /absolute/path/to/metarch-truthsrc/bin/truthsrc.js mcp
Install the query skill
The toolchain ships a skill that teaches an agent the query discipline (budgeted graph walks, following next_actions, over-report semantics of blast_radius). Copy it into your project:
mkdir -p .claude/skills
cp -r /absolute/path/to/metarch-truthsrc/skills/truthsrc .claude/skills/
The exercise: plan an incremental change by blast radius
Give the agent a requirement
Try: “We need to change what happens when an SIP installment fails. Before proposing anything, query the truth graph for the blast radius of SipInstallmentFailed and report which slices, read models and pipelines are affected.”
Watch the discipline work
The agent should report nodes actually reached, traversal limits and missing modeled connections. The website’s 55-node snapshot result contains aggregates, commands, events and slices—not read models or pipelines F-21. Review those dependencies separately before drafting a proposal against the appropriate author inputs.
Apply the editing contract
A human approves the business expectation and editing scope. Validate and roundtrip check their specified contracts; neither approves business meaning. Preview update actions with generate-project --project truthsrc.project.json --out generated/current --update --plan, then run the relevant behavioral checks and anchor verification. The plan is not a textual diff.
Also shipped: skills for extracting a tree from an existing codebase, from reachable data, or bootstrapping workshop drafts from a one-line description — skills/ in the toolchain repo.
Red lines & recovery
Do not patch derived artifacts or force past failed gates. Business meaning belongs in the author tree; technical choices in bindings; parsing/generation defects in the shared toolchain; external effects in supported handwritten implementations. Preserve conflicts and failed evidence. A graphstore cache and the project knowledge/anchor database are different assets: one graph command cannot recover every kind of evidence. Do not delete SQLite files indiscriminately.
Stuck? The toolchain README has a diagnostics section; the facts page tells you exactly which claims are verified on which date — if your numbers differ from ours, trust your terminal.