objectstack-ai · os-litant · Aug 26, 2026 · Aug 25, 2026 · Aug 25, 2026 · Aug 25, 2026
diff --git a/.changeset/advanced-plugin-lifecycle-config-retired.md b/.changeset/advanced-plugin-lifecycle-config-retired.md
@@ -0,0 +1,64 @@
+---
+"@objectstack/spec": minor
+---
+
+feat(spec): retire the authorable `AdvancedPluginLifecycleConfig` surface; the lifecycle classes stay as a host-driven library (#11825, ADR-0049)
+
+<!-- adr-0087: registered advanced-plugin-lifecycle-config-retired -->
+
+**BREAKING** export removal, landing after the v17.0.0 cut (the lockstep
+launch-window convention ships it as `minor`; the prescription is registered
+under protocol major 18 — `RETIRED_DEFS_BY_MAJOR[18]` + the D3 semantic entry
+`advanced-plugin-lifecycle-config-retired` — where `os migrate meta` users
+will look).
+
+`AdvancedPluginLifecycleConfigSchema` aggregated six lifecycle config groups —
+`health`, `hotReload`, `degradation`, `updates`, `resources`,
+`observability` — and NO group had a runtime reader, re-measured per group at
+the retirement's base commit with positive controls: the kernel never
+constructs `PluginHealthMonitor` or `HotReloadManager` (only their own unit
+tests and `core/examples/phase2-integration.ts` do, passing config DIRECTLY
+to the classes, never through this container); the `degradation` / `updates`
+/ `resources` / `observability` keys have no implementation body at all; and
+no manifest, stack collection or metadata-type binding ever embedded the
+container, so no authored document could carry it. An author declaring
+`health: {...}` or `rollback: { automatic: true }` got a clean parse and
+NOTHING — the #3950 shape at container scale, sharpened by production-safety
+vocabulary (auto-restart, zero-downtime rolling updates, automatic rollback)
+an AI author reads as proof the capability exists.
+
+FROM → TO:
+
+- `AdvancedPluginLifecycleConfigSchema` / `AdvancedPluginLifecycleConfig` /
+ `AdvancedPluginLifecycleConfigParsed` → *(removed — no replacement
+ container)*. The supported lifecycle surface is the host-driven library in
+ `@objectstack/core`: construct `PluginHealthMonitor` and pass a
+ `PluginHealthCheck`, construct `HotReloadManager` and pass a
+ `HotReloadConfig` (the `content/docs/protocol/kernel/lifecycle.mdx`
+ examples, #11811, are the supported usage).
+- `GracefulDegradationSchema` / `GracefulDegradation` /
+ `GracefulDegradationParsed` and `PluginUpdateStrategySchema` /
+ `PluginUpdateStrategy` / `PluginUpdateStrategyParsed` → *(removed)* — value
+ schemas whose only consumer was the retired container; no implementation
+ body exists for any of their keys. They return only via the ENFORCE route
+ of ADR-0049 through a new ADR — the executor first, the vocabulary second.
+
+One-line fix: delete the config object (it configured nothing); if you drive
+the library classes yourself, keep passing `PluginHealthCheck` /
+`HotReloadConfig` directly — those vocabularies survive unchanged.
+
+The retirement kit:
+
+- whole-def deletion (route 3 — no carrier key, no authored document, so no
+ tombstone and no D2 conversion; the #8715 `identity/ApiKey` shape):
+ `kernel/AdvancedPluginLifecycleConfig`, `kernel/GracefulDegradation`,
+ `kernel/PluginUpdateStrategy` in `RETIRED_DEFS_BY_MAJOR[18]`, plus the D3
+ semantic entry `advanced-plugin-lifecycle-config-retired`
+- pin test (`kernel/plugin-lifecycle-advanced-retirement.test.ts`): zero
+ holders for all 9 retired names on every public entry, survivors pinned
+ (`PluginHealthStatus` / `PluginHealthCheck` / `PluginHealthReport`,
+ `HotReloadConfig` + `DistributedStateConfig`, `PluginStateSnapshot` — the
+ kept host-driven library vocabularies)
+- zero authored occurrences in objectstack or objectui (measured at
+ dispatch, re-verified per group), so no in-repo source changes ride along;
+ `@objectstack/core` classes and tests are untouched and stay green
diff --git a/content/docs/getting-started/quick-reference.mdx b/content/docs/getting-started/quick-reference.mdx
@@ -71,7 +71,7 @@ Plugin architecture, manifests, and kernel runtime.
 | **[Context](/docs/references/kernel/context)** | `context.zod.ts` | KernelContext | Runtime execution context |
 | **[Plugin](/docs/references/kernel/plugin)** | `plugin.zod.ts` | Plugin, PluginLifecycle | Plugin system interface |
 | **[Plugin Capability](/docs/references/kernel/plugin-capability)** | `plugin-capability.zod.ts` | PluginCapability | Plugin capability declarations |
-| **[Plugin Lifecycle Advanced](/docs/references/kernel/plugin-lifecycle-advanced)** | `plugin-lifecycle-advanced.zod.ts` | AdvancedPluginLifecycleConfig, PluginHealthCheck | Advanced lifecycle hooks |
+| **[Plugin Lifecycle Advanced](/docs/references/kernel/plugin-lifecycle-advanced)** | `plugin-lifecycle-advanced.zod.ts` | PluginHealthCheck, HotReloadConfig | Host-driven lifecycle library inputs |
 | **[Plugin Loading](/docs/references/kernel/plugin-loading)** | `plugin-loading.zod.ts` | PluginLoadingConfig | Plugin loading and init |
 | **[Plugin Registry](/docs/references/kernel/plugin-registry)** | `plugin-registry.zod.ts` | PluginRegistryEntry, PluginVendor | Plugin registry entries and quality metrics |
 | **[Plugin Security](/docs/references/kernel/plugin-security)** | `plugin-security.zod.ts` | PluginSecurityProtocol, SBOM | Plugin security policies |

diff --git a/content/docs/references/index.mdx b/content/docs/references/index.mdx
@@ -1,6 +1,6 @@
 ---
 title: Protocol Reference
-description: Every schema published by @objectstack/spec — 1589 schemas across 14 protocol modules
+description: Every schema published by @objectstack/spec — 1586 schemas across 14 protocol modules
 ---
 
 {/* ⚠️ AUTO-GENERATED — DO NOT EDIT. Run build-docs.ts to regenerate. Hand-written docs live in the module folders under content/docs/. */}
@@ -26,14 +26,14 @@ counts are sums of the rows they head. Regenerate with
 | [Data Protocol](/docs/references/data) | 29 | 166 | Objects, fields, queries, filters, datasources and drivers — the ObjectQL layer. |
 | [Identity Protocol](/docs/references/identity) | 5 | 27 | Users and accounts, organizations, positions, SCIM provisioning. |
 | [Integration Protocol](/docs/references/integration) | 1 | 27 | The single connector protocol (ADR-0097) — catalog descriptors and provider-bound instances. |
-| [Kernel Protocol](/docs/references/kernel) | 31 | 176 | Plugin lifecycle and manifests, capabilities and security, metadata loading, service registry. |
+| [Kernel Protocol](/docs/references/kernel) | 31 | 173 | Plugin lifecycle and manifests, capabilities and security, metadata loading, service registry. |
 | [QA Protocol](/docs/references/qa) | 1 | 8 | Declarative test suites — scenarios, steps, actions and assertions. |
 | [Security Protocol](/docs/references/security) | 5 | 27 | Permission sets, row-level security, sharing rules, tenancy posture. |
 | [Shared Protocol](/docs/references/shared) | 8 | 32 | Primitives used across every protocol — identifiers, HTTP, expressions, error maps, enums. |
 | [Studio Protocol](/docs/references/studio) | 3 | 35 | Studio designer metadata — the authoring surfaces for the protocols above. |
 | [System Protocol](/docs/references/system) | 36 | 288 | The runtime environment — logging, jobs, cache, metrics, notifications, i18n and compliance. |
 | [UI Protocol](/docs/references/ui) | 16 | 152 | Apps, pages, views, dashboards, reports, actions and themes — the ObjectUI layer. |
-| **Total** | **199** | **1589** | 14 protocol modules |
+| **Total** | **199** | **1586** | 14 protocol modules |
 
 ---
 
@@ -215,7 +215,7 @@ The single connector protocol (ADR-0097) — catalog descriptors and provider-bo
 
 ## Kernel Protocol
 
-**Source:** `packages/spec/src/kernel/` · **Import:** `@objectstack/spec/kernel` · **31 pages, 176 schemas**
+**Source:** `packages/spec/src/kernel/` · **Import:** `@objectstack/spec/kernel` · **31 pages, 173 schemas**
 
 Plugin lifecycle and manifests, capabilities and security, metadata loading, service registry.
 
@@ -242,7 +242,7 @@ Plugin lifecycle and manifests, capabilities and security, metadata loading, ser
 | [`package-upgrade.zod.ts`](/docs/references/kernel/package-upgrade) | `MetadataChangeType`, `MetadataDiffItem`, `RollbackPackageRequest`, `RollbackPackageResponse`, `UpgradeImpactLevel`, `UpgradePackageRequest`, `UpgradePackageResponse`, `UpgradePhase`, `UpgradePlan`, `UpgradeSnapshot` |
 | [`plugin.zod.ts`](/docs/references/kernel/plugin) | `Plugin` |
 | [`plugin-capability.zod.ts`](/docs/references/kernel/plugin-capability) | `CapabilityConformanceLevel`, `ExtensionPoint`, `PluginCapability`, `PluginCapabilityManifest`, `PluginDependency`, `PluginInterface`, `ProtocolFeature`, `ProtocolReference`, `ProtocolVersion` |
-| [`plugin-lifecycle-advanced.zod.ts`](/docs/references/kernel/plugin-lifecycle-advanced) | `AdvancedPluginLifecycleConfig`, `DistributedStateConfig`, `GracefulDegradation`, `HotReloadConfig`, `PluginHealthCheck`, `PluginHealthReport`, `PluginHealthStatus`, `PluginStateSnapshot`, `PluginUpdateStrategy` |
+| [`plugin-lifecycle-advanced.zod.ts`](/docs/references/kernel/plugin-lifecycle-advanced) | `DistributedStateConfig`, `HotReloadConfig`, `PluginHealthCheck`, `PluginHealthReport`, `PluginHealthStatus`, `PluginStateSnapshot` |
 | [`plugin-loading.zod.ts`](/docs/references/kernel/plugin-loading) | `PluginLoadingEvent`, `PluginLoadingState` |
 | [`plugin-registry.zod.ts`](/docs/references/kernel/plugin-registry) | `PluginInstallConfig`, `PluginQualityMetrics`, `PluginRegistryEntry`, `PluginSearchFilters`, `PluginStatistics`, `PluginVendor` |
 | [`plugin-security.zod.ts`](/docs/references/kernel/plugin-security) | `DependencyGraph`, `DependencyGraphNode`, `PackageDependencyConflict`, `PackageDependencyResolutionResult`, `PluginProvenance`, `PluginTrustScore`, `ResolvedPackageDependency`, `SBOM`, `SBOMEntry`, `SecurityPolicy`, `SecurityScanResult`, `SecurityVulnerability`, `VulnerabilitySeverity` |

diff --git a/content/docs/references/kernel/plugin-lifecycle-advanced.mdx b/content/docs/references/kernel/plugin-lifecycle-advanced.mdx
@@ -5,16 +5,18 @@ description: Plugin Lifecycle Advanced protocol schemas
 
 {/* ⚠️ AUTO-GENERATED — DO NOT EDIT. Run build-docs.ts to regenerate. Hand-written docs live in the module folders under content/docs/. */}
 
-# Advanced Plugin Lifecycle Protocol
+# Advanced Plugin Lifecycle — host-driven library vocabularies
 
-Defines advanced lifecycle management capabilities including:
-- Hot reload and live updates
-- Graceful degradation and fallback mechanisms
-- Health monitoring and auto-recovery
-- State preservation during updates
+Declares the INPUT contracts of the host-driven lifecycle classes exported
+by `@objectstack/core` — `PluginHealthMonitor` (reads `PluginHealthCheck`,
+emits `PluginHealthStatus` / `PluginHealthReport`) and `HotReloadManager`
+(reads `HotReloadConfig`, snapshots via `PluginStateSnapshot`). The kernel
+does not construct either class: a HOST composes them and passes these
+shapes directly (`content/docs/protocol/kernel/lifecycle.mdx`, the #11811
+examples, is the supported usage).
 
-This protocol extends the basic plugin lifecycle with enterprise-grade
-features for production environments.
+This module deliberately declares NO authorable configuration surface — see
+the #11825 retirement record below.
 
 <Callout type="info">
 **Source:** `packages/spec/src/kernel/plugin-lifecycle-advanced.zod.ts`
@@ -23,85 +25,13 @@ features for production environments.
 ## TypeScript Usage
 
 ```typescript
-import { AdvancedPluginLifecycleConfigSchema, DistributedStateConfigSchema, GracefulDegradationSchema, HotReloadConfigSchema, PluginHealthCheckSchema, PluginHealthReportSchema, PluginHealthStatusSchema, PluginStateSnapshotSchema, PluginUpdateStrategySchema } from '@objectstack/spec/kernel';
-import type { AdvancedPluginLifecycleConfig, DistributedStateConfig, GracefulDegradation, HotReloadConfig, PluginHealthCheck, PluginHealthReport, PluginHealthStatus, PluginStateSnapshot, PluginUpdateStrategy } from '@objectstack/spec/kernel';
+import { DistributedStateConfigSchema, HotReloadConfigSchema, PluginHealthCheckSchema, PluginHealthReportSchema, PluginHealthStatusSchema, PluginStateSnapshotSchema } from '@objectstack/spec/kernel';
+import type { DistributedStateConfig, HotReloadConfig, PluginHealthCheck, PluginHealthReport, PluginHealthStatus, PluginStateSnapshot } from '@objectstack/spec/kernel';
 
 // Validate data
-const result = AdvancedPluginLifecycleConfigSchema.parse(data);
+const result = DistributedStateConfigSchema.parse(data);
 ```
 
----
-
-## AdvancedPluginLifecycleConfig
-
-### Properties
-
-| Property | Type | Required | Description |
-| :--- | :--- | :--- | :--- |
-| **health** | `{ interval: integer; timeout: integer; failureThreshold: integer; successThreshold: integer; … }` | optional | |
-| **hotReload** | `{ enabled: boolean; watchPatterns?: string[]; debounceDelay: integer; preserveState: boolean; … }` | optional | |
-| **degradation** | `{ enabled: boolean; fallbackMode: Enum<'minimal' \| 'cached' \| 'readonly' \| 'offline' \| 'disabled'>; criticalDependencies?: string[]; optionalDependencies?: string[]; … }` | optional | |
-| **updates** | `{ mode: Enum<'manual' \| 'automatic' \| 'scheduled' \| 'rolling'>; autoUpdateConstraints?: object; schedule?: object; rollback?: object; … }` | optional | |
-| **resources** | `{ maxMemory?: integer; maxCpu?: number; maxConnections?: integer; timeout?: integer }` | optional | |
-| **observability** | `{ enableMetrics: boolean; enableTracing: boolean; enableProfiling: boolean; metricsInterval: integer }` | optional | |
-
-### Nested Shape: `AdvancedPluginLifecycleConfig.health`
-
-| Property | Type | Required | Description |
-| :--- | :--- | :--- | :--- |
-| **interval** | `integer` | optional (default: `30000`) | How often to perform health checks (default: 30s) |
-| **timeout** | `integer` | optional (default: `5000`) | Maximum time to wait for health check response |
-| **failureThreshold** | `integer` | optional (default: `3`) | Consecutive failures needed to mark unhealthy |
-| **successThreshold** | `integer` | optional (default: `1`) | Consecutive successes needed to mark healthy |
-| **checkMethod** | `string` | optional | Method name to call for health check |
-| **autoRestart** | `boolean` | optional (default: `false`) | Automatically restart plugin on health check failure |
-| **maxRestartAttempts** | `integer` | optional (default: `3`) | Maximum restart attempts before giving up |
-| **restartBackoff** | `Enum<'fixed' \| 'linear' \| 'exponential'>` | optional (default: `"exponential"`) | Backoff strategy for restart delays |
-
-### Nested Shape: `AdvancedPluginLifecycleConfig.hotReload`
-
-| Property | Type | Required | Description |
-| :--- | :--- | :--- | :--- |
-| **enabled** | `boolean` | optional (default: `false`) | |
-| **watchPatterns** | `string[]` | optional | Glob patterns to watch for changes |
-| **debounceDelay** | `integer` | optional (default: `1000`) | Wait time after change detection before reload |
-| **preserveState** | `boolean` | optional (default: `true`) | Keep plugin state across reloads |
-| **stateStrategy** | `Enum<'memory' \| 'disk' \| 'distributed' \| 'none'>` | optional (default: `"memory"`) | How to preserve state during reload |
-| **distributedConfig** | `{ provider: Enum<'redis' \| 'etcd' \| 'custom'>; endpoints?: string[]; keyPrefix?: string; ttl?: integer; … }` | optional | Configuration for distributed state management |
-| **shutdownTimeout** | `integer` | optional (default: `30000`) | Maximum time to wait for graceful shutdown |
-| **beforeReload** | `string[]` | optional | Hook names to call before reload |
-| **afterReload** | `string[]` | optional | Hook names to call after reload |
-
-### Nested Shape: `AdvancedPluginLifecycleConfig.degradation`
-
-| Property | Type | Required | Description |
-| :--- | :--- | :--- | :--- |
-| **enabled** | `boolean` | optional (default: `true`) | |
-| **fallbackMode** | `Enum<'minimal' \| 'cached' \| 'readonly' \| 'offline' \| 'disabled'>` | optional (default: `"minimal"`) | |
-| **criticalDependencies** | `string[]` | optional | Plugin IDs that are required for operation |
-| **optionalDependencies** | `string[]` | optional | Plugin IDs that are nice to have but not required |
-| **degradedFeatures** | `{ feature: string; enabled: boolean; reason?: string }[]` | optional | |
-| **autoRecovery** | `{ enabled: boolean; retryInterval: integer; maxAttempts: integer }` | optional | |
-
-### Nested Shape: `AdvancedPluginLifecycleConfig.resources`
-
-| Property | Type | Required | Description |
-| :--- | :--- | :--- | :--- |
-| **maxMemory** | `integer` | optional | Maximum memory in bytes |
-| **maxCpu** | `number` | optional | Maximum CPU percentage |
-| **maxConnections** | `integer` | optional | Maximum concurrent connections |
-| **timeout** | `integer` | optional | Operation timeout in milliseconds |
-
-### Nested Shape: `AdvancedPluginLifecycleConfig.observability`
-
-| Property | Type | Required | Description |
-| :--- | :--- | :--- | :--- |
-| **enableMetrics** | `boolean` | optional (default: `true`) | |
-| **enableTracing** | `boolean` | optional (default: `true`) | |
-| **enableProfiling** | `boolean` | optional (default: `false`) | |
-| **metricsInterval** | `integer` | optional (default: `60000`) | Metrics collection interval in ms |
-
-
 ---
 
 ## DistributedStateConfig
@@ -119,38 +49,6 @@ const result = AdvancedPluginLifecycleConfigSchema.parse(data);
 | **customConfig** | `Record<string, any>` | optional | Provider-specific configuration |
 
 
----
-
-## GracefulDegradation
-
-### Properties
-
-| Property | Type | Required | Description |
-| :--- | :--- | :--- | :--- |
-| **enabled** | `boolean` | optional (default: `true`) | |
-| **fallbackMode** | `Enum<'minimal' \| 'cached' \| 'readonly' \| 'offline' \| 'disabled'>` | optional (default: `"minimal"`) | |
-| **criticalDependencies** | `string[]` | optional | Plugin IDs that are required for operation |
-| **optionalDependencies** | `string[]` | optional | Plugin IDs that are nice to have but not required |
-| **degradedFeatures** | `{ feature: string; enabled: boolean; reason?: string }[]` | optional | |
-| **autoRecovery** | `{ enabled: boolean; retryInterval: integer; maxAttempts: integer }` | optional | |
-
-### Nested Shape: `GracefulDegradation.degradedFeatures[number]`
-
-| Property | Type | Required | Description |
-| :--- | :--- | :--- | :--- |
-| **feature** | `string` | ✅ | Feature name |
-| **enabled** | `boolean` | ✅ | Whether feature is available in degraded mode |
-| **reason** | `string` | optional | |
-
-### Nested Shape: `GracefulDegradation.autoRecovery`
-
-| Property | Type | Required | Description |
-| :--- | :--- | :--- | :--- |
-| **enabled** | `boolean` | optional (default: `true`) | |
-| **retryInterval** | `integer` | optional (default: `60000`) | Interval between recovery attempts (ms) |
-| **maxAttempts** | `integer` | optional (default: `5`) | Maximum recovery attempts before giving up |
-
-
 ---
 
 ## HotReloadConfig
@@ -285,26 +183,3 @@ Current health status of the plugin
 
 ---
 
-## PluginUpdateStrategy
-
-### Properties
-
-| Property | Type | Required | Description |
-| :--- | :--- | :--- | :--- |
-| **mode** | `Enum<'manual' \| 'automatic' \| 'scheduled' \| 'rolling'>` | optional (default: `"manual"`) | |
-| **autoUpdateConstraints** | `{ major: boolean; minor: boolean; patch: boolean }` | optional | |
-| **schedule** | `{ cron?: string; timezone: string; maintenanceWindow: integer }` | optional | |
-| **rollback** | `{ enabled: boolean; automatic: boolean; keepVersions: integer; timeout: integer }` | optional | |
-| **validation** | `{ checkCompatibility: boolean; runTests: boolean; testSuite?: string }` | optional | |
-
-### Nested Shape: `PluginUpdateStrategy.autoUpdateConstraints`
-
-| Property | Type | Required | Description |
-| :--- | :--- | :--- | :--- |
-| **major** | `boolean` | optional (default: `false`) | Allow major version updates |
-| **minor** | `boolean` | optional (default: `true`) | Allow minor version updates |
-| **patch** | `boolean` | optional (default: `true`) | Allow patch version updates |
-
-
----
-
diff --git a/docs/audits/2026-07-unknown-key-strictness-ledger.counts.md b/docs/audits/2026-07-unknown-key-strictness-ledger.counts.md
@@ -261,7 +261,7 @@ directory rather than per file.
 | `cloud/` | 83 |
 | `identity/` | 32 |
 | `integration/` | 10 |
-| `kernel/` | 288 |
+| `kernel/` | 277 |
 | `qa/` | 6 |
 | `shared/` | 20 |
 | `system/` | 361 |