@elevasis/sdk 0.4.5 → 0.4.7

package/reference/resources/types.mdx

@@ -0,0 +1,207 @@
+---
+title: SDK Types
+description: Complete type reference for @elevasis/sdk -- package exports, re-exported platform types, ElevasConfig interface, StepHandler context, and runtime values
+loadWhen: "Looking up type signatures or SDK exports"
+---
+
+`@elevasis/sdk` is published to the public npm registry. It bundles all platform types from `@repo/core` into a single self-contained type declaration file with zero internal monorepo references. External developers install the package and get full TypeScript support without any monorepo tooling.
+
+```
+npm install @elevasis/sdk zod
+```
+
+Zod is a peer dependency and must be installed separately.
+
+---
+
+## Package Exports
+
+The package exposes two subpaths:
+
+```json
+{
+  "exports": {
+    ".": { "types": "./dist/index.d.ts", "import": "./dist/index.js" },
+    "./worker": { "import": "./dist/worker/index.js" }
+  }
+}
+```
+
+- `@elevasis/sdk` -- all types plus runtime values (`StepType`, `ExecutionError`, `ToolingError`)
+- `@elevasis/sdk/worker` -- worker runtime module (`startWorker`, `platform`, `PlatformToolError`)
+
+---
+
+## Type Re-exports
+
+All types come from the platform core. The SDK re-exports them grouped by source domain:
+
+### Platform Types
+
+| Type | Description |
+| ---- | ----------- |
+| `ResourceDefinition` | Base interface for all resource types |
+| `ResourceType` | Enum: `'workflow' | 'agent'` |
+| `ResourceStatus` | Enum: `'dev' | 'production'` |
+| `ResourceDomain` | Domain classification for a resource |
+| `DomainDefinition` | Structure for grouping resources by domain |
+| `OrganizationResources` | Top-level export shape: `{ workflows, agents }` |
+| `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 |
+
+### Execution Types
+
+| Type | Description |
+| ---- | ----------- |
+| `WorkflowDefinition` | Complete workflow definition including config, contract, steps, entryPoint |
+| `WorkflowStep` | Individual step definition with type, handler, and next routing |
+| `WorkflowConfig` | Metadata block: name, description, status |
+| `StepHandler` | Function type: `(input: unknown, context: StepContext) => Promise<unknown>` |
+| `NextConfig` | Union of `LinearNext` and `ConditionalNext` |
+| `LinearNext` | `{ target: string }` -- fixed next step |
+| `ConditionalNext` | `{ routes: Route[], defaultTarget: string }` -- branching routing |
+| `StepType` | Runtime enum: `LINEAR | CONDITIONAL` (also a runtime value -- see below) |
+| `AgentDefinition` | Complete agent definition including config, agentConfig, tools |
+| `AgentConfig` | Agent metadata: name, description, status |
+| `AgentConstraints` | Execution limits for agents |
+| `Tool` | Tool definition for agent use |
+| `ToolExecutionOptions` | Options passed when a tool executes |
+| `ToolingErrorType` | Enum of tool error categories |
+| `ToolingError` | Error class for tool execution failures (also a runtime value -- see below) |
+| `ExecutionError` | Error class for execution-level failures (also a runtime value -- see below) |
+| `Contract` | Input/output Zod schema pair |
+| `ExecutionContext` | Runtime context passed to step handlers |
+| `ExecutionMetadata` | Metadata about a running execution |
+| `LLMModel` | Model identifier: provider + model name |
+| `ModelConfig` | Full model configuration including temperature and token limits |
+| `ExecutionInterface` | Interface for triggering and inspecting executions |
+
+### Form and Metrics Types
+
+| Type | Description |
+| ---- | ----------- |
+| `FormField` | Individual form field definition |
+| `FormSchema` | Collection of form fields |
+| `FormFieldType` | Enum of supported field types |
+| `ResourceMetricsConfig` | Observability configuration for a resource |
+
+---
+
+## ElevasConfig
+
+`ElevasConfig` is the only type defined by the SDK itself (not re-exported from the platform). It configures SDK behavior via `elevasis.config.ts` in your project root.
+
+```typescript
+export interface ElevasConfig {
+  defaultStatus?: ResourceStatus
+  dev?: { port?: number }
+}
+```
+
+| Field | Type | Default | Description |
+| ----- | ---- | ------- | ----------- |
+| `defaultStatus` | `'dev' | 'production'` | `'production'` | Default status applied to all resources that do not set their own `config.status`. Set to `'dev'` to keep resources inactive while building. |
+| `dev.port` | `number` | `3001` | Local port for the development worker process. Change this if port 3001 conflicts with another service. |
+
+Usage:
+
+```typescript
+import type { ElevasConfig } from '@elevasis/sdk';
+
+const config: ElevasConfig = {
+  defaultStatus: 'dev',
+  dev: { port: 3002 },
+};
+
+export default config;
+```
+
+---
+
+## StepHandler Context
+
+`StepHandler` accepts two parameters: `input` (validated by your contract schema) and `context` (runtime metadata). The `context` parameter is not optional in the type definition, but TypeScript allows you to omit it in your handler function -- writing `async (input) => { ... }` works without error.
+
+```typescript
+import type { StepHandler, ExecutionContext } from '@elevasis/sdk';
+
+const handler: StepHandler = async (input, context: ExecutionContext) => {
+  const { executionId, organizationId, resourceId, logger, store } = context;
+
+  logger.info('Processing', { executionId, resourceId });
+
+  await store.set('checkpoint', JSON.stringify({ step: 'started' }));
+
+  return { done: true };
+};
+```
+
+### ExecutionContext Fields
+
+| Field | Type | Description |
+| ----- | ---- | ----------- |
+| `executionId` | `string` | Unique identifier for this execution run |
+| `organizationId` | `string` | Your organization identifier |
+| `resourceId` | `string` | Identifier of the executing workflow or agent |
+| `logger` | `Logger` | Structured logger -- messages appear in the Elevasis dashboard under the execution |
+| `store` | `Store` | Key-value store scoped to the current execution. Useful for passing data between steps or checkpointing progress. |
+
+---
+
+## Runtime Values
+
+Three runtime values are exported from `@elevasis/sdk` as JavaScript values (not just types). They are defined directly in the SDK package to avoid pulling in the full platform execution engine.
+
+### StepType
+
+An enum used to configure step routing in multi-step workflows.
+
+```typescript
+import { StepType } from '@elevasis/sdk';
+
+// StepType.LINEAR   -- fixed next step via { target: 'stepName' }
+// StepType.CONDITIONAL -- branching via { routes: [...], defaultTarget: 'stepName' }
+```
+
+### ToolingError
+
+Thrown by platform tool calls when a tool fails. Use this class to distinguish tool failures from general errors in `try/catch` blocks.
+
+```typescript
+import { ToolingError } from '@elevasis/sdk';
+
+try {
+  const result = await platform.call({ ... });
+} catch (err) {
+  if (err instanceof ToolingError) {
+    // tool-specific failure -- check err.type for category
+    console.error('Tool failed:', err.type, err.message);
+  } else {
+    throw err; // re-throw unexpected errors
+  }
+}
+```
+
+### ExecutionError
+
+Represents a failure at the execution level (distinct from a tool-level failure). Throw this from a step handler to signal that the execution should be marked as failed with a structured error message.
+
+```typescript
+import { ExecutionError } from '@elevasis/sdk';
+
+const handler = async (input) => {
+  if (!input.userId) {
+    throw new ExecutionError('userId is required', { code: 'MISSING_INPUT' });
+  }
+  return { result: 'ok' };
+};
+```
+
+---
+
+**Last Updated:** 2026-02-25

package/reference/roadmap/index.mdx

@@ -0,0 +1,147 @@
+---
+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:** Planned -- none of these features are implemented yet.
+
+For currently implemented behavior, see [Runtime](../runtime/index.mdx).
+
+---
+
+## Structured Error Taxonomy
+
+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
+
+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
+
+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).
+
+**Step error response format:**
+
+```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
+
+Agents have multiple failure paths due to the LLM loop:
+
+- **Max iterations reached:** The agent returns the best output produced so far, plus a warning flag (`maxIterationsReached: true`). This is a graceful termination, not an error.
+- **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
+
+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
+
+### 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 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
+
+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
+
+### Deprecation Status
+
+Beyond the current `dev` and `production` 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-02-25

package/reference/runtime/index.mdx

@@ -0,0 +1,141 @@
+---
+title: Execution Runtime
+description: How your code runs on the Elevasis platform -- execution lifecycle, concurrency, timeouts, cancellation, error handling, and observability
+loadWhen: "Debugging execution behavior or understanding the runtime model"
+---
+
+This page covers everything that happens after you deploy -- how resources execute as managed processes, how failures surface to you, and what observability data you can access. For resource limits and quotas, see [Resource Limits & Quotas](limits.mdx).
+
+---
+
+## Execution Lifecycle
+
+### The Four Stages
+
+Every execution traverses four stages: trigger, route, execute, and return.
+
+1. **Trigger** -- A user, CLI command, or API call initiates execution. The platform creates an execution record with `status: 'running'` and generates a unique `executionId`.
+2. **Route** -- The platform resolves the target resource from the registry. All resources (static and external) coexist in a single in-memory registry with no database queries at lookup time.
+3. **Execute** -- An ephemeral worker thread is created from your deployed bundle and sent the execution request. The worker matches the `resourceId` to your definition, validates the input against your Zod schema, and runs the handler. For workflows, steps execute sequentially following the `next` chain. The worker is terminated immediately after execution completes.
+4. **Return** -- The worker posts the result back to the platform. The platform stores the final result, updates the execution record, and fans events out to AI Studio and CLI subscribers.
+
+### Concurrency Model
+
+Workers are ephemeral -- each execution creates a new worker thread. There is no persistent pool:
+
+- **Per-execution isolation:** Each execution gets its own worker thread. Concurrent executions for the same organization run in separate workers with no shared state.
+- **Memory:** Each worker is capped at 256MB. Concurrent workers multiply memory usage proportionally.
+- **No cold start:** Workers are created fresh per execution. Your first execution and hundredth are identical in terms of startup behavior.
+
+### Timeout Enforcement
+
+Timeouts are enforced by the platform. You do not handle them explicitly in your code:
+
+- **Default timeout:** A platform default applies to all resource types unless overridden.
+- **Per-resource override:** Agents can configure `constraints.timeout` in the agent definition. Workflows use the platform default.
+- **Enforcement:** When a timeout fires, the worker is terminated immediately -- even if it is stuck in a synchronous loop. No special handler signature is required on your part.
+
+### Cancellation Protocol
+
+Cancellation is initiated by the platform and requires no special code in your handler:
+
+1. A cancellation request is received -- via CLI, API, or platform timeout.
+2. The platform aborts the execution controller registered for that `executionId`.
+3. The worker is terminated immediately (kills the worker even if stuck in a synchronous loop).
+4. The platform records the cancellation in the execution record.
+
+**What triggers cancellation:**
+
+- You call `POST /api/external/executions/:resourceId/:executionId/cancel` via CLI or API
+- The platform timeout expires
+- The resource is deleted while an execution is in-flight
+
+---
+
+## Error Handling
+
+### How Errors Reach You
+
+Errors are displayed depending on the surface you use to inspect them:
+
+- **AI Studio:** Shows the error message and execution status. Example: `Remote resource 'onboard-client' failed: Email delivery failed: invalid address`
+- **CLI (`elevasis execution <resourceId> <id>`):** Shows full execution detail including the error message. The `--json` flag includes an `error` field in structured output.
+- **Error message source:** The error string comes directly from your handler's catch block (`String(err)`). The platform stores this verbatim and displays it as-is. Write descriptive error messages in your handlers -- they surface directly to users.
+
+### What Causes a Failed Execution
+
+- **Unhandled exception in your handler:** The worker reports `status: 'failed'` with the error message.
+- **Memory limit exceeded (256MB):** The worker crashes with an out-of-memory error. The platform catches this; other tenants are unaffected.
+- **Timeout exceeded:** The platform terminates the worker and marks the execution failed with a timeout reason.
+- **Cancellation:** Execution is marked cancelled.
+
+---
+
+## Observability
+
+### Logging
+
+You produce logs using standard `console` methods -- no special logger object is needed:
+
+- **Console interception:** The SDK worker runtime intercepts `console.log`, `console.warn`, and `console.error` during handler execution and captures them as structured `{ level, message }` entries.
+- **Level mapping:** `console.log` maps to `info`, `console.warn` maps to `warn`, `console.error` maps to `error`.
+- **No changes required:** Any code that already uses `console.log` automatically has its output captured. Existing code works without modification.
+
+### Log Transport
+
+Logs are delivered to the platform atomically with the execution result:
+
+- **Bundled delivery:** All logs for an execution are included in the result message when the handler completes. There is no real-time streaming -- logs arrive with the final result.
+- **Crash behavior:** If the worker crashes before completing, logs captured up to the crash point are lost. The platform records only the crash error.
+
+### Log Retention and Display
+
+- **Retention:** 30 days by default (configurable per plan).
+- **Real-time fanout:** After execution completes, logs are stored and fanned out to AI Studio and CLI subscribers. AI Studio shows them in the execution detail view.
+- **CLI access:** Use `elevasis execution <resourceId> <id>` to view execution details including logs.
+
+---
+
+## Resource Lifecycle
+
+### Status
+
+Every resource on the platform has a status that you control in your definition:
+
+- **`dev`** -- Default for new resources. Visible in AI Studio and executable, but marked with a "Development" badge. Use this during testing and iteration.
+- **`prod`** -- Set `status: 'prod'` in your resource definition before deploying. No badge. This is the live, production-ready state.
+
+### Versioning
+
+v1 versioning is intentionally simple:
+
+- **One active version per resource per org.** Deploying replaces the running version. There is no version history at the resource level; previous deploys are marked stopped.
+- **Immutable per deploy.** A resource definition is frozen at deploy time. Changing code requires a new deploy.
+
+### Deletion
+
+- **Via CLI:** Remove the resource from your `OrganizationResources` export and run `elevasis deploy`. Resources absent from the new bundle are automatically deregistered from the platform.
+- **Via AI Studio:** The delete button unregisters the resource immediately and marks the deployment stopped.
+- **In-flight executions:** Workers already running complete normally. Deletion affects only new execution attempts.
+- **Data retention:** Execution logs and history for a deleted resource are retained for 30 days, then purged.
+
+---
+
+## Platform Storage
+
+Your deployed bundle is stored in Supabase Storage. On API restart, the platform re-registers all active deployments from the database and re-downloads bundles if needed. This means:
+
+- **No data loss on restart:** Your resources are automatically re-registered after platform restarts.
+- **No action required from you:** The platform handles recovery transparently.
+
+---
+
+## Platform Maintenance
+
+- **Rolling updates:** Platform upgrades trigger a re-registration of all active deployments on startup. No in-flight executions are lost (workers are ephemeral and complete independently).
+- **In-flight executions during restart:** Already-running workers complete normally. New executions use the newly reloaded registry after restart.
+- **Advance notice:** You will receive 24-hour advance notice for breaking maintenance windows. These are rare and reserved for major infrastructure changes.
+
+---
+
+**Last Updated:** 2026-02-25

package/reference/runtime/limits.mdx

@@ -0,0 +1,77 @@
+---
+title: Resource Limits & Quotas
+description: Memory limits, execution timeouts, scale quotas, networking constraints, and v1 platform limitations for SDK resources
+loadWhen: "Hitting resource limits or planning for scale"
+---
+
+This page documents the hard limits enforced on all SDK resources running on the Elevasis platform. These limits exist to ensure platform stability and fair resource usage across all organizations.
+
+---
+
+## Resource Limits
+
+Limits enforced per worker thread at runtime:
+
+| Resource | Value |
+| -------- | ----- |
+| Memory (V8 heap) | 256MB per worker |
+| Disk | Bundle file only (ephemeral, not persistent across deploys) |
+
+- **Memory:** Enforced by the platform. Exceeding 256MB crashes the worker. The platform catches the error; other tenants are unaffected. If your workflow processes large datasets, consider streaming or batching to stay within the limit.
+- **Disk:** Your bundle is written to disk during deploy and available to the worker at execution time. It is not a persistent write surface -- do not write files to disk from within your handler expecting them to persist.
+
+---
+
+## Scale Limits & Quotas
+
+Hard limits to prevent abuse and ensure platform stability:
+
+| Limit | Value |
+| ----- | ----- |
+| Max resources per org | 50 |
+| Max execution duration (workflows) | 300s (5 min) |
+| Max execution duration (agents) | 600s (10 min) |
+| Max log volume | 100MB/day |
+| Max deploy frequency | 60/day |
+
+- **Resources per org:** The combined count of all workflows and agents across your organization cannot exceed 50.
+- **Execution duration:** Executions exceeding the timeout are terminated by the platform. The execution is marked failed with a timeout reason.
+- **Log volume:** Total log output across all executions is capped at 100MB per day. Logs beyond this threshold may be truncated.
+- **Deploy frequency:** 60 deploys per day is generous for normal development. This limit prevents accidental deploy loops (for example, a CI pipeline misconfigured to deploy on every commit).
+
+---
+
+## Networking
+
+- **Outbound:** Unrestricted. Your handlers can call any external API (OpenAI, Twilio, Stripe, etc.) from within the worker.
+- **Inbound:** Workers receive input from the platform coordinator via internal message passing -- they are not exposed to the network directly.
+- **No ports:** Workers communicate with the platform via zero-network-overhead message passing. No port allocation occurs.
+- **Isolation:** Workers have no access to other organizations' data or platform credentials by default. Supabase credentials are not present in the worker environment.
+
+---
+
+## Platform Maintenance
+
+- **Rolling updates:** Platform upgrades re-register all active deployments on startup. No executions are lost.
+- **Node.js updates:** When the server's Node.js version is updated, worker threads pick up the new version on the next execution with no action required from you.
+- **Advance notice:** 24-hour advance notice is provided for breaking maintenance windows. These are rare and reserved for major infrastructure changes.
+
+---
+
+## v1 Limitations
+
+| Limitation | Reason | Future path |
+| ---------- | ------ | ----------- |
+| **No nested execution from external resources** | External resources cannot call back to the platform's execution coordinator to trigger other resources as sub-executions. | A callback API endpoint that external processes can call to trigger nested executions (requires auth token forwarding). |
+| **No streaming logs** | Execution logs are returned in the response body after completion. There is no real-time SSE streaming from within the worker. | SSE/WebSocket push from external processes to the platform log system. |
+| **Static resource priority conflicts** | If your organization has a static (monorepo) resource with the same ID as a resource in your SDK bundle, the deploy will fail. Static definitions always take priority and cannot be overridden. | Conflict detection is surfaced in the CLI with a clear error message. |
+
+---
+
+## Organization Provisioning
+
+Organization creation is currently admin-only. If you need a new organization provisioned for SDK access, contact the Elevasis team. Self-serve organization creation and API key generation is on the roadmap.
+
+---
+
+**Last Updated:** 2026-02-25