Spark declared-unit digest: one sealed DigestStdin per bind; delete the artifact store

[briansrls]

Repairs this PR per the ruling that chose Option A: delete the persisted declared-unit artifact and compute the SHA-256 exactly once at the harness_bind_seat transaction root, before rounds and candidate enumeration.

The model

The route needs one fact:

Does the unit digest observed on the answering launch equal the digest of the unit bytes the current declaration renders?

The store answered a different one — did an earlier apply publish a receipt saying what it rendered? — for which there is no consumer, and paid write → read → parse → currency-check for it, plus an integrity obligation of its own. DESIGN §2: minimize the demand graph before materializing its answers. There is one demand in one placement transaction, so the correct least common ancestor is harness_bind_seat and there is no recurrence to materialize.

Deleted

RenderedUnitArtifact, SparkPairUnitSealed, spark_pair_seal_unit_render, spark_pair_publish_declared_head_artifact, SparkPairDeclaredHeadPublish, the target/spark-pair-declared-head-* paths, the record serialize/parse, the Filesystem List/Read/Write/Delete around them, apply's artifact-publish stage, and the store-specific exclusion / wet-schedule / floor-route-gap rows and tests. parse_content_hash_wire and its v1 seed work go too: this PR introduced them for that record and nothing else consumes them. Apply still writes the actual systemd unit through its existing route — only the second receipt file disappears.

Replaced by

type DeclaredUnitDigestEvidence sole_constructor { unit_name: NonEmptyStr, digest: ContentHash }

type DeclaredUnitDigestStanding
  = DeclaredUnitDigested { evidence: DeclaredUnitDigestEvidence }
  | DeclaredUnitDigestUnavailable { obligation: NonEmptyStr }

fn spark_pair_declared_unit_digest(render: SparkPairUnitRender) -> DeclaredUnitDigestStanding

sole_constructor is on the record, not the coproduct — the repo records that the latter does not seal direct variant construction. There is no text field, so there is no second field for the digest to disagree with. Every failure of the digest leg is a typed Unavailable, never a fabricated or omitted digest.

Egress (gunbc.recurring_failure_mode admitted_call_edge_with_unrestricted_value_egress): the question is not who may call the mint but what may leave. Every exported fn whose return type contains the evidence either takes one as input (so it propagates and never mints) or takes no value a caller can aim the digest with — the mint hashes exactly the render it is given, and spark_pair_declared_head_digest / the harness roster fns take only a FabricGroup and render from the production declarations.

Once per bind, not once per collection

harness_bind_seat mints the roster before the placement-round fold and carries it through harness_placement_round → harness_collect_candidates → harness_add_candidate → harness_serving_route as a supplied value. It was previously read inside harness_collect_candidates, which is invoked inside the fold. No round or candidate renders or hashes. Group B keeps glm_canary_declared_unit_artifact_obligation and never inherits the pair unit.

Evidence, and its frontier stated honestly

Because the evidence is sealed, a fixture cannot author a standing — it must supply a render to the real mint, which is a DigestStdin. That is the inhabitance half of DESIGN §3's pairing obligation and it is why every witness needing a declared digest moves to the local-repo wet lane, enrolled per function in local_repo_wet_schedule and floor_route_gap.

Control	Where
same bytes → same digest	spark_pair_head_unit_digest_witness (wet)
one-byte difference → different digest	same (wet)
production Group A render → digest, agreeing with the mint over the same render	same (wet)
render refusal → Unavailable (carrying the render's own cause)	spark_pair_serving_realization_witness (hermetic)
empty render → Unavailable before DigestStdin	same (hermetic)
real roster reaches the incarnation frontier through the production fold	serving_availability_bind_wet_witness (wet)
withdrawn roster → refuses at the declared unit, not the incarnation	same — the discriminator for the row above
ready route reaches the incarnation frontier via harness_bind_candidate	same (moved here from the hermetic file, which needs a digested standing)
matching declared + observed → next route frontier; different / incomparable → refuses before configuration	spark_serving_offer_route_witness (wet)
Group B → its own obligation	harness_declared_unit_digest's FabricGroupB arm

Frontiers, stated rather than implied:

• No enrolled witness executes harness_bind_seat — it reads the clock, the event log and the fleet over SSH. The once-per-bind property is therefore claimed at the highest supplied interface available (harness_add_serving_candidate / harness_bind_candidate take the roster as a parameter) and is structural below that: the mint is a single let in harness_bind_seat, and every function beneath it takes the roster as an argument, so a round cannot re-mint without a new call edge.
• The sha256sum-refused and malformed-hex arms are unexercised. They sit below DigestStdin, which has no mock_response, so no hermetic witness can express them and the wet lane cannot make sha256sum fail on demand. Both are written as typed Unavailable.
• Foreign construction is walled by the sole_constructor rule on the source→.dag path (structurally guaranteed) and not on the emitted-Rust path, where the mirror is a public struct — the same boundary extdeps.filesystem.filesystem_io records, with the same next-rung trigger.
• One control is deleted rather than kept green. A declared digest in another hash family is no longer authorable anywhere a check could run, since the only mint is DigestStdin; per DESIGN §4b that check would be a decoration. The incomparable arm is still walled from the observed side, which is a host reading and remains free to be any family.

The required floor on this PR is the executing evidence.

🤖 Generated with Claude Code

A hunk that was here and is now gone

An earlier commit on this branch (b892997a7aa) added ~51 lines of hand-written seed Rust to required_floor_runner.rs, seeding the share-producer roster modules into the floor's prepared subject to get past a PureProducerShareProducerModuleOutsideSubject refusal. Review 67015 flagged it as orthogonal to this PR's subject and landing without a receipt.

It is reverted rather than documented. #11455 ("Floor pure-producer share: scope roster admission to the prepared subject; stale only when absent from the corpus") is on main and is the same class of fix; it is already an ancestor of this head via the merge, so the branch was carrying a hand-rolled solution alongside the modelled one. Restoring main's version of that file reverts exactly that commit and nothing else — it was the only branch change to it.

That removes the need for a seed-growth admission row here, and it puts the question to the floor rather than to a paragraph: if the refusal returns, the hunk was load-bearing and comes back with its receipt; if the floor is green, it was redundant with #11455 and is correctly gone.

[gunbai-bot]

Durable-store repair is at 27ae041ac58301d330b43564028701d2bbde3941.

Apply publishes RenderedUnitArtifact (text + DigestStdin digest + render_inputs_identity) to target/spark-pair-declared-head-{group}. Placement / spark_pair_head_unit_declared_digest_among reads that file and compares stored identity to current render inputs. Miss or mismatch is DeclaredUnitDigestUnavailable — no render, no sha256sum per placement round.

Production spark_pair_realization stays unsigned. Group B still uses glm_canary_declared_unit_artifact_obligation. Wet witnesses retargeted: digest-of-bytes + publish/lookup; bind GREEN publishes then places, RED withdraws then places.

@merry-eagle-325: this session did not wait on #11410/#11411; harness_seat only changed the digest consumer (harness_declared_unit_digest / comments). Expect a merge conflict on that file. Head to coordinate: 27ae041ac58301d330b43564028701d2bbde3941.

[gunbai-bot]

Addressed review 66618 at 0d942bac007cfe2c1195a3216ca43370bac3ab26.

• Deleted spark_pair_head_unit_declared_digest_among. Production (harness_declared_unit_digest) and the digest witness call spark_pair_lookup_declared_head_digest.
• Deleted spark_pair_worker_unit_file (no callers; would have hashed worker units nobody reads).
• Deleted spark_pair_head_unit_file. The wet digest witness now seals via spark_pair_seal_unit_render over spark_pair_head_unit_unsigned, the same seal apply publish uses.

— sent from bright-gull-790

[gunbai-bot]

Addressed review 66631 at 0858bf86fb0c9e152ae1a06d349a4ec779227fd1.

• render_inputs_identity now includes executor backend, kv dtype, memory request, prefix caching, prefill scheduling, snapshot repo cache directory, and the lane netdev / RDMA device / rail address — the same inputs the head unit text reads. Lookup still refuses on identity mismatch; a subset key can no longer treat uncovered desire drift as current.
• a_withdrawn_roster_is_refused_at_the_declared_unit_not_the_incarnation publishes (DigestStdin) then writes withdrawn then places, so the enrolled DigestStdin floor-route-gap row is a real route on that identity.

— sent from bright-gull-790

[gunbai-bot]

Addressed review 66641 at 8a5f98fd49d56726750dc841cc3190a103e1c38f.

excl_local_repo_wet_digest_stdin_reason no longer claims DigestStdin is the only effect or that these fns write nothing. Loss text names DigestStdin and Filesystem.Write/Read of target/spark-pair-declared-head-*. Dissolve requires mock coverage sufficient for both (DigestStdin alone does not retire). The two exclusion rows still share that standing because both files reach both effects.

— sent from bright-gull-790

[gunbai-bot]

Addressed review 66656 at cd9ce218134e1a21769cba2bbaddc26adf3cf8cf.

• parse_content_hash_wire lives beside serialize_content_hash in std.content_hash, sharing content_hash_sha256_wire_tag / content_hash_sha512_wire_tag. Pair serving no longer hard-codes sha256: offsets.
• The declared-head file is one record: spark_pair_declared_head_artifact_record_text / _parse. Lookup compares parsed identities with compare_content_hash, not a second string codec.
• Hermetic invert + refuse-short-hex rows are on content_hash_family_grounded_witness.

— sent from bright-gull-790

[gunbai-bot]

review 66665 is right: spark_pair_head_render_inputs_identity keyed engine/lane/snapshot/unit_name and omitted values the unsigned head unit interpolates as module rows (spark_pair_served_model_name, spark_pair_serve_port, spark_pair_tool_call_parser, Ray cpus/gpus/object-store/gcs-port). Lookup would treat a stored digest as current after those rows changed.

baa7f3a27d adds serve_surface and ray_cluster identity inputs covering those rows, and a digest witness that an incomplete key (the previous four-input set) is ContentHashDifferent from the production identity.

[gunbai-bot]

review 66683: both findings match HEAD.

• Deleted spark_pair_withdraw_declared_head_artifact. A missing file is already DeclaredUnitDigestUnavailable; the bind RED establishes absence with Filesystem.Delete in the witness and looks up, instead of writing a parse-fail sentinel from production. Wet exclusion / floor_route_gap now name that Delete rather than a withdraw writer.
• Inlined spark_pair_worker_realizations_using back into spark_pair_worker_realizations; no worker path seals.

[gunbai-bot]

review 66717: both findings match HEAD.

• spark_pair_publish_declared_head_artifact now returns SparkPairDeclaredHeadPublish. Seal causes, unsigned render, missing identity, realization refuse, and Write error stay on SparkPairDeclaredHeadPublishRefused { cause }. Apply interpolates those causes into the exit string.
• Bind RED deletes then Filesystem.Reads the same path. The wall is !rd.success (store absent). cleared.success || !rd.success still fails when Delete fails and the file remains.

[gunbai-bot]

review 66721: both findings match HEAD.

• spark_pair_head_render_inputs_identity now includes runtime_create (pinned image, runtime tag, build dir, vllm/ray binaries, container name, weight/jit mounts, head log path, shm, infiniband) and Ray monitor_ms. Those are values the unsigned head unit interpolates that were not on the previous key.
• head_render_identity_refuses_a_key_that_omits_runtime_create is in spark_pair_serving_realization_witness_test.dag (hermetic discovery). It was removed from the DigestStdin wet file so it is not parked unscheduled.

[gunbai-bot]

review 66726: the enumerated spark_pair_*_inputs_wire / spark_pair_head_render_inputs_identity path was validation beside the renderer.

The store now keeps unit text plus SHA-256. Lookup re-renders the unsigned head unit (pure) and requires byte equality with the stored text. DigestStdin stays at apply. The hand-maintained identity wires are deleted. Hermetic RED: stored_unit_text_that_is_not_the_current_render_is_unavailable.

[gunbai-bot]

Addressing review 66796 (artifact 66796).

1. Absence from a failed Read — fixed on def9d7af3d. spark_pair_lookup_declared_head_digest_at now Filesystem.Lists target/, treats membership via filesystem_listing_names_entry, and only then filesystem_exact_read. List failure is spark_pair_declared_unit_artifact_store_unlistable_obligation; listed-and-unreadable is …_unreadable_obligation; a successful listing without the entry is the unavailable obligation. Bind RED no longer treats !Read.success as proof the store is gone: after Delete it requires a successful listing that does not contain the entry name.

2. Second durable store — stated divergence, not inhabit. Apply must replace the current head-unit receipt for a fabric group on every publish. extdeps.realization.materialization_store_local is WriteOnce / MissThenCreate / Occupied on a second writer, and refuses an uninitialized root. That is the wrong object for a named replaceable slot under checkout target/. The MATERIALIZATION comment now names that §3b divergence (review 66796). Opening a grant-admitted WriteOnce store would erase replace-on-publish.

3. Stored digest as a second source — kept, with reason. Placement must not DigestStdin. One Write still publishes name + apply-time digest + unit bytes; lookup currency is string equality of stored body vs a fresh unsigned render. Dropping the digest line and re-hashing at lookup would put DigestStdin back on the token turn, which is the path this PR closes. A truncated record still fails parse.

— sent from bright-gull-790

[gunbai-bot]

Addressing review 66806.

Placement never renders — fixed on 9b9b8543c5. The claim was false: spark_pair_lookup_declared_head_digest re-renders the unsigned unit as a pure fold and compares that text to the stored body. What placement does not do is DigestStdin. harness_declared_unit_digest and the sibling harness_serving_realization annotation now say that, matching the mint-home comment in pair_serving_realization.

The rest of that review (parse_content_hash_wire, TargetChanged roster, wet enrollment, WriteOnce divergence) needed no further code change.

[gunbai-bot]

Addressing review 66833.

Hermetic bind claim does not compile — fixed on 903a44648b. a_ready_route_reaches_the_existing_incarnation_frontier_in_the_product_path now supplies incarnations: [] and incarnation: EndpointIncarnationUnobserved { … }, matching harness_bind_candidate. The claim stays hermetic: it still supplies a digested unit and does not DigestStdin.

Lookup per admitted candidate — fixed. harness_collect_candidates now calls harness_declared_unit_roster() once (Group A lookup + Group B canary obligation) and threads that roster through add/bind. harness_add_serving_candidate takes a supplied declared_unit and does not look up again. The wet witness still executes lookup by calling harness_declared_unit_digest before place.

[gunbai-bot]

review 66839 — fixed on b56bd54ab4.

the_production_route_refuses_because_no_incarnation_is_observed and the_production_route_consumes_an_observed_incarnation now pass t_declared(hex: t_unit_hex) into harness_serving_route, the same fixture t_standing already uses. Digest-unavailable-before-incarnation stays the job of the_declared_unit_is_refused_before_the_incarnation. With a digested unit, the unobserved claim can actually reach ServiceIncarnationUnobserved; the observed claim now expects ServingRouteOperatorAsserted, so ignoring the incarnation argument would go red at Unobserved.

Advisory on required_floor_runner.rs: not changing that seed in this PR. It is a floor share-producer bootstrap so PureProducerShare does not fail after main's warm rows; ctrl review policy, not a DESIGN.md defect of the declared-unit digest cut.

[gunbai-bot]

Taken — review 67007's finding was right, and the field is gone as of 4dfb2b78dd8.

DeclaredUnitDigestEvidence.unit_name was written at the mint and read by nothing; spark_service_from_observation takes the digest alone. That is §3c red however well shaped, and it is the same argument the module already makes two lines above for carrying no text.

I did not repair it by naming a consumer. The refusal text was the only honest candidate (ServiceIncarnationNotFromDeclaredUnit could say which unit was declared), but which unit was compared is already fixed by the group the route is deciding for — so carrying the name in the evidence would be a second authority for a fact the caller already holds, and adding a reader to justify a field is not a consumer.

One consequence worth stating rather than leaving to be rediscovered: the record is now a single-field sole-constructor carrier, which is exactly the shape gunbc.recurring_failure_mode sole_constructor_wrapper_satisfies_a_typecheck_declared_for_its_payload describes — such a carrier is Accepted where its payload type is declared and then fails at evaluation. Consumers read evidence.digest explicitly, and the comment on the type now says so. That class's wall is a compiler trigger; it is not a reason to keep a dead field as padding.

The two witness rows that asserted the name drop those conjuncts. Each still discriminates on the digest, which is what they exist to establish — the stability row on equality across two mints of the same bytes, the production row on the group producer agreeing with the mint over the same render.

Thanks for the read on the rest; the floor on this head is still the evidence and I'll report it when it settles.

— sent from royal-ram-691

[gunbai-bot]

Taken, and taken further than the finding asked — review 67015's hunk is reverted, not documented. Head ec4bb35e443.

You read it as plausibly passing §6 because it decodes an existing modelled roster the way local_repo_wet_schedule_rows already is. That reading is right, and it is also what made the revert the better move: #11455 ("Floor pure-producer share: scope roster admission to the prepared subject; stale only when absent from the corpus") landed the same class of fix on main and is already an ancestor of this head via the merge. So the branch was carrying a hand-rolled solution beside the modelled one — one fact with two authorities (§3), and seed growth with no receipt.

b892997a7aa was the only branch commit to required_floor_runner.rs, so restoring main's version reverts exactly it and nothing else: 51 lines out, no residue.

This also puts the question to the floor rather than to a paragraph. If PureProducerShareProducerModuleOutsideSubject returns, the hunk was load-bearing and comes back with its receipt and a gunbc.seed_growth_admission row; if the floor is green, it was redundant with #11455 and is correctly gone. I would rather learn that from a run than assert it.

Worth noting for the record: the branch was already red when I adopted it — the merge commit failed on a genuine integration break (spark_pair_container_spec changed env: → lane: on main while the old digest witness still called it the old way). The Option A rewrite removed that call entirely, and every surviving call site now matches the declaration. So there is no green baseline behind this work; the floor on this head is the first real evidence either way, and it has not settled yet.

— sent from royal-ram-691

[gunbai-bot]

Review 67089: not changing this, and stating the divergence rather than leaving it implicit. The route-fold rows route their declared side through the production mint because the side-chat ruling on this PR (2026-09-16) required DeclaredUnitDigestEvidence to be a sole-constructor record with no fixture or alternate mint — a supplied DeclaredUnitDigested value is, by construction, not authorable outside gunbc.spark.pair_serving_realization, and that seal is the whole point (the previous head was refused precisely because a caller could aim the confined value through the sanctioned mint). The repository's own repair receipt for this class (gunbc.recurring_failure_mode admitted_call_edge_with_unrestricted_value_egress) took the same path: delete the fixture mint and have witnesses obtain readings through the real constructor. So the §3 witness-pairing rule and the seal pull in opposite directions here, and the seal wins for a confined evidence type: the cost is the wet-lane enrollment the review counts (a subprocess per row, which we accept), not a second authority. The pairing obligation is still discharged once at the real interface (serving_availability_bind_wet_witness, spark_pair_head_unit_digest_witness); the route rows vary the OBSERVED side against a real declared digest, which keeps them discriminating. A hermetic form becomes possible when sha256sum DigestStdin gains mock_response coverage — that is the dissolution named on the wet exclusion row.

— sent from merry-eagle-325

[gunbai-bot]

On review 67105 — the finding is sharp and it caught a real defect, but the proposed fix is inverted. I have not deleted the enrollment, and here is the receipt. Head 59b2e4baf7d.

The row does reach DigestStdin. It passes t_unit_unavailable(), as the review says — but it also builds an observed incarnation from t_incarnation():

t_incarnation() -> t_launch_with_unit(unit: t_declared_digest())
                -> t_declared() -> spark_pair_declared_head_digest -> Sha256.DigestStdin

The launch fixture's unit_digest has to be real bytes, or the agreeing and disagreeing arms stop discriminating at all. The fold's refusal order says nothing about what the row evaluated to build its arguments.

Measured, not argued. floor_route_gap's own contract: "Enrolled, and the route did NOT gap: reds the build as a stale row." The floor was green on 351e42fb7f8 and e549dfda76d with this row enrolled. A green build with the row enrolled is the receipt that the route gapped — so the row is not stale.

Deleting it would be the mirror defect, from the same four-case contract: "NOT enrolled, and the route gapped: reds the build. A new route gap is a new fact."

The two t_unit_unavailable rows are the clean contrast, and the discriminator is not the one the review used:

row	enrolled	reaches t_incarnation()
an_observed_incarnation_without_a_declared_unit_digest_refuses	1	1 → correctly enrolled
the_declared_unit_is_refused_before_the_incarnation	0	0 → correctly omitted

Both pass t_unit_unavailable(). Only one builds an incarnation fixture. I also checked that no other route-gap row names a t_unit_unavailable row.

What the review did find is mine, and it is fixed. My own chunk_13 comment asserted that such rows are omitted "because the arm is decided before the mint is reached" — false as a rule, and precisely what led a careful reviewer to the wrong conclusion. A comment that misstates the membership rule is a real defect even though it compiles. 59b2e4baf7d replaces it with the actual discriminator — does the row's argument closure reach the mint — and spells out those two rows as the contrasting pair so the next reader doesn't have to re-derive it. Comment-only; no enrollment changed.

— sent from royal-ram-691