Decouple application from consensus core via pluggable StateMachine

[naveed949]

What & why

First step toward using this project as a framework in real backend systems (embedded-library consumption): make the Raft consensus core domain-agnostic so any application can plug in its own state machine, instead of the book domain being hard-wired into the core.

Decisions confirmed with the owner: consume as an embedded library, and the first phase is the pluggable state machine (decoupling) — recorded in ADR-0017.

The change

• consensus/stateMachine.ts now defines the generic StateMachine<C, T> interface (apply / snapshot / restore / optional size) that an application implements.
• The replicated log carries a flat command union Command<C> = NOOP | CONFIG | C, so domain commands ride the log directly — the wire/persistence format is unchanged and node.submit(domainCommand) stays ergonomic. NOOP and CONFIG are reserved type discriminators.
• RaftNode<C, T, SM> and ReplicatedStateMachine<C, T> are generic. The substrate concerns — audit hash-chain, idempotency, snapshotting, observability — stay in the substrate and now work for any state machine.
  • node.app → the concrete application state machine (domain reads).
  • node.stateMachine → the substrate wrapper (audit, size, dedup).
• The book service moves to the example layer (models/book.ts, models/bookStateMachine.ts). Audit and raft HTTP routes are generic; book routes / app.ts are the example's adapter.
• Added src/index.ts public library surface. Renamed the books_total metric → state_machine_entries and node status books → stateSize.
• Type inference flows from the supplied state machine (stateMachine: SM & StateMachine<C, T>), so C/T are inferred at the construction site without explicit type args.
• Casts are localized to the two inherently untyped boundaries (transport entries, persisted log) and commented.

Bring-your-own-state-machine

class CounterStateMachine implements StateMachine<{ type: 'INCR'; by: number }, number> {
  private n = 0;
  apply(cmd) { this.n += cmd.by; return { status: 200, data: this.n }; }
  snapshot() { return this.n; }
  restore(d: unknown) { this.n = (d as number) ?? 0; }
}
const node = new RaftNode({ id: 'node1', peers: [], stateMachine: new CounterStateMachine() }, new HttpTransport());

Verification

• npx tsc --noEmit clean.
• All 42 tests pass (consensus, bookApi, platform, snapshot, readBarrier, membership, crashConsistency, logBacktracking).

Not in this PR (follow-ups)

Developer-ergonomics polish (builder DSL, richer public API) and production-hardening (joint-consensus membership, snapshot chunking, follower read leases, pluggable adapters) are deliberately deferred to later phases.

🤖 Generated with Claude Code

---

Generated by Claude Code