feat(spec,cli): one platform capability vocabulary — canonical kebab tokens, deprecated aliases, warn-first validation (#3265)#3281
Merged
Conversation
…tokens, deprecated aliases, warn validation (#3265) The standalone serve path and cloud's objectos-runtime resolve `requires` tokens through parallel registries that had already diverged: framework shipped `ai-studio` (kebab) while cloud used `aiStudio` (camel), and both sides silently ignored unknown tokens, so the mismatch failed silently. Make the spec the single owner of the vocabulary: - spec/kernel/platform-capabilities: canonical PLATFORM_CAPABILITY_TOKENS (kebab-case; includes cloud-runtime tokens ai-seat/governance and hierarchy-security), DEPRECATED_PLATFORM_CAPABILITY_ALIASES (aiStudio -> ai-studio, aiSeat -> ai-seat, one deprecation cycle), canonicalizePlatformCapability, isKnownPlatformCapability. - defineStack: rewrite deprecated aliases to canonical at authoring time (fix the producer, PD#12) and warn on unknown tokens. Warn-first by design - both runtimes previously ignored unknown tokens, so a hard reject could brick working stacks; intended to become an error once the vocabulary proves complete. - serve.ts: canonicalize raw artifact `requires` through the same helper (covers artifacts compiled by an older spec), warn on declared-but- unknown tokens instead of silently ignoring them, and lift CAPABILITY_PROVIDERS / CAPABILITY_TO_TIER to statics with a drift test asserting every registry key stays inside the spec vocabulary. - types: move the missing-vs-crashed module classifier to @objectstack/types isModuleNotFoundError (the #1595 err.code-first fix); Serve.isModuleNotFoundError delegates. Cloud's objectos-runtime adopts the shared classifier at its next framework pin bump. 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 3 package(s): 109 hand-written doc(s) reference the affected code and may need an implementation-accuracy re-verification:
|
…surface snapshot check:api-surface guards the public API; the vocabulary exports (root + /kernel) are intentional additions (0 breaking), so regenerate and commit the snapshot. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01TjHfkKmEvgk8v7N8nTe5sH
os-zhuang
marked this pull request as ready for review
July 19, 2026 16:05
This was referenced Jul 19, 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 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.
First implementation slice of #3265 (Phase 1 + the small Phase-2 core), following up on #3228/#1597. Companion cloud PR (token migration
aiStudio/aiSeat→ kebab) follows separately.Problem
The standalone serve path (
packages/cli/src/commands/serve.ts) and cloud'sobjectos-runtimecapability loader resolverequires: [...]through parallel registries that had already diverged: framework shipsai-studio(kebab, consistent withpinyin-search/hierarchy-security) while cloud usesaiStudio(camelCase). Both sides silently ignore unknown tokens, so the same declaration means different things per runtime and the mismatch never surfaces (declared ≠ enforced across the repo boundary).Change — spec becomes the single owner of the vocabulary
Canonical spelling: lower-case kebab-case (decision recorded on #3265).
packages/spec/src/kernel/platform-capabilities.ts(new):PLATFORM_CAPABILITY_TOKENS— the one vocabulary across both runtimes (tier-gated + service tokens + enterprise/cloud-runtime tokenshierarchy-security,ai-seat,governance).DEPRECATED_PLATFORM_CAPABILITY_ALIASES—aiStudio → ai-studio,aiSeat → ai-seat; honored for one deprecation cycle, no new aliases.canonicalizePlatformCapability/isKnownPlatformCapabilityhelpers. Exported from@objectstack/specroot and/kernelsubpath.defineStack: rewrites deprecated aliases to canonical at authoring time (fix the producer, Prime Directive Add comprehensive test suite for Zod schema validation #12) with a deprecation warning, and warns on unknown tokens. Warn-first by design — both runtimes previously ignored unknown tokens silently, so a hard reject could brick working stacks; the warn is intended to become an error once the vocabulary proves complete. Non-strict mode stays untouched (it skips all validation by contract).serve.ts: canonicalizes raw artifactrequiresthrough the same helper (covers artifacts compiled by an older spec), warns on declared-but-unknown tokens instead of silently ignoring them (closes the silent-typo hole the Make optional-plugin loading intent-driven: fail-fast on declared-but-missing, drop presence-based auto-enable #1597 fail-fast left: a token with no registry entry fell throughif (!spec) continue), and liftsCAPABILITY_PROVIDERS/CAPABILITY_TO_TIERto statics (pure-data move) so a drift test can assert every registry key stays inside the spec vocabulary.@objectstack/types: the missing-vs-crashed module classifier moves to a sharedisModuleNotFoundError(the perf(build): OS_SKIP_DTS gating + fix optional AI plugin "Cannot find package" skip #1595err.code-first fix);Serve.isModuleNotFoundErrordelegates. Cloud'sobjectos-runtimeadopts the shared classifier at its next framework pin bump — one owner, no more re-introducing the perf(build): OS_SKIP_DTS gating + fix optional AI plugin "Cannot find package" skip #1595 false-alarm class.Known vocabulary tokens without a local provider (
hierarchy-securityvia the enterprise plugin inplugins[];ai-seat/governancecloud-runtime-only) stay quiet in the serve resolver — only genuinely unknown tokens warn, so there are no false alarms for cross-runtime stacks.Verification
platform-capabilities.test.ts(13) +stack-requires.test.ts(5: alias rewrite + warn, canonical pass-through, unknown warn-not-throw, per-token dedupe, non-strict untouched) + existingstack.test.ts(89) — 102 passingserve-capability-vocabulary.test.tsdrift tests (5) +serve-optional-plugin-intent(14) +serve-defaults/serve-host-config/serve-log-level/serve-automation-summary— 40 passingtsc -p packages/cli/tsconfig.build.json --noEmitexit 0 · eslint clean🤖 Generated with Claude Code
Generated by Claude Code