asm-bead-closure

name	asm-bead-closure
description	Use when implementing, reviewing, or closing gbllm ASM/ISA beads in gbf-asm, including instruction modeling, sections, symbols, builders, layout, relaxation, effects, privileges, encoders, cycle models, and listings.

ASM Bead Closure

Use this before closing gbf-asm beads and when addressing review feedback on assembly IR, ISA modeling, symbolic sections, builders, effect typing, layout, or lowering boundaries.

Scope Discipline

• State whether the type is symbolic pre-layout IR, post-relaxation machine IR, or an adapter between them.
• Keep symbolic labels, relocations, pseudo-ops, branch relaxation, far-call thunking, final align padding, and byte lowering in their owner beads.
• Distinguish legal CPU encodings from canonical project encodings. If canonical forms reject legal CPU encodings, document and test that boundary.
• When a bead supersedes an older planv0.md sketch, state the mapping in code docs and closure.

Type Boundaries

• Do not derive Deserialize for constructor-validated newtypes unless serde goes through the same validation boundary, for example #[serde(try_from = ...)].
• Add at least one negative deserialization test for every private-field newtype whose constructor rejects values.
• Symbol names must be built from validated segments, not by joining raw caller strings and validating afterward. Add collision tests for dotted helper arguments.
• Symbol tables should allow address aliases unless the bead explicitly owns a primary-symbol-only table. Reverse lookups must return all names for an address.
• JSON-facing schema with maps must verify JSON serialization directly. Avoid non-string map keys in JSON output, or provide a stable representation.

Builder And Section Rules

• Builder beads emit symbolic pre-layout section IR. They may record concrete Instrs, labels, alignment directives, pseudo-op intent, and raw escape hatches.
• Raw byte escape hatches must not be publicly constructible through multiple paths. Keep raw constructors crate-private or guarded, keep section mutation behind builder APIs, and add a raw-specific test or closure note.
• Do not model unknown-width symbolic items as zero-byte fixed size. Size APIs for alignments, pseudo-ops, relocations, or runtime-lowered markers should return None/unknown or be explicitly named as lower bounds.
• Pseudo-op tests must assert exact payloads, not only that pseudo-op calls do not panic. If a builder tracks lease-like state, test duplicate, unknown, released, and range-error paths.
• Provenance-scope helpers that temporarily mutate builder state must restore that state on normal return and caught panic.

Effect And Privilege Rules

• Effect classifiers must not collapse stack-touching instructions into pure compute. PUSH/POP, calls, returns, RST, and two-byte stores need explicit stack/control or mixed-region tests.
• Full-address classifiers must test memory-map boundaries, including $FF00..=$FFFF high memory and two-byte writes that cross regions.
• Section privilege is a durable section invariant. Any API that changes privilege after emission must revalidate existing items, and tests must cover downgrade rejection.
• Raw bytes are opaque privileged effects unless a bead explicitly narrows the claim to data-only sections.
• Dynamic-address load/store effects must be named as reachability obligations; do not silently call them fixed-region effects without a proof from a later pass.

Closure Evidence

• When citing filtered cargo-test commands, confirm the command actually ran tests in the current patch. A passing filter with running 0 tests is not evidence.
• Include a claim-to-gate matrix for non-trivial ASM beads, especially when code has symbolic, layout, and byte-lowering boundaries.