test(spec): field-level contract lock for explain / access-matrix schemas#2844
Merged
Conversation
…emas api-surface.json guards the export NAMES; this locks the FIELD SHAPE that downstream consumers depend on — notably the ADR-0091 L3 enterprise product (cloud security-enterprise: recert review UX, evidence export, break-glass attribution) which reads ExplainDecision.layers[].contributors[] and AccessMatrixEntry directly. Locks: the 7 operations, the 9-layer pipeline, the 6 verdicts, contributor kind + the ADR-0091 D2 lifecycle 'state' member, the ExplainDecision principal shape (nullable userId, positions/permissionSets defaults, principalKind, onBehalfOf), and AccessMatrixEntry's required crud/bypass bits + scopes + version literal. Any break is now a deliberate, reviewable protocol change. Test-only; empty changeset (no release). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_012oLzaP8n7A3YKFmgaHWC8H
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
github-actions
Bot
added
documentation
os-zhuang
marked this pull request as ready for review
July 11, 2026 14:41
Contributor
📓 Docs Drift CheckThis PR changes 1 package(s): 96 hand-written doc(s) reference the affected code and may need an implementation-accuracy re-verification:
|
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
2 participants
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.
What
Adds
packages/spec/src/security/explain.test.ts— a field-level shape lock for the publicexplain/access-matrixschemas (ADR-0090 D6). Test-only; empty changeset (no release).Why
api-surface.jsonalready guards the export names (a removed export fails the lint gate). But it doesn't guard the field shape — andexplain.zod.tshad no test (unlikepermission/rls/sharing/territory). So a breaking change toExplainDecision's internals (a dropped enum member, a removed field, a changed default) would pass CI silently.These schemas are the wire contract the ADR-0091 L3 enterprise product will consume (cloud
security-enterprise: recertification review UX, evidence export, break-glass attribution readExplainDecision.layers[].contributors[]andAccessMatrixEntrydirectly — see cloud#808 §8 / cloud#812 #8). Locking the shape now makes explain a stable contract cloud can depend on without drift fear — the "zero-waste prerequisite" that's worth doing regardless of when L3 is built, because the explain engine already ships and the lock also protects the community Studio "why can this user access?" panel.What it locks
kind+ the ADR-0091 D2 lifecyclestatemember (active/expired) L3 reads for the "expired" report;ExplainDecision.principalshape (nullableuserId,positions/permissionSetsdefaults,principalKind,onBehalfOf);AccessMatrixEntry's required crud + View/Modify-All bypass bits + optional scopes +sharingModel;AccessMatrixversionliteral +entriesdefault.Any break here is now a deliberate, reviewable protocol change — bump the protocol major with it.
Tests
explain.test.ts— 13/13 green (spec builds clean;check-changeset-fixedpasses).🤖 Generated with Claude Code
https://claude.ai/code/session_012oLzaP8n7A3YKFmgaHWC8H
Generated by Claude Code