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

os-zhuang · claude · os-zhuang · commit d231332302ce · 2026-07-27T19:12:30.000+08:00
Follow-through of #3605: kernel/feature.zod.ts (FeatureStrategy, FeatureFlagSchema, the FeatureFlag factory + types) had zero runtime consumers, and its only protocol home — the static ObjectStackCapabilities.system.features descriptor — was itself removed as dead in #3605. Not authorable (defineStack has no features key), not registered, not read by any engine. Live toggles are the feature_flags settings manifest (ADR-0007, OS_FEATURE_FLAGS_*) and the PUBLIC_AUTH_FEATURES registry for auth gates. - Delete feature.zod.ts + feature.test.ts; kernel/index export dropped with a removal note; manifest keys kernel/FeatureFlag + kernel/FeatureStrategy dropped; PROTOCOL_MAP row dropped; SKILL_MAP entry dropped (skill refs regenerated). - Docs: references/kernel/feature.mdx removed by regen; the hand-written quick-reference row removed; the platform skill's Feature Flags section rewritten to point at the settings surface; public-auth-features.ts "not to be confused" comment updated. - api-surface: 4 exports, pure removal. Changeset (minor) carries the removed-shape → settings-manifest migration table. Verified: 6663 spec tests green, tsc clean, check:docs/api-surface/ skill-refs/skill-docs/react-blocks/skill-examples all in sync, downstream-contract typecheck clean. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
diff --git a/.changeset/prune-orphan-featureflag-schema.md b/.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.
diff --git a/content/docs/getting-started/quick-reference.mdx b/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 |
 
diff --git a/content/docs/references/kernel/feature.mdx b/content/docs/references/kernel/feature.mdx
diff --git a/content/docs/references/kernel/index.mdx b/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" />
diff --git a/content/docs/references/kernel/meta.json b/content/docs/references/kernel/meta.json
@@ -27,7 +27,6 @@
     "context",
     "dev-plugin",
     "execution-context",
-    "feature",
     "metadata-customization",
     "metadata-loader",
     "metadata-persistence",
diff --git a/packages/spec/PROTOCOL_MAP.md b/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. |
diff --git a/packages/spec/api-surface.json b/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)",
diff --git a/packages/spec/json-schema.manifest.json b/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",
diff --git a/packages/spec/scripts/build-skill-references.ts b/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': [
diff --git a/packages/spec/src/kernel/feature.test.ts b/packages/spec/src/kernel/feature.test.ts
diff --git a/packages/spec/src/kernel/feature.zod.ts b/packages/spec/src/kernel/feature.zod.ts
diff --git a/packages/spec/src/kernel/index.ts b/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';
diff --git a/packages/spec/src/kernel/public-auth-features.ts b/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
diff --git a/skills/objectstack-platform/SKILL.md b/skills/objectstack-platform/SKILL.md
diff --git a/skills/objectstack-platform/references/_index.md b/skills/objectstack-platform/references/_index.md
