Uh oh!
There was an error while loading. Please reload this page.
feat(spec)!: close ApiEndpointSchema against undeclared keys, and name the author state on the upgrade path (#5384, #5227) - #6840
Merged
Conversation
…e the author state on the upgrade path (#5384, #5227) `api` became a registered metadata type at #5312, making `endpoint.zod.ts` an authoring surface (`defineStack({ apis })`, the Studio form, `PUT /meta/api/:name`) while it was still an open `z.object`. A `cacheTTL` / `objectParam` / `outputMappings` typo parsed green, published green, and served without the policy or projection its author wrote. The shape is `strictObject` now, with curated wrong-layer prescriptions for `namespace` (ADR-0121 D2 — derived from `manifest.namespace`, never per-endpoint) and the six stored-envelope bookkeeping keys. The ORDER is the record: closing this was measured and refused first, because the same schema parsed STORED rows carrying `packageId` / `state`. #5309 (PR #6576) paid that debt at the layer that owned it (`peelStoredEnvelope`), after which the conversion was an ordinary #4001 one. `ApiEndpointSchema` never learned a bookkeeping key. Corpus measured before landing: examples/* = 2 endpoints, cloud = 0 endpoints, zero undeclared keys either side, so direction A carried and no key had to stay. `api` leaves STILL_STRIP (closed 24 -> 25 of 26; `view` alone remains) and the CLI gate row moves NOT_YET_CLOSED -> GATED_AT. #5227 needed no schema change: ADR-0122 phase 2 (PR #6279) already made `ApiEndpoint` the author state, so omitting `authRequired` compiles. The `declarative-apis-endpoints-live` upgrade-guide entry now says so with a usable annotation. An `ApiEndpointInput` alias is deliberately NOT added — after the flip it would be a synonym, which ADR-0122 D3 forbids and `check:spec-parsed-alias` rule 4 rejects. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_011sGk4SKHqGRgmmqUok1P8M
… guidance Caught by the drift pin added in the same change, on its first run: `STORED_ENVELOPE_KEYS` has SEVEN entries and the guidance table listed six. This is the drift the pin exists for, and it is silent in the direction that matters — `package` is peeled correctly on the stored paths, so every other test stays green, while an author who hand-writes it into a declaration gets the generic "unrecognized key" instead of the wrong-layer prescription. A rejection arriving without its upgrade is the ledger's finding 7. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_011sGk4SKHqGRgmmqUok1P8M
The latest updates on your projects. Learn more about Vercel for GitHub. 1 Skipped Deployment
|
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:
|
…#6148) The gate does not decide whether an entry is needed; it requires the question be answered. Answered `not-required (no-migration-prescription)`: this change retires no key, only the unknown-key posture moves, and an undeclared key was never honoured — so no stored shape carries it and nothing that ever worked becomes invalid. The schema rejection is the upgrade channel and is more specific than a ledger line could be. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_011sGk4SKHqGRgmmqUok1P8M
…w syntax The marker's own category name supplies the word 'migration', and the two worked examples supplied the arrow — so the disposition line matched the gate's framed-line rewrite-prescription detector and contradicted itself. Same reasoning, stated without FROM/TO arrow syntax; the per-key prescriptions live in the schema's aliases/guidance, which is where an author meets them. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_011sGk4SKHqGRgmmqUok1P8M
This was referenced Aug 9, 2026
os-zhuang
marked this pull request as ready for review
August 9, 2026 01:07
Uh oh!
There was an error while loading. Please reload this page.
This was referenced Aug 9, 2026
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 freeto 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#5384
Fixes#5227
Two cards on one surface (
packages/spec/src/api/endpoint.zod.ts), maintainer-batched in the v17 window ruling. One landed as a schema change; the other's type half had already landed upstream, so what remains of it here is the documentation half — itemized per card below.Ruling chain (quoted verbatim, untranslated)
The 2026-08-05 "GA 后实施" hold was superseded by the maintainer's 2026-08-07 window re-ruling:
The hard prerequisite #5309 landed in PR #6576 (merged 2026-08-08T06:10:55Z) and is in this branch's base.
#5227's triage ruled the fix direction as:
That first clause is now impossible, and the reason is recorded below — it is not a scope reduction taken on my own authority.
Corpus measurement (the ruling made direction A conditional on it)
Direction A carried: zero
apis:entries carry an undeclared key, so no key had to be preserved and direction B does not apply.apis:entriesexamples/*grep -rn "apis:" examples/→ the one declaration site, keys read against the schema's 20 declared keyscloud(objectstack-ai/cloud)git -C /home/user/cloud fetch origin main --deepen=100, thengit -C … grep -l … origin/mainforapis:,ApiEndpoint,authRequired,objectParams,inputMappingTaskFeedEndpoint/InquiryPurgeEndpointinexamples/app-showcase/src/system/apis/index.ts; they use only declared keys (name,path,method,summary,description,type,target,objectParams,authRequired,cacheTtl).cloudwas reachable, and 0 is a measurement, not an unreachability.origin/main=781fd036; all five greps returned zero files. Grepped againstorigin/main, never the working tree.Card 1 — #5384:
ApiEndpointSchemais closedpackages/spec/src/api/endpoint.zod.tsz.object, no catchallstrictObject— catchallnever, with curatedaliases+guidanceguidance.namespacenamespaceparsed green, gated nothingguidance× 7 bookkeeping keyspackages/spec/src/kernel/metadata-type-schemas.test.tsSTILL_STRIP = ['view','api'], closed 24 of 26STILL_STRIP = ['view'], closed 25 of 26packages/cli/test/metadata-type-schema-gate.test.tsapiinNOT_YET_CLOSED("both gates agree, author still told")apiinGATED_AT("both gates REJECT"); table now empty, emptiness assertedpackages/metadata/src/publish-endpoint-gate.test.tsdocs/audits/…-strictness-ledger.mdapi/=wire — tolerant by designendpoint.zod.tsauthorable, rest wirepackages/metadata/src/stored-envelope.test.tsSTORED_ENVELOPE_KEYSentry carries the prescriptionThe order is the record. Closing this shape was measured and refused first (2026-08-05): the same schema parsed STORED rows, so a naked
strictObjectfailed every row withunrecognized_keys: ['packageId', 'state']— the load-time backstop excluded the endpoint (404) and the publish gate reported a schema error in place of the ADR-0121 D6 verdict it exists to give. The debt was real and it was not in this vocabulary, so #5309 paid it at the layer that owned it (peelStoredEnvelope).ApiEndpointSchemanever learned a bookkeeping key.The drift pin earned its place on its first run.
STORED_ENVELOPE_KEYShas seven entries and my guidance table had six —packagewas missing. That drift is silent in the direction that matters: the key is peeled correctly on the stored paths, so every other test stays green, while a hand-authoring author gets a generic "unrecognized key" instead of the upgrade. Fixed in the second commit.Rejection cases assert the named verdict, never a bare throw
ApiEndpointSchema.safeParsespeaks in zod issues, not an ADR-0112{ code, status }envelope — that envelope appears further out, wherePUT /meta/api/:nameturns this verdict into a 422. So every new rejection case assertsissue.code === 'unrecognized_keys', the offending key inissue.keys, and the prescription text.publishPackagespeaks invalidationErrors[], so its cases assert the named entry (name,type, message content) — the #6576 precedent. No case relies ontoThrow().Card 2 — #5227: premise expired upstream; only the guide half was left to build
premise_still_valid: falsefor the type half. The issue's fact — "export type ApiEndpoint = z.infer是输出类型,该键是必填" — stopped being true before this card was dispatched. PR #6279 (ADR-0122 phase 2, #6083, merged 2026-08-08 03:47) flipped all 1384 bare aliases toz.input. Measured on this base withtsc:const e: ApiEndpoint = { name, path, method, type, target }— compiles. The omission TS 作者写不出「省略 authRequired」这个安全形状:ApiEndpoint是输出类型,authRequired在上面是必填 #5227 says an author cannot express is expressible today.ApiEndpointParsedreproduces TS 作者写不出「省略 authRequired」这个安全形状:ApiEndpoint是输出类型,authRequired在上面是必填 #5227's exactTS2741: Property 'authRequired' is missing. That error now belongs to the parsed-state name, which is correct.The ruled remedy is now prohibited. ADR-0122 D3 forbids a permanent synonym, and phase 2 retired 102
XInputaliases for exactly this reason.check:spec-parsed-aliasrule 4 rejects "anXInputthat denotes exactly what a bare name denotes". AddingApiEndpointInputwould therefore fail a CI gate — so it is deliberately not added, and the file says why so the next reader does not re-add it.Not #6606, incidentally: that PR added
ApiMappingand four otherapi/aliases, and never touchedApiEndpoint.packages/spec/src/migrations/registry.ts→declarative-apis-endpoints-liveApiEndpointfor declarations,ApiEndpointParsedfor parse resultsdocs/protocol-upgrade-guide.md,spec-changes.jsongen:upgrade-guide,gen:spec-changes) — never hand-editedendpoint.zod.tsdocblockApiEndpointInputmust not come backpackages/spec/src/api/endpoint.test.tsApiEndpointomits;ApiEndpointParsedrequires, via@ts-expect-error)Verification
Build order: the worktree's first command was
pnpm --filter @objectstack/spec build; cross-package work built each closure first (pnpm --filter '@objectstack/metadata^...' build), then a full workspace build before the build-dependent gates and typecheck. Sweep direction for the consumption radius is the prefix form —pnpm --filter '...@objectstack/spec'is downstream consumers — and because this is a contract tightening the full-repo gate is the standard, with scoped filters used only to iterate.@objectstack/spec@objectstack/metadatapnpm lint(ESLint job — hosts the familycheck:*gates)check:*× 40 + spec-scopedcheck:*× 17turbo typecheck(TypeScript Type Check job)check:authorable-surfaceis green;gen:schemaleftauthorable-surface.base.jsonuntouched and reports the expected baseRev lag (the anchor is a snapshot proved authentic, not current) — not hand-edited, not re-anchored.packages/spec/json-schema/is gitignored, so the newadditionalProperties: falseis regenerated rather than committed.ADR-0087 disposition (#6148). The changeset answers the question in writing as
not-required (no-migration-prescription): this change retires no key, only the posture moves, and an undeclared key was never honoured — so no stored shape carries one and nothing that ever worked becomes invalid. Worth recording how the first two attempts failed, because it is a neat self-reference: the marker's own category name supplies the word "migration" and my two worked examples supplied the arrow, so the disposition line matched the gate's own rewrite-prescription detector and read as contradicting itself. The reasoning is unchanged; the arrow syntax is gone.Three gates failed on the first pass and all three were infrastructure, not this change:
check:i18n,check:i18n-coverage,check:app-nav-i18neach require the built CLI and each said so explicitly ("Nothing was checked … this result says NOTHING"). After the full workspace build, all three pass.Reverse verification — direction declared before running
Predicted: the new rejection cases go RED with the fix removed; the controls stay GREEN. Taken out with
git checkout origin/main -- packages/spec/src/api/endpoint.zod.ts(nevergit stash— that stack is shared across worktrees).@objectstack/specapi REJECTS unknown keys@objectstack/metadataControls held in both directions: the clean endpoint parses, the loader-stamped ADR-0010 envelope parses, and
authRequiredstill defaults totrue.endpoint.zod.tscannot exercise them, because the fix they pin landed in PR #6279, not here. They would go red only if someone flippedApiEndpointback toz.infer, which is exactly the regression worth pinning.Blast radius
An
apis:entry carrying an undeclared key now failsobjectstack validate,objectstack buildand the metadata write path instead of publishing with the key discarded. Measured in-tree impact: zero (see the corpus table). Callers were enumerated rather than assumed — the twopackages/metadataparse sites, plus the third atselectDocumentableEndpoints(packages/rest/src/openapi-endpoints.ts), which #5309's dev measured as bodies-only and which is re-covered here by the full-repo suite.Notes for the reviewer
cursor被静默丢弃(SDK 分页永远第一页),limit默认 20 声明 vs 50 实现 #6361 (notifications wire schema):packages/spec/src/api/protocol.zod.tsis not in this diff and carries zero references toApiEndpoint.view'sSTILL_STRIPexit (view的 spec 校验闸门形同虚设:saveMetaItem({ item: { nope: 1 } })返回 success 并把{"nope":1}存成一个 active view #5599) is mechanically unchanged in cost. It is now the only entry, so closing it empties the set — and a vitestit.each([])registers zero cases silently rather than erroring (probed). That vacuity is already backstopped by the neighbouring campaign-number assertion (closed.length === 25), which goes red the momentviewcloses without the count being updated. Nothing inview's own row was touched.skip-changesetlabel: this PR ships a real changeset, so the label does not apply. Labels read back after the bots settled:documentation,size/l,tests,tooling.Generated by Claude Code