feat(spec): reject unknown requires capability tokens at authoring (#3265)#3302
Merged
Conversation
…3265) The warn-first phase (framework#3281) is over: the platform capability vocabulary is now the proven-complete union of every token the framework CLI and cloud's objectos-runtime resolve (audited across both repos — the only out-of-vocabulary token in either is a test fixture). So defineStack now REJECTS an unknown `requires` token instead of warning: - Split canonicalizeStackRequires (alias rewrite + deprecation warn only) from a new validateKnownCapabilities that returns one error per distinct unknown token; defineStack throws on any, consistent with its other validators. - Deprecated aliases (aiStudio/aiSeat) still canonicalize with a warning — they are valid, just deprecated; only genuinely unknown tokens (typos / stale references no runtime provides) throw. - The serve resolver keeps WARNING (not throwing) on an unknown token in a raw artifact: authoring is the gate (Prime Directive #12), and a pre-built or older-spec artifact must not crash-boot a running server over a no-op token. Closes the "declared ≠ enforced" gap for capability tokens: a typo used to be silently ignored by every runtime; now it fails loudly at build time. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01TjHfkKmEvgk8v7N8nTe5sH
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
Contributor
📓 Docs Drift CheckThis PR changes 1 package(s): 103 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 19, 2026 17:06
This was referenced Jul 19, 2026
This was referenced Jul 19, 2026
os-zhuang
added a commit
that referenced
this pull request
Jul 20, 2026
) (#3329) The one-cycle deprecation window from #3265 is over and a major release is being prepared, so the legacy camelCase `requires` aliases are dropped. `aiStudio`/`aiSeat` are no longer canonicalized to `ai-studio`/`ai-seat` — they now reject as unknown tokens in defineStack (the #3302 end-state). - spec: remove DEPRECATED_PLATFORM_CAPABILITY_ALIASES + canonicalizePlatformCapability; isKnownPlatformCapability no longer canonicalizes; defineStack drops canonicalizeStackRequires. - cli: serve resolver no longer canonicalizes raw-artifact requires. - Regenerate api-surface.json (4 export deletions); sync ADR-0087 spec-changes.json + protocol-upgrade-guide.md (pre-existing v16 drift surfaced by the path-filtered check). Breaking change shipped as minor per the launch-window convention. Cloud objectos-runtime (pinned to an older framework) follows on its next .framework-sha bump.
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.
The terminal state of the framework#3265 vocabulary work (Prime Directive #12). The warn-first phase (#3281) becomes a hard reject in
defineStack.What
canonicalizeStackRequires(alias rewrite + deprecation warn only) from a new internalvalidateKnownCapabilitiesthat returns one error per distinct unknown token;defineStackthrows on any, consistent with its existing validators (namespace-prefix, cross-ref, hierarchy-scope).aiStudio/aiSeat) still canonicalize with a warning — they're valid, just deprecated; only genuinely unknown tokens (typos / stale references no runtime provides) throw.Closes the "declared ≠ enforced" gap for capability tokens: a typo like
requires: ['automations']used to be silently ignored by every runtime; now it fails loudly atdefineStacktime.Completeness audit (the precondition for flipping)
I enumerated every
requires/defaultRequires/ dynamic token source across both repos before flipping:examples/,packages/, templates): every token is inPLATFORM_CAPABILITY_TOKENS. The only out-of-vocabulary literal,automations, exists solely in the Unify optional-plugin loading: frameworkserve.tsand cloudobjectos-runtimeare parallel implementations with divergent capability tokens (ai-studiovsaiStudio) #3265 test fixtures (the deliberate "unknown" case) — never in a real config.apps/objectos*,objectos-runtime,security-enterprise): alldefaultRequires/requirestokens are in-vocabulary;aiStudiois a recognized deprecated alias (canonicalizes →ai-studio);enterpriseCapabilityRequires()emitsai-studio/governance— both in-vocabulary.So no real app build in either repo breaks.
The warn added in #3281 has not shipped in a released spec yet. Merging this makes the transition, for any consumer, go straight from silent no-op → hard
defineStackerror, with no warn-only release in between. In-repo this is safe (audited above), and unknown tokens are no-ops today so no real functionality breaks — only a build surfaces a latent typo. But a downstream/customer stack that happens to carry a stale no-op token would start failing its build on upgrade.If you'd rather preserve the usual deprecation cadence, hold this until #3281's warn has shipped one release; otherwise it's ready. (Consistent with
defineStack's other hard validators, I did not add an env escape hatch — Prime Directive #2 keeps env/business logic out ofpackages/spec.)Verification
platform-capabilities.test.ts+ updatedstack-requires.test.ts(unknown → throws + names every distinct unknown; alias still canonicalizes+passes; non-strict skips) +stack.test.ts— 104 passingtsc --noEmiton spec exit 0 · eslint clean · no new public exports (api-surface snapshot unaffected)🤖 Generated with Claude Code
Generated by Claude Code