Skip to content

fix(sdl): keep imported tool affordances bound to their own tool content - #1440

Merged
Brad-Edwards merged 13 commits into
devfrom
298-tool-authoring-verification
Oct 15, 2026
Merged

fix(sdl): keep imported tool affordances bound to their own tool content#1440
Brad-Edwards merged 13 commits into
devfrom
298-tool-authoring-verification

Conversation

@doublewhy

@doublewhy doublewhy commented Oct 9, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

Summary

Verifies DSL-117 (tools, affordances, interfaces, channels, scope) through parsing, validation, composition and compiler output, delivering all five #298 done-when bullets, and fixes two composition gaps for an imported unit's tool_ref:

  • A section-qualified tool_ref (content.scanner-package) was never rewritten, so it bound the importer's own content and could not be renamed. It is now namespaced and renamed with its declaration.
  • A bare tool_ref naming two unit declarations fails in the unit alone but composition bound it silently. Composition now raises the identical diagnostic at the unit file (ADR-053; ADR-076 section 3).

Requirement governance is skipped (no scope file) pending the maintainer's decision on #1510; forced for DSL-117, it reports only requirement-ownership-mismatch for the DSL-117 and decision records.

Requirement UIDs

  • DSL-117

Related Issues

Refs #298

Adjacent defects, filed: #1573 (nested-ref rename refused), #1574 (reference-typed action arguments not namespaced on import), #1575 (the same silent binding in other symbols["named"] families). #1498 tracks __private refs in importers.

Merge order: no prerequisite; drafts #1576, #1592, #1584 and #1484 share files with it and rebase onto it once it merges.

ADR Impact

  • No ADR required: the change applies ADR-053 and ADR-076 section 3 as written.

Changes

  • _behavior.py:_rewrite_tool_affordance keeps a bare content name on symbols["content"] and any other spelling on symbols["named"]; _behavior.py:_reject_ambiguous_unit_tool_refs, called by _expand.py:_expand_one_import before namespacing, resolves each tool_ref through the unit's own DeclarationIndex.
  • Examples examples/scenarios/participant-tools/ (a unit imported twice; README maps each DSL-117 concern to its field); decision record (rule, boundaries, migration); DSL-117 clause mapping.
  • Captures capture-e33b51ac... and capture-1decb5d4..., collected on clean 3ecaf6bd (dev 348c4903), recorded with python -m tools.research_capture record. Specification: 6 pinned artifacts via _execute_artifact (38 stages passed, 4 preregistered non-execution, 0 failed); recompute_analysis 10 of 10 load-bearing passed. Formal: 10 retained cases via replay_case, 4 via raes processor, 14 participant functions (18 passed); 20 of 20 outcomes as expected. Drift from dev's record templates c9ca186a / 3bad3945: the sdl-pipeline surface digest, the replay command id and versions.python.

Done-when matrix. Tests: test_issue_298_tool_authoring.py (36 cases), CI lane canonical / test-shard; evidence for every row: 36 passed locally, run 38461730034 green.

Done-when (verbatim) Change Test; result without the change
Map tools, affordances, interfaces, interaction channels, and scope constraints to current authored fields. examples, clause mapping test_reusable_tool_bindings_resolve_inside_their_own_namespace (reads the examples)
Exercise local and imported bindings through parser, semantic validation, composition, and compiler output. _rewrite_tool_affordance test_imported_affordance_keeps_its_own_tool_when_the_importer_declares_the_same_name[qualified]: fails
Cover role-specific availability, ambiguous/missing references, unsupported carriers, and inconsistent action/observation bindings. _reject_ambiguous_unit_tool_refs, _expand_one_import test_bare_tool_ref_naming_two_unit_declarations_fails_composition_as_it_fails_alone: both cases fail (composition succeeds); plus test_importing_scenario_bindings_fail_closed
Show that declaring or displaying a tool does not authorize invocation or prove execution. existing runtime refusal test_declared_and_displayed_tool_neither_admits_nor_records_an_invocation
Record any residual DSL-117 gap, implement it at the existing seam, and update examples and traceability. both fixes, records, examples test_renaming_a_declaration_rewrites_either_spelling_of_its_tool_or_access_ref[tool-qualified], [tool-is-a-node]: fail

Test Plan

  • Unit tests pass
  • Integration tests pass if applicable
  • Full completion suite required in CI before merge
  • No coverage regression

Fail before the change: with _behavior.py and _expand.py restored to origin/dev, 7 cases fail; with the change all 36 pass (uv run --project implementations/python --frozen --all-extras python -m pytest implementations/python/tests/test_issue_298_tool_authoring.py -q).

c1ee3ee4 carries the code commits of f3d5db90, where nox -s contracts -- --base-rev origin/dev (both evidence steps), the module with the three evidence modules (244 passed; 18 with -m integration), 14 related modules (704 passed, 1 skipped), lint, make policy and docs-local passed. At c1ee3ee4 both evidence checkers pass, also on the git merge-tree --write-tree origin/dev HEAD tree, and verify-fast-feedback passes every stage except expected SKIPs. CI run 38461730034: all checks green, including sonar.

Ground Control Checks

  • Repository policy command passes
  • Fail-before run above

Traceability

  • IMPLEMENTS: DSL-117 ← implementations/python/packages/raes/composition/{_behavior,_expand}.py
  • TESTS: DSL-117 ← implementations/python/tests/test_issue_298_tool_authoring.py
  • VERIFIES: DSL-117 ← examples/scenarios/participant-tools/{tool-kit,twice-imported}.sdl.yaml
  • DOCUMENTS: DSL-117 ← docs/decisions/issue-298-tool-authoring.md, examples/scenarios/participant-tools/README.md, docs/explain/sdl/sections.md

Checklist

  • Code follows the project coding standards (ruff format, ruff check clean)
  • FM1: after composition or rename, a tool_ref resolves to the rewritten form of the declaration it named, or composition fails with the unit's own diagnostic.
  • Published contract schemas regenerated if models changed: no model or schema changed
  • PR title is a Conventional Commit; fix cuts a patch release
  • Architectural docs updated if applicable: decision record; no ADR change

@doublewhy
doublewhy force-pushed the 298-tool-authoring-verification branch from 89b2ade to 94dc1b8 Compare October 9, 2026 11:38
@doublewhy
doublewhy marked this pull request as ready for review October 9, 2026 12:27
This was referenced Oct 9, 2026
Closed
Merged
Open
Open
Open
Open
Draft
@doublewhy
doublewhy force-pushed the 298-tool-authoring-verification branch from 600080a to 76bb083 Compare October 13, 2026 03:12
@doublewhy
doublewhy marked this pull request as draft October 13, 2026 03:12
@doublewhy doublewhy mentioned this pull request Oct 13, 2026
Draft
9 of 11 tasks
@doublewhy
doublewhy marked this pull request as ready for review October 13, 2026 04:37
This was referenced Oct 13, 2026
Open
Open
Open
Open
@doublewhy
fix(sdl): keep imported tool affordances bound to their own tool content
9e1617d 
Rewrite an imported tool affordance's tool_ref through the import's named
symbols, so a section-qualified content ref such as content.scanner-package
binds the unit's own tool instead of the importing scenario's content of
the same name. Verify DSL-117 tool, affordance and interactive-access
authoring through composition, compilation and runtime admission, and
record clause verification, fulfillment boundary and traceability.
@doublewhy
test: cover tool_ref rename, both affordance relations and an ambiguo…
4c4b230 
…us tool for issue #298

The rewrite that the fix changed is shared by module composition and
rename_sdl_declaration. Renaming the tool content now rewrites a
section-qualified tool_ref to content.<new-name>, where dev refused the
rename with artifact-transformation.target-invalid. Add bare and qualified
rename cases, check that the published authoring schema requires each
affordance relation on its own, and add an importer tool_ref that names
both an exported node and exported content. Record the rename effect and
the boundary-classification rewrite in the DSL-117 record.
@doublewhy
fix(sdl): keep bare content tool refs on the content map
6da111d 
Rewriting every imported tool_ref through the named symbol map changed
one composition that dev accepted: a bare tool_ref whose name the unit
also gives to an unexported declaration of a later section (ambiguous in
the unit alone) was rewritten to that declaration's private name and
failed. Keep a bare content name on the content map, as before, and send
only other spellings, such as content.<name>, through the named map.
@doublewhy
test: raise from one call in the shared-name tool_ref test
33c082b
@doublewhy
fix(sdl): reject an imported tool_ref that its own unit finds ambiguous
7a54d4c 
Before an import is namespaced, composition now resolves each authored
tool_ref of the unit through the unit's own declaration index, the index
standalone validation uses. A ref with more than one candidate fails with
the standalone "is ambiguous; use one of" diagnostic, anchored at the unit
file and naming only the unit's own addresses. Composition used to bind the
content silently, although the unit already failed on its own.

The two-file fixture moves to examples/scenarios/participant-tools with a
README mapping each DSL-117 concern to its authored field, and the test
module reads the examples. New cases cover the ambiguity for a relationship
clash and a content-item clash, the qualified spelling beside each clash, a
cross-fragment ref to root content, an unsupported channel in the unit and
in the importer, the invocation interface reached through each import's own
action contract, and renames of the access account in both spellings.

docs/decisions/issue-298-tool-authoring.md records the composition rule, the
three settled boundaries and the migration. The DSL-117 record maps each
clause to its fields and paths, and links adjacent defects #1573, #1574,
#1575 and #1498. sections.md rejoins the binding-reference sentence that
#1426's paragraph split.
@doublewhy
test: raise from one call in the tool_ref ambiguity test
80005e3 
SonarCloud python:S5778 flagged two possibly raising calls inside one pytest.raises block. The test module is outside the research-evidence digest, so the recorded captures still bind this source.
@doublewhy
docs(examples): limit the participant-tools import rules to tool_ref
b1a6935 
The README's Imports section stated the import binding and ambiguity rules
for every reference, but composition applies them to tool_ref only. Scope both
sentences to tool_ref and say that other reference families still bind an
ambiguous bare name silently (#1575) and that reference-typed action argument
values are not resolved or namespaced on import (#1574).
@doublewhy
docs(examples): state which reference families reject an ambiguous im…
3ecaf6b 
…port name

The Imports section said that every reference family other than tool_ref binds
an ambiguous bare name silently, but composition already rejects a bare stateful
dependency name that matches both a generated artifact and a persistent volume
(_rewrite_stateful_dependency_ref). Name that check and limit the silent-binding
statement to references renamed through the combined name map, such as
authority_scope_refs (#1575).
@doublewhy
doublewhy force-pushed the 298-tool-authoring-verification branch from c7f9679 to f3d5db9 Compare October 13, 2026 14:58
@doublewhy doublewhy mentioned this pull request Oct 13, 2026
Draft
9 of 11 tasks
@doublewhy
doublewhy marked this pull request as draft October 13, 2026 19:38
@doublewhy
chore(research): record research captures for issue #298
c1ee3ee 
Collected on this branch's source (3ecaf6b, implementation digest b4e37ba26a53): every pinned specification artifact ran through the production pipeline, the 10 retained formal SDL cases were replayed with replay_case, the 4 production cases ran with their raes processor argv, and the 14 participant functions ran (18 passed).
@doublewhy
doublewhy force-pushed the 298-tool-authoring-verification branch from f3d5db9 to c1ee3ee Compare October 13, 2026 20:18
@doublewhy
doublewhy marked this pull request as ready for review October 14, 2026 03:33
@Brad-Edwards
Brad-Edwards merged commit fdbcbc8 into dev Oct 15, 2026
34 checks passed
@Brad-Edwards
Brad-Edwards deleted the 298-tool-authoring-verification branch October 15, 2026 06:14
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@doublewhy @Brad-Edwards