Skip to content

ADR-0023: a profile matches its own firmware's client - #81

Open
jonathanstokes wants to merge 1 commit into
mainfrom
docs/profile-override-trigger
Open

jonathanstokes wants to merge 1 commit into
mainfrom
docs/profile-override-trigger

Conversation

@jonathanstokes

@jonathanstokes jonathanstokes commented Sep 23, 2026 •

Copy link
Copy Markdown
Contributor

Summary

ADR-0020 reads two ways. Its Decision names "the operations measured to behave differently"; its Rationale names "the wire behaviours that were measured to differ" and "a profile overrides where it was measured to differ". Outcome or wire, and nothing had parted them until #59. This record reads all three as the wire, and says what that costs.

  • docs/ADR.md: ADR-0023, appended, plus a Narrows: line registered in the Format section beside Supersedes: and Settles with:. ADR-0020 is byte-for-byte untouched and its status is unchanged.
  • docs/STEERING.md: the ADR table row and a change-log entry.
  • CLAUDE.md: one bullet in "Profiles and the wire".
  • docs/architecture.md and the QuadCortex41 docstring: both gave the outcome reading, and both are what a contributor finishing a profile actually reads.

Why now

On CorOS 4.1.0, 2026-09-11, a contributor drove four setlist operations against disposable folders, each confirmed by a listing, both folders absent afterwards:

shape sent result on CorOS 4.1.0
the 4.0.1 create_setlist shape folder created
the 4.0.1 delete_setlist shape folder removed
Cortex Control 4.1's create shape folder created
Cortex Control 4.1's delete shape folder removed

So the shapes differ on the wire and not in outcome. #59 wants to override on that basis, and ADR-0020's words as written invite the opposite reading. Writing the rule down first means #59's review can cite it instead of arguing it.

The rejected option is recorded as it stands: overriding only where the inherited shape was measured to fail is the cheaper rule. It loses because the evidence it waits for is a delete that silently does nothing, and because delete_from_library has no known meaning while the inherited shape leaves it unset, handing that choice to the firmware.

The rule's edge is named in the record: it covers a profile's operations, which is what QuadCortex.operations() lists. The keepalive is not one of them, so protocol.md 4.3 keeps its own reasoning and is untouched here.

Validation

Head: 4e847be

  • offline suite: 2974 passed, 7 skipped
  • python -m mypy pyquadcortex: clean, 46 source files
  • git diff --check: clean
  • every block of the new record is under docs/writing.md's 150-word cap (max 145). docs/ADR.md sits in NOT_CAPPED, so the suite does not check this; measured by hand.
  • git merge-tree against Scope setlist mutation wire shapes by CorOS profile #59's head 61b0e2a is clean, so the profiles.py docstring edit does not conflict with it.

Hardware

No run. The diff is four .md files and one docstring in pyquadcortex/protocol/profiles.py, which is library source. Nothing here can reach the wire: the change is confined to a string literal, and nothing under pyquadcortex/ reads __doc__. The owner has waived the hardware run for this pull request, under contributing.md's allowance for a change that cannot reach the wire.

🤖 Generated with Claude Code

@jonathanstokes
jonathanstokes force-pushed the docs/profile-override-trigger branch from 00ae16a to 719e232 Compare September 23, 2026 18:55
ADR-0020 reads two ways. Its Decision names "the operations measured to
behave differently"; its Rationale names "the wire behaviours that were
measured to differ" and "a profile overrides where it was measured to
differ". Outcome or wire, and nothing had parted them until #59.

On CorOS 4.1.0 a contributor drove four setlist operations against
disposable folders: the 4.0.1 create and delete shapes, and the shapes
Cortex Control 4.1 sends. All four worked, each confirmed by a listing. So
the shapes differ on the wire and not in outcome.

This record reads all three clauses as the wire. ADR-0020's decision stands
and its status is unchanged. An override's record now carries two
measurements, the client's shape and what the inherited shape did on that
firmware, rather than one.

architecture.md's new-profile recipe and the QuadCortex41 docstring gave the
outcome reading and are corrected here, since they are what a contributor
finishing a profile actually reads.
@jonathanstokes
jonathanstokes force-pushed the docs/profile-override-trigger branch from 719e232 to 4e847be Compare September 23, 2026 19:09
@jonathanstokes
jonathanstokes marked this pull request as ready for review September 23, 2026 20:41
@tony-xmelon

Copy link
Copy Markdown
Contributor

This PR is ready for its initial review. The current head 4e847be passes all five CI checks (Python 3.11/3.12/3.13, mypy, and build/twine). When you have a chance, feedback on the ADR and profile-matching policy would be welcome.

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