objectstack-ai · os-zhuang · Jul 30, 2026 · Jul 30, 2026 · Jul 30, 2026
diff --git a/.changeset/lifecycle-event-registry-enforced.md b/.changeset/lifecycle-event-registry-enforced.md
@@ -0,0 +1,64 @@
+---
+"@objectstack/spec": major
+"@objectstack/core": patch
+---
+
+fix(spec)!: retire the never-built typed-event system; the lifecycle registry now lists the events that actually fire (#4212 follow-up)
+
+The lifecycle-event surface promised a typed-event system that was never
+built, in three layers. `kernel/plugin-lifecycle-events.zod.ts` shipped ten
+payload schemas (`PluginRegisteredEvent`, `PluginErrorEvent`,
+`HookTriggeredEvent`, `KernelReadyEvent`, …) and a 21-name
+`PluginLifecycleEventType` enum — zero consumers for every export, and the
+enum was wrong in both directions: 17 names nothing fires, 10 real events
+missing. `contracts/plugin-lifecycle-events.ts` declared the same 17 dead
+names in `IPluginLifecycleEvents` next to 5 real ones, plus an
+`ITypedEventEmitter` interface nothing implements. All of it read as a
+promise; anyone who coded against it (hooking `plugin:started`, awaiting
+`plugin:error`) registered a handler that could never fire, with no error
+saying so — the same silent-drop shape as the #4212 lifecycle-hook family.
+
+Removed, with zero consumers verified repo-wide:
+
+- `kernel/plugin-lifecycle-events.zod.ts` and every export: `EventPhase`,
+ `PluginEventBase`, `PluginRegisteredEvent`, `PluginLifecyclePhaseEvent`,
+ `PluginErrorEvent`, `ServiceRegisteredEvent`, `ServiceUnregisteredEvent`,
+ `HookRegisteredEvent`, `HookTriggeredEvent`, `KernelEventBase`,
+ `KernelReadyEvent`, `KernelShutdownEvent`, `PluginLifecycleEventType`
+ (schemas and inferred types).
+- `ITypedEventEmitter` from `contracts/plugin-lifecycle-events.ts`.
+- The 17 never-fired names from `IPluginLifecycleEvents`.
+
+`IPluginLifecycleEvents` is now the registry of the **14 events with a real
+emitter** — `kernel:{ready,bootstrapped,listening,shutdown}`, `app:seeded`,
+`metadata:reloaded` (payload `metadata` now optional, matching the documented
+contract), `external.schema.drift`, `ai:routes`, `auth:configure`, and the
+`{service}:ready` convention family (`mcp`, `automation`, `analytics`,
+`external-datasource`, `datasource-admin`) — each payload as observed at its
+fire site. A new `LifecycleEventName` union types
+`PluginContext.hook`/`trigger` in `@objectstack/core` as
+`LifecycleEventName | (string & {})`: known names autocomplete, custom
+cross-plugin names stay legal, existing callers compile unchanged. A pinning
+test asserts two-way equality between the interface keys and the fire-site
+inventory.
+
+FROM → TO:
+
+- `PluginLifecycleEventType` → `LifecycleEventName` (the union of names that
+ fire). There is no runtime enum; the bus is open by design.
+- Event payload schemas (`KernelReadyEvent`, `PluginErrorEvent`, …) → the
+ payload tuples on `IPluginLifecycleEvents`. No wire format existed or
+ exists; payloads are in-process arguments.
+- `ITypedEventEmitter` → `PluginContext.hook`/`trigger` (the emitter that
+ actually exists).
+- Handlers for the 17 dead names → delete them; they never ran. For plugin
+ phase observation use the boot report (ADR-0084); for per-plugin errors the
+ kernel throws/logs at the failing phase.
+
+Plain deletion rather than `retiredKey()` tombstones, per the #4233
+precedent: these keys were never authorable — they described runtime event
+payload records no config author can write, so the silent-strip class the
+authorable-surface ratchet guards against is vacuous. Its baseline entries
+and the `json-schema.manifest.json` keys are dropped deliberately in this PR.
+No ADR-0087 conversion: no stack metadata names these types; there is nothing
+for `os migrate meta` to rewrite.
diff --git a/content/docs/getting-started/quick-reference.mdx b/content/docs/getting-started/quick-reference.mdx
@@ -64,7 +64,6 @@ 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](/docs/references/kernel/plugin-lifecycle-events)** | `plugin-lifecycle-events.zod.ts` | PluginEventBase, EventPhase | Plugin lifecycle events |
 | **[Plugin Lifecycle Advanced](/docs/references/kernel/plugin-lifecycle-advanced)** | `plugin-lifecycle-advanced.zod.ts` | AdvancedPluginLifecycleConfig, PluginHealthCheck | Advanced lifecycle hooks |
 | **[Plugin Loading](/docs/references/kernel/plugin-loading)** | `plugin-loading.zod.ts` | PluginLoadingConfig | Plugin loading and init |
 | **[Plugin Security](/docs/references/kernel/plugin-security-advanced)** | `plugin-security-advanced.zod.ts` | KernelSecurityPolicy, PluginPermission | Plugin sandboxing |

diff --git a/content/docs/references/index.mdx b/content/docs/references/index.mdx
@@ -115,7 +115,6 @@ Defines the plugin architecture and kernel runtime.
 | `context.zod.ts` | `KernelContextSchema` | Kernel execution context with user, org, tenant info |
 | `plugin.zod.ts` | `PluginSchema` | Plugin lifecycle and interface definitions |
 | `plugin-capability.zod.ts` | `PluginCapabilitySchema` | Plugin capability declarations |
-| `plugin-lifecycle-events.zod.ts` | `PluginLifecycleEventsSchema` | Plugin lifecycle event definitions |
 | `plugin-lifecycle-advanced.zod.ts` | `PluginLifecycleAdvancedSchema` | Advanced lifecycle hooks |
 | `plugin-loading.zod.ts` | `PluginLoadingSchema` | Plugin loading and initialization |
 | `plugin-security-advanced.zod.ts` | `PluginSecurityAdvancedSchema` | Plugin security and sandboxing |

diff --git a/content/docs/references/kernel/index.mdx b/content/docs/references/kernel/index.mdx
@@ -22,7 +22,6 @@ This section contains all protocol schemas for the kernel layer of ObjectStack.
  <Card href="/docs/references/kernel/plugin" title="Plugin" description="Source: packages/spec/src/kernel/plugin.zod.ts" />
  <Card href="/docs/references/kernel/plugin-capability" title="Plugin Capability" description="Source: packages/spec/src/kernel/plugin-capability.zod.ts" />
  <Card href="/docs/references/kernel/plugin-lifecycle-advanced" title="Plugin Lifecycle Advanced" description="Source: packages/spec/src/kernel/plugin-lifecycle-advanced.zod.ts" />
- <Card href="/docs/references/kernel/plugin-lifecycle-events" title="Plugin Lifecycle Events" description="Source: packages/spec/src/kernel/plugin-lifecycle-events.zod.ts" />
  <Card href="/docs/references/kernel/plugin-loading" title="Plugin Loading" description="Source: packages/spec/src/kernel/plugin-loading.zod.ts" />
  <Card href="/docs/references/kernel/plugin-registry" title="Plugin Registry" description="Source: packages/spec/src/kernel/plugin-registry.zod.ts" />
  <Card href="/docs/references/kernel/plugin-runtime" title="Plugin Runtime" description="Source: packages/spec/src/kernel/plugin-runtime.zod.ts" />

diff --git a/content/docs/references/kernel/meta.json b/content/docs/references/kernel/meta.json
@@ -4,7 +4,6 @@
  "---Plugin Lifecycle---",
  "plugin",
  "plugin-lifecycle-advanced",
- "plugin-lifecycle-events",
  "plugin-loading",
  "plugin-registry",
  "plugin-runtime",

diff --git a/content/docs/references/kernel/plugin-lifecycle-events.mdx b/content/docs/references/kernel/plugin-lifecycle-events.mdx
diff --git a/packages/core/src/types.ts b/packages/core/src/types.ts
@@ -1,7 +1,7 @@
 // Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
 
 import { ObjectKernel } from './kernel.js';
-import type { Logger } from '@objectstack/spec/contracts';
+import type { Logger, LifecycleEventName } from '@objectstack/spec/contracts';
 
 /**
  * PluginContext - Runtime context available to plugins
@@ -58,18 +58,26 @@ export interface PluginContext {
  getServices(): Map<string, any>;
 
  /**
- * Register a hook handler
+ * Register a hook handler.
+ *
+ * Known lifecycle-bus names (see `IPluginLifecycleEvents` in
+ * `@objectstack/spec`) autocomplete; the bus stays open to custom
+ * cross-plugin event names, so any string remains valid.
+ *
  * @param name - Hook name (e.g., 'kernel:ready', 'data:beforeInsert')
  * @param handler - Hook handler function
  */
- hook(name: string, handler: (...args: any[]) => void | Promise<void>): void;
+ hook(
+ name: LifecycleEventName | (string & {}),
+ handler: (...args: any[]) => void | Promise<void>,
+ ): void;
 
  /**
  * Trigger a hook
- * @param name - Hook name
+ * @param name - Hook name (known lifecycle names autocomplete; custom names stay legal)
  * @param args - Arguments to pass to hook handlers
  */
- trigger(name: string, ...args: any[]): Promise<void>;
+ trigger(name: LifecycleEventName | (string & {}), ...args: any[]): Promise<void>;
 
  /**
  * Logger instance

diff --git a/packages/spec/PROTOCOL_MAP.md b/packages/spec/PROTOCOL_MAP.md
@@ -202,7 +202,7 @@ This document serves as the **Grand Map** of the ObjectStack specification. It l
 | [`plugin-validator.zod.ts`](src/kernel/plugin-validator.zod.ts) | | **Validation**. Integrity checks for plugins. |
 | [`plugin-structure.zod.ts`](src/kernel/plugin-structure.zod.ts) | | **Structure**. Zod rules for folder layout and file naming. |
 | [`plugin-capability.zod.ts`](src/kernel/plugin-capability.zod.ts) | | **Capabilities**. What a plugin can do. |
-| [`plugin-lifecycle-events.zod.ts`](src/kernel/plugin-lifecycle-events.zod.ts) | | **Lifecycle Events**. Hooks for plugin state changes. |
+| [`plugin-lifecycle-events.ts`](src/contracts/plugin-lifecycle-events.ts) | | **Lifecycle Events**. Registry of every kernel-bus event that actually fires, with payload tuples; feeds `hook`/`trigger` autocomplete. |
 | [`plugin-lifecycle-advanced.zod.ts`](src/kernel/plugin-lifecycle-advanced.zod.ts) | | **Advanced Lifecycle**. Health monitoring, hot reload state management, graceful degradation, and update strategies. |
 | [`plugin-security-advanced.zod.ts`](src/kernel/plugin-security-advanced.zod.ts) | | **Advanced Security**. Permission system, sandbox configuration (V8/WASM/container/process), security scanning, and trust levels. |
 | [`startup-orchestrator.zod.ts`](src/kernel/startup-orchestrator.zod.ts) | | **Startup**. Boot sequence orchestration. |