feat(spec)!: remove deprecated aiStudio/aiSeat capability aliases (#3308)

The one-cycle deprecation window opened in #3265 is over. The legacy
camelCase `requires` spellings `aiStudio`/`aiSeat` are no longer
canonicalized to `ai-studio`/`ai-seat` — they are now plain unknown
tokens, rejected by defineStack like any other typo.

- spec: drop DEPRECATED_PLATFORM_CAPABILITY_ALIASES and
  canonicalizePlatformCapability exports; isKnownPlatformCapability
  no longer canonicalizes.
- spec: defineStack no longer rewrites aliases (canonicalizeStackRequires
  removed); validateKnownCapabilities rejects the legacy spellings.
- cli: serve resolver no longer canonicalizes raw-artifact requires.
- Regenerate api-surface snapshot (4 export deletions).

BREAKING shipped as minor per the launch-window convention. Migration:
use the canonical kebab-case tokens ai-studio / ai-seat. First-party
configs were migrated in cloud #862/#863; cloud's objectos-runtime
(pinned to an older framework) follows on its next .framework-sha bump.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01TjHfkKmEvgk8v7N8nTe5sH

Author: claude

.changeset/remove-capability-aliases-3308.md

@@ -0,0 +1,22 @@
+---
+"@objectstack/spec": minor
+"@objectstack/cli": minor
+---
+
+feat(spec)!: remove deprecated `aiStudio`/`aiSeat` capability aliases (#3308)
+
+**BREAKING** (shipped as minor per the launch-window convention). The one-cycle
+deprecation window from #3265 is over: the legacy camelCase `requires` spellings
+`aiStudio`/`aiSeat` are no longer canonicalized to `ai-studio`/`ai-seat` — they
+are now plain unknown tokens, rejected by `defineStack` like any other typo.
+
+- Removed exports `DEPRECATED_PLATFORM_CAPABILITY_ALIASES` and
+  `canonicalizePlatformCapability` from `@objectstack/spec`; `isKnownPlatformCapability`
+  no longer canonicalizes.
+- `defineStack` no longer rewrites aliases (the `canonicalizeStackRequires` pass
+  is gone); the serve resolver no longer canonicalizes raw-artifact `requires`.
+
+Migration: use the canonical kebab-case tokens `ai-studio` / `ai-seat`. All
+first-party configs were migrated in #862/#863; only stacks still carrying the
+legacy spelling are affected. Cloud's `objectos-runtime` (pinned to an older
+framework) follows on its next `.framework-sha` bump.

packages/cli/src/commands/serve.ts

@@ -10,7 +10,7 @@ import { loadConfig, BUNDLE_REQUIRE_EXTERNALS } from '../utils/config.js';
 import { isHostConfig, shouldBootWithLibrary } from '../utils/plugin-detection.js';
 import { resolveDriverType, createStorageDriver, UnsupportedDriverError } from '../utils/storage-driver.js';
 import { readEnvWithDeprecation, resolveMultiOrgEnabled, resolveAllowDegradedTenancy, isMcpServerEnabled, resolveSearchPinyinEnabled, isModuleNotFoundError } from '@objectstack/types';
-import { PLATFORM_CAPABILITY_TOKENS, canonicalizePlatformCapability } from '@objectstack/spec/kernel';
+import { PLATFORM_CAPABILITY_TOKENS } from '@objectstack/spec/kernel';
 import { resolveObjectStackHome } from '@objectstack/runtime';
 import { LOG_LEVELS, resolveLogLevel, readLogLevelEnv } from '../utils/log-level.js';
 import {
@@ -695,22 +695,14 @@ export default class Serve extends Command {
       // instance wins over the auto-loader).
       const presetName = flags.preset ?? (isDev ? 'default' : 'default');
       const presetTiers = Serve.TIER_PRESETS[presetName] ?? Serve.TIER_PRESETS.default;
+      // Dedupe `requires` (Set keeps first-seen order). The deprecated
+      // `aiStudio`/`aiSeat` alias canonicalization was removed in framework#3308
+      // — legacy spellings are now unknown tokens (warned below, rejected at
+      // authoring by defineStack).
       const rawRequires: string[] = Array.isArray((config as any).requires)
         ? (config as any).requires.filter((c: unknown) => typeof c === 'string')
         : [];
-      // Canonicalize deprecated capability spellings (aiStudio → ai-studio, …)
-      // so artifacts compiled by an older spec keep booting; `defineStack`
-      // already rewrites + warns on the source path, this covers raw artifact
-      // JSON (framework#3265). Dedupe after mapping (Set keeps first-seen order).
-      const requires: string[] = [...new Set(rawRequires.map((c: string) => {
-        const canonical = canonicalizePlatformCapability(c);
-        if (canonical !== c) {
-          console.warn(chalk.yellow(
-            `  ⚠ requires: '${c}' is a deprecated spelling — use '${canonical}' (framework#3265)`,
-          ));
-        }
-        return canonical;
-      }))];
+      const requires: string[] = [...new Set(rawRequires)];
       // Snapshot the app's EXPLICIT capability declarations BEFORE the platform
       // appends its own convenience defaults (auth→email, mcp, pinyin-search,
       // ALWAYS_ON_CAPABILITIES, queue/job). Only these explicit declarations carry

packages/cli/test/serve-capability-vocabulary.test.ts

@@ -1,8 +1,5 @@
 import { describe, expect, it } from 'vitest';
-import {
-  PLATFORM_CAPABILITY_TOKENS,
-  DEPRECATED_PLATFORM_CAPABILITY_ALIASES,
-} from '@objectstack/spec/kernel';
+import { PLATFORM_CAPABILITY_TOKENS } from '@objectstack/spec/kernel';
 import Serve from '../src/commands/serve.js';
 
 // framework#3265 — drift guard: the serve path's provider registries must stay
@@ -22,8 +19,8 @@ describe('serve capability registries vs spec vocabulary (#3265)', () => {
     }
   });
 
-  it('registries use only canonical spellings — never deprecated aliases', () => {
-    const legacy = Object.keys(DEPRECATED_PLATFORM_CAPABILITY_ALIASES);
+  it('registries use only canonical spellings — never the removed camelCase aliases (#3308)', () => {
+    const legacy = ['aiStudio', 'aiSeat'];
     for (const token of [...Object.keys(Serve.CAPABILITY_PROVIDERS), ...Object.keys(Serve.CAPABILITY_TO_TIER)]) {
       expect(legacy).not.toContain(token);
     }

packages/spec/api-surface.json

@@ -26,7 +26,6 @@
     "ConversionFixture (interface)",
     "ConversionNotice (interface)",
     "CronExpressionInputSchema (const)",
-    "DEPRECATED_PLATFORM_CAPABILITY_ALIASES (const)",
     "DatasourceMappingRule (type)",
     "DatasourceMappingRuleSchema (const)",
     "DefineStackOptions (interface)",
@@ -102,7 +101,6 @@
     "applyConversions (function)",
     "applyConversionsToFlow (function)",
     "applyMetaMigrations (function)",
-    "canonicalizePlatformCapability (function)",
     "cel (function)",
     "collectConversionNotices (function)",
     "composeMigrationChain (function)",
@@ -1294,7 +1292,6 @@
     "CustomizationPolicy (type)",
     "CustomizationPolicySchema (const)",
     "DEFAULT_METADATA_TYPE_REGISTRY (const)",
-    "DEPRECATED_PLATFORM_CAPABILITY_ALIASES (const)",
     "DeadLetterQueueEntry (type)",
     "DeadLetterQueueEntrySchema (const)",
     "DependencyConflict (type)",
@@ -1750,7 +1747,6 @@
     "VersionConstraint (type)",
     "VersionConstraintSchema (const)",
     "VulnerabilitySeverity (type)",
-    "canonicalizePlatformCapability (function)",
     "deriveNamespaceFromPackageId (function)",
     "evaluateLockForDelete (function)",
     "evaluateLockForWrite (function)",

packages/spec/src/index.ts

@@ -123,8 +123,6 @@ export { type PluginContext } from './kernel/plugin.zod';
 // Platform SERVICE capability vocabulary for `requires: [...]` (framework#3265).
 export {
   PLATFORM_CAPABILITY_TOKENS,
-  DEPRECATED_PLATFORM_CAPABILITY_ALIASES,
-  canonicalizePlatformCapability,
   isKnownPlatformCapability,
 } from './kernel/platform-capabilities';
 

packages/spec/src/kernel/platform-capabilities.test.ts

@@ -1,13 +1,12 @@
 import { describe, expect, it } from 'vitest';
 import {
   PLATFORM_CAPABILITY_TOKENS,
-  DEPRECATED_PLATFORM_CAPABILITY_ALIASES,
-  canonicalizePlatformCapability,
   isKnownPlatformCapability,
 } from './platform-capabilities';
 
 // framework#3265 — one capability vocabulary across the standalone serve path
-// and cloud's objectos-runtime loader, canonical spelling kebab-case.
+// and cloud's objectos-runtime loader, canonical spelling kebab-case. The
+// deprecated `aiStudio`/`aiSeat` aliases were removed in #3308.
 
 describe('PLATFORM_CAPABILITY_TOKENS', () => {
   it('is frozen and duplicate-free', () => {
@@ -27,37 +26,23 @@ describe('PLATFORM_CAPABILITY_TOKENS', () => {
     }
   });
 
-  it('contains no deprecated spellings', () => {
-    for (const legacy of Object.keys(DEPRECATED_PLATFORM_CAPABILITY_ALIASES)) {
+  it('contains no camelCase legacy spellings (aliases removed, #3308)', () => {
+    for (const legacy of ['aiStudio', 'aiSeat']) {
       expect(PLATFORM_CAPABILITY_TOKENS).not.toContain(legacy);
     }
   });
 });
 
-describe('DEPRECATED_PLATFORM_CAPABILITY_ALIASES / canonicalizePlatformCapability', () => {
-  it('maps every alias onto a token that exists in the vocabulary', () => {
-    for (const canonical of Object.values(DEPRECATED_PLATFORM_CAPABILITY_ALIASES)) {
-      expect(PLATFORM_CAPABILITY_TOKENS).toContain(canonical);
-    }
-  });
-
-  it('canonicalizes the legacy cloud spellings', () => {
-    expect(canonicalizePlatformCapability('aiStudio')).toBe('ai-studio');
-    expect(canonicalizePlatformCapability('aiSeat')).toBe('ai-seat');
-  });
-
-  it('is identity for canonical and unknown tokens', () => {
-    expect(canonicalizePlatformCapability('ai-studio')).toBe('ai-studio');
-    expect(canonicalizePlatformCapability('automation')).toBe('automation');
-    expect(canonicalizePlatformCapability('not-a-capability')).toBe('not-a-capability');
-  });
-});
-
 describe('isKnownPlatformCapability', () => {
-  it('accepts canonical tokens and deprecated aliases, rejects unknowns', () => {
+  it('accepts canonical tokens verbatim', () => {
     expect(isKnownPlatformCapability('ai-studio')).toBe(true);
-    expect(isKnownPlatformCapability('aiStudio')).toBe(true);
+    expect(isKnownPlatformCapability('ai-seat')).toBe(true);
     expect(isKnownPlatformCapability('governance')).toBe(true);
+  });
+
+  it('rejects the removed camelCase aliases and typos (no canonicalization, #3308)', () => {
+    expect(isKnownPlatformCapability('aiStudio')).toBe(false);
+    expect(isKnownPlatformCapability('aiSeat')).toBe(false);
     expect(isKnownPlatformCapability('automations')).toBe(false);
   });
 });

packages/spec/src/kernel/platform-capabilities.ts

@@ -12,10 +12,10 @@
  * ADR-0066 authorization capabilities declared in `capabilities: [...]`.)
  *
  * Canonical spelling is lower-case kebab-case (`ai-studio`, `pinyin-search`,
- * `hierarchy-security`). Legacy camelCase spellings that shipped in cloud
- * configs are mapped through {@link DEPRECATED_PLATFORM_CAPABILITY_ALIASES}
- * for one deprecation cycle — `defineStack` normalizes them with a warning at
- * authoring time, and runtimes canonicalize raw artifact input the same way.
+ * `hierarchy-security`). The legacy camelCase spellings (`aiStudio` / `aiSeat`)
+ * that shipped transitionally were honored as deprecated aliases for one cycle
+ * (framework#3265) and have been REMOVED (framework#3308) — they are now plain
+ * unknown tokens, rejected by `defineStack` like any other typo.
  *
  * Growing the platform: when a new `requires`-resolvable service ships, add
  * its token HERE as well as to the runtime's provider registry — the CLI's
@@ -66,30 +66,10 @@ export const PLATFORM_CAPABILITY_TOKENS: readonly string[] = Object.freeze([
 ]);
 
 /**
- * Deprecated `requires` spellings → canonical token. One deprecation cycle:
- * authoring (`defineStack`) rewrites these with a warning; runtimes accept
- * them via {@link canonicalizePlatformCapability} so artifacts built by an
- * older spec keep booting. Do not add new aliases — new tokens ship in
- * canonical kebab-case only.
- */
-export const DEPRECATED_PLATFORM_CAPABILITY_ALIASES: Readonly<Record<string, string>> =
-  Object.freeze({
-    aiStudio: 'ai-studio',
-    aiSeat: 'ai-seat',
-  });
-
-/**
- * Map a `requires` token to its canonical spelling (identity for tokens that
- * are already canonical or unknown).
- */
-export function canonicalizePlatformCapability(token: string): string {
-  return DEPRECATED_PLATFORM_CAPABILITY_ALIASES[token] ?? token;
-}
-
-/**
- * True when the token (after alias canonicalization) is part of the platform
- * capability vocabulary.
+ * True when the token is part of the platform capability vocabulary. There is
+ * no longer any alias canonicalization (framework#3308) — a token is known iff
+ * it appears verbatim in {@link PLATFORM_CAPABILITY_TOKENS}.
  */
 export function isKnownPlatformCapability(token: string): boolean {
-  return PLATFORM_CAPABILITY_TOKENS.includes(canonicalizePlatformCapability(token));
+  return PLATFORM_CAPABILITY_TOKENS.includes(token);
 }

packages/spec/src/stack-requires.test.ts

@@ -1,30 +1,16 @@
-import { afterEach, describe, expect, it, vi } from 'vitest';
+import { describe, expect, it } from 'vitest';
 import { defineStack } from './stack.zod';
 
-// framework#3265 — defineStack canonicalizes deprecated `requires` spellings at
-// the PRODUCER (authoring time) and validates tokens against the platform
-// capability vocabulary: deprecated aliases are rewritten with a warning, an
-// unknown token is a hard error (no runtime provides it → declared ≠ enforced).
+// framework#3265/#3308 — defineStack validates `requires` tokens against the
+// platform capability vocabulary at the PRODUCER (authoring time): an unknown
+// token is a hard error (no runtime provides it → declared ≠ enforced). The
+// deprecated `aiStudio`/`aiSeat` aliases were removed in #3308, so those now
+// reject like any other typo — there is no canonicalization step left.
 
-afterEach(() => {
-  vi.restoreAllMocks();
-});
-
-describe('defineStack requires canonicalization (#3265)', () => {
-  it('rewrites deprecated aliases to canonical kebab tokens with a warning', () => {
-    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
-    const stack = defineStack({ requires: ['ai', 'aiStudio', 'automation'] });
-    expect(stack.requires).toEqual(['ai', 'ai-studio', 'automation']);
-    expect(warn).toHaveBeenCalledTimes(1);
-    expect(warn.mock.calls[0][0]).toContain("'aiStudio' is a deprecated spelling");
-    expect(warn.mock.calls[0][0]).toContain("'ai-studio'");
-  });
-
-  it('canonical declarations pass through untouched and warning-free', () => {
-    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
-    const stack = defineStack({ requires: ['ai', 'ai-studio', 'hierarchy-security', 'governance'] });
-    expect(stack.requires).toEqual(['ai', 'ai-studio', 'hierarchy-security', 'governance']);
-    expect(warn).not.toHaveBeenCalled();
+describe('defineStack requires validation (#3265/#3308)', () => {
+  it('canonical declarations pass through untouched', () => {
+    const stack = defineStack({ requires: ['ai', 'ai-studio', 'ai-seat', 'hierarchy-security', 'governance'] });
+    expect(stack.requires).toEqual(['ai', 'ai-studio', 'ai-seat', 'hierarchy-security', 'governance']);
   });
 
   it('THROWS on an unknown token (a typo no runtime provides), naming it', () => {
@@ -33,6 +19,15 @@ describe('defineStack requires canonicalization (#3265)', () => {
     );
   });
 
+  it('the removed camelCase aliases now REJECT like any other unknown token (#3308)', () => {
+    expect(() => defineStack({ requires: ['aiStudio'] })).toThrowError(
+      /'aiStudio' is not a known platform capability/,
+    );
+    expect(() => defineStack({ requires: ['aiSeat'] })).toThrowError(
+      /'aiSeat' is not a known platform capability/,
+    );
+  });
+
   it('reports every distinct unknown token but not known ones', () => {
     let msg = '';
     try {
@@ -46,23 +41,8 @@ describe('defineStack requires canonicalization (#3265)', () => {
     expect(msg).not.toContain("'ai' is not"); // known token isn't flagged
   });
 
-  it('a deprecated alias is NOT treated as unknown — it canonicalizes and passes', () => {
-    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
-    expect(() => defineStack({ requires: ['aiStudio', 'ai-seat'] })).not.toThrow();
-    // aiStudio → ai-studio (warned); ai-seat is already canonical
-    expect(warn).toHaveBeenCalledTimes(1);
-  });
-
-  it('warns once per distinct token, not once per occurrence', () => {
-    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
-    defineStack({ requires: ['aiStudio', 'aiStudio'] });
-    expect(warn).toHaveBeenCalledTimes(1);
-  });
-
-  it('non-strict mode skips canonicalization and warnings by contract', () => {
-    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+  it('non-strict mode skips validation by contract (unknown token passes through)', () => {
     const stack = defineStack({ requires: ['aiStudio'] }, { strict: false });
     expect(stack.requires).toEqual(['aiStudio']);
-    expect(warn).not.toHaveBeenCalled();
   });
 });