fix(spec): the error-code waiver reasons and the auth-feature registry notes state each decision in words instead of a tracker number (stage 7) - #21636
Conversation
…y notes state each decision in words instead of a tracker number (stage 7) Class (f) of the spec lane's runtime-string share: 17 registry rationales (33 tracker ids) in STANDARD_SYNONYM_WAIVERS / PROVENANCE_WAIVERS and PUBLIC_AUTH_FEATURES. Each now states the cited decision in words, or drops a citation its sentence already explained. Text only; one patch changeset. Claude-Session: https://claude.ai/code/session_01T9u38rswFp5Rw8DswRUReJ Co-authored-by: Claude <noreply@anthropic.com>
📓 Docs Drift CheckThis PR changes 1 package(s): 12 hand-written doc(s) NAME something this change touched and may need an implementation-accuracy re-verification:
⛔ 5 release-owned page(s) also name something this change touched. These are read-only:
What this run could not see
Coarse fallback — 138 page(s) merely mention a changed package (the pre-#9192 predicate, kept for the deliberately-wide backstop): Which tree this was computed onThis run read A worktree cut from an older # while this PR is open — GitHub drops the merge commit once it closes
git fetch origin 2222890b5baabfc72e66382a9a317cda2f939eb1 && git checkout 2222890b5baabfc72e66382a9a317cda2f939eb1
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin 0fc80878f859d434b1d4cf52cc91d486b2b4ada6 151a8ce4ed95321fd74fb3ff9b57ad892b0b1e80 && git checkout -B drift-repro 0fc80878f859d434b1d4cf52cc91d486b2b4ada6 && git merge --no-ff 151a8ce4ed95321fd74fb3ff9b57ad892b0b1e80
node scripts/docs-audit/affected-docs.mjs --json 0fc80878f859d434b1d4cf52cc91d486b2b4ada6
|
Part of #20749
Clause-②: no
Stage 7 of the
domain:speclane's share of the runtime-string burn-down (ruling5902360492, A / A; form D per5749154545): class (f), the internal registry rationales inpackages/spec/src. Every rewritten reason or note now states in words what the cited decision was, or drops a citation its sentence already explained. Text only. The card stays open for its later stages (migrations/registry.ts, then the test strings).What changed
api/error-code-ledger.zod.ts: thereasonof all fiveSTANDARD_SYNONYM_WAIVERSentries and of ninePROVENANCE_WAIVERSentries (14 messages / 29 ids).kernel/public-auth-features.ts:PUBLIC_AUTH_FEATURES.deviceAuthorization.exempt.reason,.phoneNumber.notesand.phoneNumberOtp.exempt.reason(3 / 4).@objectstack/specpatch changeset,Clause-②: no. These are exported constants, and the new text ships in the package'sdist: measured in 14.jsand 14.mjschunks, and in no.d.ts(the reasons are+chains, so their type isstring).check:generated: all 15 up to date). No reader matches these strings by their text (see "Readers" below), so no test or gate moves.packages/spec, as the claim predicted. Each producer is the constant itself, so no other package is touched.Census at the base (A1)
The earlier stages'
census.cjsis not on disk in this container. I re-implemented it from stage 3's stated semantics, then held it to two references:check-doc-authoring.mjs --censuswas run from a scratch copy whosePACKAGES_PROSE_ROOT/PACKAGES_PROSE_EXCLUDEDwere pointed atpackages/spec/srcand at nothing (two lines differ, nothing else). Result: 3 files, 231 = 231 ids, 0 per-file differences.2f30de851c. Test strings 1804 / 1920 in 425 files, identical. Class (f) 17 / 33, identical, line for line against stage 3's table.At base
045b946256, 1849 files were scanned and 1346 parsed after the byte prefilter, with 0 parse diagnostics:packages/spec/src)line:id)api/error-code-ledger.zod.tskernel/public-auth-features.ts2513is the cross-repoobjectui#2513) · 220:2871 · 230:2780The claim's raw-grep figures (192 and 14 lines) include comments. Comments are out of this stage.
Controls.
error-code-ledger.zod.ts:1773-1776reads as ONE message, with 4 ids on lines 1773-1774.public-auth-features.ts:220reads as one message,#2871.error-code-ledger.zod.ts:1589(docblock,#8211),:1687(a//heading,#13353),public-auth-features.ts:106(// [#11544]) and:209(a//inside the array,#9968) each read 0.The rest of the non-test population at this base is
migrations/registry.ts: 45 messages / 198 ids. Stage 6 read 43 / 196 at2f30de851c, so main has since added two messages there. That file is the next stage's.Delivered (A2): each site, the decision as read, the new words
I read each cited card in full through REST, body and every comment. The decision column names the record. Line is the base line of the message.
error-code-ledger.zod.ts:1618(CONFLICT)5272495731(census-first route5271501976). The record-sharing errors moved onto the ADR-0112 envelope, and the unregistered 409CONFLICTwas registered as it stood under@objectstack/rest, so the wire stayed byte-identical. 8211: triage adjudication5273232415, option C. The admission gate refuses a semantic synonym unless waived. The existing synonyms are grandfathered by waivers, and consolidation (B) is deferred until a specific code has a measured victim(respondSharingError 409 arm; registered by #8111). Wire value kept; consolidation deferred per #8211.→(respondSharingError 409 arm), registered as it stood when the record-sharing errors moved onto the ADR-0112 envelope, so the wire stayed byte-identical. Wire value kept; consolidation deferred until it has a measured victim.error-code-ledger.zod.ts:1625(FORBIDDEN)5489077644and ACCEPT5489099444. The provenance gate landed, and cloud-connection's own-route 403 got itsFORBIDDENrow; this waiver's reason was extended, not endorsed. 8211 as above#13353 added the cloud-connection provenance row for the same pre-existing wire value→cloud-connection lists the same pre-existing wire value under its own provenance row; the closing clause as forCONFLICTerror-code-ledger.zod.ts:1633(INTERNAL)consolidation deferred per #8211.→consolidation deferred until it has a measured victim.error-code-ledger.zod.ts:1639(NOT_FOUND)5788584892. plugin-security's class-field stamps got their rows, the overlay-discard 404'sNOT_FOUNDamong them, and this waiver's reason named the new emitter. 8211 as above#19441 added the plugin-security provenance row for the same pre-existing wire value→plugin-security lists the same pre-existing wire value under its own provenance row; the closing clause as forCONFLICTerror-code-ledger.zod.ts:1646(UNAUTHORIZED)surfaced by the detector when the #8211 gate landed, beyond the four the card named→surfaced by the synonym detector when it landed, beyond the four first reported; the closing clause as forCONFLICTerror-code-ledger.zod.ts:1752(UPDATE_ID_MISMATCH)5383569192(unequal scalarwhere.id) and5386672884(non-scalarwhere.id). Both shapes are refused 400 with one code, from metadata-core's shared constructor, thrown byObjectQL.update. The objectql row's comment records itrecords "hence registered here" (#11142/#11230).→records "hence registered here".(the sentence already said it)error-code-ledger.zod.ts:1760(FLOW_DISABLED)5322602563. A disabled flow answers 409FLOW_DISABLED, registered under runtime because the door names the wire vocabulary. 9446: maintainer ruling5322867819. The status table is a property of the flow-dispatch contract, so every door convergesanswer 409 (#9415/#9446; the runtime row's comment records the decision).→answer 409 — every door that dispatches a flow answers from one status table, by ruling (the runtime row's comment records the decision).error-code-ledger.zod.ts:1766(FLOW_NO_START_NODE)Same decision as FLOW_DISABLED, 422 arm (#9415/#9446):→Same decision as FLOW_DISABLED, its 422 arm:error-code-ledger.zod.ts:1773(FLOW_INPUT_SCHEMA_INVALID)5353928368(B). A definition-level input-schema refusal is non-retryable and becomes a never-dispatched exit with its own code. 11504 (the card answers 404; its comments are still served, claim5429880388, dev report5430346333): the contract half of that ruling, which minted the code ahead of its producer. 10413 / 10576: maintainer ruling5364977280filed the contract half as its own card, ahead of the implementing half. That is the split shapeRegistered ahead of its producer by design (#10025 → #11504, the #10413 → #10576 split shape):→Registered ahead of its producer by design: the ruling that a definition-level input-schema refusal is non-retryable and never dispatched split into a contract half, which minted this code, and a services half that emits it, the contract half landing first.error-code-ledger.zod.ts:1782(EXTERNAL_IMPORT_ERROR)5267576256and dev report5268577504. One thrown-error mapping (resolveThrownHttpError,@objectstack/types) shared by both doors honours a throw's ownstatusandcode.importNameRefusedErrorsets exactly those two (external-datasource-service.ts:337-342)Adjudicated on #13353:→Adjudicated when the provenance gate landed:;is the #8016 declaration shape,→declares its own `status` and `code`, the shape the shared thrown-error resolver honours,error-code-ledger.zod.ts:1793(UPLOAD_SESSION_EXPIRED)5270541620and dev report5274803860.resumeUploadshort-circuits onexpiredwith the server's 410 pair. 13353: ACCEPT5489099444. The scope question stays recorded on the waiver, with no new card, for want of pullClient-side synthesis (#7870):→Client-side synthesis:;is the open scope question #13353 recorded —→is an open scope question, recorded when the provenance gate landed and left unruled for want of pull —error-code-ledger.zod.ts:1812(VALIDATION_FAILED)fields[], never 500, matching rest. 8016:validationFailuremoved into@objectstack/typesbeside the shared mapping (validation-failure.tsheader)Shared constructor by design (#8016/#3918): `validationFailure()` lives in the dependency-light package so BOTH doors recognise one shape;→Shared constructor by design: `validationFailure()` lives in the dependency-light package beside the one thrown-error mapping both doors share, so BOTH doors recognise one shape and answer it 400 with its `fields[]`, never 500;error-code-ledger.zod.ts:1821(ANALYTICS_DATE_RANGE_UNRECOGNIZED)dateRangeidentically, held by one shared conformance fixture. 8016: the shared-constructor shape, which the sentence already statesShared constructor one package over, the #8016 shape (#16322):→Shared constructor one package over:;refuse identically — which is the property the card's shared conformance fixture→refuse an unrecognised `dateRange` identically — which is the property the shared date-range conformance fixtureerror-code-ledger.zod.ts:1838(TENANT_SCOPE_REQUIRED)5261730657. An uninstall across every tenant must be declared explicitly; no organization and no flag is a loud 400, never every tenant's rows. 20492: triage5877470267and dev report5878755305. Every refusal runs beforeuninstallPackage, so a refused request changes nothingrefuses with (#7780), so a refused uninstall changes nothing (#20492).→refuses a scope-less uninstall with (an uninstall across every organization must be declared, never inferred from a missing one), so a refused uninstall changes nothing.public-auth-features.ts:197(deviceAuthorization)features.deviceAuthorizationand shows a not-enabled state instead of calling the endpoints; the client type gained the key. 2874: card body. P2② is the login-surface audit of objectui's consumptionKnown gap: objectui DeviceAuthPage hits the device-auth endpoints without checking this flag (absent from its client type) — tracked in objectui#2513 (#2874 P2②).→Login consumption verified: objectui DeviceAuthPage reads this flag and, when it is off, says device authorization is not enabled instead of calling the device-auth endpoints.(see Acceptance notes: the old text was stale)public-auth-features.ts:220(phoneNumber)phoneNumberparam is visible only onfeatures.phoneNumber == true, and default-loading the plugin was rejectedThe original #2871 fix.→The fix this registry generalizes: create-user's phone field follows the opt-in phoneNumber plugin instead of offering a field the backend refuses.public-auth-features.ts:230(phoneNumberOtp)smschannel for phone OTP.isPhoneOtpDeliverable()(auth-manager.ts:7735-7740) answers false without an SMS service, and false for a log-only one in productionwhen SMS is actually deliverable (#2780).→when an SMS service can actually deliver the code; a log-only transport in production keeps it off.Six of the longer reasons (
FLOW_INPUT_SCHEMA_INVALID,EXTERNAL_IMPORT_ERROR,UPLOAD_SESSION_EXPIRED,VALIDATION_FAILED,ANALYTICS_DATE_RANGE_UNRECOGNIZED,TENANT_SCOPE_REQUIRED) were re-wrapped after the edit so no continuation line is ragged. A script compared each message's joined string value before and after the re-wrap: identical, read back from disk. Code spans never break across a line.Readers (A3)
StandardSynonymWaiverSchema/ProvenanceWaiverSchemarequirereason: z.string().min(1).error-code-ledger.test.tsandcheck:error-code-provenanceparse every waiver through them.public-auth-features.test.ts:54requiresexempt.reason.length > 0.check:error-code-provenance: "OK — every registered-code stamp site is listed under its own owner key or carries a recorded waiver (10 waiver(s), all live)", 330 sites, 311 listed, 19 waived.git grep -Facross the tree, the two edited files excluded. One hit: a//section heading inpackages/runtime/src/domains/packages-uninstall-refuse-before-mutate.test.ts:221, not an assertion.content/docs/**page,skills/**file, snapshot or generated artifact quotes a changed message.platform-objectsandplugin-authregistry guards read keys,semanticsandgatedInputs, nevernotesorreason.Text only (A4)
The earlier stages'
skeleton.cjsis not on disk either, so I re-implemented it from its stated semantics, with TypeScript 6.0.3:+chain's adjacent string operands read as one string. Identifiers, numbers, regex literals, keywords and punctuation are kept, and comments are never read.Base copies against the committed head
151a8ce4ed:error-code-ledger.zod.tspublic-auth-features.tsParse diagnostics were 0 / 0. The 17 changed groups are the 17 census messages.
Controls, on scratch copies of the head ledger. Each mutation was counted on disk: anchor hits 1, replacement present 1, anchor left 0, differs from head.
standardSynonymViolationsrenamed===flipped to!==in the waiver check+operands.describe()string that never carried an idNo repo file was mutated for the controls.
Edits were applied by a script whose 20 anchors each had to hit exactly once in the original text before any write. They were read back from disk after it: 20 gone, 20 replacements present once.
Census after: class (f) 0 / 0. Non-test went from 62 / 231 to 45 / 198, all of it
migrations/registry.ts. That file is the lit control: the instrument still sees its ids, so the zero is not blindness. Test strings are unchanged at 1804 / 1920. The gate's per-literal leg agrees: 198 ids, all inmigrations/registry.ts.Gates
All heavy runs went through
scripts/pm/os-verify-lock.sh(slotdev-20749-s7). Every exit code was written to a file before it was read. All runs are at151a8ce4ed.pnpm --filter @objectstack/spec build: exit 0, "38/38 declared declaration file(s) present".pnpm --filter @objectstack/spec check:generated: exit 0, "All 15 generated artifacts are up to date".pnpm --filter @objectstack/spec test: "Test Files 608 passed (608) / Tests 18017 passed | 1 todo (18018)".pnpm --filter @objectstack/spec run typecheck: exit 0, "check:test-typecheck: OK … 52 file(s) / 246 error(s) / 135 pinned signature(s) held".repoproject's one file that reads a changed module (scripts/file-description.test.ts, which reads the ledger file's opening docblock): 111 of 111.pnpm turbo run build --concurrency=2over every package: 71 / 71. This fed the dist-reading gates. On the first pass, before this build, three of them answered PREREQUISITE NOT MET (exit 3):check:doc-formula-expressions,check:dual-build-cjs-loadsandcheck:lean-entry-closure. The other two (check:dts-closure,check:sourcemap-no-sources-content) had swept only 1 built package. All five were re-run after the build.node scripts/pm/dispatch-gates.mjs --commands --repo objectstack-ai/objectstack(no paths) derived 82 commands for 3 paths vs merge base045b94625: 139 changed lines (+85 / -54), under 5000. All 82 exit 0 on the built tree.--ran: "82 derived famil(ies) accounted for — 82 run, 0 NOT-MEASURED (a DERIVED zero — all 82 recorded an exit code and none of them is 3)".check:doc-authoring: "17351 customer-facing string(s) across 1255 spec sources clean" / "0 pinned site(s) … no growth, no burn-down unrecorded".check:nul-bytes: "OK (scanned 9998 text file(s) …)". A self-scan of the added lines for raw control bytes found none.check:issue-citations,check:api-surfaceandcheck:error-code-provenanceall exit 0.check-issue-citations --census, the shard attestations,check-test-completeness). They are CI's.eslint --no-inline-config --format jsonover the 2 changed TS files read 2 files, 0 errors, 0 warnings. Population comes from ESLint's own config:calculateConfigForFilereturns a config for each, andisPathIgnoredis false. Invariance: no type-aware linting (parserOptions.project/projectServiceare null for both), so a string-text edit cannot move an untouched file's verdict. Repo-widepnpm lintis CI's.check-changeset-no-major --event,check-partof-closing-keyword) were run against this exact title and body before it was sent; their lines are in the dev report.Acceptance notes
deviceAuthorizationexemption said objectui'sDeviceAuthPagecalled the device-auth endpoints without checking the flag, a gap "tracked in" objectui 2513. That card closed completed on 2026-07-15. At the.objectui-shapin89cad75d55,apps/console/src/pages/auth/DeviceAuthPage.tsx:66-130readsfeatures.deviceAuthorizationand renders "Device authorization not enabled" when it is off, andpackages/auth/src/types.ts:286declares the key. Stating that card's decision in words makes the text say the gap is closed. The registry's semantics, surface and keys are untouched.a4f0cb0a45,0fc80878f8: service-automation and lint, plus their changesets). Neither touches this PR's three paths orpackages/spec, so main was not merged; the merge queue rebuilds onto currentmain. No open PR touches these paths: 12 open PRs read, file lists included.migrations/registry.ts(45 / 198 at this base), the test strings (1804 / 1920), the two.mjsgate scripts, and every comment, including the docblocks and the//headings beside these tables..claude/**,skills/**, ADR, NORTH-STAR or AGENTS.md path.Line budget
139 changed lines (+85 / -54) over 3 files vs merge base
045b94625(dispatch-gates): the ledger (+59 / -48), the auth registry (+9 / -6), and the changeset (+17). No generated file, no governed surface.Generated by Claude Code