feat(spec)!: remove the dead static capabilities-descriptor cluster (#3605)

* feat(spec)!: remove the dead static capabilities-descriptor cluster (#1878 family)

The "RUNTIME CAPABILITIES PROTOCOL" tail of stack.zod.ts (ObjectQL/ObjectUI/
Kernel/ObjectStack CapabilitiesSchema + the deprecated ObjectOS alias + all
five types, 214 lines) had zero consumers repo-wide: never authorable
(defineStack has no such key), never registered, never fed any endpoint.
Worse, the fixed-boolean self-portrait lied — fieldLevelSecurity/
rowLevelSecurity/auditLogging/backgroundJobs all default(false) while live
and enforced, and odataApi never existed. Real capability discovery is
dynamic: GET /api/v1/discovery (declared===enforced, #3298) + the
/.well-known WellKnownCapabilitiesSchema contract + driver-level
Driver/DatasourceCapabilities.

- Delete the cluster + the four dead stack.test.ts describe blocks + the
  src/index.ts explicit re-exports + two now-orphan imports
  (ClusterCapabilityConfigSchema/FeatureFlagSchema — both modules stay,
  ApiEndpointSchema remains consumed by the stack `apis` key).
- api-surface: 10 exports, pure removal. No manifest keys existed; no doc
  page was generated for them.
- Changeset (minor) carries the dead-boolean → live-discovery migration
  table. objectui re-exports dropped in the companion PR.

Verified: 6716 spec tests green, tsc clean, check:docs/api-surface/
skill-refs/react-blocks in sync, downstream-contract typecheck clean.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* docs(skills): drop the removed capabilities-descriptor reference from the feature-flags example

The platform skill's os:check example imported ObjectStackCapabilities to
type a system.features array — the descriptor this PR removes (and which no
endpoint ever served). The example now shows only the live part
(FeatureFlag.create compile-checked values) and the prose points capability
discovery at GET /api/v1/discovery. Caught by check:skill-examples — my
repo-wide grep excluded *.md and missed TS blocks inside skill docs.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

---------

Co-authored-by: Jack Zhuang <277994282+os-zhuang@users.noreply.github.com>
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>

Author: os-zhuang

.changeset/prune-dead-capabilities-descriptor.md

@@ -0,0 +1,32 @@
+---
+"@objectstack/spec": minor
+---
+
+feat(spec)!: remove the dead static capabilities-descriptor cluster (`ObjectQL`/`ObjectUI`/`Kernel`/`ObjectStack`/`ObjectOS CapabilitiesSchema`) (#1878 family)
+
+The "RUNTIME CAPABILITIES PROTOCOL" tail of `stack.zod.ts` — `ObjectQLCapabilitiesSchema`,
+`ObjectUICapabilitiesSchema`, `KernelCapabilitiesSchema`, `ObjectStackCapabilitiesSchema`,
+the deprecated `ObjectOSCapabilitiesSchema` alias, and all five inferred types — is
+removed. Verified zero consumers repo-wide (framework, objectui apart from bare
+re-exports, cloud, downstream-contract): it was never authorable (`defineStack` has
+no such key), never registered, and never fed any endpoint.
+
+Worse than dead, it **lied**: the fixed-boolean self-portrait defaulted
+`fieldLevelSecurity` / `rowLevelSecurity` / `auditLogging` / `backgroundJobs` to
+`false` while every one of those is live and enforced on the platform, and
+advertised `odataApi` which has never existed. An AI reading the schema would
+build a systematically wrong model of the platform.
+
+**Migration — runtime capability discovery is dynamic, not a static schema:**
+
+| Removed | Live replacement |
+| --- | --- |
+| `KernelCapabilitiesSchema` booleans (`restApi`/`websockets`/`auditLogging`/…) | `GET /api/v1/discovery` — dynamic `capabilities` record with **declared === enforced** discipline (#3298: a capability is advertised only when the route is actually mounted AND the engine supports it) |
+| `WellKnown`-style backend feature probes | `WellKnownCapabilitiesSchema` (`@objectstack/spec/api` discovery contract: `comments`/`automation`/`cron`/`search`/…) |
+| `ObjectQLCapabilitiesSchema` driver/query booleans | driver-level `DriverCapabilities` / `DatasourceCapabilities` (`@objectstack/spec/data`) — per-connection, resolved at runtime |
+| `ObjectStackCapabilitiesSchema` layer roll-up + `ObjectOS*` aliases | none — no replacement import |
+
+The objectui `@object-ui/types` re-exports of these symbols are dropped in the
+companion objectui change. `ClusterCapabilityConfigSchema` / `FeatureFlagSchema` /
+`ApiEndpointSchema` (referenced by the dead cluster) are untouched — they live in
+their own modules and `ApiEndpointSchema` remains consumed by the stack `apis` key.

packages/spec/api-surface.json

@@ -47,8 +47,6 @@
     "ExpressionSchema (const)",
     "F (const)",
     "GUEST_POSITION (const)",
-    "KernelCapabilities (type)",
-    "KernelCapabilitiesSchema (const)",
     "MAP_SUPPORTED_FIELDS (const)",
     "METADATA_ALIASES (const)",
     "MIGRATIONS_BY_MAJOR (const)",
@@ -67,19 +65,11 @@
     "ORGANIZATION_ADMIN (const)",
     "ORGANIZATION_ADMIN_GRANTS (const)",
     "ORGANIZATION_ADMIN_NO_BYPASS (const)",
-    "ObjectOSCapabilities (type)",
-    "ObjectOSCapabilitiesSchema (const)",
-    "ObjectQLCapabilities (type)",
-    "ObjectQLCapabilitiesSchema (const)",
     "ObjectStack (type)",
-    "ObjectStackCapabilities (type)",
-    "ObjectStackCapabilitiesSchema (const)",
     "ObjectStackDefinition (type)",
     "ObjectStackDefinitionInput (type)",
     "ObjectStackDefinitionSchema (const)",
     "ObjectStackSchema (const)",
-    "ObjectUICapabilities (type)",
-    "ObjectUICapabilitiesSchema (const)",
     "P (const)",
     "PLATFORM_CAPABILITY_PROVIDERS (const)",
     "PLATFORM_CAPABILITY_TOKENS (const)",

packages/spec/src/index.ts

@@ -59,12 +59,7 @@ export {
   ComposeStacksOptionsSchema,
   ConflictStrategySchema,
   ObjectStackDefinitionSchema,
-  ObjectStackSchema,
-  ObjectStackCapabilitiesSchema,
-  ObjectQLCapabilitiesSchema,
-  ObjectUICapabilitiesSchema,
-  KernelCapabilitiesSchema,
-  ObjectOSCapabilitiesSchema
+  ObjectStackSchema
 } from './stack.zod';
 
 export type { DefineStackOptions, ComposeStacksOptions, ConflictStrategy, ObjectStackDefinitionInput } from './stack.zod';