@elevasis/core 0.21.0 → 0.22.0

package/src/organization-model/organization-model.mdx

@@ -1,6 +1,6 @@
 ---
 title: Organization Model
-description: Organization OS Model layer documentation for the flat feature hierarchy, semantic domains, resource graph links, and curated @elevasis/core public API.
+description: Organization OS Model layer documentation for the flat feature hierarchy, semantic domains, resource descriptors, and curated @elevasis/core public API.
 ---
 
 ## Overview
@@ -35,10 +35,13 @@ Top-level fields on `OrganizationModel`:
 - `offerings`
 - `roles`
 - `goals`
+- `systems`
+- `resources`
 - `statuses`
 - `operations`
+- `knowledge`
 
-Resources are not authored inside `OrganizationModel`. Deployable workflows, agents, triggers, integrations, external resources, and human checkpoints declare graph links on their resource metadata.
+Resource identity is authored inside `OrganizationModel.resources.entries`. Runtime workflows, agents, and integrations import those descriptors, derive `resourceId` and kind from them, and attach executable behavior in operations code.
 
 ## Feature Shape
 
@@ -71,7 +74,7 @@ Development-only features remain defined and enabled with `devOnly: true`; shell
 
 Navigation surfaces may also carry `devOnly` for compatibility with the legacy/domain navigation model. `knowledge.command-view` is intentionally development-only while its graph visualization modes continue to mature.
 
-## Graph IDs and Resource Links
+## Graph IDs and Resource Descriptors
 
 Cross-collection links use kind-prefixed graph IDs:
 
@@ -80,18 +83,30 @@ Cross-collection links use kind-prefixed graph IDs:
 - `resource:lead-import`
 - `capability:operations.queue.review`
 
-Example resource metadata:
+Resource identity is authored in the OM Resources domain. Operations imports descriptors from `organizationModel.resources.entries` and derives runtime `resourceId` / `type` while attaching executable behavior.
 
 ```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'
-}
+import { defineResources } from '@elevasis/core/organization-model'
+
+export const resourceDescriptors = defineResources({
+  leadImport: {
+    id: 'lead-import',
+    kind: 'workflow',
+    systemId: 'sys.prospecting',
+    ownerRoleId: 'role-ops-lead',
+    status: 'active',
+    capabilityKey: 'prospecting.lead-import'
+  }
+})
+
+export const resourceGovernanceModel = {
+  systems: {
+    systems
+  },
+  resources: {
+    entries: Object.values(resourceDescriptors)
+  }
+} as const
 ```
 
 ## Domain Semantics
@@ -102,7 +117,10 @@ The model keeps business semantics in named domains:
 - `prospecting` -- company/contact lifecycle stages
 - `projects` -- project, milestone, and task statuses
 - `identity`, `customers`, `offerings`, `roles`, `goals` -- organizational reality
+- `systems` -- bounded contexts that group governed operational resources
+- `resources` -- governance-only workflow, agent, and integration descriptors
 - `statuses` and `operations` -- runtime/vibe-layer semantic registries
+- `knowledge` -- playbooks, strategies, references, and graph-governing links
 
 ## Authoring and Resolution
 
@@ -121,8 +139,9 @@ The model keeps business semantics in named domains:
 - container/leaf path rules
 - valid sidebar positions
 - reality-domain cross references such as offering target segments and role reporting lines
+- system, resource, role, knowledge, and goal cross references used by resource governance
 
-Resource graph links are validated during resource registry registration because resources live in deployment specs.
+`DeploymentSpec` remains the runtime/deploy assembly around these descriptors. It is not the source of resource identity.
 
 ## Provider Integration
 

package/src/organization-model/published.ts

@@ -48,8 +48,40 @@ export {
   ProductSchema,
   PricingModelSchema
 } from './domains/offerings'
-export { DEFAULT_ORGANIZATION_MODEL_ROLES, RolesDomainSchema, RoleSchema } from './domains/roles'
+export {
+  AgentRoleHolderSchema,
+  DEFAULT_ORGANIZATION_MODEL_ROLES,
+  HumanRoleHolderSchema,
+  RoleHolderSchema,
+  RoleHoldersSchema,
+  RoleIdSchema,
+  RolesDomainSchema,
+  RoleSchema,
+  TeamRoleHolderSchema
+} from './domains/roles'
 export { DEFAULT_ORGANIZATION_MODEL_GOALS, GoalsDomainSchema, ObjectiveSchema, KeyResultSchema } from './domains/goals'
+export {
+  DEFAULT_ORGANIZATION_MODEL_SYSTEMS,
+  SystemEntrySchema,
+  SystemIdSchema,
+  SystemKindSchema,
+  SystemsDomainSchema,
+  SystemStatusSchema
+} from './domains/systems'
+export {
+  AgentKindSchema,
+  AgentResourceEntrySchema,
+  DEFAULT_ORGANIZATION_MODEL_RESOURCES,
+  defineResource,
+  defineResources,
+  IntegrationResourceEntrySchema,
+  ResourceEntrySchema,
+  ResourceGovernanceStatusSchema,
+  ResourceIdSchema,
+  ResourceKindSchema,
+  ResourcesDomainSchema,
+  WorkflowResourceEntrySchema
+} from './domains/resources'
 export {
   KnowledgeDomainSchema,
   KnowledgeLinkSchema,
@@ -73,6 +105,20 @@ export type {
   OrganizationModelGoals,
   OrganizationModelKeyResult,
   OrganizationModelObjective,
+  OrganizationModelSystemEntry,
+  OrganizationModelSystemId,
+  OrganizationModelSystemKind,
+  OrganizationModelSystems,
+  OrganizationModelSystemStatus,
+  OrganizationModelAgentKind,
+  OrganizationModelAgentResourceEntry,
+  OrganizationModelIntegrationResourceEntry,
+  OrganizationModelResourceEntry,
+  OrganizationModelResourceGovernanceStatus,
+  OrganizationModelResourceId,
+  OrganizationModelResourceKind,
+  OrganizationModelResources,
+  OrganizationModelWorkflowResourceEntry,
   OrganizationModelOfferings,
   OrganizationModelOperationEntry,
   OrganizationModelOperationSemanticClass,
@@ -80,7 +126,12 @@ export type {
   OrganizationModelPricingModel,
   OrganizationModelProduct,
   OrganizationModelRole,
+  OrganizationModelAgentRoleHolder,
+  OrganizationModelHumanRoleHolder,
+  OrganizationModelRoleHolder,
+  OrganizationModelRoleId,
   OrganizationModelTechStackEntry,
+  OrganizationModelTeamRoleHolder,
   OrganizationModelRoles,
   OrganizationModelStatuses,
   OrganizationModelStatusEntry,

package/src/organization-model/schema.ts

@@ -13,6 +13,8 @@ import { GoalsDomainSchema, DEFAULT_ORGANIZATION_MODEL_GOALS } from './domains/g
 import { OperationsDomainSchema } from './domains/operations'
 import { StatusesDomainSchema } from './domains/statuses'
 import { KnowledgeDomainSchema } from './domains/knowledge'
+import { SystemsDomainSchema, DEFAULT_ORGANIZATION_MODEL_SYSTEMS } from './domains/systems'
+import { ResourcesDomainSchema, DEFAULT_ORGANIZATION_MODEL_RESOURCES } from './domains/resources'
 
 const OrganizationModelSchemaBase = z.object({
   version: z.literal(1).default(1),
@@ -27,6 +29,8 @@ const OrganizationModelSchemaBase = z.object({
   offerings: OfferingsDomainSchema.default(DEFAULT_ORGANIZATION_MODEL_OFFERINGS),
   roles: RolesDomainSchema.default(DEFAULT_ORGANIZATION_MODEL_ROLES),
   goals: GoalsDomainSchema.default(DEFAULT_ORGANIZATION_MODEL_GOALS),
+  systems: SystemsDomainSchema.default(DEFAULT_ORGANIZATION_MODEL_SYSTEMS),
+  resources: ResourcesDomainSchema.default(DEFAULT_ORGANIZATION_MODEL_RESOURCES),
   statuses: StatusesDomainSchema.default({ entries: [] }),
   operations: OperationsDomainSchema.default({ entries: [] }),
   knowledge: KnowledgeDomainSchema.default({ nodes: [] })
@@ -74,6 +78,12 @@ function defaultFeaturePathFor(id: string): string {
   return `/${id.replaceAll('.', '/')}`
 }
 
+function asRoleHolderArray(
+  heldBy: NonNullable<z.infer<typeof OrganizationModelSchemaBase>['roles']['roles'][number]['heldBy']>
+) {
+  return Array.isArray(heldBy) ? heldBy : [heldBy]
+}
+
 export const OrganizationModelSchema = OrganizationModelSchemaBase.superRefine((model, ctx) => {
   const featuresById = collectIds(model.features, ctx, ['features'], 'Feature')
   const featureIdsByEffectivePath = new Map<string, string>()
@@ -199,6 +209,9 @@ export const OrganizationModelSchema = OrganizationModelSchemaBase.superRefine((
     }
   })
 
+  const goalsById = new Map(model.goals.objectives.map((objective) => [objective.id, objective]))
+  const knowledgeById = new Map(model.knowledge.nodes.map((node) => [node.id, node]))
+
   // Roles -> reportsToId cross-ref: each reportsToId must resolve to another role in the same collection
   const rolesById = new Map(model.roles.roles.map((role) => [role.id, role]))
   model.roles.roles.forEach((role, roleIndex) => {
@@ -210,4 +223,112 @@ export const OrganizationModelSchema = OrganizationModelSchemaBase.superRefine((
       )
     }
   })
+
+  const systemsById = collectIds(model.systems.systems, ctx, ['systems', 'systems'], 'System')
+  model.roles.roles.forEach((role, roleIndex) => {
+    role.responsibleFor?.forEach((systemId, systemIndex) => {
+      if (!systemsById.has(systemId)) {
+        addIssue(
+          ctx,
+          ['roles', 'roles', roleIndex, 'responsibleFor', systemIndex],
+          `Role "${role.id}" references unknown responsibleFor system "${systemId}"`
+        )
+      }
+    })
+  })
+
+  model.systems.systems.forEach((system, systemIndex) => {
+    if (system.responsibleRoleId !== undefined && !rolesById.has(system.responsibleRoleId)) {
+      addIssue(
+        ctx,
+        ['systems', 'systems', systemIndex, 'responsibleRoleId'],
+        `System "${system.id}" references unknown responsibleRoleId "${system.responsibleRoleId}"`
+      )
+    }
+
+    system.governedByKnowledge.forEach((nodeId, nodeIndex) => {
+      if (!knowledgeById.has(nodeId)) {
+        addIssue(
+          ctx,
+          ['systems', 'systems', systemIndex, 'governedByKnowledge', nodeIndex],
+          `System "${system.id}" references unknown knowledge node "${nodeId}"`
+        )
+      }
+    })
+
+    system.drivesGoals.forEach((goalId, goalIndex) => {
+      if (!goalsById.has(goalId)) {
+        addIssue(
+          ctx,
+          ['systems', 'systems', systemIndex, 'drivesGoals', goalIndex],
+          `System "${system.id}" references unknown goal "${goalId}"`
+        )
+      }
+    })
+  })
+
+  const resourcesById = collectIds(model.resources.entries, ctx, ['resources', 'entries'], 'Resource')
+  model.resources.entries.forEach((resource, resourceIndex) => {
+    if (!systemsById.has(resource.systemId)) {
+      addIssue(
+        ctx,
+        ['resources', 'entries', resourceIndex, 'systemId'],
+        `Resource "${resource.id}" references unknown systemId "${resource.systemId}"`
+      )
+    }
+
+    if (resource.ownerRoleId !== undefined && !rolesById.has(resource.ownerRoleId)) {
+      addIssue(
+        ctx,
+        ['resources', 'entries', resourceIndex, 'ownerRoleId'],
+        `Resource "${resource.id}" references unknown ownerRoleId "${resource.ownerRoleId}"`
+      )
+    }
+
+    if (resource.kind === 'agent' && resource.actsAsRoleId !== undefined && !rolesById.has(resource.actsAsRoleId)) {
+      addIssue(
+        ctx,
+        ['resources', 'entries', resourceIndex, 'actsAsRoleId'],
+        `Agent resource "${resource.id}" references unknown actsAsRoleId "${resource.actsAsRoleId}"`
+      )
+    }
+  })
+
+  model.roles.roles.forEach((role, roleIndex) => {
+    if (role.heldBy === undefined) return
+
+    asRoleHolderArray(role.heldBy).forEach((holder, holderIndex) => {
+      if (holder.kind !== 'agent') return
+
+      const resource = resourcesById.get(holder.agentId)
+      if (resource === undefined) {
+        addIssue(
+          ctx,
+          ['roles', 'roles', roleIndex, 'heldBy', Array.isArray(role.heldBy) ? holderIndex : 'agentId'],
+          `Role "${role.id}" references unknown agent holder resource "${holder.agentId}"`
+        )
+        return
+      }
+
+      if (resource.kind !== 'agent') {
+        addIssue(
+          ctx,
+          ['roles', 'roles', roleIndex, 'heldBy', Array.isArray(role.heldBy) ? holderIndex : 'agentId'],
+          `Role "${role.id}" agent holder "${holder.agentId}" must reference an agent resource`
+        )
+      }
+    })
+  })
+
+  model.knowledge.nodes.forEach((node, nodeIndex) => {
+    node.ownerIds.forEach((roleId, ownerIndex) => {
+      if (!rolesById.has(roleId)) {
+        addIssue(
+          ctx,
+          ['knowledge', 'nodes', nodeIndex, 'ownerIds', ownerIndex],
+          `Knowledge node "${node.id}" references unknown owner role "${roleId}"`
+        )
+      }
+    })
+  })
 })

package/src/organization-model/types.ts

@@ -10,7 +10,15 @@ import { OperationsDomainSchema, OperationEntrySchema, OperationSemanticClassSch
 import { StatusesDomainSchema, StatusEntrySchema, StatusSemanticClassSchema } from './domains/statuses'
 import { CustomersDomainSchema, CustomerSegmentSchema, FirmographicsSchema } from './domains/customers'
 import { OfferingsDomainSchema, ProductSchema, PricingModelSchema } from './domains/offerings'
-import { RolesDomainSchema, RoleSchema } from './domains/roles'
+import {
+  AgentRoleHolderSchema,
+  HumanRoleHolderSchema,
+  RoleHolderSchema,
+  RoleIdSchema,
+  RolesDomainSchema,
+  RoleSchema,
+  TeamRoleHolderSchema
+} from './domains/roles'
 import { GoalsDomainSchema, ObjectiveSchema, KeyResultSchema } from './domains/goals'
 import {
   KnowledgeDomainBindingSchema,
@@ -19,6 +27,24 @@ import {
   OrgKnowledgeKindSchema,
   OrgKnowledgeNodeSchema
 } from './domains/knowledge'
+import {
+  SystemEntrySchema,
+  SystemIdSchema,
+  SystemKindSchema,
+  SystemsDomainSchema,
+  SystemStatusSchema
+} from './domains/systems'
+import {
+  AgentKindSchema,
+  AgentResourceEntrySchema,
+  IntegrationResourceEntrySchema,
+  ResourceEntrySchema,
+  ResourceGovernanceStatusSchema,
+  ResourceIdSchema,
+  ResourceKindSchema,
+  ResourcesDomainSchema,
+  WorkflowResourceEntrySchema
+} from './domains/resources'
 import { OrganizationModelIconTokenSchema, OrganizationModelBuiltinIconTokenSchema } from './icons'
 import { OrganizationModelSchema } from './schema'
 
@@ -47,9 +73,28 @@ export type OrganizationModelProduct = z.infer<typeof ProductSchema>
 export type OrganizationModelPricingModel = z.infer<typeof PricingModelSchema>
 export type OrganizationModelRoles = z.infer<typeof RolesDomainSchema>
 export type OrganizationModelRole = z.infer<typeof RoleSchema>
+export type OrganizationModelRoleId = z.infer<typeof RoleIdSchema>
+export type OrganizationModelRoleHolder = z.infer<typeof RoleHolderSchema>
+export type OrganizationModelHumanRoleHolder = z.infer<typeof HumanRoleHolderSchema>
+export type OrganizationModelAgentRoleHolder = z.infer<typeof AgentRoleHolderSchema>
+export type OrganizationModelTeamRoleHolder = z.infer<typeof TeamRoleHolderSchema>
 export type OrganizationModelGoals = z.infer<typeof GoalsDomainSchema>
 export type OrganizationModelObjective = z.infer<typeof ObjectiveSchema>
 export type OrganizationModelKeyResult = z.infer<typeof KeyResultSchema>
+export type OrganizationModelSystems = z.infer<typeof SystemsDomainSchema>
+export type OrganizationModelSystemEntry = z.infer<typeof SystemEntrySchema>
+export type OrganizationModelSystemId = z.infer<typeof SystemIdSchema>
+export type OrganizationModelSystemKind = z.infer<typeof SystemKindSchema>
+export type OrganizationModelSystemStatus = z.infer<typeof SystemStatusSchema>
+export type OrganizationModelResources = z.infer<typeof ResourcesDomainSchema>
+export type OrganizationModelResourceEntry = z.infer<typeof ResourceEntrySchema>
+export type OrganizationModelResourceId = z.infer<typeof ResourceIdSchema>
+export type OrganizationModelResourceKind = z.infer<typeof ResourceKindSchema>
+export type OrganizationModelResourceGovernanceStatus = z.infer<typeof ResourceGovernanceStatusSchema>
+export type OrganizationModelAgentKind = z.infer<typeof AgentKindSchema>
+export type OrganizationModelWorkflowResourceEntry = z.infer<typeof WorkflowResourceEntrySchema>
+export type OrganizationModelAgentResourceEntry = z.infer<typeof AgentResourceEntrySchema>
+export type OrganizationModelIntegrationResourceEntry = z.infer<typeof IntegrationResourceEntrySchema>
 export type OrganizationModelKnowledge = z.infer<typeof KnowledgeDomainSchema>
 export type OrgKnowledgeNode = z.infer<typeof OrgKnowledgeNodeSchema>
 export type OrgKnowledgeKind = z.infer<typeof OrgKnowledgeKindSchema>

package/src/platform/api/types.ts

@@ -1,35 +1,38 @@
-/**
- * Standard API error response format
- * Returned by APIError.toJSON() in apps/api
- * Consumed by Command Center UI for type-safe error handling
- */
-export interface APIErrorResponse {
-  /** Human-readable error message */
-  error: string
-
-  /** Machine-readable error code */
-  code: APIErrorCode
-
-  /** Request ID for debugging (optional) */
-  requestId?: string
-
-  /** Field-level validation errors (only present for VALIDATION_ERROR code) */
-  fields?: Record<string, string[]>
-
-  /** Seconds until the rate limit resets (only present for RATE_LIMIT_EXCEEDED code) */
-  retryAfter?: number
-}
-
-/**
- * Type-safe error codes
- * MUST match API_ERROR_CODES in apps/api/src/errors/error-codes.ts
- */
-export type APIErrorCode =
-  | 'VALIDATION_ERROR'
-  | 'AUTHENTICATION_FAILED'
-  | 'FORBIDDEN'
-  | 'NOT_FOUND'
-  | 'CONFLICT'
-  | 'RATE_LIMIT_EXCEEDED'
-  | 'INTERNAL_SERVER_ERROR'
-  | 'SERVICE_UNAVAILABLE'
+/**
+ * Standard API error response format
+ * Returned by APIError.toJSON() in apps/api
+ * Consumed by Command Center UI for type-safe error handling
+ */
+export interface APIErrorResponse {
+  /** Human-readable error message */
+  error: string
+
+  /** Machine-readable error code */
+  code: APIErrorCode
+
+  /** Request ID for debugging (optional) */
+  requestId?: string
+
+  /** Field-level validation errors (only present for VALIDATION_ERROR code) */
+  fields?: Record<string, string[]>
+
+  /** Seconds until the rate limit resets (only present for RATE_LIMIT_EXCEEDED code) */
+  retryAfter?: number
+
+  /** Structured detail payload (e.g. linked-row counts on CONFLICT errors) */
+  details?: Record<string, unknown>
+}
+
+/**
+ * Type-safe error codes
+ * MUST match API_ERROR_CODES in apps/api/src/errors/error-codes.ts
+ */
+export type APIErrorCode =
+  | 'VALIDATION_ERROR'
+  | 'AUTHENTICATION_FAILED'
+  | 'FORBIDDEN'
+  | 'NOT_FOUND'
+  | 'CONFLICT'
+  | 'RATE_LIMIT_EXCEEDED'
+  | 'INTERNAL_SERVER_ERROR'
+  | 'SERVICE_UNAVAILABLE'