docs(spec): ledger the data-field step (slider) as UI-only and deliberately unenforced (#6514) - #6769
Merged
Merged
Conversation
…berately unenforced Fixes #6514 The ADR-0049 "ledger" half of the maintainer's 2026-08-08 ruling: `step` is the slider's UI increment, not a stored-value constraint. Recorded in three places that a future reader actually consults — the declaration site, the liveness ledger row, and the dead-surface disposition plan — with the reason enforcement was rejected and the shape it would take if it ever returns. Zero behaviour change: comments, a ledger note and a handwritten audit row. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01K94yzy5CVgC2JtrqYAuDk2
|
The latest updates on your projects. Learn more about Vercel for GitHub. 1 Skipped Deployment
|
qq9340100
added
skip-changeset
Claude
Contributor
📓 Docs Drift CheckThis PR changes 1 package(s): 112 hand-written doc(s) reference the affected code and may need an implementation-accuracy re-verification:
|
github-actions
Bot
added
documentation
qq9340100
marked this pull request as ready for review
August 8, 2026 15:16
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.
Fixes #6514
The ADR-0049 ledger half of the maintainer's 2026-08-08 ruling: the data-field
step(slider) is a UI increment, deliberately not a stored-value constraint. No enforcement, no behaviour change — comments, a liveness-ledger note and a handwritten audit row, so the next reader finds a verdict instead of silence.Premise check (against
origin/main, not the issue's snapshot)All three premises hold, re-verified at
a5d25734c(and again after merging main):packages/objectql/src/validation/record-validator.tsstill has nodef.stepreader. Its numeric branch (number | currency | percent | rating | slider) readsdef.minanddef.maxonly;git grep -n step origin/main -- packages/objectql/src/validation/returns four hits, all prose (lock-step, "step 2" inrule-validator.ts).stepis still absent from the comment block above the declaration, and no one has enforced or ledgered it since filing.f_slider(min: 0, max: 100, step: 5).Measured, not asserted — driving the built
validateRecordagainst exactly that field definition:That is the asymmetry the issue named, in one run: the declared window binds, the declared grid does not. Deliberately not committed as a test — a pin asserting "off-grid values are accepted" would lock in the non-enforcement and have to be deleted by the very feature request the ruling leaves the door open for.
One mechanism assumption falsified (the dispatch invited this)
The ruling's disposition was "add
stepto the runtime-ignored key list atfield.zod.ts:691-695, besideshowValue/marks". That block exists (now at 709-714, line numbers drifted) but it is not a list of surviving keys the runtime ignores — it is a pruned-keys tombstone:showValueandmarksare gone from the schema (git grep showValue -- packages/spec/src/finds only this comment). Addingstepto that list would therefore have stated thatstepwas removed — false, and exactly the kind of ledger rot the liveness gate's ORPHAN direction exists to catch.The second half of the falsification changes the verdict's shape, not its outcome:
stepis not dead surface at all. It is renderer-live — objectuipackages/fields/src/widgets/SliderField.tsx:14readsfield.step ?? 1and passes it to the Slider — andpackages/spec/liveness/field.jsonalready ledgers itliveon that evidence. So the honest ledger is not "inert likeshowValue" but "live in the renderer, deliberately unbinding on the write path", which is a different fact and the one an author needs.Implemented as the ruling's intent rather than its letter: a sibling comment on the surviving declaration, carrying the ruling, its reasoning, and the return path.
What changed (3 files, 19 insertions)
packages/spec/src/data/field.zod.ts— a comment above thestepdeclaration: UI increment, not a value constraint; renderer-live (with the objectuifile:line) which is why it is not in the pruned list above;record-validator.tsenforcesmin/maxand readsstepnowhere; why settings 的step是同族第五个声明但不执行的值约束键 —— 先要一个「它算不算值约束」的判断 #6199 / PR fix(service-settings): enforce the declaredstepgrid on the settings write path and the env path (#6199) #6501 does not transfer (its hook was that schema's own "numeric bounds and step" grouping); the stored-data hazard (record-validator judges updates to existing rows, so stored off-grid values would start failing on their next edit); and the return path — PR fix(service-settings): enforce the declaredstepgrid on the settings write path and the env path (#6199) #6501's shape, anchor atmin + k * stepfalling back to 0 when nominis declared, epsilon-tolerant comparison..describe()untouched, so nothing reader-visible regenerates.docs/audits/2026-06-dead-surface-disposition-plan.md— the ledger row, appended after the P2 field paragraph. The historical paragraph is left verbatim (that doc's correction header says the sections are kept for history); the row instead splits the parenthetical that caused the ambiguity — "(slider: min/max/step live)" is a renderer verdict that had been read as an enforcement one.packages/spec/liveness/field.json— one deliberate extension beyond the ruling's two files, flagged for review:step's row said"slider — SliderField.tsx (min/max/step live).", an unqualifiedlivethat is precisely the ambiguity this issue is about, and that row is where a future agent looks first. Rewritten with the file's own existing convention for live-but-not-on-the-write-path —uniquecarries"CAVEAT — DDL-only; NOT validated on the write path"andprecision"CAVEAT — UI display formatting only"— plusverifiedAt: "2026-08-08". Status stayslive;check:livenessgreen. Revert this one file if it reads as scope creep; the other two carry the ruling on their own.Regeneration: MEASURED, and it is zero
Not inherited from #6723 (that was
contracts/, this isdata/). Ran the spec build and every generated-artifact gate on the edited tree:check:generated— All 10 generated artifacts are up to datecheck:authorable-surface— green;authorable-defaults/verified against upstreama5d25734c9a0, 1308 defaults unchanged.authorable-surface.base.jsondid not move, so the dispatch's STOP condition never fired.check:docs230 files in sync ·check:skill-refs9 in sync ·check:skill-docsin sync ·check:react-blocks2 in sync ·check:api-surfaceunchanged ·check:spec-changesup to date ·check:upgrade-guideup to dategit statusafter all of it: only the 3 files above.A plain
//comment (no.describe(), no TSDoc bound to a generator) regenerates nothing. One honest caveat:gen:authorable-surface-baserefuses to run in this environment — a shallow checkout cannot establish the anchor's ancestry, so it exits 1 by design (#5235 / #5370). Pre-existing, unrelated to this change, and the gate CI actually runs (check:authorable-surface) is green.Reverse verification: the template does not fit, and here is why
There is nothing to take out. The change adds no branch, no rule and no assertion, so no diagnostic can move in any direction — predicting red, extra-findings or inverted would all be fabrication. What was verifiable was the ledger's factual claim, and that is the probe above: restoring the claim's negation is impossible without writing the enforcement the ruling rejected. Reported as a blank rather than dressed up.
Gates + tests
Enumerated one by one from
.github/workflows/lint.ymlon the merged tree (not from memory) — all PASS:lint(ESLint),slot-lookup,query-options-erasure,verify-stand-in,nul-bytes,doc-authoring,docs-audit-scope,role-word,quick-reference-counts,adr-anchors,org-identifier,authz-resolver,service-providers,route-envelope,error-code-casing,wildcard-fallthrough,meta-type-normalized,init-service-contract,durability-log-level,startup-registry-verdict,objectui-changeset,release-notes,release-body,node-version,workflow-status-functions,shard-attestation,published-files,engine-double-contract,kernel-hook-pairs,resume-authority-declared,driver-memory-census,merge-driver,spec-parsed-alias,type-check-coverage,type-check-debt,driver-conformance,stall-guard,skill-frame-sync,skill-compatibility,i18n,i18n-coverage,app-nav-i18n, plus the spec set (generated,skill-docs,spec-changes,upgrade-guide,authorable-surface,docs,skill-refs,react-blocks,exported-any,dual-source-exports,skill-examples,api-surface) and@objectstack/lint check:doc-formula-expressions.Also run, since I edited a liveness ledger —
spec-liveness-check.yml's own set:check:liveness✓ (every governed property classified, everyliveentry's evidence path resolves),check:empty-state✓,check:variant-docs✓,check:strictness-ledger✓.pnpm --filter @objectstack/spec test— 345 files / 8846 tests passedpnpm --filter @objectstack/spec typecheck— green (incl.check:test-typecheck)turbo run typecheckover packages + apps — 120 tasks, all green;turbo run build— 70 tasks green; examples + downstream-contract typecheck greenThree gates (
check:i18n,check:i18n-coverage,check:app-nav-i18n) first reported PREREQUISITE NOT MET in the fresh worktree — the missing-build trap, not a failure. Re-run after building the workspace: all three green.Merge with
mainorigin/mainmoved 12 commits mid-flight, including the sibling spec PR #6705 (api/export.zod.tsdescribe + regeneratedexport.mdx). Followed the four-step sequence —git merge origin/main(never rebase), no conflicts on any os-regen path, merge committed before any regeneration, then the generated-artifact gates re-run on the merged tree (check:generated10/10). Asserted both sides survived: #6705'sdryRunprose is present incontent/docs/references/api/export.mdx, and this PR's three entries are intact.Changeset
None, deliberately. No published behaviour changes: a source comment, an internal ledger note and an internal audit doc under
docs/audits/(notcontent/docs/), with zero regenerated product in the diff — so there is nothing for a release note to say. That is the measurement's answer, not a preference; #6705's patch-changeset precedent applies to a diff that carries reader-visible regenerated docs, and this one does not.skip-changesetapplied to this PR.content/docs/releases/untouched.Generated by Claude Code