@elevasis/sdk 1.10.0 → 1.12.0

package/reference/packages/core/src/organization-model/README.md

@@ -1,97 +1,102 @@
-# Organization Model
-
-The organization model is the published semantic contract that maps a tenant's product shape to domain surfaces, features, and navigation.
-
-Use this module when you need to resolve or validate an organization's contract before wiring UI shells, routing, or domain-specific capability checks.
-
-## Published Exports
-
-The public entry point exposes:
-
-- `OrganizationModelSchema`
-- `DEFAULT_ORGANIZATION_MODEL`
-- `defineOrganizationModel`
-- `resolveOrganizationModel`
-- `PROJECTS_FEATURE_ID`
-- `PROJECTS_INDEX_SURFACE_ID`
-- `PROJECTS_VIEW_CAPABILITY_ID`
-- `OrganizationModel` and the supporting domain types
-
-Import it from the published subpath:
-
-```ts
-import {
-  DEFAULT_ORGANIZATION_MODEL,
-  PROJECTS_VIEW_CAPABILITY_ID,
-  defineOrganizationModel,
-  PROJECTS_FEATURE_ID,
-  PROJECTS_INDEX_SURFACE_ID,
-  resolveOrganizationModel,
-  type OrganizationModel
-} from '@elevasis/core/organization-model'
-```
-
-## Contract Shape
-
-The model is versioned and currently validates against `version: 1`.
-
-Top-level fields:
-
-- `version` - schema version for the resolved contract.
-- `branding` - organization branding defaults and overrides.
-- `features` - unified feature entries that combine enablement, labels, and semantic references.
-- `navigation` - navigation model for the product shell.
-- `sales` - sales pipeline and relationship management.
-- `prospecting` - lists, companies, and contacts.
-- `projects` - projects, milestones, and tasks.
-- `identity`, `customers`, `offerings`, `roles`, `goals` - reality domains (2026-04 expansion).
-- `statuses` - unified status registry across delivery / hitl / execution / request / schedule.
-- `operations` - catalog of stateful runtime entities (HITL queue, sessions, executions, notifications, schedules).
-- `resourceMappings` - cross-surface resource mappings (includes techStack subsection).
-
-## Default Feature Set
-
-The default model includes eight feature IDs:
-
-- `sales` - deal pipeline and relationship management.
-- `prospecting` - lists, companies, and contacts.
-- `projects` - projects, milestones, and tasks.
-- `operations` - organization graph and command-view surfaces.
-- `monitoring` - monitoring surfaces.
-- `settings` - organization settings.
-- `seo` - SEO surfaces (disabled by default).
-- `configure` - `/configure` skill entry point (external projects).
-
-## Project Bridge Constants
-
-The organization-model surface exports a narrow set of canonical IDs for the shared Projects bridge:
-
-- `PROJECTS_FEATURE_ID` -> `projects`
-- `PROJECTS_INDEX_SURFACE_ID` -> `projects.index`
-- `PROJECTS_VIEW_CAPABILITY_ID` -> `delivery.projects.view`
-
-Use these when wiring shared UI manifests, template adapters, or other consumers that need to agree on the same Projects contract without repeating raw literals.
-
-## Resolution Semantics
-
-- `defineOrganizationModel()` is a typed helper. It does not validate or merge anything by itself.
-- `resolveOrganizationModel()` deep-merges a partial override into the default model, then validates the result with `OrganizationModelSchema`.
-- Plain objects merge recursively.
-- Arrays replace the default value instead of merging element-by-element.
-- If `navigation.surfaces` is replaced without also supplying `navigation.groups`, inherited default groups are dropped when they no longer point at declared surfaces.
-- Missing fields fall back to `DEFAULT_ORGANIZATION_MODEL`.
-
-## Referential Integrity
-
-- `navigation.defaultSurfaceId` must point at a declared navigation surface.
-- Every navigation group `surfaceId` must resolve to a declared surface.
-- Feature, surface, and resource-mapping IDs must resolve to declared counterparts; dangling references fail validation.
-- Feature-to-surface and feature/surface-to-resource links are validated in both directions so one-sided declarations fail during resolution.
-- Feature-bearing surfaces validate `featureId` against the canonical feature set.
-
-## Practical Guidance
-
-- Use `resolveOrganizationModel()` when you need a runtime-safe model for rendering or policy checks.
-- Use `defineOrganizationModel()` when authoring a static partial model in source.
-- Treat feature IDs such as `sales`, `prospecting`, and `projects` as the canonical shell-level contract in new organization-model authoring.
-- Keep feature IDs, surface IDs, and capability IDs stable because downstream UI and policy code depend on them.
+# Organization Model
+
+The organization model is the published semantic contract that maps a tenant's product shape to flat feature hierarchy, shell navigation, business semantics, and graph bindings.
+
+Use this module when resolving or validating an organization's contract before wiring UI shells, routing, feature gates, or domain-specific capability checks.
+
+## Published Exports
+
+The public entry point exposes:
+
+- `OrganizationModelSchema`
+- `FeatureSchema`
+- `DEFAULT_ORGANIZATION_MODEL`
+- `defineOrganizationModel`
+- `resolveOrganizationModel`
+- `createFoundationOrganizationModel`
+- node ID and feature helper types
+- `OrganizationModel` and supporting domain types
+
+Import it from the published subpath:
+
+```ts
+import {
+  DEFAULT_ORGANIZATION_MODEL,
+  createFoundationOrganizationModel,
+  defineOrganizationModel,
+  resolveOrganizationModel,
+  type OrganizationModel
+} from '@elevasis/core/organization-model'
+```
+
+## Contract Shape
+
+The model is versioned and currently validates against `version: 1`.
+
+Top-level fields:
+
+- `version`
+- `branding`
+- `features`
+- `navigation`
+- `sales`
+- `prospecting`
+- `projects`
+- `identity`
+- `customers`
+- `offerings`
+- `roles`
+- `goals`
+- `statuses`
+- `operations`
+
+Resources bind to the graph from deployment metadata through `links` and `category`.
+
+## Feature Set
+
+Feature hierarchy is authored as a flat array. Dotted IDs define parent/child relationships:
+
+```ts
+features: [
+  { id: 'dashboard', label: 'Dashboard', enabled: true, path: '/', uiPosition: 'sidebar-primary' },
+  { id: 'sales', label: 'Sales', enabled: true, uiPosition: 'sidebar-primary' },
+  { id: 'sales.crm', label: 'CRM', enabled: true, path: '/crm' },
+  { id: 'operations.resources', label: 'Resources', enabled: true, path: '/operations/resources' }
+]
+```
+
+Containers omit `path`; leaves provide `path`. `uiPosition`, `requiresAdmin`, and `devOnly` inherit from ancestors.
+Development-only features remain in the contract with `enabled: true` and `devOnly: true`; shell consumers hide them and guard their paths outside development mode.
+
+## Graph IDs
+
+Cross-collection links use kind-prefixed IDs:
+
+- `feature:sales.crm`
+- `integration:instantly`
+- `resource:lead-import`
+- `capability:operations.queue.review`
+
+## Resolution Semantics
+
+- `defineOrganizationModel()` is a typed helper.
+- `resolveOrganizationModel()` deep-merges a partial override into the default model, then validates it.
+- `createFoundationOrganizationModel()` resolves the canonical model and returns UI-facing helper outputs.
+- Plain objects merge recursively.
+- Arrays replace the default value.
+- Missing fields fall back to `DEFAULT_ORGANIZATION_MODEL`.
+
+## Referential Integrity
+
+- Feature IDs must be unique.
+- Child feature IDs require ancestor feature nodes.
+- Container features omit `path`.
+- Leaf features provide `path`.
+- Resource links are validated against graph node IDs during registry registration.
+
+## Practical Guidance
+
+- Use `resolveOrganizationModel()` when you need a runtime-safe model.
+- Use `defineOrganizationModel()` when authoring static overrides.
+- Keep feature IDs stable because shell routing, gating, breadcrumbs, and docs depend on them.
+- Put semantic resource relationships on resource metadata, not on feature nodes.

package/reference/resources/types.mdx

@@ -1,23 +1,19 @@
 ---
 title: SDK Types
-description: Complete type reference for @elevasis/sdk -- package exports, re-exported platform types, ElevasConfig interface, StepHandler context, and runtime values
+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` 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.
+`@elevasis/sdk` bundles platform types into a self-contained package for external projects.
 
 ```bash
 pnpm add @elevasis/sdk zod
 ```
 
-Zod is a peer dependency and must be installed separately.
-
----
+Zod is a peer dependency.
 
 ## Package Exports
 
-The package exposes two subpaths:
-
 ```json
 {
   "exports": {
@@ -27,181 +23,94 @@ The package exposes two subpaths:
 }
 ```
 
-- `@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' | 'prod'`                         |
-| `ResourceDomain`        | Domain classification for a resource            |
-| `DomainDefinition`      | Structure for grouping resources by domain      |
-| `DeploymentSpec`        | 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`           | `{ type: 'linear', target: string }` -- fixed next step                          |
-| `ConditionalNext`      | `{ type: 'conditional', routes: Route[], default: 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 |
+- `@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: 'feature: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
 
-`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
+```ts
 export interface ElevasConfig {
   defaultStatus?: ResourceStatus
   dev?: { port?: number }
 }
 ```
 
-| Field           | Type              | Default  | Description                                                                                                                                  |
-| --------------- | ----------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
-| `defaultStatus` | `'dev' | 'prod'` | `'prod'` | 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;
-```
-
----
+| 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
 
-`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';
+```ts
+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 };
-};
-```
+  context.logger.info('Processing', {
+    executionId: context.executionId,
+    resourceId: context.resourceId
+  })
 
-### 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 { type: 'conditional', routes: [...], default: '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
-  }
+  await context.store.set('checkpoint', JSON.stringify({ step: 'started' }))
+  return { done: true }
 }
 ```
 
-### 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.
+## Runtime Values
 
-```typescript
-import { ExecutionError } from '@elevasis/sdk';
+Runtime exports include:
 
-const handler = async (input) => {
-  if (!input.userId) {
-    throw new ExecutionError('userId is required', { code: 'MISSING_INPUT' });
-  }
-  return { result: 'ok' };
-};
-```
-
----
+- `StepType`
+- `ToolingError`
+- `ExecutionError`
 
-**Last Updated:** 2026-02-25
+Use `ToolingError` for platform adapter failures and `ExecutionError` for execution-level failures that should be surfaced in run history.