feat(spec)!: remove the orphaned FeatureFlagSchema module (kernel/feature.zod)

.changeset/prune-orphan-featureflag-schema.md

@@ -0,0 +1,26 @@
+---
+"@objectstack/spec": minor
+---
+
+feat(spec)!: remove the orphaned `FeatureFlagSchema` module (`@objectstack/spec/kernel` feature.zod)
+
+Follow-through of the capabilities-descriptor prune (#3605). `kernel/feature.zod.ts`
+(`FeatureStrategy`, `FeatureFlagSchema`, the `FeatureFlag` factory and its
+`FeatureFlag` / `FeatureFlagInput` types) had **zero runtime consumers**, and its
+only protocol home — the static `ObjectStackCapabilities.system.features`
+descriptor — was itself removed as dead in #3605 (no endpoint ever served it).
+The module was a compile-checkable shape with nowhere to go: not authorable
+(`defineStack` has no `features` key; strict parsing strips it), not registered,
+not read by any engine.
+
+**Migration — flags are runtime configuration, not authored metadata:**
+
+| Removed | Live replacement |
+| --- | --- |
+| `FeatureFlagSchema` / `FeatureFlag.create()` rollout documents (strategies, percentage/group conditions) | the `feature_flags` **settings manifest** (`@objectstack/service-settings`, ADR-0007) — org-tunable `ai_enabled` / `beta_*` toggles, env-overridable via `OS_FEATURE_FLAGS_*` |
+| deployment-level capability gating | `PUBLIC_AUTH_FEATURES` registry (`kernel/public-auth-features.ts`) + `requiresFeature` sugar on actions/params (unchanged, live) |
+| runtime capability discovery | `GET /api/v1/discovery` (dynamic, declared === enforced) |
+
+Docs regenerated (`references/kernel/feature.mdx` removed); the platform skill's
+Feature Flags section and the hand-written quick-reference row now point at the
+settings surface; `PROTOCOL_MAP.md` row dropped.

content/docs/getting-started/quick-reference.mdx

@@ -74,7 +74,6 @@ Plugin architecture, manifests, and kernel runtime.
 | **[Service Registry](/docs/references/kernel/service-registry)** | `service-registry.zod.ts` | ServiceRegistryConfig, ServiceMetadata | Service discovery |
 | **[Startup Orchestrator](/docs/references/kernel/startup-orchestrator)** | `startup-orchestrator.zod.ts` | StartupOptions, StartupOrchestrationResult | System startup |
 | **[Events](/docs/kernel/events)** | `events.zod.ts` | Event, EventBusConfig | System event bus |
-| **[Feature](/docs/references/kernel/feature)** | `feature.zod.ts` | FeatureFlag | Feature flags |
 | **[Metadata Loader](/docs/references/kernel/metadata-loader)** | `metadata-loader.zod.ts` | MetadataLoaderContract | Metadata loading |
 | **[Package Registry](/docs/references/kernel/package-registry)** | `package-registry.zod.ts` | InstalledPackage, InstallPackageRequest | Package resolution |
 

content/docs/references/kernel/index.mdx

@@ -12,7 +12,6 @@ This section contains all protocol schemas for the kernel layer of ObjectStack.
   <Card href="/docs/references/kernel/dependency-resolution" title="Dependency Resolution" description="Source: packages/spec/src/kernel/dependency-resolution.zod.ts" />
   <Card href="/docs/references/kernel/dev-plugin" title="Dev Plugin" description="Source: packages/spec/src/kernel/dev-plugin.zod.ts" />
   <Card href="/docs/references/kernel/execution-context" title="Execution Context" description="Source: packages/spec/src/kernel/execution-context.zod.ts" />
-  <Card href="/docs/references/kernel/feature" title="Feature" description="Source: packages/spec/src/kernel/feature.zod.ts" />
   <Card href="/docs/references/kernel/manifest" title="Manifest" description="Source: packages/spec/src/kernel/manifest.zod.ts" />
   <Card href="/docs/references/kernel/metadata-customization" title="Metadata Customization" description="Source: packages/spec/src/kernel/metadata-customization.zod.ts" />
   <Card href="/docs/references/kernel/metadata-loader" title="Metadata Loader" description="Source: packages/spec/src/kernel/metadata-loader.zod.ts" />

content/docs/references/kernel/meta.json

@@ -27,7 +27,6 @@
     "context",
     "dev-plugin",
     "execution-context",
-    "feature",
     "metadata-customization",
     "metadata-loader",
     "metadata-persistence",

packages/qa/dogfood/test/expression-conformance.ledger.ts

@@ -80,13 +80,15 @@ export const EXPRESSION_SURFACE: ExprSurface[] = [
   },
   {
     id: 'cel-formula',
-    summary: 'computed / formula field + mapping / feature expressions',
+    summary: 'computed / formula field + mapping expressions',
     dialect: 'cel', mode: 'interpret', state: 'enforced', failPolicy: 'fail-soft-log',
     enforcement: '@objectstack/formula celEngine (interpret)',
+    // kernel/feature.zod.ts:expression was covered here until the orphaned
+    // FeatureFlagSchema module was removed (zero runtime consumers once its
+    // capabilities-descriptor home went, #3605).
     covers: [
       'data/field.zod.ts:expression',
       'shared/mapping.zod.ts:expression',
-      'kernel/feature.zod.ts:expression',
     ],
   },
   {

packages/spec/PROTOCOL_MAP.md

@@ -192,7 +192,6 @@ This document serves as the **Grand Map** of the ObjectStack specification. It l
 | [`manifest.zod.ts`](src/kernel/manifest.zod.ts) | ⭐ | **Manifest**. The `package.json` equivalent for the stack. |
 | [`context.zod.ts`](src/kernel/context.zod.ts) | | **Execution Context**. Request-scoped context (user, transaction). |
 | [`events.zod.ts`](src/kernel/events.zod.ts) | | **Kernel Events**. System lifecycle events. |
-| [`feature.zod.ts`](src/kernel/feature.zod.ts) | | **Feature Flags**. Toggleable system features. |
 | [`service-registry.zod.ts`](src/kernel/service-registry.zod.ts) | | **Service Registry**. Internal dependency injection. |
 | [`metadata-loader.zod.ts`](src/kernel/metadata-loader.zod.ts) | | **Loader**. Logic for loading definitions from disk/DB. |
 | [`plugin-loading.zod.ts`](src/kernel/plugin-loading.zod.ts) | ⭐ | **Plugin Loading**. Loading strategies, production-safe hot reload (`environment`, `productionSafety`), full plugin sandboxing (`scope`, `ipc`), code splitting, caching, and performance monitoring. |

packages/spec/api-surface.json

@@ -1419,10 +1419,6 @@
     "ExecutionContextSchema (const)",
     "ExtensionPoint (type)",
     "ExtensionPointSchema (const)",
-    "FeatureFlag (type)",
-    "FeatureFlagInput (type)",
-    "FeatureFlagSchema (const)",
-    "FeatureStrategy (const)",
     "FieldChange (type)",
     "FieldChangeSchema (const)",
     "GetPackageRequest (type)",

packages/spec/json-schema.manifest.json

@@ -979,8 +979,6 @@
     "kernel/EventWebhookConfig",
     "kernel/ExecutionContext",
     "kernel/ExtensionPoint",
-    "kernel/FeatureFlag",
-    "kernel/FeatureStrategy",
     "kernel/FieldChange",
     "kernel/GetPackageRequest",
     "kernel/GetPackageResponse",

packages/spec/scripts/build-skill-references.ts

@@ -113,7 +113,6 @@ const SKILL_MAP: Record<string, string[]> = {
     'kernel/plugin-lifecycle-events.zod.ts',
     'kernel/plugin-capability.zod.ts',
     'kernel/plugin-loading.zod.ts',
-    'kernel/feature.zod.ts',
     'kernel/metadata-plugin.zod.ts',
   ],
   'objectstack-i18n': [

packages/spec/src/kernel/index.ts

@@ -6,7 +6,12 @@ export * from './context.zod';
 export * from './dependency-resolution.zod';
 export * from './dev-plugin.zod';
 export * from './events.zod';
-export * from './feature.zod';
+// feature.zod (FeatureFlagSchema / FeatureStrategy / FeatureFlag factory) was
+// REMOVED per ADR-0056 D8: zero runtime consumers, and its only protocol home —
+// the static ObjectStackCapabilities.system.features descriptor — was itself
+// removed as dead (#3605). Live toggles are the `feature_flags` settings
+// manifest (ADR-0007, env-overridable via OS_FEATURE_FLAGS_*) and the
+// PUBLIC_AUTH_FEATURES registry (public-auth-features.ts) for auth gates.
 export * from './manifest.zod';
 export * from './metadata-customization.zod';
 export * from './namespace-prefix';

packages/spec/src/kernel/public-auth-features.ts

@@ -18,10 +18,12 @@ import type { z } from 'zod';
  * where each flag's consumption surface, default semantics, and gated spec
  * inputs (or exemption rationale) are recorded and CI-enforced.
  *
- * NOT to be confused with `kernel/feature.zod.ts` (`FeatureFlagSchema`) —
- * that schema models tenant-scoped runtime rollout toggles (strategies,
- * expiry, conditions). This registry classifies the fixed, deployment-level
- * capability flags that plugin-auth advertises to anonymous clients.
+ * NOT to be confused with runtime rollout toggles — those live on the
+ * `feature_flags` settings manifest (ADR-0007), not in the spec (the former
+ * `kernel/feature.zod.ts` `FeatureFlagSchema` was removed as an orphan: zero
+ * runtime consumers once its dead capabilities-descriptor home went, #3605).
+ * This registry classifies the fixed, deployment-level capability flags that
+ * plugin-auth advertises to anonymous clients.
  *
  * Consumers:
  * - `ui/action.zod.ts` — `requiresFeature` sugar on actions/params is lowered