@elevasis/sdk 1.24.0 → 1.26.0

package/reference/resources/types.mdx

@@ -1,116 +1,115 @@
----
-title: SDK Types
-description: Type reference for @elevasis/sdk package exports, resource metadata, platform types, ElevasConfig, StepHandler context, and runtime values.
-loadWhen: "Looking up type signatures or SDK exports"
----
-
-`@elevasis/sdk` bundles platform types into a self-contained package for external projects.
-
-```bash
-pnpm add @elevasis/sdk zod
-```
-
-Zod is a peer dependency.
-
-## Package Exports
-
-```json
-{
-  "exports": {
-    ".": { "types": "./dist/index.d.ts", "import": "./dist/index.js" },
-    "./worker": { "import": "./dist/worker/index.js" }
-  }
-}
-```
-
-- `@elevasis/sdk` -- resource, workflow, agent, trigger, deployment, and execution types plus runtime errors.
-- `@elevasis/sdk/worker` -- worker runtime module, platform adapters, and worker helpers.
-
-## Platform Types
-
-| Type | Description |
-| --- | --- |
-| `ResourceDefinition` | Base interface for resource definitions |
-| `ResourceType` | Resource kind such as `workflow`, `agent`, `trigger`, `integration`, `external`, or `human_checkpoint` |
-| `ResourceStatus` | Resource lifecycle status such as `dev` or `prod` |
-| `ResourceLink` | Graph link `{ nodeId, kind }` binding a resource to an Organization Model node |
-| `ResourceCategory` | Operational category: `production`, `diagnostic`, `internal`, or `testing` |
-| `DeploymentSpec` | Top-level export shape: `{ workflows, agents, triggers, integrations, humanCheckpoints, externalResources, relationships }` |
-| `TriggerDefinition` | Base for trigger configuration |
-| `IntegrationDefinition` | Integration configuration structure |
-| `WebhookProviderType` | Supported webhook providers |
-| `WebhookTriggerConfig` | Webhook trigger configuration |
-| `ScheduleTriggerConfig` | Cron/schedule trigger configuration |
-| `EventTriggerConfig` | Internal event trigger configuration |
-| `TriggerConfig` | Union of all trigger config types |
-
-Resource metadata uses graph links:
-
-```ts
-config: {
-  resourceId: 'lead-import',
-  name: 'Lead Import',
-  type: 'workflow',
-  version: '1.0.0',
-  status: 'prod',
-  links: [{ nodeId: 'system:sales.lead-gen', kind: 'operates-on' }],
-  category: 'production'
-}
-```
-
-## Execution Types
-
-| Type | Description |
-| --- | --- |
-| `WorkflowDefinition` | Complete workflow definition including config, contract, steps, and entryPoint |
-| `WorkflowStep` | Individual step definition with type, handler, and next routing |
-| `WorkflowConfig` | Metadata block: name, description, status, links, category |
-| `StepHandler` | Function type: `(input: unknown, context: StepContext) => Promise<unknown>` |
-| `NextConfig` | Union of `LinearNext` and `ConditionalNext` |
-| `LinearNext` | Fixed next step routing |
-| `ConditionalNext` | Branching step routing |
-| `StepType` | Runtime enum for step routing |
-| `AgentDefinition` | Complete agent definition including config, agentConfig, and tools |
-| `ExecutionContext` | Runtime context passed to step handlers |
-| `ExecutionMetadata` | Metadata about a running execution |
-| `ExecutionInterface` | Interface for triggering and inspecting executions |
-
-## ElevasConfig
-
-```ts
-export interface ElevasConfig {
-  defaultStatus?: ResourceStatus
-  dev?: { port?: number }
-}
-```
-
-| Field | Type | Default | Description |
-| --- | --- | --- | --- |
-| `defaultStatus` | `'dev' | 'prod'` | `'prod'` | Default status applied when resources do not set `config.status` |
-| `dev.port` | `number` | `3001` | Local worker development port |
-
-## StepHandler Context
-
-```ts
-import type { StepHandler, ExecutionContext } from '@elevasis/sdk'
-
-const handler: StepHandler = async (input, context: ExecutionContext) => {
-  context.logger.info('Processing', {
-    executionId: context.executionId,
-    resourceId: context.resourceId
-  })
-
-  await context.store.set('checkpoint', JSON.stringify({ step: 'started' }))
-  return { done: true }
-}
-```
-
-## Runtime Values
-
-Runtime exports include:
-
-- `StepType`
-- `ToolingError`
-- `ExecutionError`
-
-Use `ToolingError` for platform adapter failures and `ExecutionError` for execution-level failures that should be surfaced in run history.
+---
+title: SDK Types
+description: Type reference for @elevasis/sdk package exports, resource metadata, platform types, ElevasConfig, StepHandler context, and runtime values
+---
+
+`@elevasis/sdk` bundles platform types into a self-contained package for external projects.
+
+```bash
+pnpm add @elevasis/sdk zod
+```
+
+Zod is a peer dependency.
+
+## Package Exports
+
+```json
+{
+  "exports": {
+    ".": { "types": "./dist/index.d.ts", "import": "./dist/index.js" },
+    "./worker": { "import": "./dist/worker/index.js" }
+  }
+}
+```
+
+- `@elevasis/sdk` -- resource, workflow, agent, trigger, deployment, and execution types plus runtime errors.
+- `@elevasis/sdk/worker` -- worker runtime module, platform adapters, and worker helpers.
+
+## Platform Types
+
+| Type                    | Description                                                                                                                 |
+| ----------------------- | --------------------------------------------------------------------------------------------------------------------------- |
+| `ResourceDefinition`    | Base interface for resource definitions                                                                                     |
+| `ResourceType`          | Resource kind such as `workflow`, `agent`, `trigger`, `integration`, `external`, or `human_checkpoint`                      |
+| `ResourceStatus`        | Resource lifecycle status such as `dev` or `prod`                                                                           |
+| `ResourceLink`          | Graph link `{ nodeId, kind }` binding a resource to an Organization Model node                                              |
+| `ResourceCategory`      | Operational category: `production`, `diagnostic`, `internal`, or `testing`                                                  |
+| `DeploymentSpec`        | Top-level export shape: `{ workflows, agents, triggers, integrations, humanCheckpoints, externalResources, relationships }` |
+| `TriggerDefinition`     | Base for trigger configuration                                                                                              |
+| `IntegrationDefinition` | Integration configuration structure                                                                                         |
+| `WebhookProviderType`   | Supported webhook providers                                                                                                 |
+| `WebhookTriggerConfig`  | Webhook trigger configuration                                                                                               |
+| `ScheduleTriggerConfig` | Cron/schedule trigger configuration                                                                                         |
+| `EventTriggerConfig`    | Internal event trigger configuration                                                                                        |
+| `TriggerConfig`         | Union of all trigger config types                                                                                           |
+
+Resource metadata uses graph links:
+
+```ts
+config: {
+  resourceId: 'lead-import',
+  name: 'Lead Import',
+  type: 'workflow',
+  version: '1.0.0',
+  status: 'prod',
+  links: [{ nodeId: 'system:sales.lead-gen', kind: 'operates-on' }],
+  category: 'production'
+}
+```
+
+## Execution Types
+
+| Type                 | Description                                                                    |
+| -------------------- | ------------------------------------------------------------------------------ |
+| `WorkflowDefinition` | Complete workflow definition including config, contract, steps, and entryPoint |
+| `WorkflowStep`       | Individual step definition with type, handler, and next routing                |
+| `WorkflowConfig`     | Metadata block: name, description, status, links, category                     |
+| `StepHandler`        | Function type: `(input: unknown, context: StepContext) => Promise<unknown>`    |
+| `NextConfig`         | Union of `LinearNext` and `ConditionalNext`                                    |
+| `LinearNext`         | Fixed next step routing                                                        |
+| `ConditionalNext`    | Branching step routing                                                         |
+| `StepType`           | Runtime enum for step routing                                                  |
+| `AgentDefinition`    | Complete agent definition including config, agentConfig, and tools             |
+| `ExecutionContext`   | Runtime context passed to step handlers                                        |
+| `ExecutionMetadata`  | Metadata about a running execution                                             |
+| `ExecutionInterface` | Interface for triggering and inspecting executions                             |
+
+## ElevasConfig
+
+```ts
+export interface ElevasConfig {
+  defaultStatus?: ResourceStatus
+  dev?: { port?: number }
+}
+```
+
+| Field           | Type     | Default | Description                   |
+| --------------- | -------- | ------- | ----------------------------- | ---------------------------------------------------------------- |
+| `defaultStatus` | `'dev'   | 'prod'` | `'prod'`                      | Default status applied when resources do not set `config.status` |
+| `dev.port`      | `number` | `3001`  | Local worker development port |
+
+## StepHandler Context
+
+```ts
+import type { StepHandler, ExecutionContext } from '@elevasis/sdk'
+
+const handler: StepHandler = async (input, context: ExecutionContext) => {
+  context.logger.info('Processing', {
+    executionId: context.executionId,
+    resourceId: context.resourceId
+  })
+
+  await context.store.set('checkpoint', JSON.stringify({ step: 'started' }))
+  return { done: true }
+}
+```
+
+## Runtime Values
+
+Runtime exports include:
+
+- `StepType`
+- `ToolingError`
+- `ExecutionError`
+
+Use `ToolingError` for platform adapter failures and `ExecutionError` for execution-level failures that should be surfaced in run history.

package/reference/roadmap.mdx

@@ -1,165 +1,164 @@
----
-title: Roadmap
-description: Planned SDK features -- error taxonomy, retry semantics, circuit breaker, metrics, alerting, and resource lifecycle extensions
-loadWhen: "Asking about future features or planned capabilities"
----
-
-**Status:** Mixed -- some features below are implemented, others remain planned. Each section notes its current status.
-
-For currently implemented behavior, see [Runtime](runtime.mdx).
-
----
-
-## Structured Error Taxonomy
-
-**Status: Partially implemented.** The runtime has a structured error hierarchy (`ExecutionError`, `PlatformToolError`, `ToolingError`) with error codes and context fields. The taxonomy below describes a planned _redesign_ that is not yet implemented.
-
-The current runtime reports errors as plain strings. A future SDK version will introduce a structured error taxonomy. All SDK errors will extend `ResourceError`, the base class for errors surfaced through the execution protocol.
-
-Every error carries: `message` (string), `code` (string enum), `details` (optional structured data), and `retryable` (boolean).
-
-**Error types:**
-
-- **`ResourceError`** -- Base class for all SDK errors
-- **`ValidationError`** -- Input or output schema validation failed. Thrown automatically when Zod `.parse()` fails. Code: `VALIDATION_ERROR`. Not retryable.
-- **`StepError`** -- A workflow step handler threw. Includes `stepId` and `stepName`. Code: `STEP_ERROR`. Retryable (transient failures may succeed on retry).
-- **`ToolError`** -- A tool execution failed. Includes `toolName`. Code: `TOOL_ERROR`. Retryability depends on the underlying error.
-- **`TimeoutError`** -- Execution exceeded the deadline. Code: `TIMEOUT`. Retryable.
-- **`CancellationError`** -- Execution was cancelled by the platform or user. Code: `CANCELLED`. Not retryable.
-
----
-
-## Retry Semantics
-
-**Status: Planned.**
-
-Retries are platform-side only -- workers are ephemeral and never retry internally.
-
-- **Configuration:** Per-resource via `maxRetries` (default: 0) and `backoffStrategy` (exponential with jitter)
-- **Retryable conditions:** Worker crash or timeout (worker terminated by `AbortSignal`)
-- **Non-retryable conditions:** Worker reports `status: 'failed'` (handler ran and returned an error -- application logic, not infrastructure failure), user cancellation
-- **Idempotency:** On retry, the same `executionId` is reused. Design handlers to be idempotent where possible.
-
----
-
-## Workflow Step Failure
-
-**Status: Planned.** The current runtime uses fail-fast behavior: when a step handler throws, the worker logs a `step-failed` context entry and re-throws the original error unchanged. The `onError` callback, `completedSteps`, and `partialOutput` features described below are not yet implemented.
-
-Default behavior is fail-fast: when a step throws, the workflow fails immediately.
-
-- **Error handler:** Optional `onError` callback per step. The callback receives the error and can return a recovery value or rethrow to propagate the failure.
-- **Partial output:** Steps completed before the failure are included in the error response. The platform receives: `failedStepId`, `completedSteps[]` (IDs of successfully completed steps), and `partialOutput` (the last successful step's output).
-
-**Proposed step error response format** (not yet implemented -- subject to change):
-
-```json
-{
-  "status": "failed",
-  "error": {
-    "code": "STEP_ERROR",
-    "message": "Email delivery failed: invalid address",
-    "stepId": "send-welcome",
-    "stepName": "Send Welcome Email"
-  },
-  "completedSteps": ["validate"],
-  "partialOutput": { "clientName": "Jane", "isValid": true }
-}
-```
-
----
-
-## Agent Failure Modes
-
-**Status: Planned.** Agent execution runs in ephemeral worker threads with full tool calling support via `PostMessageLLMAdapter`. The current runtime uses fail-fast behavior for all agent error paths; the richer failure handling described below is not yet implemented.
-
-**Current behavior:** Any unhandled error from the agent (including `AgentMaxIterationsError` thrown by `@repo/core` when the iteration limit is reached) propagates out of the worker and is reported as a failed execution. The worker sends: `{ type: 'result', status: 'failed', error: 'ErrorName: message', logs, metrics: { durationMs } }`. There is no graceful termination, partial output, or retry logic in the worker itself.
-
-**Planned improvements:**
-
-- **Max iterations reached:** Instead of throwing, the agent returns the best output produced so far, plus a warning flag (`maxIterationsReached: true`). This becomes a graceful termination rather than a failure.
-- **Tool crash:** Tool errors are caught by the SDK runtime, formatted as a tool result, and sent back to the LLM. The LLM decides whether to retry, try a different approach, or give up.
-- **Model refusal:** If the model refuses the prompt, the SDK retries once with an adjusted system prompt. If the retry also refuses, the agent fails with `code: 'MODEL_REFUSAL'`.
-- **Model API error:** Network errors, rate limits, or server errors from the model provider. The SDK retries with exponential backoff (3 attempts, 1s/2s/4s), then fails with `code: 'MODEL_ERROR'`.
-- **Agent error response includes:** `iterationCount` (LLM iterations completed), `toolCallHistory` (array of tool calls made), `lastModelResponse` (final response from the LLM before failure).
-
----
-
-## Circuit Breaker
-
-**Status: Planned.**
-
-The platform will implement a circuit breaker to prevent runaway failures:
-
-- **Trip condition:** 5 consecutive failures on the same resource within a 10-minute window
-- **Action:** Pause executions for 60 seconds. New execution requests for that resource return `503` with: "Resource temporarily unavailable (circuit breaker tripped)"
-- **Auto-recovery:** After the 60-second pause, the next execution attempt is allowed through. If it succeeds, the circuit breaker resets. If it fails, the pause extends (120s, then 240s, capped at 5 minutes).
-- **Alerting:** You are notified via webhook callback or email when the circuit breaker trips. Configurable per organization.
-
----
-
-## Metrics
-
-**Status: Planned.**
-
-### Auto-Collected
-
-The SDK runtime and platform will automatically collect these metrics for every execution:
-
-- `execution_duration_ms` -- Total wall-clock time from request received to result sent
-- `step_duration_ms` -- Per-step timing for workflows (array of `{ stepId, durationMs }`)
-- `iteration_count` -- Number of LLM loop iterations for agents
-- `ai_token_usage` -- Token counts per model call: `{ prompt_tokens, completion_tokens, total_tokens }`
-- `ai_cost_usd` -- Calculated from model pricing multiplied by token usage
-- `tool_call_count` -- Total number of tool invocations during the execution
-- `tool_call_duration_ms` -- Per-tool timing (array of `{ toolName, durationMs }`)
-- `error_count` -- Number of errors encountered (including recovered errors)
-
-### Cost Attribution
-
-Metrics are aggregated at multiple levels:
-
-- **Per-execution:** Total AI spend and total duration
-- **Per-resource:** Aggregated over configurable time periods (daily, weekly, monthly)
-- **Per-organization:** Total platform cost (execution time + AI spend + managed hosting compute)
-- **Visibility:** Platform dashboard and the CLI via `elevasis-sdk executions <resourceId>`
-
-### Developer-Defined Metrics
-
-A future SDK version will support custom metrics emitted from your handlers:
-
-- `sdk.metrics.counter('custom_name', value)` -- Increment a counter
-- `sdk.metrics.gauge('queue_depth', value)` -- Set a point-in-time gauge value
-- Custom metrics are stored alongside auto-collected metrics and queryable through the same APIs
-
----
-
-## Alerting
-
-**Status: Planned.**
-
-Developer-configurable alerts for production monitoring:
-
-- **Error rate threshold:** Notify when more than X% of executions fail within Y minutes
-- **Latency percentile:** Notify when p95 execution duration exceeds a threshold
-- **Cost budget:** Notify when daily or weekly AI spend exceeds a configured limit
-- **Channel:** Webhook callback to a developer-provided URL (integrates with Slack, PagerDuty, and similar services via webhook)
-
----
-
-## Resource Lifecycle Extensions
-
-**Status: Planned.**
-
-### Deprecation Status
-
-Beyond the current `dev` and `prod` statuses, two additional statuses are planned:
-
-- **`deprecated`** -- Marked via the platform UI. Existing executions continue working. New executions show a warning: "This resource is deprecated." The resource still appears in the platform and can still be triggered.
-- **`offline`** -- Set automatically when a deployment is unregistered (for example, after a failed deploy or explicit deletion). Clears automatically on the next successful deploy. No executions are accepted while a resource is offline.
-
-Deprecation requires no automatic removal -- the developer must explicitly delete the resource to remove it.
-
----
-
-**Last Updated:** 2026-03-08
+---
+title: Roadmap
+description: Planned SDK features -- error taxonomy, retry semantics, circuit breaker, metrics, alerting, and resource lifecycle extensions
+---
+
+**Status:** Mixed -- some features below are implemented, others remain planned. Each section notes its current status.
+
+For currently implemented behavior, see [Runtime](runtime.mdx).
+
+---
+
+## Structured Error Taxonomy
+
+**Status: Partially implemented.** The runtime has a structured error hierarchy (`ExecutionError`, `PlatformToolError`, `ToolingError`) with error codes and context fields. The taxonomy below describes a planned _redesign_ that is not yet implemented.
+
+The current runtime reports errors as plain strings. A future SDK version will introduce a structured error taxonomy. All SDK errors will extend `ResourceError`, the base class for errors surfaced through the execution protocol.
+
+Every error carries: `message` (string), `code` (string enum), `details` (optional structured data), and `retryable` (boolean).
+
+**Error types:**
+
+- **`ResourceError`** -- Base class for all SDK errors
+- **`ValidationError`** -- Input or output schema validation failed. Thrown automatically when Zod `.parse()` fails. Code: `VALIDATION_ERROR`. Not retryable.
+- **`StepError`** -- A workflow step handler threw. Includes `stepId` and `stepName`. Code: `STEP_ERROR`. Retryable (transient failures may succeed on retry).
+- **`ToolError`** -- A tool execution failed. Includes `toolName`. Code: `TOOL_ERROR`. Retryability depends on the underlying error.
+- **`TimeoutError`** -- Execution exceeded the deadline. Code: `TIMEOUT`. Retryable.
+- **`CancellationError`** -- Execution was cancelled by the platform or user. Code: `CANCELLED`. Not retryable.
+
+---
+
+## Retry Semantics
+
+**Status: Planned.**
+
+Retries are platform-side only -- workers are ephemeral and never retry internally.
+
+- **Configuration:** Per-resource via `maxRetries` (default: 0) and `backoffStrategy` (exponential with jitter)
+- **Retryable conditions:** Worker crash or timeout (worker terminated by `AbortSignal`)
+- **Non-retryable conditions:** Worker reports `status: 'failed'` (handler ran and returned an error -- application logic, not infrastructure failure), user cancellation
+- **Idempotency:** On retry, the same `executionId` is reused. Design handlers to be idempotent where possible.
+
+---
+
+## Workflow Step Failure
+
+**Status: Planned.** The current runtime uses fail-fast behavior: when a step handler throws, the worker logs a `step-failed` context entry and re-throws the original error unchanged. The `onError` callback, `completedSteps`, and `partialOutput` features described below are not yet implemented.
+
+Default behavior is fail-fast: when a step throws, the workflow fails immediately.
+
+- **Error handler:** Optional `onError` callback per step. The callback receives the error and can return a recovery value or rethrow to propagate the failure.
+- **Partial output:** Steps completed before the failure are included in the error response. The platform receives: `failedStepId`, `completedSteps[]` (IDs of successfully completed steps), and `partialOutput` (the last successful step's output).
+
+**Proposed step error response format** (not yet implemented -- subject to change):
+
+```json
+{
+  "status": "failed",
+  "error": {
+    "code": "STEP_ERROR",
+    "message": "Email delivery failed: invalid address",
+    "stepId": "send-welcome",
+    "stepName": "Send Welcome Email"
+  },
+  "completedSteps": ["validate"],
+  "partialOutput": { "clientName": "Jane", "isValid": true }
+}
+```
+
+---
+
+## Agent Failure Modes
+
+**Status: Planned.** Agent execution runs in ephemeral worker threads with full tool calling support via `PostMessageLLMAdapter`. The current runtime uses fail-fast behavior for all agent error paths; the richer failure handling described below is not yet implemented.
+
+**Current behavior:** Any unhandled error from the agent (including `AgentMaxIterationsError` thrown by `@repo/core` when the iteration limit is reached) propagates out of the worker and is reported as a failed execution. The worker sends: `{ type: 'result', status: 'failed', error: 'ErrorName: message', logs, metrics: { durationMs } }`. There is no graceful termination, partial output, or retry logic in the worker itself.
+
+**Planned improvements:**
+
+- **Max iterations reached:** Instead of throwing, the agent returns the best output produced so far, plus a warning flag (`maxIterationsReached: true`). This becomes a graceful termination rather than a failure.
+- **Tool crash:** Tool errors are caught by the SDK runtime, formatted as a tool result, and sent back to the LLM. The LLM decides whether to retry, try a different approach, or give up.
+- **Model refusal:** If the model refuses the prompt, the SDK retries once with an adjusted system prompt. If the retry also refuses, the agent fails with `code: 'MODEL_REFUSAL'`.
+- **Model API error:** Network errors, rate limits, or server errors from the model provider. The SDK retries with exponential backoff (3 attempts, 1s/2s/4s), then fails with `code: 'MODEL_ERROR'`.
+- **Agent error response includes:** `iterationCount` (LLM iterations completed), `toolCallHistory` (array of tool calls made), `lastModelResponse` (final response from the LLM before failure).
+
+---
+
+## Circuit Breaker
+
+**Status: Planned.**
+
+The platform will implement a circuit breaker to prevent runaway failures:
+
+- **Trip condition:** 5 consecutive failures on the same resource within a 10-minute window
+- **Action:** Pause executions for 60 seconds. New execution requests for that resource return `503` with: "Resource temporarily unavailable (circuit breaker tripped)"
+- **Auto-recovery:** After the 60-second pause, the next execution attempt is allowed through. If it succeeds, the circuit breaker resets. If it fails, the pause extends (120s, then 240s, capped at 5 minutes).
+- **Alerting:** You are notified via webhook callback or email when the circuit breaker trips. Configurable per organization.
+
+---
+
+## Metrics
+
+**Status: Planned.**
+
+### Auto-Collected
+
+The SDK runtime and platform will automatically collect these metrics for every execution:
+
+- `execution_duration_ms` -- Total wall-clock time from request received to result sent
+- `step_duration_ms` -- Per-step timing for workflows (array of `{ stepId, durationMs }`)
+- `iteration_count` -- Number of LLM loop iterations for agents
+- `ai_token_usage` -- Token counts per model call: `{ prompt_tokens, completion_tokens, total_tokens }`
+- `ai_cost_usd` -- Calculated from model pricing multiplied by token usage
+- `tool_call_count` -- Total number of tool invocations during the execution
+- `tool_call_duration_ms` -- Per-tool timing (array of `{ toolName, durationMs }`)
+- `error_count` -- Number of errors encountered (including recovered errors)
+
+### Cost Attribution
+
+Metrics are aggregated at multiple levels:
+
+- **Per-execution:** Total AI spend and total duration
+- **Per-resource:** Aggregated over configurable time periods (daily, weekly, monthly)
+- **Per-organization:** Total platform cost (execution time + AI spend + managed hosting compute)
+- **Visibility:** Platform dashboard and the CLI via `elevasis-sdk executions <resourceId>`
+
+### Developer-Defined Metrics
+
+A future SDK version will support custom metrics emitted from your handlers:
+
+- `sdk.metrics.counter('custom_name', value)` -- Increment a counter
+- `sdk.metrics.gauge('queue_depth', value)` -- Set a point-in-time gauge value
+- Custom metrics are stored alongside auto-collected metrics and queryable through the same APIs
+
+---
+
+## Alerting
+
+**Status: Planned.**
+
+Developer-configurable alerts for production monitoring:
+
+- **Error rate threshold:** Notify when more than X% of executions fail within Y minutes
+- **Latency percentile:** Notify when p95 execution duration exceeds a threshold
+- **Cost budget:** Notify when daily or weekly AI spend exceeds a configured limit
+- **Channel:** Webhook callback to a developer-provided URL (integrates with Slack, PagerDuty, and similar services via webhook)
+
+---
+
+## Resource Lifecycle Extensions
+
+**Status: Planned.**
+
+### Deprecation Status
+
+Beyond the current `dev` and `prod` statuses, two additional statuses are planned:
+
+- **`deprecated`** -- Marked via the platform UI. Existing executions continue working. New executions show a warning: "This resource is deprecated." The resource still appears in the platform and can still be triggered.
+- **`offline`** -- Set automatically when a deployment is unregistered (for example, after a failed deploy or explicit deletion). Clears automatically on the next successful deploy. No executions are accepted while a resource is offline.
+
+Deprecation requires no automatic removal -- the developer must explicitly delete the resource to remove it.
+
+---
+
+**Last Updated:** 2026-03-08

package/reference/rules/organization-model.md

@@ -2,6 +2,7 @@
 description: Edits to the canonical organization model go through /om
 paths:
   - core/config/organization-model.ts
+  - core/config/organization-model/**/*.ts
   - core/config/extensions/**/*.ts
 ---
 <!-- @generated by packages/sdk/scripts/copy-reference-docs.mjs -- DO NOT EDIT -->
@@ -18,6 +19,19 @@ New semantic authoring should start in system-colocated `ontology` scopes. Top-l
 `entities` and top-level `actions` remain compatibility mirrors while published
 consumers finish moving to compiled ontology indexes. `System.content` is retired.
 
+## File Layout
+
+Projects keep the organization model either as a single `core/config/organization-model.ts`
+file, or split into an entry file plus a sibling directory. Both layouts are valid; the entry
+filename never changes, so consumer imports and the SDK loader resolve identically:
+
+- `organization-model.ts` -- ENTRY: assembles the model and re-exports every public symbol.
+- `organization-model/profile.ts` -- the `defineOrganizationModel(...)` body (identity, customers, offerings, roles, goals). Primary `/om` codify write target.
+- `organization-model/systems.ts` -- systems, resources, topology, entities, actions, resource governance, feature/system-ID constants.
+- `organization-model/navigation.ts` -- sidebar navigation and surface projection; imports `systems.ts` directly to stay acyclic.
+
+`/om` routes domain edits to the right file automatically (identity/customers/offerings/roles/goals → `profile.ts`; systems/actions/resources → `systems.ts`). Unsplit projects default every edit to the entry file.
+
 ## Preferred Entry Point: `/om`
 
 Direct edits to `organization-model.ts` are discouraged. Instead, use `/om` (or