Skip to content

feat(sdl): add reusable participant tool profiles - #1576

Merged
Brad-Edwards merged 10 commits into
devfrom
301-participant-tool-profiles
Oct 27, 2026
Merged

Brad-Edwards merged 10 commits into
devfrom
301-participant-tool-profiles

Conversation

@doublewhy

@doublewhy doublewhy commented Oct 13, 2026 •

Copy link
Copy Markdown
Contributor

Summary

One behavior specification can provide a reusable tool profile to multiple roles. Explicit binding selectors control availability, while observation boundaries and action contracts retain visibility and invocation constraints. The change also repairs the approved parser/projection defects and preserves hidden-reference enforcement across authored and canonical history names.

Requirement UIDs

  • ACT-619

Related Issues

Refs #301

ADR Impact

  • ADR-053
  • ADR-076
  • ADR-083
  • ADR-095
  • ADR-109

Changes

  • Add participant and role selectors that only narrow the owning profile; preserve conflict rejection, v2 participant filtering, and v1 refusal of scoped bindings.
  • Require projected actions and observation boundaries to belong to the participant, and filter bindings by their declared boundary.
  • Compile authored visibility references to canonical addresses and resolve incoming history aliases before visibility/evidence checks; reject ambiguous aliases and conflicting classifications.
  • Reject authored private module references across participant and nested binding fields, including parameter substitution, while preserving exact generated references.
  • Publish unique, nonblank selector constraints in all five affected schemas, update publication records and migration/design guidance, and propose ACT-619 ACTIVE with reconciled implementation/test links.
  • Record fresh content-addressed formal and specification evidence without changing historical captures or claim limits.

Test Plan

  • Unit tests pass
  • Applicable integration tests pass in CI
  • Full completion suite required in CI before merge
  • Coverage checks pass in CI

490 targeted tests passed on the synchronized branch, including schema parity and full-history regressions for hidden authored references. Generated schema/publication/catalog checks, changed-file Ruff, native Vale, file-local policy, requirement governance, and fresh current-capture replay passed. The complete 61-file review found two classes; both are repaired and covered by regression tests. The merged branch preserves dev's imported tool identity and declaration-resolution behavior. Hosted current-head CI and SonarCloud gates are required before readiness.

Ground Control Checks

  • Repository policy checks required in CI before merge
  • Pre-push Codex review completed; all findings fixed or dispositioned

Traceability

  • IMPLEMENTS: ACT-619 ← implementations/python/packages/raes/participant_behavior_specification.py, ACT-619 ← implementations/python/packages/raes_processor/compiler/participant_contracts.py, ACT-619 ← implementations/python/packages/raes_processor/models/behavior_ref_checks.py, ACT-619 ← implementations/python/packages/raes/_behavior_authoring.py
  • TESTS: ACT-619 ← implementations/python/tests/test_issue_301_participant_tool_profiles.py, ACT-619 ← implementations/python/tests/test_issue_301_participant_tool_profile_conflicts.py, ACT-619 ← implementations/python/tests/test_issue_301_selector_schema_parity.py, ACT-619 ← implementations/python/tests/test_issue_301_history_alias_visibility.py, ACT-619 ← implementations/python/tests/test_issue_301_private_references.py, ACT-619 ← implementations/python/tests/test_issue_301_projection_boundaries.py

Checklist

  • Code follows the project's coding standards
  • Changelog: owned by Release Please (generated from the Conventional Commit PR title; no per-PR fragment)
  • Architectural docs updated if stack, package structure, or key behaviors changed

Documentation

Updated: see diff.

@doublewhy
doublewhy marked this pull request as ready for review October 13, 2026 04:39
doublewhy added a commit that referenced this pull request Oct 13, 2026
doublewhy added a commit that referenced this pull request Oct 13, 2026
Specification-coverage capture capture-4798f874 and formal-validation
capture capture-d4e3fc83 bind the implementation digest of this branch,
which combines dev cf8b430, #1576 1195c8d and the issue #1572 change;
outcomes and claim limits are unchanged.
…profiles

A behavior specification's tool_affordances are its participant tool
profile. Each binding may now carry participant_refs and
participant_role_refs, which only narrow the specification's selection
and use the same PI-03 resolver over the composed scenario. Both empty
keeps today's meaning.

The validator rejects selectors that widen the specification, dangle or
name an authored __private ref, and checks each binding's actions and
boundaries against the participants it selects. Composition namespaces
explicit selectors and keeps roles global. The compiler records the raw
selectors and resolved participant addresses, with defense-in-depth
diagnostics, and makes the existing specification-level dangling
participant diagnostic reachable.

v2 projection offers a binding only to the participants it selects,
deciding scope from the raw selector lists so an empty resolution fails
closed. v1 refuses specifications with scoped bindings. Admission is
unchanged and independent of bindings.

The five SDL schemas and their publication records gain the two fields.
Docs, the ACT-619 formal section, the decision record and the migration
page describe the semantics, conflict classes and unsupported cases.

Refs #301
SonarCloud python:S9073 flags two combined assertions and python:S5778
flags an exception test that builds its selection and admission request
inside pytest.raises. Assert each condition separately and build the
inputs first. Test-only; the research captures still bind the source.

Refs #301
…ence catalog

The tool_affordances participant_role_refs row said a role ref is fatal unless bound by a participant inside the owning behavior specification, which reads as the relative selector semantics the decision record rejects. State the absolute rule that TP-3 and the validator enforce: at least one participant has the role, and every participant with the role is inside the owning behavior specification. The parity expectation changes with the row.
Specification-coverage capture capture-97145a5b and formal-validation
capture capture-49729647 bind this branch's implementation digest
(17c00fe3) on top of dev 348c490, with zero formal replay drift. They
follow docs/develop/research-captures.md, using dev's current captures
(capture-c9ca186a and capture-3bad3945) as templates; outcomes,
classifications and claim limits are unchanged.

Refs #301
@Brad-Edwards Brad-Edwards changed the title feat(sdl): add participant-scoped tool affordances for reusable tool profiles feat(sdl): add reusable participant tool profiles Oct 26, 2026
@Brad-Edwards
Brad-Edwards marked this pull request as ready for review October 26, 2026 23:05
@Brad-Edwards

Copy link
Copy Markdown
Collaborator

Ground Control delivery — this pull request delivers issue #301; Phase E runs on merge.

@Brad-Edwards

Copy link
Copy Markdown
Collaborator

Ground Control delivery — this pull request delivers issue #301; Phase E runs on merge.

@Brad-Edwards
Brad-Edwards merged commit 2ace10c into dev Oct 27, 2026
33 checks passed
@Brad-Edwards
Brad-Edwards deleted the 301-participant-tool-profiles branch October 27, 2026 03:51
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants