feat(spec): the error-code ledger states its federation contract; makeApiErrorSchema(extraCodes) (#4805) - #7110
Merged
Conversation
…eApiErrorSchema(extraCodes) (#4805) The three objectstack-side items of the federated ERROR_CODE_LEDGER ruling (#4805, 2026-08-03, re-confirmed 2026-08-09). 1. `error-code-ledger.zod.ts` header: "this ledger registers framework packages only" becomes a stated RULE — with what a downstream product repo does instead (its own ledger, composed as `envelopeViolations` for shape + `code ∈ StandardErrorCode ∪ <its own ledger>` for vocabulary), and why the ruling went this way (a commercial vocabulary does not belong in an Apache-2.0 spec; per-code cross-repo friction breeds semantic reuse). Previously inferable only by scanning the package names. 2. `ApiErrorSchema.code`'s description: `StandardErrorCode ∪ ERROR_CODE_LEDGER` -> `StandardErrorCode` ∪ the ledger the serving side registers, naming `ERROR_CODE_LEDGER` as the framework packages' one. Description only. 3. New export `makeApiErrorSchema(extraCodes)`: the same envelope with `StandardErrorCode ∪ extraCodes` as the code vocabulary, so a downstream conformance suite gets one parse with a Zod issue path instead of a shape assertion plus a hand-written membership test. The envelope shape is `ApiErrorSchema`'s, reused rather than restated. Additive: `ApiErrorSchema` parses exactly what it parsed before. Regenerated: api-surface/api.json, export-origins/api.json (the new export), content/docs/references/api/{contract,error-code-ledger}.mdx (gen:schema && gen:docs). Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01GmC5HAjupdHqdB9bzsYzPg
|
The latest updates on your projects. Learn more about Vercel for GitHub. 1 Skipped Deployment
|
Contributor
📓 Docs Drift CheckThis PR changes 1 package(s): 106 hand-written doc(s) reference the affected code and may need an implementation-accuracy re-verification:
⛔ 7 release-owned page(s) also reference the affected code. These are read-only:
|
github-actions
Bot
added
documentation
os-zhuang
marked this pull request as ready for review
August 9, 2026 18:53
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
1 participant
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 #4805
The ruling this implements
Maintainer ruling on #4805, 2026-08-03, re-confirmed 2026-08-09 — quoted verbatim, untranslated:
The cloud-side ledger and the 36-code migration are the cloud shard's work under cloud#944 — not in this PR. No
ERROR_CODE_LEDGERentry is added, removed or changed, and no new error code is introduced.The three items
packages/spec/src/api/error-code-ledger.zod.ts— file headerenvelopeViolationsfor shape +code ∈ StandardErrorCode ∪ (its own ledger)for vocabulary, or onemakeApiErrorSchemaparse). Plus why the ruling went this way (an Apache-2.0 spec should not enumerate a closed-source product's billing/plan states under package names absent from this distribution; per-code cross-repo friction pushes authors toward reusing a semantically wrong code, which is less visible than inventing one), and the corollary for this file: an owner key for a package not published from this repo is out of scope by construction.packages/spec/src/api/contract.zod.ts—ApiErrorSchema.codedescription (was:19)'Error code (e.g. VALIDATION_ERROR; StandardErrorCode ∪ ERROR_CODE_LEDGER)', with a JSDoc saying "a code registered inERROR_CODE_LEDGER".'Error code (e.g. VALIDATION_ERROR; StandardErrorCode ∪ the ledger the serving side registers — ERROR_CODE_LEDGER for framework packages)', with the JSDoc naming the federation and pointing atmakeApiErrorSchema. Description only — the parsed vocabulary is untouched.packages/spec/src/api/contract.zod.ts— new exportmakeApiErrorSchema(extraCodes)— the same envelope withStandardErrorCode ∪ extraCodesas thecodevocabulary, so the suite gets one verdict with a Zod issue path. The shape isApiErrorSchema's, reused via.extendrather than restated, so a field added to the base envelope reaches every downstream ledger with it.ERROR_CODE_LEDGER's own entries are deliberately not folded in: a service that also relays framework-produced errors says so explicitly (makeApiErrorSchema([...REGISTERED_ERROR_CODES, ...MY_CODES])).Additive throughout. Federating the ledger does not open the vocabulary; it moves where the other half of it is declared.
Verification
Premise re-located on current main before editing. Both anchors exist as the ruling describes: the ledger header's two-tier prose ran straight into the "Registering a new code" section with no scope statement anywhere, and
ApiErrorSchema.codesat atcontract.zod.ts:19composing its vocabulary fromErrorCode(error-code-ledger.zod.ts—z.enum([...StandardErrorCode.options, ...REGISTERED_ERROR_CODES])). The factory reuses that same composition rule with the caller's list in place of the framework ledger.Reverse verification — direction predicted before measuring. Revert the factory's union to the standard catalog alone (
[...StandardErrorCode.options],extraCodesignored) and the two pins that exercise an extra code must flip red, while the standard-catalog pin and the rejection pin stay green — those two do not depend on the union:Tests 2 failed | 48 passed (50)under the reverted union;50 passedrestored. The rejection pins assert the Zod issue path (['code']) and code (invalid_value), so they cannot pass on an unrelated failure.ApiErrorSchemabehaviour byte-identical. Its own tests were not touched, and the four API error suites run unchanged and green (contract,error-code-ledger,errors,envelope-violations— 99 passed). Only itscodedescription changed, which is item 2 and shows up exactly where a description should: one line of generated reference docs.Gates
Run one by one from
.github/workflows/lint.yml, both jobs:pnpm lint(ESLint,--no-inline-config)pnpm check:nul-bytes(incl. self-test)pnpm check:error-code-casing(incl. self-test)pnpm --filter @objectstack/spec exec tsc --noEmitpnpm --filter @objectstack/spec typecheck(src + scripts + tests)pnpm --filter @objectstack/spec check:generated --reconcile-onlycheck:+ 14gen:all classifiedcheck:export-origins(self-test + check)check:api-surfacecheck:authorable-surfacecheck:docscheck:skill-docs,check:spec-changes,check:upgrade-guidecheck:exported-any,check:dual-source-exportspnpm check:spec-parsed-alias(ADR-0122)z.inferalias)node scripts/check-adr-0087-registration.mjs --base origin/mainpnpm --filter @objectstack/spec testRegenerated snapshots committed — item 3 adds a public export, and
check:export-originsis new in the Type Check job today (a missed snapshot is what red-lit PR #7103 on exactly this gate):packages/spec/api-surface/api.json—gen:api-surface(needs the builtdist/*.d.ts; ran afterpnpm --filter @objectstack/spec build)packages/spec/export-origins/api.json—gen:export-origins(named bycheck:generated --reconcile-only)content/docs/references/api/{contract,error-code-ledger}.mdx—gen:schema && gen:docsOne changeset,
@objectstack/specminor (the factory ships). Nocontent/docs/releases/edit.Findings
StandardErrorCode ∪ extraCodes, notErrorCode ∪ extraCodes, matching the ruling's formula (code ∈ StandardErrorCode ∪ CLOUD_ERROR_CODE_LEDGER) rather than quietly widening it. A downstream that also relays framework-package codes has to say so —makeApiErrorSchema([...REGISTERED_ERROR_CODES, ...MY_CODES])— and that spelling is documented on the factory. Worth a reviewer's eye: it is the one design decision in this PR that could reasonably have gone the other way, and it is the direction that keeps a downstream ledger from silently inheriting 200-odd framework codes it never audited.packages/types/src/response-envelope.tsandpackages/metadata-protocol/src/protocol.tsstill saysStandardErrorCode ∪ ERROR_CODE_LEDGER. Left alone deliberately — both describe the framework side, where that union is still exactly right;ErrorCodeis unchanged.