FABRIC-MEM-GRANT-0: one memory grant carrier, one microVM sizing policy, one grain-parameterised rounder (reconciles #11883 + #11885)

[gunbai-bot]

Summary

FABRIC-MEM-GRANT-0, reconciled from the two independent green implementations (#11883 session/bright-ram-63 @ 125659f and #11885 session/royal-moth-544 @ 80ec506). One carrier, one policy, one rounder, one witness suite. Both superseded PRs are closed with a comment saying which base won.

The defect this addresses is a bypass around the fabric transaction, not an absence of demand consumption: memory is screened before reservation and the runner reads the requirement, but memory is never converted into a grant, never atomically reserved against live host use, and never carried on CellReservation. This PR lands the first of those — the grant carrier and the policy that mints one — and nothing else (see "What this does NOT do").

Base chosen: session/royal-moth-544, and why

Both lanes converged on more than the brief recorded: both carry MemoryGrant<P, A> with a sole_constructor authority token constructed only inside the policy's issue fold, and both take the per-cell ceiling as a parameter. Re-derived, the differences that decided the base:

1. The rounder fork is resolved, not repeated. royal-moth moves GrainRounding and round_up_to_grain(bytes, grain) to std.measure, reduces gunbc.floor_demand round_up_to_gibibyte_grain to its gibibyte binding, and re-points the three consumer imports (§3 replacement migration, cut at the root). bright-ram inlined a second grain-parameterised rounder in the policy beside floor_demand's — which is the fork.
2. References are modeled, not nicknamed. royal-moth's policy reference and permit issuer are std.decl_ref DeclarationRef; bright-ram's are NonEmptyStr where brand(...) free text (§3: cite the symbol).
3. The permit is a reasoned record carrying its default. royal-moth's MemoryCompatibilityPermit { default_grant, permitted_by, reason } rides inside the provenance, so "unstated axis without permit" has no constructor at the carrier and the policy refuses on its own typed arm. bright-ram carried compatibility_permit: Ref? beside a separate compatibility_default: ByteSize on the policy record — permit absent + default present is writable there, and the carrier needed a third refusal arm to validate it.

Ported from session/bright-ram-63

• Every fleet quantity the policy needs arrives as a parameter. royal-moth imported gunbc.runner_microvm for the cache allowance and admitted in its own frontier note that the wiring item (runner consuming the policy) would then close an import cycle. bright-ram's acyclicity argument is right: the binding now takes (allowance, ceiling), imports nothing from the runner, and is total (grain constructed via gibibyte_grain(), reference and permit are the module's own rows — no Unavailable arm left for a consumer to answer). The witness keeps the pairing obligation by executing the real allowance producer gunbc_runner_microvm_guest_cache_allowance() and assembling the policy exactly as the wiring consumer will.
• The unstated-axis-through-the-real-route claim (the_fleet_policy_binding_grants_an_unstated_axis_under_its_own_permit).
• The executed authority-token wall — re-executed here, not cited (M3 below).

Not ported, with reason: bright-ram's token carrying policy: Ref (the fixture policy can set that ref to anything, so it adds no guarantee over the type identity); microvm_memory_grant_is_compatibility_default (no consumer but its witness — §3c dangling; the carrier's memory_grant_standing_is_requirement_checked already answers it).

Applied once: the ByteSize repair (review 69467, review 69468)

gunbc_microvm_memory_compatibility_default_bytes: Int = 4294967296 on both branches is now data gunbc_microvm_memory_compatibility_default: ByteSize = gibibyte_to_byte_size(g: gibibyte(count: 4)) — the unit in the type, the magnitude reached through std.measure gibibyte_scale_factor_bytes, and the witness compares through byte_size_count.

The four decided things, kept

1. Representability is bounded against int_inclusive_max first (policy microvm_memory_grant_size), the ceiling second (carrier issue_memory_grant). M1 shows exactly one claim goes red when the order is flipped.
2. A gibibyte-grain control cannot discriminate the checked-add rounder from the subtraction rounder; the discriminator uses grain 1000 (measure_grain_rounding_witness_test an_aligned_count_at_the_bound_is_its_own_ceiling). M2 re-measures it.
3. Refusal-arm claims assert the arm and that the right inputs reach it (a_minimum_within_one_byte_of_the_bound_refuses_as_unrepresentable uses a small ceiling and still expects the unrepresentable arm).
4. The carrier does not foreclose the per-host CAS-linearized ledger (FABRIC-HOST-MEMORY-0): a MemoryGrant names its Work and Attempt by FabricIdentity, carries no host, cell or ledger state, and is the value a CellReservation will carry and one CAS will commit alongside occupancy.

Topology precondition (a gate, not an item): exact per-Work sizing is valid only where Work is bound before the VM boots. Nothing here lets a guest discover its Work after boot.

What this carrier does NOT do

• No production path consumes the policy. gunbc.runner_microvm runner_microvm_shape_after_cpu_admitted still reads the requirement as a fit gate and sizes the guest from the cell remainder. The wiring item is a declared frontier (§3c) at the foot of fabric_memory_grant_policy.dag, with the capability as its trigger: the microVM shape derives its guest memory from a MemoryGrant, with the remainder exposed as one nameable runner function and the runner's memory witnesses re-pointed at the granted size. Import direction for that wiring: runner → policy, never the reverse.
• No host ledger, no atomic reservation, no field on CellReservation. Those are items 2+ of the program.
• The witnesses do not run in CI. required_gate_prefixes has no test.claim.fabric row, so this suite is discovered and declined by the required gate; a green check says nothing about these files. Evidence is the local claim_batch run below.

Test plan — executed, at this head, with a binary built from it

Binary: claim_batch built locally (CTRL_BUILD_MODE=local cargo build --release --bin claim_batch, private target dir) from this branch's Rust tree, sha256 ee16009ead17190ef367c71b826d6737b36a09ed94ce04642d5956d8ec6aa611. The change is .dag-only, so the Rust tree at every head below is identical to the one the binary was built from. Recipe per entry: claim_batch --source-root dag --source-root src/v2 --entry <entry> --functions <all test fns>. Every log line carries the binary path, its sha256, git rev-parse HEAD and the dirty count.

Green at 0bbf7a163f3 (the semantic head; a65bcee222b adds one // annotation block only, and the fabric suite was re-run there — see the last row):

entry	result
test.claim.fabric_memory_grant_witness_test	16/16 PASS
test.claim.measure_grain_rounding_witness_test	4/4 PASS
test.claim.floor_demand_witness_test — the two rounder consumers (gibibyte_grain_rounds_up_and_leaves_a_whole_gibibyte_alone, a_count_at_the_representable_bound_has_no_gibibyte_ceiling)	2/2 PASS
test.claim.runner_microvm_witness_test — the_guest_cache_allowance_derives_from_the_receipts_last_unstalled_beat (the re-pointed GrainRounded consumer)	1/1 PASS
test.claim.fabric_memory_grant_witness_test at a65bcee222b	16/16 PASS

Mutation controls, each executed at 0bbf7a163f3 (dirty=1) and the tree restored to dirty=0 before the next:

#	mutation	measured
M1	policy bounds representability by policy.ceiling instead of int_inclusive_max (the ceiling-first order)	exactly ONE red: the_policy_carries_the_ceiling_refusal_out_rather_than_resizing; both sizing claims stay green — which is why they are not coverage for this distinction
M2	std.measure round_up_to_grain refuses n > max - (g-1) (the old checked-add pre-check restored)	an_aligned_count_at_the_bound_is_its_own_ceiling (grain 1000) RED; a_gibibyte_aligned_count_at_the_bound_is_its_own_ceiling stays GREEN — the power-of-two control does not discriminate, as decided
M3	a fn returning MicroVmMemoryGrantAuthority { } appended to the witness module	module REFUSED at resolve, no claim runs: fabric_memory_grant_witness_test.dag:416:3: error: sole_constructor type 'MicroVmMemoryGrantAuthority' cannot be constructed outside its defining module
M4	carrier clamps to the ceiling instead of refusing	4 red: a_grant_above_the_ceiling_refuses_and_does_not_clamp, a_demand_larger_than_the_cell_is_reported_against_the_ceiling, the_policy_carries_the_ceiling_refusal_out_rather_than_resizing, a_permit_default_above_the_ceiling_is_refused_by_the_ceiling_law
M5	policy representability guard deleted	a_minimum_within_one_byte_of_the_bound_refuses_as_unrepresentable RED with runtime error [integer-overflow]: 9223372036854775807 + 1 does not fit in a 64-bit Int — the untyped abort the guard replaces
M6	carrier decides the minimum before the ceiling	a_demand_larger_than_the_cell_is_reported_against_the_ceiling RED

Not run: the required floor. These modules are outside required_gate_prefixes, so a green check on this PR is not evidence about them (and the floor's own SUCCESS-over-refusal defect is open — docs/plans/microvm-and-floor-wind-down-state.md §1).

Superseded

• PARKED: dynamic per-VM memory (stage 1) — side-chat design ruled and approved, build parked #11883 (session/bright-ram-63) — closed, comment says why.
• PARKED: FABRIC-MEM-GRANT-0 mid-build — two uncompiled branches, and the overflow construction to carry forward #11885 (session/royal-moth-544) — closed, comment says why; this PR's base.

🤖 Generated with Claude Code

[gunbai-bot]

review 69638 addressed in d08c9b8: memory_grant_standing_is_requirement_checked deleted from the carrier — verified its only call sites were the witness suite (DESIGN §3c: a witness is not a consumer). Each witness site now matches the MemoryGrantStanding arm through a witness-local helper. Re-run at head d08c9b8 with the same locally built claim_batch (sha ee16009e…): fabric suite 16/16 PASS, dirty=0.