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.

00

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
01

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.

02

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.

02b

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 countExpected decisionExpected event / state
-1reject · NEGATIVE_COUNTNo event; old state unchanged.
0continueCountSet(count=0); next count 0.
100continueCountSet(count=100); next count 100.
101reject · NEGATIVE_COUNTNo 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.

WHAT THIS CHECK DOES NOT PROVE

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.

03

L2 · Bank generation and formal workshop scopes

PREREQUISITES — NOT AN INSTALLATION SHORTCUT

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 scopeRequired inputs and environment
sourceYour bank checkout, the complete adjacent matched tool checkout and Node. No JVM, database or browser. Rejects unused --archive and --runtime-supply flags.
anchorsSource 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.
codeBoth supplies above, plus native Darwin x64, an installed x64 JDK11 selected by --java-home, and the sandbox/Python prerequisites F-28.
serviceAll 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.

CURRENT TECHNICAL EVIDENCE, NOT YOUR RUN’S RESULT

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.

04

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

in Claude Code, inside bank-wealth-demo

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

describe → expand → blast_radius, following next_actions

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

agents draft; humans approve; gates check

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.

05

Red lines & recovery

NEVER

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.