The engineering loop
What is generated,
and what remains yours?
Keep domain knowledge, technical bindings and handwritten integration in their proper places. Compile the declarations, inspect the generated changes, test the behavior, then trace the implementation back to its source.
Follow the lifecycle · Read anchor precision · Check the evidence boundaries
A lifecycle with explicit responsibilities
Edit the truth tree for knowledge. Review the business expectation; record human approval through the project’s review process.
Validation checks structure and supported semantics; roundtrip checks preservation. Neither substitutes for a business test.
Compile declarations into products and build the queryable graph. Do not hand-edit these derived knowledge representations.
Use the project’s technical bindings. Inspect the generation plan before writing supported behavior and structural code.
Keep external effects and remaining computations in the separate handwritten zone. Test them against agreed outcomes.
Compile and run the appropriate tests. Verify source anchors and output freshness; investigate drift before updating.
status-project distinguishes changed inputs from output-byte drift; generate-project --update --plan lists prospective actions, not a textual diff. Derive reverse-query line numbers from a verified UTF-8 span and matching source bytes, never a guessed filename or line.
Recorded bank generation evidence · 2026-11-11
Validation: 0 hard findings F-01; 157 atoms and byte-identical roundtrip F-02; graph: 389 nodes / 413 edges F-03; 235 generated files F-04; 0 compile errors F-06; 792 verified anchors F-05. These retain their capture date; the newer service acceptance is separate.
Ask where an implementation came from
A source anchor connects a knowledge declaration to a generated location. The useful answer includes identity, precision and freshness—not just a plausible filename.
A relation, not a correctness proof
An anchor supports “this location came from this declaration.” It does not establish that the declaration was approved or that every line of the program is correct.
Span and file are different answers
A span identifies a byte range; file identifies only a file. Treat ambiguous or unavailable as a limit, not permission to guess a line.
Check the matching bytes
Use source fingerprints and verification before translating a UTF-8 byte span into a line number. A graph snapshot without matching code locations cannot supply a precise code jump.
The Counter reverse-query guide walks both query directions using an actual verified location. It also explains stale inputs, output drift and updates. A canonical graph, a project knowledge graph and a workshop export are different representations; do not splice their identities together by name.
The Explorer Code view consumes a fixed, verified public snapshot rather than local paths. Its bank dataset passed matching-project source/anchor verification (F-30); it does not inherit this page’s historical runtime results.
Counter command reminder · after the guide’s setup
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" query-project --project truthsrc.project.json --out generated --knowledge SetCount --format human node "$TRUTHSRC_CLI" verify-project --project truthsrc.project.json --out generated --format human
Edit the layer that owns the change
Generate supported, declared behavior; handwrite the remaining computations and host integration. The tree is the only knowledge editing surface—not the only editable file in the project.
Supported finite folds do not yet provide reusable pure function definitions/references or function-level BDD; DEF-21 tracks that separate design without relaxing deterministic replay, type or version admission.
Domain declarations
Aggregates, commands and events, together with supported guard, binding and fold declarations, drive generation. Structure includes schemas, ports and test scaffolding. An invariant name alone does not implement a missing rule.
Technical bindings
Bindings connect the declared model to the chosen implementation profile and host contracts. Review them separately from business policy; generated products are not a second place to edit the same knowledge.
Host integration
Mock TA effect execution, JDBC wiring, recovery loops, read-side catch-up and HTTP pages remain explicit implementations. The bank’s 35 handwritten files were recorded as complete implementations F-08 · 2026-11-11.
The bank build includes its separate handwritten module through unmanagedSourceDirectories. The filesystem boundary keeps it outside normal regeneration; it is not a promise that arbitrary output paths or unrelated tools cannot overwrite files.
When the tree changes, generated files are refreshed; the handwritten zone is not overwritten. The 23/23 result from 2026-11-11 is generated unit tests F-07: handwritten production sources compile with that build, but this is not evidence of independent handwritten test expectations. In the newer technical candidate, actor 64 and readside 47 passed with fixed business expectations; those scopes share 23 generated tests and must not be summed as distinct cases F-25.
Where saga & Monarch come in
Two engines, two jobs — declared in truth, never confused:
Cross-aggregate consistency
A saga atom declares participants (aggregates), phases (Try / Confirm / Cancel) and compensation. It compiles to saga IR for saga-core — an Akka Typed, event-sourced TCC coordinator. The bank tree declares 2 sagas: cash payment (investor outgoing → collection incoming → order commit) and the independent refund.
Flow orchestration
A pipeline atom is an ordered business-step queue; steps execute slices (R16). It compiles to a plan for monarch-core — a recoverable stage-queue engine with cursor-based resume, journaled by monarch-persistence. The bank tree declares 4 pipelines (cash payment, TA submission, SIP dispatch, independent refund).
The rule that keeps them straight: Sagas own transaction boundaries; pipelines own flow order. They are not interchangeable, and the truth tree refuses to blur them.
Current technical result, separate acceptance boundaries
On 2026-11-12, bank030-relocated-20261112-02 passed and rechecked source / anchors / code / service F-24, including real database/HTTP and automated browser observations F-26. Its fresh SQL rebuild reached readiness in 66.847 s within the unchanged 90 s gate F-27. Native Darwin x64 / JDK11, one owner; inputs were unchanged and that owner’s resources and lease were released F-28. See the sanitized scope and evidence summary. The old P23/service02 failure remains historical (DEF-06).
Independent service experience remains open (DEF-07): session03 readiness failed; slot cleanup was not a pass, and the later fix candidate is unexecuted. Technical HTTP/browser passes do not close public material delivery (DEF-15) or human usability (DEF-16). Family observations (DEF-17), retry/backoff/deadline debt (DEF-18), targeted negatives and extra Node CI/typecheck (DEF-19), and legacy offline-bundle migration (DEF-20) are not signed off by the bank run.
BDD/Gherkin specs remain an unbuilt derivative (DEF-01). Formal workshop verification also needs the explicit paired materials and scope-specific environment; the convenience generation path is not a substitute.
Take the smallest useful loop first
Counter exercises creation, generation, querying, an author change, update and verification using Node. It does not claim to run the bank or validate a JVM service. The guide separates those later prerequisites.