Repository navigation
fix(processor): compile participant reference fields from the declarations validation resolved #1596
Description
Gap Claim
The fix for #1503 makes behavior authority_scope_refs compile from the declaration that semantic validation resolved. The other participant reference fields still compile through _runtime_addresses_for_refs over _runtime_addressable_ref_index (raes_processor/compiler/alias_index.py). That alias map gives every named node service a bare alias, and the helper keeps a ref only when the map yields exactly one address. Validation resolves the same fields through declaration-index projections that give services no bare alias. A validated ref can therefore compile to nothing, or to a same-named service the author never referenced, with no diagnostic.
Repro on branch 1503-authority-scope-compilation at 2a89a2b1 (base dev cf8b4308; the agent compile path is unchanged from dev), with node web declaring services web and httpd, entity httpd, and agent blue:
agents.blue.authority_anchors: [web]: validation (_validate_named_ref(..., targetable=False),raes/validator/_content_objectives.py:303-305) resolvesnodes.web. The compiledauthority_anchor_addressesis(), with no diagnostic.agents.blue.authority_anchors: [httpd]: validation resolvesentities.httpd. The compiledauthority_anchor_addressesis("provision.node.web.service.httpd",), with no diagnostic.
Fields that compile through the same alias-map path on dev cf8b4308 (not individually reproduced here):
- agent
authority_anchors(raes_processor/compiler/participant_behaviors.py:140, reproduced above); - interactive access target and accounts (
participant_behaviors.py:197-198); - mixed-control
authority_basis_refs,scope_refsandevidence_refs(raes_processor/compiler/_mixed_control.py:38-46) and transition evidence and completion refs (_mixed_control.py:93-97), validated atraes/validator/_mixed_control.py:137,:152and:239; - participant inject delivery source and result items,
control_authority_scope_refsand evidence (raes_processor/compiler/participant_inject_deliveries.py:111-115,:161-165); - autonomous execution targets (
raes_processor/compiler/participant_autonomous_execution.py:184); - evaluation subjects (
raes_processor/compiler/evaluation.py:54); - observation demand component refs, which union the alias-map candidates of the authored ref and its canonical declaration (
raes_processor/compiler/observation_demands.py:40-46).
Existing Surface Audit
- The Authority scopes that pass validation compile to no authority_scope_addresses #1503 fix adds
_declared_runtime_addressesand_runtime_canonical_addressestoalias_index.py. The first binds each ref through a resolver supplied by the caller, maps the one resolved declaration to its runtime address through the second, and reports an error diagnostic when a ref does not resolve to exactly one declaration. Only behaviorauthority_scope_refsuses them. - Agent
operating_scope(participant_behaviors.py:144) also compiles through the alias map, but its validator index (_operating_scope_ref_index,raes/validator/_core.py:81) gives services bare aliases too. With the fixture above,[web]is refused as ambiguous and[httpd]compiles to the service it validated against, so the two stages agree in the cases tried. - feat!: make reference eligibility explicit per purpose and align the editor with validation #1446 (for Make target eligibility explicit and align editor suggestions #1339) adds
DeclarationIndex.resolve_for(ref, purpose)with oneReferencePurposeper field, which gives each field above its own validator resolver. - feat(sdl): add reusable mixed-control policies and api-409 v2 occurrences #1584 (for Implement reusable mixed-control authoring and occurrence contracts #1363) adds a v2 mixed-control policy compile that also passes
addressable_ref_index. - Specify participant address mappings across authoring, runtime, and evidence #1341 owns which semantic references get runtime projections. Complete participant conformance coverage, including identity boundaries (ASR-507) #220 verifies that reference-purpose rules agree across validation, composition, compilation and editor suggestions.
Alternatives
- Remove bare service aliases from
_runtime_addressable_ref_index: rejected. Operating scope validates bare service names, so those refs would start compiling to nothing, and two resolvers would remain. - Make validation refuse every bare name the compiler's alias map finds ambiguous: rejected. It changes the language for every field and adds a second resolution authority beside the declaration index (ADR-076 §4).
- Compile each field with
_declared_runtime_addresses, passing the resolver that field's validator uses, and report a ref that does not bind exactly one declaration: selected.
Chosen Architecture
For each field listed in the Gap Claim, compile with _declared_runtime_addresses(refs, resolve=<the field's validator resolver>, canonical_addresses=_runtime_canonical_addresses(scenario), ...) and a field-specific ...-ref-unbound error diagnostic. Land it after #1446, so each field uses its ReferencePurpose, and after #1584, so the v1 and v2 mixed-control compiles are converted together. Record in specs/sdl/references.md which declarations contribute runtime addresses for each converted field, reusing the authority-scope rule where it is the same. Any new runtime projection stays with #1341.
Verification Plan
- Per field, a parametrized test over a collision fixture (node
webwith serviceweb; an entity, an agent, a relationship and a content item named like services) asserts that the compiled addresses are the runtime address of the declaration validation resolved, with no diagnostic. - A differential test asserts that each field's compile resolver is the resolver its validator uses.
- Existing participant, mixed-control, inject-delivery, evaluation and observation-demand compile tests,
verify-fast-feedback, and both research-evidence checkers.
Lineage and Precedent
- Split from Authority scopes that pass validation compile to no authority_scope_addresses #1503, whose fix covers behavior
authority_scope_refsonly. - ADR-076 §3 (resolution must not guess; the compiler boundary enforces identity invariants), §4 (one declaration index) and §5.1 (cardinality exactly one).
specs/formal/participant-behavior-model/README.md(ACT-607 extensibility seam): "If runtime claims need normalized addresses, add that normalization at the compiler addressing boundary rather than copying raw, possibly ambiguous authoring refs into a second resolver."
Activity