Role: source-reading guide
Audience: protocol implementers and auditors
Authority: current source paths, enforced by check:runtime-doc-paths
The core/ tree contains three nested state machines and the infrastructure
that drives them. Read the cascade before the services around it.
core/runtime/types.ts — Runtime Input, Tx, Frame, and live replica.core/entity/types.ts — Entity State, candidate, Frame, and replica.core/types/account.ts — Account State, replica, Input, Tx, and Frame.core/account/commitment/state-root.ts — the exact bilateral commitment.core/entity/consensus/state-root.ts — Entity commitment, including the
deterministic Account-replica projection.core/runtime/frame/process.ts — the visible Runtime coordinator.core/runtime/frame/lifecycle/prepare.ts — detach one immutable Runtime input.core/runtime/frame/apply.ts — apply Runtime and routed Entity work.core/entity/consensus/input/consensus.ts — the Entity entry point.core/entity/consensus/frame/application.ts — replay a candidate.core/account/consensus/index.ts — the Account entry point.core/account/tx/apply.ts — validate one Account transaction.core/account/tx/mutation.ts — mutate Account-owned financial state.core/entity/consensus/proposal/start.ts — one canonical proposal builder;
a one-member board certifies its own quorum without a second implementation.core/entity/consensus/proposal/precommit-input.ts — multi-validator
precommit collection and threshold certification.core/account/consensus/incoming/collision.ts — deterministic same-height
LEFT-wins rollback.core/account/consensus/incoming/ack-commit.ts — bilateral commit.core/runtime/frame/lifecycle/storage-failure.ts — pre/post-WAL failure rules.core/storage/commit/commit.ts — the only durable Runtime commit point.core/storage/recovery/journal/replay.ts — rebuild from durable truth.core/jurisdiction/machine/history-consensus/index.ts — certified J-prefix facts.core/jurisdiction/adapter/events/ingress-transform.ts — external evidence boundary.core/entity/tx/j-events.ts — certified J effects enter Entity.core/account/settlement/j-finality.ts — Account-owned settlement finality.core/runtime/j-submit/j-submit.ts — durable post-frame submission lifecycle.| Folder | Owns | Must not own |
|---|---|---|
core/runtime/ |
Runtime input, frame, WAL ordering, routing | Entity/Account financial rules |
core/entity/ |
Entity transactions, candidates, Hanko consensus | physical storage or transport |
core/account/ |
bilateral consensus and every money mutation | Entity/Runtime orchestration |
core/jurisdiction/machine/ |
deterministic J protocol facts | RPC/provider behavior |
core/jurisdiction/adapter/ |
chain reads, authenticated receipts, submissions | consensus authority |
core/storage/ |
current state, WAL, history views, replay | protocol decisions |
core/network/p2p/ |
Runtime-to-Runtime delivery | financial state |
core/network/relay/ |
discovery and market relay services | Runtime consensus |
core/api/public/ |
public typed Runtime surface | service lifecycle |
core/api/server/ |
HTTP/WebSocket delivery | process orchestration |
core/orchestrator/ |
process startup and service composition | reducer logic |
core/api/runtime-adapter/ |
frontend projections and commands | direct state mutation |
core/watchtower/ |
encrypted appointments and chain action | spend-capable user keys |
core/qa/ |
diagnostics and human-readable state dumps | protocol behavior |
Runtime
one local writer
Input → apply owned state → WAL → publish → effects
Entity
validator set
Input → isolated candidate → Hanko certificate → install → outputs
Account
two peers
Input → isolated candidate → bilateral ACK → install → outputs
*State is frame-committed deterministic data. *Replica is the live instance
that also owns the next candidate, mempool, certification, retry, or delivery
metadata. *Machine describes transition logic; it is not a data type.
Runtime is locally single-writer, not concurrent consensus. Entity consensus may be single-signer or multi-signer. Account consensus is always bilateral. The common vocabulary must not hide these different trust boundaries behind a generic base class.
core/__tests__/runtime/commit/runtime-frame-atomicity.test.ts — mutation/WAL/read
barriers and input recovery.core/scripts/operations/persistence/persistence-simultaneous-proposal-smoke.ts — Account
collision, rollback ordering, and LEFT wins.core/__tests__/account/consensus/account-frame-integrity.test.ts — exact frame validation.core/__tests__/finance/state/derive-delta-property.test.ts — the single balance model.core/__tests__/storage/runtime/storage-canonical-hash.test.ts — durable canonical bytes.core/__tests__/security/authority/multisig-secondary-hanko.test.ts — candidate
certification.Generated bindings live under jurisdictions/typechain-types/. Scenario,
benchmark, QA, and archived files are valuable evidence but are not protocol
authority.