Skip to main content

Embedded / Library First Run

Choose this track when you want to understand Transit as a shared local engine first.

What You Are Proving​

This path is about four things:

  • local append and replay
  • branch and merge as first-class lineage
  • tiered publication and remote restore
  • the fact that the same semantics later power server mode

Fastest Proof Path​

From the repo root, run the shared local-engine proof directly:

transit proof local-engine --root target/transit-docs/local

That gives you the shortest direct proof of local append, replay, and lineage behavior without routing through repo-local helper tasks.

If You Want To Narrow The Scope​

Run the embedded proof directly:

transit proof local-engine --root target/transit-docs/local

Run the tiered publication/restore proof:

transit proof tiered-engine --root target/transit-docs/tiered

Run the controlled failover proof:

transit proof controlled-failover --root target/transit-docs/controlled-failover

Run the integrity proof:

transit proof integrity --root target/transit-docs/integrity

Run the materialization proof:

transit proof materialization --root target/transit-docs/materialization

Run the reference-projection proof:

transit proof reference-projection --root target/transit-docs/reference-projection

Check the local log state after a proof:

transit status --root target/transit-docs/local

What To Look For​

When these proofs pass, you should have evidence that:

  • appends become ordered immutable history
  • branches reuse ancestor history instead of copying old bytes
  • merges preserve explicit parent lineage
  • rolled immutable segments can be published and restored through the remote tier
  • the current failover slices use explicit readiness, lease handoff, former-primary fencing, and automatic leader election without relaxing the one-writer model
  • integrity and derived-state proofs remain attached to the same shared history model

Mental Model​

Think of the embedded engine as the local station where trains are assembled and dispatched.

  • the local head is the active platform
  • rolled segments are completed carriages
  • the manifest is the switching sheet that says where each carriage belongs
  • the remote tier is the yard where cold history can be restored later

Where To Go Next​