docs(spec): document validation governance fields + cross_field/script overlap; tidy stale form mirror#3198
Merged
Conversation
…t overlap; tidy stale form mirror Follow-up to the 2026-06 validation liveness audit (#3106 / #3184). No runtime behavior change — documentation, a form-schema cleanup, and a docs pointer: - Document that label/description/tags are governance/editor metadata (surfaced to the Studio rule editor, not evaluated on the write path). Kept, not removed: they're set by nearly every example rule and feed the /meta/types editor form, so they're declared on purpose rather than silent no-ops. - Document that cross_field evaluates identically to script (same CEL predicate); only fields[0] is read, to target the violation at a field. Noted on the schema, its fields .describe(), and the validation docs. Variant kept for the field-targeting affordance + backward compatibility (removing it would break discriminated-union parsing of existing cross_field metadata). - Remove dead form-field entries (scope/caseSensitive/url/handler) and the stale type=unique hint from the hand-written HAND_CRAFTED_SCHEMAS['validation'] fallback in metadata-protocol — leftovers from the removed unique/async/custom variants. - Add the missing beforeDelete pointer to the docs' "not a rule type" callout so delete-time guards aren't stranded (validation has no delete event since #3184). Regenerated content/docs/references/data/validation.mdx. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01VCUSMJBsX14C3RQdWFw7N7
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
github-actions
Bot
added
documentation
Contributor
📓 Docs Drift CheckThis PR changes 2 package(s): 102 hand-written doc(s) reference the affected code and may need an implementation-accuracy re-verification:
|
os-zhuang
marked this pull request as ready for review
July 18, 2026 08:45
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.
Summary
Follow-up to the 2026-06 validation-rule liveness audit (
docs/audits/2026-06-validationschema-property-liveness.md), completing its two remaining recommendations after #3106 / #3184. No runtime behavior change — documentation, a form-schema cleanup, and one docs pointer. Both audit recommendations were investigated and resolved the non-breaking way (document, not delete/merge), because the evidence showed the aggressive versions carry real cost:label/description/tagsare not dead — they're surfaced to the Studio validation-rule editor form (via the/meta/typesform schema) and to rule listings, and are set by nearly every example rule. Deleting them would be a breaking TS change to authored metadata. Documented as governance/editor metadata (declared on purpose, not evaluated on the write path) instead of removed.cross_fieldisscript+ afields[0]error-label hint — same CEL predicate path. A merge would break discriminated-union parsing of existingcross_fieldmetadata and drop a capabilityscriptcan't express (scripthas nofields). Documented the overlap on the schema, itsfields.describe(), and the validation docs so authors can choose; kept the variant.Changes
packages/spec/src/data/validation.zod.ts— doc block onBaseValidationSchemaclarifyinglabel/description/tagsare governance/editor metadata, not write-path-evaluated; a note +fields.describe()onCrossFieldValidationSchemadocumenting thescriptoverlap andfields[0]-only semantics.packages/metadata-protocol/src/protocol.ts— removed dead entries (scope,caseSensitive,url,handler) and the staletype=uniquehint from the hand-writtenHAND_CRAFTED_SCHEMAS['validation']form fallback (leftovers from the removedunique/async/customvariants; thetype/eventsenums there were already fixed in fix(spec): trim dead 'delete' member from validation-rule events enum #3189).content/docs/data-modeling/validation.mdx— added the missingbeforeDeletepointer to the "not a rule type" callout (delete-time guards) and across_field-vs-scriptoverlap callout.content/docs/references/data/validation.mdx— regenerated..changeset/— patch.Related — issues filed from the same PD #10
events-enum auditThis follow-up also ran a broader "declared ≠ enforced" sweep of every
events-style enum in the spec. Findings filed as separate issues (out of scope here):HookEventvalues never dispatch (beforeFindOne/count/aggregate/*Many). Verified; security-relevant fail-open.undeleteandapiare declared but never fire #3196 — webhook triggersundeleteandapinever fire. Verified.Verification
spec suite 256 files / 6885 tests green, objectql suite 71 files / 954 tests green,
check:docs256 generated files in sync, spec + metadata-protocol builds green, eslint clean.🤖 Generated with Claude Code
https://claude.ai/code/session_01VCUSMJBsX14C3RQdWFw7N7
Generated by Claude Code