---
title: Plugin Lifecycle Events
description: Plugin Lifecycle Events protocol schemas
---

{/* ⚠️  AUTO-GENERATED — DO NOT EDIT. Run build-docs.ts to regenerate. Hand-written docs go in content/docs/guides/. */}

Plugin Lifecycle Events Protocol

Zod schemas for plugin lifecycle event data structures.

These schemas align with the IPluginLifecycleEvents contract interface.

Following ObjectStack "Zod First" principle - all data structures

must have Zod schemas for runtime validation and JSON Schema generation.

<Callout type="info">
**Source:** `packages/spec/src/kernel/plugin-lifecycle-events.zod.ts`
</Callout>

## TypeScript Usage

```typescript
import { EventPhase, HookRegisteredEvent, HookTriggeredEvent, KernelEventBase, KernelReadyEvent, KernelShutdownEvent, PluginErrorEvent, PluginEventBase, PluginLifecycleEventType, PluginLifecyclePhaseEvent, PluginRegisteredEvent, ServiceRegisteredEvent, ServiceUnregisteredEvent } from '@objectstack/spec/kernel';
import type { EventPhase, HookRegisteredEvent, HookTriggeredEvent, KernelEventBase, KernelReadyEvent, KernelShutdownEvent, PluginErrorEvent, PluginEventBase, PluginLifecycleEventType, PluginLifecyclePhaseEvent, PluginRegisteredEvent, ServiceRegisteredEvent, ServiceUnregisteredEvent } from '@objectstack/spec/kernel';

// Validate data
const result = EventPhase.parse(data);
```

---

## EventPhase

Plugin lifecycle phase

### Allowed Values

* `init`
* `start`
* `destroy`


---

## HookRegisteredEvent

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **hookName** | `string` | ✅ | Name of the hook |
| **timestamp** | `integer` | ✅ | Unix timestamp in milliseconds |
| **handlerCount** | `integer` | ✅ | Number of handlers registered for this hook |


---

## HookTriggeredEvent

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **hookName** | `string` | ✅ | Name of the hook |
| **timestamp** | `integer` | ✅ | Unix timestamp in milliseconds |
| **args** | `any[]` | ✅ | Arguments passed to the hook handlers |
| **handlerCount** | `integer` | optional | Number of handlers that will handle this event |


---

## KernelEventBase

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **timestamp** | `integer` | ✅ | Unix timestamp in milliseconds |


---

## KernelReadyEvent

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **timestamp** | `integer` | ✅ | Unix timestamp in milliseconds |
| **duration** | `number` | optional | Total initialization duration in milliseconds |
| **pluginCount** | `integer` | optional | Number of plugins initialized |


---

## KernelShutdownEvent

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **timestamp** | `integer` | ✅ | Unix timestamp in milliseconds |
| **reason** | `string` | optional | Reason for kernel shutdown |


---

## PluginErrorEvent

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **pluginName** | `string` | ✅ | Name of the plugin |
| **timestamp** | `integer` | ✅ | Unix timestamp in milliseconds when event occurred |
| **error** | `Object` | ✅ | Serializable error representation |
| **phase** | `Enum<'init' \| 'start' \| 'destroy'>` | ✅ | Lifecycle phase where error occurred |
| **errorMessage** | `string` | optional | Error message |
| **errorStack** | `string` | optional | Error stack trace |


---

## PluginEventBase

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **pluginName** | `string` | ✅ | Name of the plugin |
| **timestamp** | `integer` | ✅ | Unix timestamp in milliseconds when event occurred |


---

## PluginLifecycleEventType

Plugin lifecycle event type

### Allowed Values

* `kernel:ready`
* `kernel:listening`
* `kernel:shutdown`
* `kernel:before-init`
* `kernel:after-init`
* `plugin:registered`
* `plugin:before-init`
* `plugin:init`
* `plugin:after-init`
* `plugin:before-start`
* `plugin:started`
* `plugin:after-start`
* `plugin:before-destroy`
* `plugin:destroyed`
* `plugin:after-destroy`
* `plugin:error`
* `service:registered`
* `service:unregistered`
* `hook:registered`
* `hook:triggered`


---

## PluginLifecyclePhaseEvent

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **pluginName** | `string` | ✅ | Name of the plugin |
| **timestamp** | `integer` | ✅ | Unix timestamp in milliseconds when event occurred |
| **duration** | `number` | optional | Duration of the lifecycle phase in milliseconds |
| **phase** | `Enum<'init' \| 'start' \| 'destroy'>` | optional | Lifecycle phase |


---

## PluginRegisteredEvent

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **pluginName** | `string` | ✅ | Name of the plugin |
| **timestamp** | `integer` | ✅ | Unix timestamp in milliseconds when event occurred |
| **version** | `string` | optional | Plugin version |


---

## ServiceRegisteredEvent

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **serviceName** | `string` | ✅ | Name of the registered service |
| **timestamp** | `integer` | ✅ | Unix timestamp in milliseconds |
| **serviceType** | `string` | optional | Type or interface name of the service |


---

## ServiceUnregisteredEvent

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **serviceName** | `string` | ✅ | Name of the unregistered service |
| **timestamp** | `integer` | ✅ | Unix timestamp in milliseconds |


---

