[S2] Correct the immutability contract + ADR-025 (resolves C-63, #181)#188
Merged
Merged
Conversation
…s C-63, #181) The leaf advertised "immutable value objects", but only the index is setflags(write=False)-enforced; the value buffer is writeable (index.py:55-56 vs the frame constructors' bare self._values = values), so an in-place .values mutation silently corrupts buffer-sharing frames. Enforcing it via setflags would be "tightening an invariant" on the frozen-surface `values` — a MAJOR under GOVERNANCE/ADR-018, triggering the cross-repo coordinated bump — disproportionate for a hole the audit found nothing exercises. Correct the contract instead of enforcing it: ADR-025 records that value-buffer immutability is by convention (writeable on purpose, to preserve zero-copy / mmap; mutating .values is unsupported) and the index is the enforced one, and records the setflags-enforce as a deferred MAJOR-rider. Reword the three frame CICs §9/§3 + README design principle 3 to match; correct the principle cross-ref number (2→3). Resolves register C-63 (relocated to Resolved; open 13→12). Docs-only — no src/ or test change; validate_docs + ruff + pytest 100% green. Epic #179 / S2. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This was referenced Jun 28, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Epic #179 · Story S2 · closes #181 · resolves register C-63 (contract corrected; enforce deferred)
The leaf advertised "immutable value objects", but only the index is
setflags(write=False)-enforced (index.py:55-56); the frame value buffer iswriteable (bare
self._values = valuesin all three constructors) and shared bywith_metadata, so an in-place.valuesmutation silently corrupts buffer-sharingframes. Enforcing it would be "tightening an invariant" on the frozen-surface
values→ a MAJOR (GOVERNANCE/ADR-018) + cross-repo coordinated bump — disproportionatefor a hole the audit found nothing exercises (zero in-place
.valuesmutations insrc//tests/).Changes (correct the contract, don't enforce it)
docs/ADRs/025_value_buffer_immutability_by_convention.md(new): value-buffer immutability isby convention (writeable to preserve zero-copy /
mmap); the index is the enforced one; thesetflags-enforce on.valuesis a deferred MAJOR-rider (added free on the next MAJOR).PredictionFrame/TargetFrame/FeatureFrame) §9/§3 + README design principle 3:reworded so the
pf.values[:] = 0example states it does not raise (silent shared-buffercorruption), not that it's prevented. Cross-ref number corrected (principle 2→3).
docs/ADRs/README.md: ADR-025 indexed.reports/technical_risk_register.md: C-63 → Resolved (relocated; open 13→12); thewriteable-buffer residual + deferred-enforce trigger are captured in the resolution.
Validation
src/or test change (the enforce is deferred, not done).index.py:55-56setflags the index; the constructors do notsetflags
.values./review-diffCLEAN (one cross-ref-number warning found and fixed).validate_docs✅ ·ruff✅ ·pytest100% ✅🤖 Generated with Claude Code