Skip to content

[S2] Correct the immutability contract + ADR-025 (resolves C-63, #181)#188

Merged
Polichinel merged 1 commit into
developmentfrom
story/s2-immutability-contract
Jun 28, 2026
Merged

[S2] Correct the immutability contract + ADR-025 (resolves C-63, #181)#188
Polichinel merged 1 commit into
developmentfrom
story/s2-immutability-contract

Conversation

@Polichinel

Copy link
Copy Markdown
Contributor

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 is
writeable (bare self._values = values in all three constructors) and shared by
with_metadata, so an in-place .values mutation silently corrupts buffer-sharing
frames. Enforcing it would be "tightening an invariant" on the frozen-surface
values → a MAJOR (GOVERNANCE/ADR-018) + cross-repo coordinated bump — disproportionate
for a hole the audit found nothing exercises (zero in-place .values mutations in src//tests/).

Changes (correct the contract, don't enforce it)

  • docs/ADRs/025_value_buffer_immutability_by_convention.md (new): value-buffer immutability is
    by convention (writeable to preserve zero-copy / mmap); the index is the enforced one; the
    setflags-enforce on .values is a deferred MAJOR-rider (added free on the next MAJOR).
  • 3 frame CICs (PredictionFrame/TargetFrame/FeatureFrame) §9/§3 + README design principle 3:
    reworded so the pf.values[:] = 0 example states it does not raise (silent shared-buffer
    corruption), 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); the
    writeable-buffer residual + deferred-enforce trigger are captured in the resolution.

Validation

  • Docs-only — no src/ or test change (the enforce is deferred, not done).
  • Verified against ground truth: index.py:55-56 setflags the index; the constructors do not
    setflags .values. /review-diff CLEAN (one cross-ref-number warning found and fixed).
  • validate_docs ✅ · ruff ✅ · pytest 100% ✅

🤖 Generated with Claude Code

…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>
@Polichinel Polichinel merged commit 4eb8c4c into development Jun 28, 2026
7 checks passed
@Polichinel Polichinel deleted the story/s2-immutability-contract branch June 28, 2026 00:27
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.

[S2] Correct the immutability contract + ADR-025 (resolves C-63, no enforce)

1 participant