@elevasis/sdk 1.22.0 → 1.23.0

package/reference/scaffold/reference/contracts.md

@@ -421,6 +421,42 @@ export type OrganizationModelIntegrationResourceEntry = z.infer<typeof Integrati
 export type OrganizationModelScriptResourceEntry = z.infer<typeof ScriptResourceEntrySchema>
 ```
 
+### `OrganizationModelTopology`
+
+```typescript
+export type OrganizationModelTopology = z.infer<typeof OmTopologyDomainSchema>
+```
+
+### `OrganizationModelTopologyNodeKind`
+
+```typescript
+export type OrganizationModelTopologyNodeKind = z.infer<typeof OmTopologyNodeKindSchema>
+```
+
+### `OrganizationModelTopologyNodeRef`
+
+```typescript
+export type OrganizationModelTopologyNodeRef = z.infer<typeof OmTopologyNodeRefSchema>
+```
+
+### `OrganizationModelTopologyRelationshipKind`
+
+```typescript
+export type OrganizationModelTopologyRelationshipKind = z.infer<typeof OmTopologyRelationshipKindSchema>
+```
+
+### `OrganizationModelTopologyRelationship`
+
+```typescript
+export type OrganizationModelTopologyRelationship = z.infer<typeof OmTopologyRelationshipSchema>
+```
+
+### `OrganizationModelTopologyMetadata`
+
+```typescript
+export type OrganizationModelTopologyMetadata = z.infer<typeof OmTopologyMetadataSchema>
+```
+
 ### `OrganizationModelActions`
 
 ```typescript
@@ -601,8 +637,8 @@ export type DeepPartial<T> =
 ### `ElevasisOrganizationModel`
 
 ```typescript
-export type ElevasisOrganizationModel = Omit<OrganizationModel, 'knowledge'> & {
-  knowledge?: OrganizationModel['knowledge']
+export type ElevasisOrganizationModel = Omit<OrganizationModel, 'knowledge'> & {
+  knowledge?: OrganizationModel['knowledge']
 }
 ```
 
@@ -627,107 +663,107 @@ export type SystemSidebarWidthResolver = number | ((context: { currentPath: stri
 ### `SystemModule`
 
 ```typescript
-export interface SystemModule {
-  /** Unique stable identifier for this UI system module. */
-  key: string
-  /** Organization Model system id this module presents. Omit for navigation-only app surfaces. */
-  systemId?: string
-  /** Route prefixes owned by navigation-only app surfaces. */
-  routePrefixes?: string[]
-  /** Capability identifiers contributed by this system module. */
-  capabilityIds?: string[]
-  /** Icon used when this system node appears in shell navigation. */
-  icon?: SystemIconComponent
-  /** Sidebar component rendered when this system's subtree route is active. */
-  sidebar?: SystemSidebarComponent
-  /** Optional shell sidebar width override. Defaults to 250px. */
-  sidebarWidth?: SystemSidebarWidthResolver
-  /** Operations-only bridge connecting this system to the organization graph node. */
-  organizationGraph?: OrganizationGraphSystemBridge
+export interface SystemModule {
+  /** Unique stable identifier for this UI system module. */
+  key: string
+  /** Organization Model system id this module presents. Omit for navigation-only app surfaces. */
+  systemId?: string
+  /** Route prefixes owned by navigation-only app surfaces. */
+  routePrefixes?: string[]
+  /** Capability identifiers contributed by this system module. */
+  capabilityIds?: string[]
+  /** Icon used when this system node appears in shell navigation. */
+  icon?: SystemIconComponent
+  /** Sidebar component rendered when this system's subtree route is active. */
+  sidebar?: SystemSidebarComponent
+  /** Optional shell sidebar width override. Defaults to 250px. */
+  sidebarWidth?: SystemSidebarWidthResolver
+  /** Operations-only bridge connecting this system to the organization graph node. */
+  organizationGraph?: OrganizationGraphSystemBridge
 }
 ```
 
 ### `ResolvedSystemAccess`
 
 ```typescript
-export interface ResolvedSystemAccess {
-  featureKey: string
-  systemId?: string
-  enabled: boolean
+export interface ResolvedSystemAccess {
+  systemKey: string
+  systemId?: string
+  enabled: boolean
 }
 ```
 
 ### `ResolvedSystemSemantics`
 
 ```typescript
-export interface ResolvedSystemSemantics {
-  capabilityIds: string[]
+export interface ResolvedSystemSemantics {
+  capabilityIds: string[]
 }
 ```
 
 ### `ResolvedSystemModule`
 
 ```typescript
-export interface ResolvedSystemModule extends SystemModule {
-  access: ResolvedSystemAccess
-  semantics: ResolvedSystemSemantics
+export interface ResolvedSystemModule extends SystemModule {
+  access: ResolvedSystemAccess
+  semantics: ResolvedSystemSemantics
 }
 ```
 
 ### `ResolvedShellSystem`
 
 ```typescript
-export type ResolvedShellSystem = OrganizationModelSystemEntry & {
-  label: string
-  iconComponent?: SystemIconComponent
+export type ResolvedShellSystem = OrganizationModelSystemEntry & {
+  label: string
+  iconComponent?: SystemIconComponent
 }
 ```
 
 ### `ResolvedShellModel`
 
 ```typescript
-export interface ResolvedShellModel {
-  systems: readonly ResolvedShellSystem[]
-  findByPath: (path: string) => ResolvedShellSystem | undefined
-  findById: (id: string) => ResolvedShellSystem | undefined
-  childrenOf: (id: string) => ResolvedShellSystem[]
-  ancestorsOf: (id: string) => ResolvedShellSystem[]
-  parentOf: (id: string) => ResolvedShellSystem | undefined
-  topLevel: () => ResolvedShellSystem[]
-  requiresAdminFor: (id: string) => boolean
-  devOnlyFor: (id: string) => boolean
+export interface ResolvedShellModel {
+  systems: readonly ResolvedShellSystem[]
+  findByPath: (path: string) => ResolvedShellSystem | undefined
+  findById: (id: string) => ResolvedShellSystem | undefined
+  childrenOf: (id: string) => ResolvedShellSystem[]
+  ancestorsOf: (id: string) => ResolvedShellSystem[]
+  parentOf: (id: string) => ResolvedShellSystem | undefined
+  topLevel: () => ResolvedShellSystem[]
+  requiresAdminFor: (id: string) => boolean
+  devOnlyFor: (id: string) => boolean
 }
 ```
 
 ### `ShellSidebarLinkItem`
 
 ```typescript
-export interface ShellSidebarLinkItem {
-  label: string
-  link: string
-  exact?: boolean
-  activeMatchPaths?: string[]
+export interface ShellSidebarLinkItem {
+  label: string
+  link: string
+  exact?: boolean
+  activeMatchPaths?: string[]
 }
 ```
 
 ### `ShellSidebarLinkGroup`
 
 ```typescript
-export interface ShellSidebarLinkGroup {
-  icon: SystemIconComponent
-  label: string
-  links?: ShellSidebarLinkItem[]
-  link?: string
+export interface ShellSidebarLinkGroup {
+  icon: SystemIconComponent
+  label: string
+  links?: ShellSidebarLinkItem[]
+  link?: string
 }
 ```
 
 ### `ShellSidebarProjectionOptions`
 
 ```typescript
-export interface ShellSidebarProjectionOptions {
-  isPlatformAdmin?: boolean
-  isDev?: boolean
-  section?: 'primary' | 'bottom'
+export interface ShellSidebarProjectionOptions {
+  isPlatformAdmin?: boolean
+  isDev?: boolean
+  section?: 'primary' | 'bottom'
 }
 ```
 
@@ -740,75 +776,75 @@ export type ShellRouteMatchStatus = 'matched' | 'hidden' | 'unmatched'
 ### `ResolvedShellRouteMatch`
 
 ```typescript
-export interface ResolvedShellRouteMatch {
-  status: ShellRouteMatchStatus
-  path: string
-  system?: ResolvedSystemModule
-  node?: ResolvedShellSystem
+export interface ResolvedShellRouteMatch {
+  status: ShellRouteMatchStatus
+  path: string
+  system?: ResolvedSystemModule
+  node?: ResolvedShellSystem
 }
 ```
 
 ### `ShellRuntime`
 
 ```typescript
-export interface ShellRuntime {
-  resolveRoute: (path: string) => ResolvedShellRouteMatch
+export interface ShellRuntime {
+  resolveRoute: (path: string) => ResolvedShellRouteMatch
 }
 ```
 
 ### `OrganizationGraphSystemBridge`
 
 ```typescript
-export interface OrganizationGraphSystemBridge {
-  systemId?: string
+export interface OrganizationGraphSystemBridge {
+  systemId?: string
 }
 ```
 
 ### `OrganizationGraphContextValue`
 
 ```typescript
-export interface OrganizationGraphContextValue {
-  available: boolean
-  systemId?: string
-  systemPath?: string
+export interface OrganizationGraphContextValue {
+  available: boolean
+  systemId?: string
+  systemPath?: string
 }
 ```
 
 ### `ElevasisSystemsProviderProps`
 
 ```typescript
-export interface ElevasisSystemsProviderProps {
-  systems?: SystemModule[]
-  organizationModel?: ElevasisOrganizationModel
-  timeRange?: TimeRange
-  operationsApiUrl?: string
-  operationsSSEManager?: SSEConnectionManagerLike
-  deliveryApiUrl?: string
-  deliverySSEManager?: SSEConnectionManagerLike
-  disabledSubsectionPaths?: string[]
-  children: ReactNode
+export interface ElevasisSystemsProviderProps {
+  systems?: SystemModule[]
+  organizationModel?: ElevasisOrganizationModel
+  timeRange?: TimeRange
+  operationsApiUrl?: string
+  operationsSSEManager?: SSEConnectionManagerLike
+  deliveryApiUrl?: string
+  deliverySSEManager?: SSEConnectionManagerLike
+  disabledSubsectionPaths?: string[]
+  children: ReactNode
 }
 ```
 
 ### `ElevasisSystemsContextValue`
 
 ```typescript
-export interface ElevasisSystemsContextValue {
-  shellModel: ResolvedShellModel
-  shellRuntime: ShellRuntime
-  getSidebarLinks: (options?: ShellSidebarProjectionOptions) => ShellSidebarLinkGroup[]
-  enabledResolvedSystems: ResolvedSystemModule[]
-  resolvedSystems: ResolvedSystemModule[]
-  organizationGraph: OrganizationGraphContextValue
-  organizationModel?: OrganizationModel
-  timeRange?: TimeRange
-  operationsApiUrl?: string
-  operationsSSEManager?: SSEConnectionManagerLike
-  deliveryApiUrl?: string
-  deliverySSEManager?: SSEConnectionManagerLike
-  disabledSubsectionPaths: string[]
-  isSystemEnabled: (key: string) => boolean
-  getResolvedSystem: (key: string) => ResolvedSystemModule | undefined
+export interface ElevasisSystemsContextValue {
+  shellModel: ResolvedShellModel
+  shellRuntime: ShellRuntime
+  getSidebarLinks: (options?: ShellSidebarProjectionOptions) => ShellSidebarLinkGroup[]
+  enabledResolvedSystems: ResolvedSystemModule[]
+  resolvedSystems: ResolvedSystemModule[]
+  organizationGraph: OrganizationGraphContextValue
+  organizationModel?: OrganizationModel
+  timeRange?: TimeRange
+  operationsApiUrl?: string
+  operationsSSEManager?: SSEConnectionManagerLike
+  deliveryApiUrl?: string
+  deliverySSEManager?: SSEConnectionManagerLike
+  disabledSubsectionPaths: string[]
+  isSystemEnabled: (key: string) => boolean
+  getResolvedSystem: (key: string) => ResolvedSystemModule | undefined
 }
 ```
 
@@ -1290,13 +1326,15 @@ export interface HumanCheckpointDefinition extends ResourceDefinition {
  * Used by ResourceRegistry for discovery and Command View for visualization.
  */
 export interface DeploymentSpec {
-  /** Deployment version (semver) */
-  version: string
-  /** Optional Organization Model governance catalog used for OM-code validation */
-  organizationModel?: {
-    systems?: OrganizationModelSystems
-    resources?: OrganizationModelResources
-  }
+  /** Deployment version (semver) */
+  version: string
+  /** Optional Organization Model governance catalog used for OM-code validation */
+  organizationModel?: Partial<
+    Pick<
+      OrganizationModel,
+      'systems' | 'resources' | 'ontology' | 'topology' | 'roles' | 'policies' | 'entities' | 'actions'
+    >
+  >
   /** Workflow definitions */
   workflows?: WorkflowDefinition[]
   /** Agent definitions */

package/reference/scaffold/reference/glossary.md

@@ -1,79 +1,81 @@
----
-title: Glossary
-description: Terminology disambiguation for Organization OS concepts used in the template scaffold, core package, and published packages.
----
+---
+title: Glossary
+description: Terminology disambiguation for Organization OS concepts used in the template scaffold, core package, and published packages.
+---
 <!-- @generated by packages/sdk/scripts/copy-reference-docs.mjs -- DO NOT EDIT -->
 <!-- Regenerate: pnpm scaffold:sync -->
 
-
-# Glossary
-
-## Terms
-
-**AdminGuard** -- route-level admin wrapper from `@elevasis/ui/features/auth`. Must nest inside `ProtectedRoute`.
-
-**Contract** -- the publishable boundary a consumer depends on: Zod schemas, TypeScript types, provider props, resource definitions, or workflow I/O schemas.
-
-**DeploymentSpec** -- runtime/deploy assembly for one organization: workflows, agents, triggers, integrations, relationships, external resources, and human checkpoints. It assembles executable behavior around Organization Model resource descriptors; it is not the source of resource identity.
-
-**Feature** -- legacy or UI-package wording for a platform capability area. In the current Organization Model, use **System** for semantic ownership and **navigation surface** for shell placement. Keep "feature" only when referring to existing UI package folders, exported manifest names, or legacy compatibility recipes.
-
-**SystemGuard** -- route-level System gate from `@elevasis/ui/features/auth`.
-
+
+# Glossary
+
+## Terms
+
+**AdminGuard** -- route-level admin wrapper from `@elevasis/ui/features/auth`. Must nest inside `ProtectedRoute`.
+
+**Contract** -- the publishable boundary a consumer depends on: Zod schemas, TypeScript types, provider props, resource definitions, or workflow I/O schemas.
+
+**DeploymentSpec** -- runtime/deploy assembly for one organization: workflows, agents, triggers, integrations, relationships, external resources, and human checkpoints. It assembles executable behavior around Organization Model resource descriptors; it is not the source of resource identity.
+
+**Feature** -- legacy or UI-package wording for a platform capability area. In the current Organization Model, use **System** for semantic ownership and **navigation surface** for shell placement. Keep "feature" only when referring to existing UI package folders, exported manifest names, or legacy compatibility recipes.
+
+**SystemGuard** -- route-level System gate from `@elevasis/ui/features/auth`.
+
 **SystemModule** -- manifest contract a shell module provides to `ElevasisSystemsProvider`. Key fields are `key`, optional `systemId`, optional `routePrefixes`, optional `capabilityIds`, optional `icon`, optional `sidebar`, and optional `sidebarWidth`. Graph bridge metadata is compatibility-only; new semantic bindings belong in the Organization Model System, ontology, navigation, and Resource descriptors.
-
-**systemId** -- the `SystemModule` field that points to an `OrganizationModel.systems` entry. Navigation-only app modules may omit it and use route prefixes/surface metadata instead.
-
-**Foundations** -- local adapter layer in external projects that exports `canonicalOrganizationModel`, `organizationModel`, and workflow I/O schemas.
-
-**Graph node ID** -- kind-prefixed cross-collection identifier such as `system:sales.crm`, `integration:instantly`, or `resource:lead-import`.
-
-**Manifest** -- a runtime declaration for a feature or resource collection.
-
+
+**systemId** -- the `SystemModule` field that points to an `OrganizationModel.systems` entry. Navigation-only app modules may omit it and use route prefixes/surface metadata instead.
+
+**systemId (resource — deprecated)** -- the legacy `resource.systemId` field on Organization Model resource descriptors. Removed from the target contract; the canonical attachment is **`resource.systemPath`** (dot-separated path resolved against the system tree). Some external templates still ship a `systemId` compatibility mirror while published `@elevasis/core` releases catch up; treat that field as legacy adapter data only and author new resource relationships against `systemPath`. Query with `getResourcesForSystem(model, path)`.
+
+**Foundations** -- local adapter layer in external projects that exports `canonicalOrganizationModel`, `organizationModel`, and workflow I/O schemas.
+
+**Graph node ID** -- kind-prefixed cross-collection identifier such as `system:sales.crm`, `integration:instantly`, or `resource:lead-import`.
+
+**Manifest** -- a runtime declaration for a feature or resource collection.
+
 **MembershipFeatureConfig** -- legacy per-member feature override config. Current System visibility should be authored through Organization Model System lifecycle/access metadata and resolved through provider compatibility layers for older consumers.
-
-**OrganizationModel** -- top-level semantic contract for an organization. Current primary fields include `version`, `domainMetadata`, `branding`, `navigation`, `ontology`, `systems`, `resources`, `identity`, `customers`, `offerings`, `roles`, `goals`, `policies`, `statuses`, and `knowledge`. Legacy domain keys such as `sales`, `prospecting`, `projects`, `actions`, and `entities` remain compatibility inputs while projects migrate to System-owned ontology/config/resource contracts.
-
+
+**OrganizationModel** -- top-level semantic contract for an organization. Current primary fields include `version`, `domainMetadata`, `branding`, `navigation`, `ontology`, `systems`, `resources`, `topology`, `identity`, `customers`, `offerings`, `roles`, `goals`, `policies`, `statuses`, and `knowledge`. Legacy domain keys such as `sales`, `prospecting`, `projects`, `actions`, and `entities` remain compatibility inputs while projects migrate to System-owned ontology/config/resource contracts.
+
 **OrganizationModelSystemEntry** -- System node in `OrganizationModel.systems`. Primary authoring fields include `id`, `label`, `description`, `parentSystemId`, `systems`, `lifecycle`, `ui`, `requiresAdmin`, `devOnly`, `responsibleRoleId`, `governedByKnowledge`, `drivesGoals`, `actions`, `policies`, `ontology`, `config`, and `order`. `subsystems` and `content` are retained compatibility inputs for older projects and should not be used for new recursive Systems, schemas, catalogs, or config.
-
-**Provider / ElevasisSystemsProvider** -- runtime that registers System modules, resolves System access against the org model, projects sidebar navigation, and exposes shell helpers through `useElevasisSystems()`.
-
-**Resource** -- governance-only descriptor in `OrganizationModel.resources` for a workflow, agent, integration, or script. Runtime code derives `resourceId` and kind from the descriptor, then attaches executable behavior in operations.
-
-**Resource descriptor** -- OM entry with canonical `id`, required `systemPath`, governance `status`, optional role ownership, optional `actionKey`, `codeRefs`, and nested `ontology` bindings for implemented actions, read/write objects, used catalogs, and emitted events. Top-level `emits` remains a compatibility mirror for older descriptors.
-
+
+**Provider / ElevasisSystemsProvider** -- runtime that registers System modules, resolves System access against the org model, projects sidebar navigation, and exposes shell helpers through `useElevasisSystems()`.
+
+**Resource** -- governance-only descriptor in `OrganizationModel.resources` for a workflow, agent, integration, or script. Runtime code derives `resourceId` and kind from the descriptor, then attaches executable behavior in operations.
+
+**Resource descriptor** -- OM entry with canonical `id`, required `systemPath`, descriptor `title` / `description`, governance `status`, optional role ownership, `codeRefs`, and nested `ontology` bindings for `actions`, optional `primaryAction`, read/write objects, used catalogs, and emitted events. Top-level `emits` remains a compatibility mirror for older descriptors.
+
 **System** -- tenant-defined bounded context in `OrganizationModel.systems` that groups operational resources and carries governance metadata such as responsible role, governing knowledge, driven goals, kind, lifecycle, System-local ontology, and System-local config.
-
-**ResourceCategory** -- resource metadata category: `production`, `diagnostic`, `internal`, or `testing`.
-
-**ResourceLink** -- graph binding on resource metadata: `{ nodeId, kind }`.
-
-**Settings asymmetry** -- Settings is a navigation/app surface whose individual pages are normally governed by admin checks rather than user-facing System toggles.
-
-**Shell model** -- provider output used by sidebars and breadcrumbs. Includes `systems`, `childrenOf`, `ancestorsOf`, `parentOf`, `topLevel`, `findByPath`, `requiresAdminFor`, and `devOnlyFor`.
-
-**Subshell / Sidebar** -- System- or route-prefix-scoped UI region rendered when the current route matches a module whose manifest supplies a sidebar.
-
-**Topology** -- runtime resource relationships declared in `DeploymentSpec.relationships`.
-
-## Package Boundary
-
-**`@elevasis/core`**
-
-- `OrganizationModel`, `OrganizationModelSystemEntry`
-- `SystemEntry`, `ResourceEntry`
-- `resolveOrganizationModel`, `defineOrganizationModel`, `DEFAULT_ORGANIZATION_MODEL`
-- `MembershipFeatureConfig`
-- `DeploymentSpec`, `ResourceLink`, `ResourceCategory`
-
-**`@elevasis/ui`**
-
-- `SystemModule`
-- `SystemGuard`, `AdminGuard`, `ProtectedRoute`
-- `ElevasisSystemsProvider`, `ElevasisCoreProvider`, `useElevasisSystems`
-
-**External project source**
-
-- `canonicalOrganizationModel`
-- `organizationModel`
-- workflow I/O schemas
+
+**ResourceCategory** -- resource metadata category: `production`, `diagnostic`, `internal`, or `testing`.
+
+**ResourceLink** -- graph binding on resource metadata: `{ nodeId, kind }`.
+
+**Settings asymmetry** -- Settings is a navigation/app surface whose individual pages are normally governed by admin checks rather than user-facing System toggles.
+
+**Shell model** -- provider output used by sidebars and breadcrumbs. Includes `systems`, `childrenOf`, `ancestorsOf`, `parentOf`, `topLevel`, `findByPath`, `requiresAdminFor`, and `devOnlyFor`.
+
+**Subshell / Sidebar** -- System- or route-prefix-scoped UI region rendered when the current route matches a module whose manifest supplies a sidebar.
+
+**Topology** -- durable OM operational wiring declared in `OrganizationModel.topology.relationships`. Initial relationship kinds are `triggers`, `uses`, and `approval`; relationships use typed refs such as `{ kind: 'resource', id: 'lead-import' }`.
+
+## Package Boundary
+
+**`@elevasis/core`**
+
+- `OrganizationModel`, `OrganizationModelSystemEntry`
+- `SystemEntry`, `ResourceEntry`
+- `resolveOrganizationModel`, `defineOrganizationModel`, `DEFAULT_ORGANIZATION_MODEL`
+- `MembershipFeatureConfig`
+- `DeploymentSpec`, `ResourceLink`, `ResourceCategory`
+
+**`@elevasis/ui`**
+
+- `SystemModule`
+- `SystemGuard`, `AdminGuard`, `ProtectedRoute`
+- `ElevasisSystemsProvider`, `ElevasisCoreProvider`, `useElevasisSystems`
+
+**External project source**
+
+- `canonicalOrganizationModel`
+- `organizationModel`
+- workflow I/O schemas