heddleGoverned
Bootstrap a Raft-governed HeddleNode over seam — the consensus-backed front door of design §9, parallel to heddleStatic. The data plane is unchanged from H4 (a replicated ledger, demand board, reservations, and liveness over the seam); what governance adds is that the non-monotone acts — mint and topology reconfiguration — are serialized through the raft log rather than applied locally:
Mint (GovernedHeddleNode.mint) is a Raft proposal; a partitioned minority can never commit one, so two halves of a split can never both mint against the same supply (§9 #1). Mint identity is derived from a per-act key that is unique, retry-stable, and restart-safe, so a distinct act never silently collides and a retry never double-mints.
Reshape (GovernedHeddleNode.prepare/activate/…) serializes through the log; the accept/refuse decision is made against a log-pure control-state projection (a deterministic function of the log prefix — never the gossip-merged Quilter), so two overlapping reshapes of one child are ordered by commit index and the loser surfaces as a structured ControlConflict, identically on every peer (§9 #2, §4.6, §10.11).
Membership (GovernedHeddleNode.enroll/depart) is a log-known roster: the set an operation that must wait for every participant quantifies over. The data-plane roster is seam-derived and therefore open, so it cannot serve; the enrolled set is a fold of the committed log and identical on every peer that applied that prefix (§9;
docs/heddle-ledger-relocation-design.md§6.2). A peer should enroll itself before its first data-plane call.Fencing/reclamation (GovernedHeddleNode.revocation) is specified only — the seam is defined, reclamation is a later feature (§9 #3; part of #1602).
The coordination-free spend/schedule/reserve path never touches the log at any frequency — the whole point of confining consensus to the embroidery (§10.13).
All supply and topology come from the log. Unlike heddleStatic, heddleGoverned takes no pre-partitioned mint or pre-built topology: a governed node starts from the empty ledger and every peer builds identical state by applying the same committed log. This is deliberate — a locally applied genesis could diverge silently across peers (inflating total supply under a front door meant to prevent split-brain supply), so genesis is not a governed-mode concept; mint the initial supply and prepare the initial tree through the control-plane verbs after bootstrap.
Paired entry points, no nullable consensus (§9): heddleStatic takes a pre-partitioned mint and no RaftNode; heddleGoverned takes a required RaftNode and no mint. Each takes exactly the dependencies its path needs — the repo's "Optional ≠ tuning" rule forbids one door with a nullable RaftNode? knob.
Shared-RaftNode compaction caveat. v1 does not publish snapshots to raft (log compaction is off), so the control plane can replay the whole log via committedFrom(1). If raft is a node shared with another state machine that publishes snapshots, a control entry below the compaction floor would be skipped on replay — give the control plane a dedicated Raft node (or one whose compaction floor never advances past unreplayed control entries).
Time is a dependency (§11): clock is required, never a wall-clock default.
Receiver
the scope the node's owned coroutines (replication, demand, liveness, and the control plane's committed-log apply loop) live on; cancel it to tear the node down.
Parameters
the data-plane fabric this peer participates over.
this peer's replica identity; matches Seam.selfId by string value.
the control plane — the required consensus log mint and reshape serialize through.
the root group of the fairness tree (the handle consumers build AttachmentRecords against).
the injected wall clock, used for demand TTL and liveness timing.
the policy caps, §8.2 bound cap, TTL, and replication/liveness/RNG knobs.
a token that MUST be fresh on every process incarnation of this peer — a boot id, a persisted monotonic epoch, or a UUID. It namespaces the per-act idempotency keys, so restart safety rests on it: reusing a value across restarts would regenerate colliding keys and a new act could silently vanish behind the dedup table. It is a required injected dependency precisely because the node cannot self-generate restart-uniqueness without durable storage or true entropy — never pass a value derived from a test-seedable Random.
the numeric sibling of incarnation: same required per-boot discipline, but it must be a strictly-increasing Long (a persisted monotonic boot counter) because it seeds the ordering of the demand-board clock rather than the uniqueness of a dedup key. A restarted peer's demand out-clocks its dead incarnation's by this epoch, closing the TTL-timing-dependent restart window on the ephemeral demand board (#1666). Must be in [0, 2^31).
Samples
val root = GroupId("root")
val leaf = GroupId("leaf")
val self = ReplicaId(seam.selfId.value)
val edge = AttachmentId("root→leaf")
val node = heddleGoverned(
seam = seam,
self = self,
raft = raft,
root = root,
clock = { Instant.fromEpochMilliseconds(0L) },
config = HeddleConfig(policy = PolicyConfig(quantum = 10L), maxHoldingsPerPeer = 1_000L),
incarnation = "boot-2026-07-24T00:00:00Z", // fresh per process incarnation — a boot id / epoch / UUID
epoch = 1L, // numeric per-boot counter — bumped every restart
)
// Enrolling self is what opens this node's write gate: until it applies, `reserve` returns null
// and `schedule` delegates nothing, so an unenrolled peer can never author entitlement (#1693).
check(node.enroll(self) is ControlOutcome.Applied)
// Mint and reshape are serialized through the Raft log — each returns a structured outcome.
check(node.mint(self, 100L) is ControlOutcome.Applied)
node.prepare(AttachmentRecord(edge, root, leaf, Weight.ONE))
node.activate(edge)
// The spend path is coordination-free — it issues no consensus messages.
node.advertise(edge, Demand(targetOutstanding = 100L, maximumUsefulGrant = 100L))
node.schedule(root)
node.reserve(leaf, maximumCost = 10L)?.let { node.complete(it, actualCost = 7L) }