Source-annotation policy: DESIGN 4c lands; // as captured authored-source data (audit complete, D-A..D-D ruled)

[briansrls]

Status

Audit complete; source-annotation policy ruled; implementation and reconciliation unstarted.

Canonical guidance landed in DESIGN.md §4c through gunbc.design_document section_4c_blocks, with DESIGN.md regenerated, never hand-edited. No slice is started, nothing deleted, migrated, or reconciled.

The defect

Banning // made comment syntax unwritable — not commentary. It removed the only structural signal saying this text is commentary, not program data. Verified in-tree as a closed causal loop:

PR	commit	title
#5579	f9cc238976	Parser-wall: remove DAG comment trivia rules (fail-closed by construction)
#6262	9e7c3c1d11	…hoist .dag // comments to typed data rows…
#6424	c14e001a34	Sweep dead prose data-String rows (comments smuggled in strings): 215 rows across ~130 files

comments banned → commentary smuggled into data rows → intent mechanically undecidable → recurring cleanup. #6262 was the deliberate compensating convention, not drift.

The rule that lands: prose is not forbidden; unclassified prose is. // becomes the explicit quarantine boundary.

Four structural corrections to the destination

• §2a — a third lexical channel. Rejecting TriviaRule is necessary but not sufficient: an ordinary TokenRule still joins the semantic token stream, buying parser filtering, token-order effects, and allocator risk. LexRule gains AnnotationRule beside the two variants it has today.
• §2b — wrap, don't widen. AuthoredParseArtifact { semantic, annotations } rather than a new field on ParseArtifact, so ordinary compilation receives a type that cannot hold annotations and erasure is structural rather than convention-plus-witness. The equality law is stated over the semantic graph projection, excluding textual provenance — inserting a comment necessarily moves byte ranges, so whole-artifact equality was wrong in the prior draft.
• §2c — annotations must not consume OccurrenceId (the blocking correction). The allocator is graph-scoped, so drawing from it lets a comment shift declaration identities in the same source and in later-parsed modules. First carrier has no annotation identity; the ordered graph carries multiplicity and source order. Target-byte equality cannot prove this — the emitter may ignore occurrence ids and stay byte-identical while the identity graph moves.
• §2e — attachment narrows to module-item grain, with an explicit AnnotationPlacement observation, because whitespace-as-trivia otherwise makes a trailing comment indistinguishable from a leading one on the next declaration.

D-D approved debt-only: SourceAnnotationRationale is not declared in Slice 1 — a variant with no authoring path, consumer, or lifecycle is speculative vocabulary.

Audit findings that stand

• The sample measures survivors. Sweep dead prose data-String rows (comments smuggled in strings): 215 rows across ~130 files #6424 swept 215 dead rows before it was drawn, so 0/48 primary-delete cannot refute the dead population or settle representation.
• Value and representation are independent axes. Every KEEP specimen is worth keeping and wrong as data Foo: String.
• 56% of annotation bytes carry a time-bound marker — under the ruled model, exactly the facts that must not become annotations.

Doc-graph rebind

From the generic StandingIntent to the seams this work actually changes: v2.std.compilers.lexing LexRule (primary), plus v2.compiler.parse ParseArtifact, v2.extdeps.languages.dag dag_line_comment_fidelity, and v2.test.round_trip.dag_comment_wall_test dag_comment_wall_line_comment_refused.

Verification — green by execution (local binary)

PASS run_generated_artifact_drift_gate_body     <- DESIGN.md == emission
PASS doc_graph_has_no_orphan_docs               PASS doc_graph_has_no_dangling_links
PASS doc_graph_universe_is_nonempty             PASS doc_graph_is_clean
PASS cited_symbol_planted_doc_graph_controls_are_enrolled
PASS cited_symbol_production_population_excludes_planted_controls

The cited-symbol wall passing is what establishes all four new DeclarationRefs resolve to exactly one declaration each.

A CI auto-heal bot regenerated DESIGN.md on this branch concurrently (my auto-WIP pushed the authority edit before I regenerated). Merged, not force-pushed: §4c appears exactly once and DESIGN.md is byte-identical to the bot's regeneration, with the drift gate re-run green after the merge.

Named as unproven: the §2c allocator hazard is reasoned from the allocator being graph-scoped, not demonstrated — the unsafe carrier was never built. The D-C controls are written to prove the disjointness law directly rather than lean on that reasoning. The LexArtifact / AuthoredParseArtifact / SourceAnnotationDebt / AnnotationPlacement shapes do not exist in tree; everything §2 cites as existing was grep-verified, and ShLineComment was found not to exist.

🤖 Generated with Claude Code

[gunbai-bot]

Fixed in 84c2eeb. Thanks — this was a real defect, and it is exactly the failure class this PR exists to describe: a prose statement that kept asserting a superseded design after the model moved.

The finding, confirmed. The HandAuthoredDocBind trigger was authored during the earlier recut, before the operator's structural corrections. I updated the audit doc and DESIGN §4c to the ruled design and did not carry the correction into the trigger string, so a typed scaffold marker was pointing Slice 2 at the rejected carrier.

A second stale claim in the same string, which review 48112 did not reach. The trigger also said semantic erasure would be "proven by identical emitted bytes." That is precisely the insufficiency D-C corrects: the emitter may ignore occurrence ids and stay byte-identical while the occurrence-identity graph moves underneath it. Byte equality cannot establish erasure. The trigger now names the seven D-C proofs rather than the byte check.

The trigger now reads: AnnotationRule on a third lexical channel (never TriviaRule, never an ordinary TokenRule), returning an authored wrapper around an unchanged semantic artifact, consuming no semantic occurrence identity, attached at module-item grain with trailing/body/unattached/block forms refusing, erasure established by the seven D-C proofs, and the representation partition complete.

Swept the rest of the diff for the same class. Every remaining TokenRule mention names it as the rejected option (§2a's title, the existing two-variant type definition, Slice 2's "never TokenRule"), and every byte-equality mention is either D-C proof (4) of seven or the explicit "target-byte equality cannot substitute" caveat. DESIGN §4c never mentions TokenRule — it says an annotation "may not produce an ordinary semantic token or namespace binding." No further instances.

Re-verified green by execution on a locally built binary after the fix:

PASS run_generated_artifact_drift_gate_body
PASS doc_graph_has_no_orphan_docs / no_dangling_links / universe_is_nonempty / is_clean
PASS cited_symbol_planted_doc_graph_controls_are_enrolled
PASS cited_symbol_production_population_excludes_planted_controls

[gunbai-bot]

Thanks for the approval (review 48124). No changes needed, but two characterizations in it are inverted in ways a later reader could mistake for defects, so correcting the record rather than letting them stand.

1. The three DeclarationRefs are not forward-references — they all resolve in tree today.

ParseArtifact                          src/v2/compiler/02_parse.dag:131   type ParseArtifact {
dag_line_comment_fidelity              src/v2/extdeps/languages/dag.dag:3382   fn dag_line_comment_fidelity()
dag_comment_wall_line_comment_refused  src/v2/test/claim/round_trip/dag_comment_wall_test.dag:23   test fn ...

This matters because if they were unresolvable forward-references, that would be a defect, not a benign plan-doc idiom: G1 (#7707) requires every typed DeclarationRef to resolve to exactly one declaration or refuse. cited_symbol_production_population_excludes_planted_controls passes on this head, which it could not do against dangling refs. The bind points at live seams the work will change, not at carriers that have yet to exist — which is exactly why it was rebound off the generic StandingIntent after review 48112.

2. DESIGN.md is not a mirror of design_document.dag — it is generated from it.

gunbc.generated_artifact_emit maps DesignArtifact => expected_design_md(), and GeneratedArtifactDriftGate byte-compares the committed file against that emission. The §4c prose exists once, in design_document.dag section_4c_blocks; DESIGN.md is its projection, regenerated via the wet gate, never hand-edited. Describing it as mirrored prose would make this diff an instance of the §3 dual representation the PR argues against, when it is the opposite. run_generated_artifact_drift_gate_body passes, which is what establishes the two are in sync.

Neither point changes the diff, and the approval's substantive read — doc-only, no code, no hand-Rust or hand-shell surface — is accurate.

— sent from fierce-pike-375