@elevasis/core 0.23.0 → 0.24.1

package/src/organization-model/domains/resources.ts

@@ -1,145 +1,223 @@
 import { z } from 'zod'
-import { ModelIdSchema } from './shared'
+import { DescriptionSchema, LabelSchema, ModelIdSchema } from './shared'
 import { SystemPathSchema, SystemLifecycleSchema } from './systems'
 import { ActionInvocationSchema } from './actions'
-
-// ---------------------------------------------------------------------------
-// Resources domain
-// ---------------------------------------------------------------------------
-//
-// Resources are governance-only OM descriptors. Runtime code imports these
-// descriptors and attaches executable behavior; it does not re-author identity.
-
-export const ResourceKindSchema = z
-  .enum(['workflow', 'agent', 'integration', 'script'])
-  .meta({ label: 'Resource kind', color: 'orange' })
-export const ResourceGovernanceStatusSchema = z
-  .enum(['active', 'deprecated', 'archived'])
-  .meta({ label: 'Governance status', color: 'teal' })
-export const AgentKindSchema = z
-  .enum(['orchestrator', 'specialist', 'utility', 'platform'])
-  .meta({ label: 'Agent kind', color: 'violet' })
-export const ScriptResourceLanguageSchema = z.enum(['shell', 'sql', 'typescript', 'python']).meta({ label: 'Language' })
-
-export const ResourceIdSchema = z
-  .string()
-  .trim()
-  .min(1)
-  .max(255)
-  .regex(/^[A-Za-z0-9]+(?:[-._][A-Za-z0-9]+)*$/, 'Resource IDs must use letters, numbers, -, _, or . separators')
-
-export const EventIdSchema = z
-  .string()
-  .trim()
-  .min(1)
-  .max(300)
-  .regex(
-    /^[A-Za-z0-9]+(?:[-._][A-Za-z0-9]+)*:[a-z0-9]+(?:[-._][a-z0-9]+)*$/,
-    'Event IDs must use <owner-id>:<event-key>'
-  )
-
-export const EventKeySchema = ModelIdSchema
-
-export const EventEmissionDescriptorSchema = z.object({
-  eventKey: EventKeySchema,
-  label: z.string().trim().min(1).max(120),
-  payloadSchema: ModelIdSchema.optional(),
-  lifecycle: SystemLifecycleSchema.optional()
-})
-
+import { OntologyIdSchema } from '../ontology'
+
+// ---------------------------------------------------------------------------
+// Resources domain
+// ---------------------------------------------------------------------------
+//
+// Resources are governance-only OM descriptors. Runtime code imports these
+// descriptors and attaches executable behavior; it does not re-author identity.
+
+export const ResourceKindSchema = z
+  .enum(['workflow', 'agent', 'integration', 'script'])
+  .meta({ label: 'Resource kind', color: 'orange' })
+export const ResourceGovernanceStatusSchema = z
+  .enum(['active', 'deprecated', 'archived'])
+  .meta({ label: 'Governance status', color: 'teal' })
+export const AgentKindSchema = z
+  .enum(['orchestrator', 'specialist', 'utility', 'platform'])
+  .meta({ label: 'Agent kind', color: 'violet' })
+export const ScriptResourceLanguageSchema = z.enum(['shell', 'sql', 'typescript', 'python']).meta({ label: 'Language' })
+export const CodeReferenceRoleSchema = z
+  .enum(['entrypoint', 'handler', 'schema', 'test', 'docs', 'config'])
+  .meta({ label: 'Code reference role', color: 'blue' })
+
+export const ResourceIdSchema = z
+  .string()
+  .trim()
+  .min(1)
+  .max(255)
+  .regex(/^[A-Za-z0-9]+(?:[-._][A-Za-z0-9]+)*$/, 'Resource IDs must use letters, numbers, -, _, or . separators')
+
+export const EventIdSchema = z
+  .string()
+  .trim()
+  .min(1)
+  .max(300)
+  .regex(
+    /^[A-Za-z0-9]+(?:[-._][A-Za-z0-9]+)*:[a-z0-9]+(?:[-._][a-z0-9]+)*$/,
+    'Event IDs must use <owner-id>:<event-key>'
+  )
+
+export const EventKeySchema = ModelIdSchema
+
+export const EventEmissionDescriptorSchema = z.object({
+  eventKey: EventKeySchema,
+  label: z.string().trim().min(1).max(120),
+  payloadSchema: ModelIdSchema.optional(),
+  lifecycle: SystemLifecycleSchema.optional()
+})
+
 export const EventDescriptorSchema = EventEmissionDescriptorSchema.extend({
   id: EventIdSchema,
   ownerId: z.union([ResourceIdSchema, ModelIdSchema]),
   ownerKind: z.enum(['resource', 'entity']).meta({ label: 'Owner kind' })
 })
 
-const ResourceEntryBaseSchema = z.object({
-  /** Canonical resource id; runtime resourceId derives from this value. */
-  id: ResourceIdSchema,
-  /** Domain-map iteration order. Convention: multiples of 10 (10, 20, 30, ...) to allow easy insertion. */
-  order: z.number().default(0),
-  /** Required single System membership — value is a dot-separated system path (e.g. "sales.lead-gen"). */
+export const ResourceOntologyBindingSchema = z
+  .object({
+    actions: z.array(OntologyIdSchema).optional(),
+    primaryAction: OntologyIdSchema.optional(),
+    reads: z.array(OntologyIdSchema).optional(),
+    writes: z.array(OntologyIdSchema).optional(),
+    usesCatalogs: z.array(OntologyIdSchema).optional(),
+    emits: z.array(OntologyIdSchema).optional()
+  })
+  .superRefine((binding, ctx) => {
+    if (binding.primaryAction === undefined) return
+    if (binding.actions?.includes(binding.primaryAction)) return
+
+    ctx.addIssue({
+      code: z.ZodIssueCode.custom,
+      path: ['primaryAction'],
+      message: 'Resource ontology primaryAction must be included in actions'
+    })
+  })
+
+type OntologyRefInput = string | { id: string }
+type ResourceOntologyBindingInput = {
+  actions?: OntologyRefInput[]
+  primaryAction?: OntologyRefInput
+  reads?: OntologyRefInput[]
+  writes?: OntologyRefInput[]
+  usesCatalogs?: OntologyRefInput[]
+  emits?: OntologyRefInput[]
+}
+
+export const CodeReferenceSchema = z.object({
+  path: z
+    .string()
+    .trim()
+    .min(1)
+    .max(500)
+    .regex(/^[A-Za-z0-9_./$@()[\] -]+$/, 'Code reference paths must be repo-relative paths'),
+  role: CodeReferenceRoleSchema,
+  symbol: z.string().trim().min(1).max(200).optional(),
+  description: z.string().trim().min(1).max(300).optional()
+})
+
+const ResourceEntryBaseSchema = z.object({
+  /** Canonical resource id; runtime resourceId derives from this value. */
+  id: ResourceIdSchema,
+  /** Domain-map iteration order. Convention: multiples of 10 (10, 20, 30, ...) to allow easy insertion. */
+  order: z.number().default(0),
+  /** Required single System membership — value is a dot-separated system path (e.g. "sales.lead-gen"). */
   systemPath: SystemPathSchema.meta({ ref: 'system' }),
-  /** Optional role responsible for maintaining this resource. */
-  ownerRoleId: ModelIdSchema.meta({ ref: 'role' }).optional(),
-  status: ResourceGovernanceStatusSchema
+  /** Executable display title owned by the OM Resource descriptor. */
+  title: LabelSchema.optional(),
+  /** Executable display description owned by the OM Resource descriptor. */
+  description: DescriptionSchema.optional(),
+  /** Optional role responsible for maintaining this resource. */
+  ownerRoleId: ModelIdSchema.meta({ ref: 'role' }).optional(),
+  status: ResourceGovernanceStatusSchema,
+  /**
+   * Ontology contract bindings for the semantic work this resource performs.
+   * `emits` stays nested here so top-level resource emits descriptors remain
+   * compatible with graph event projection during the bridge.
+   */
+  ontology: ResourceOntologyBindingSchema.optional(),
+  /** Repo-relative implementation breadcrumbs for agents and operators. */
+  codeRefs: z.array(CodeReferenceSchema).default([])
 })
-
+
 export const WorkflowResourceEntrySchema = ResourceEntryBaseSchema.extend({
   kind: z.literal('workflow'),
-  /** Mirrors WorkflowConfig.actionKey when the runtime workflow has one. */
-  actionKey: z.string().trim().min(1).max(255).optional(),
   emits: z.array(EventEmissionDescriptorSchema).optional()
 })
-
-export const AgentResourceEntrySchema = ResourceEntryBaseSchema.extend({
-  kind: z.literal('agent'),
-  /** Mirrors code-side AgentConfig.kind. */
-  agentKind: AgentKindSchema,
-  /** Role this agent embodies, if any. */
-  actsAsRoleId: ModelIdSchema.meta({ ref: 'role' }).optional(),
-  /** Mirrors AgentConfig.sessionCapable. */
-  sessionCapable: z.boolean(),
-  /** Broad/composite callable entry points orchestrated by this agent. */
-  invocations: z.array(ActionInvocationSchema).default([]),
-  emits: z.array(EventEmissionDescriptorSchema).optional()
-})
-
-export const IntegrationResourceEntrySchema = ResourceEntryBaseSchema.extend({
-  kind: z.literal('integration'),
-  provider: z.string().trim().min(1).max(100)
-})
-
-export const ScriptResourceSourceSchema = z.union([
-  z.string().trim().min(1).max(50_000),
-  z.object({
-    file: z.string().trim().min(1).max(500)
-  })
-])
-
-export const ScriptResourceEntrySchema = ResourceEntryBaseSchema.extend({
-  kind: z.literal('script'),
-  language: ScriptResourceLanguageSchema,
-  source: ScriptResourceSourceSchema
-})
-
-export const ResourceEntrySchema = z.discriminatedUnion('kind', [
-  WorkflowResourceEntrySchema,
-  AgentResourceEntrySchema,
-  IntegrationResourceEntrySchema,
-  ScriptResourceEntrySchema
-])
-
-export const ResourcesDomainSchema = z
-  .record(z.string(), ResourceEntrySchema)
-  .refine((record) => Object.entries(record).every(([key, entry]) => entry.id === key), {
-    message: 'Each resource entry id must match its map key'
-  })
-  .default({})
-
-export const DEFAULT_ORGANIZATION_MODEL_RESOURCES: z.infer<typeof ResourcesDomainSchema> = {}
-
-export function defineResource<const TResource extends ResourceEntry>(resource: TResource): TResource {
-  return ResourceEntrySchema.parse(resource) as TResource
-}
-
+
+export const AgentResourceEntrySchema = ResourceEntryBaseSchema.extend({
+  kind: z.literal('agent'),
+  /** Mirrors code-side AgentConfig.kind. */
+  agentKind: AgentKindSchema,
+  /** Role this agent embodies, if any. */
+  actsAsRoleId: ModelIdSchema.meta({ ref: 'role' }).optional(),
+  /** Mirrors AgentConfig.sessionCapable. */
+  sessionCapable: z.boolean(),
+  /** Broad/composite callable entry points orchestrated by this agent. */
+  invocations: z.array(ActionInvocationSchema).default([]),
+  emits: z.array(EventEmissionDescriptorSchema).optional()
+})
+
+export const IntegrationResourceEntrySchema = ResourceEntryBaseSchema.extend({
+  kind: z.literal('integration'),
+  provider: z.string().trim().min(1).max(100)
+})
+
+export const ScriptResourceSourceSchema = z.union([
+  z.string().trim().min(1).max(50_000),
+  z.object({
+    file: z.string().trim().min(1).max(500)
+  })
+])
+
+export const ScriptResourceEntrySchema = ResourceEntryBaseSchema.extend({
+  kind: z.literal('script'),
+  language: ScriptResourceLanguageSchema,
+  source: ScriptResourceSourceSchema
+})
+
+export const ResourceEntrySchema = z.discriminatedUnion('kind', [
+  WorkflowResourceEntrySchema,
+  AgentResourceEntrySchema,
+  IntegrationResourceEntrySchema,
+  ScriptResourceEntrySchema
+])
+
+export const ResourcesDomainSchema = z
+  .record(z.string(), ResourceEntrySchema)
+  .refine((record) => Object.entries(record).every(([key, entry]) => entry.id === key), {
+    message: 'Each resource entry id must match its map key'
+  })
+  .default({})
+
+export const DEFAULT_ORGANIZATION_MODEL_RESOURCES: z.infer<typeof ResourcesDomainSchema> = {}
+
+export function defineResource<const TResource extends ResourceEntry>(resource: TResource): TResource {
+  return ResourceEntrySchema.parse(resource) as TResource
+}
+
 export function defineResources<const TResources extends Record<string, ResourceEntry>>(
   resources: TResources
 ): TResources {
-  return Object.fromEntries(
-    Object.entries(resources).map(([key, resource]) => [key, ResourceEntrySchema.parse(resource)])
+  return Object.fromEntries(
+    Object.entries(resources).map(([key, resource]) => [key, ResourceEntrySchema.parse(resource)])
   ) as TResources
 }
 
-export type ResourceId = z.infer<typeof ResourceIdSchema>
-export type ResourceKind = z.infer<typeof ResourceKindSchema>
-export type ResourceGovernanceStatus = z.infer<typeof ResourceGovernanceStatusSchema>
-export type ResourceAgentKind = z.infer<typeof AgentKindSchema>
-export type ScriptResourceLanguage = z.infer<typeof ScriptResourceLanguageSchema>
-export type ScriptResourceSource = z.infer<typeof ScriptResourceSourceSchema>
-export type WorkflowResourceEntry = z.infer<typeof WorkflowResourceEntrySchema>
-export type AgentResourceEntry = z.infer<typeof AgentResourceEntrySchema>
-export type IntegrationResourceEntry = z.infer<typeof IntegrationResourceEntrySchema>
-export type ScriptResourceEntry = z.infer<typeof ScriptResourceEntrySchema>
-export type ResourceEntry = z.infer<typeof ResourceEntrySchema>
-export type ResourcesDomain = z.infer<typeof ResourcesDomainSchema>
+function ontologyIdFrom(input: OntologyRefInput): string {
+  return typeof input === 'string' ? input : input.id
+}
+
+function ontologyIdArrayFrom(input: OntologyRefInput[] | undefined): string[] | undefined {
+  return input?.map(ontologyIdFrom)
+}
+
+export function defineResourceOntology(input: ResourceOntologyBindingInput): ResourceOntologyBinding {
+  return ResourceOntologyBindingSchema.parse({
+    actions: ontologyIdArrayFrom(input.actions),
+    primaryAction: input.primaryAction === undefined ? undefined : ontologyIdFrom(input.primaryAction),
+    reads: ontologyIdArrayFrom(input.reads),
+    writes: ontologyIdArrayFrom(input.writes),
+    usesCatalogs: ontologyIdArrayFrom(input.usesCatalogs),
+    emits: ontologyIdArrayFrom(input.emits)
+  })
+}
+
+export type ResourceId = z.infer<typeof ResourceIdSchema>
+export type ResourceKind = z.infer<typeof ResourceKindSchema>
+export type ResourceGovernanceStatus = z.infer<typeof ResourceGovernanceStatusSchema>
+export type ResourceAgentKind = z.infer<typeof AgentKindSchema>
+export type CodeReferenceRole = z.infer<typeof CodeReferenceRoleSchema>
+export type ResourceOntologyBinding = z.infer<typeof ResourceOntologyBindingSchema>
+export type CodeReference = z.infer<typeof CodeReferenceSchema>
+export type ScriptResourceLanguage = z.infer<typeof ScriptResourceLanguageSchema>
+export type ScriptResourceSource = z.infer<typeof ScriptResourceSourceSchema>
+export type WorkflowResourceEntry = z.infer<typeof WorkflowResourceEntrySchema>
+export type AgentResourceEntry = z.infer<typeof AgentResourceEntrySchema>
+export type IntegrationResourceEntry = z.infer<typeof IntegrationResourceEntrySchema>
+export type ScriptResourceEntry = z.infer<typeof ScriptResourceEntrySchema>
+export type ResourceEntry = z.infer<typeof ResourceEntrySchema>
+export type ResourcesDomain = z.infer<typeof ResourcesDomainSchema>

package/src/organization-model/domains/roles.ts

@@ -1,96 +1,96 @@
-import { z } from 'zod'
-import { ResourceIdSchema } from './resources'
-import { ModelIdSchema } from './shared'
-import { SystemIdSchema } from './systems'
-
-// ---------------------------------------------------------------------------
-// Role schema - one entry per distinct role in the organization's chart.
-// Inspired by the EOS Accountability Chart but uses plain-language field names
-// throughout. No EOS jargon: "title" (not seatTitle), "responsibilities"
-// (not accountabilities), "reportsToId", "heldBy".
-//
-// Cross-reference enforcement lives in `OrganizationModelSchema.superRefine()`:
-// `reportsToId` must resolve to another Role, `responsibleFor` entries must
-// resolve to Systems, and agent holders must resolve to Agent Resources.
-// Role hierarchy cycle detection is also enforced at the model level.
-// ---------------------------------------------------------------------------
-
-export const RoleIdSchema = ModelIdSchema
-
-export const HumanRoleHolderSchema = z.object({
-  kind: z.literal('human'),
-  userId: z.string().trim().min(1).max(200)
-})
-
-export const AgentRoleHolderSchema = z.object({
-  kind: z.literal('agent'),
-  agentId: ResourceIdSchema.meta({ ref: 'resource' })
-})
-
-export const TeamRoleHolderSchema = z.object({
-  kind: z.literal('team'),
-  memberIds: z.array(z.string().trim().min(1).max(200)).min(1)
-})
-
-export const RoleHolderSchema = z.discriminatedUnion('kind', [
-  HumanRoleHolderSchema,
-  AgentRoleHolderSchema,
-  TeamRoleHolderSchema
-])
-
-export const RoleHoldersSchema = z.union([RoleHolderSchema, z.array(RoleHolderSchema).min(1)])
-
-export const RoleSchema = z.object({
-  /** Stable unique identifier for the role (e.g. "role-ceo", "role-head-of-sales"). */
-  id: RoleIdSchema,
-  /** Domain-map iteration order. Convention: multiples of 10 (10, 20, 30, ...) to allow easy insertion. */
-  order: z.number(),
-  /** Human-readable title shown to agents and in UI (e.g. "CEO", "Head of Sales"). */
-  title: z.string().trim().min(1).max(200),
-  /**
-   * List of responsibilities this role owns - plain-language descriptions of
-   * what the person in this role is accountable for delivering.
-   * Defaults to empty array so minimal role definitions stay concise.
-   */
-  responsibilities: z.array(z.string().trim().max(500)).default([]),
-  /**
-   * Optional: ID of another role this role reports to.
-   * When present, must reference another `roles[].id` in the same organization.
-   */
-  reportsToId: RoleIdSchema.meta({ ref: 'role' }).optional(),
-  /**
-   * Optional: human, agent, or team holder currently filling this role.
-   * Agent holders reference OM Resource IDs and are validated at the model level.
-   */
-  heldBy: RoleHoldersSchema.optional(),
-  /**
-   * Optional Systems this role is accountable for.
-   * Cross-reference enforced in `OrganizationModelSchema.superRefine()`.
-   */
-  responsibleFor: z.array(SystemIdSchema.meta({ ref: 'system' })).optional()
-})
-
-// ---------------------------------------------------------------------------
-// Roles domain schema - a collection of roles.
-// ---------------------------------------------------------------------------
-
-export const RolesDomainSchema = z
-  .record(z.string(), RoleSchema)
-  .refine((record) => Object.entries(record).every(([key, entry]) => entry.id === key), {
-    message: 'Each role entry id must match its map key'
-  })
-  .default({})
-
-// ---------------------------------------------------------------------------
-// Seed - empty by default; adapters populate with real role definitions.
-// ---------------------------------------------------------------------------
-
-export const DEFAULT_ORGANIZATION_MODEL_ROLES: z.infer<typeof RolesDomainSchema> = {}
-
-export type RoleId = z.infer<typeof RoleIdSchema>
-export type HumanRoleHolder = z.infer<typeof HumanRoleHolderSchema>
-export type AgentRoleHolder = z.infer<typeof AgentRoleHolderSchema>
-export type TeamRoleHolder = z.infer<typeof TeamRoleHolderSchema>
-export type RoleHolder = z.infer<typeof RoleHolderSchema>
-export type Role = z.infer<typeof RoleSchema>
-export type RolesDomain = z.infer<typeof RolesDomainSchema>
+import { z } from 'zod'
+import { ResourceIdSchema } from './resources'
+import { ModelIdSchema } from './shared'
+import { SystemIdSchema } from './systems'
+
+// ---------------------------------------------------------------------------
+// Role schema - one entry per distinct role in the organization's chart.
+// Inspired by the EOS Accountability Chart but uses plain-language field names
+// throughout. No EOS jargon: "title" (not seatTitle), "responsibilities"
+// (not accountabilities), "reportsToId", "heldBy".
+//
+// Cross-reference enforcement lives in `OrganizationModelSchema.superRefine()`:
+// `reportsToId` must resolve to another Role, `responsibleFor` entries must
+// resolve to Systems, and agent holders must resolve to Agent Resources.
+// Role hierarchy cycle detection is also enforced at the model level.
+// ---------------------------------------------------------------------------
+
+export const RoleIdSchema = ModelIdSchema
+
+export const HumanRoleHolderSchema = z.object({
+  kind: z.literal('human'),
+  userId: z.string().trim().min(1).max(200)
+})
+
+export const AgentRoleHolderSchema = z.object({
+  kind: z.literal('agent'),
+  agentId: ResourceIdSchema.meta({ ref: 'resource' })
+})
+
+export const TeamRoleHolderSchema = z.object({
+  kind: z.literal('team'),
+  memberIds: z.array(z.string().trim().min(1).max(200)).min(1)
+})
+
+export const RoleHolderSchema = z.discriminatedUnion('kind', [
+  HumanRoleHolderSchema,
+  AgentRoleHolderSchema,
+  TeamRoleHolderSchema
+])
+
+export const RoleHoldersSchema = z.union([RoleHolderSchema, z.array(RoleHolderSchema).min(1)])
+
+export const RoleSchema = z.object({
+  /** Stable unique identifier for the role (e.g. "role-ceo", "role-head-of-sales"). */
+  id: RoleIdSchema,
+  /** Domain-map iteration order. Convention: multiples of 10 (10, 20, 30, ...) to allow easy insertion. */
+  order: z.number(),
+  /** Human-readable title shown to agents and in UI (e.g. "CEO", "Head of Sales"). */
+  title: z.string().trim().min(1).max(200),
+  /**
+   * List of responsibilities this role owns - plain-language descriptions of
+   * what the person in this role is accountable for delivering.
+   * Defaults to empty array so minimal role definitions stay concise.
+   */
+  responsibilities: z.array(z.string().trim().max(500)).default([]),
+  /**
+   * Optional: ID of another role this role reports to.
+   * When present, must reference another `roles[].id` in the same organization.
+   */
+  reportsToId: RoleIdSchema.meta({ ref: 'role' }).optional(),
+  /**
+   * Optional: human, agent, or team holder currently filling this role.
+   * Agent holders reference OM Resource IDs and are validated at the model level.
+   */
+  heldBy: RoleHoldersSchema.optional(),
+  /**
+   * Optional Systems this role is accountable for.
+   * Cross-reference enforced in `OrganizationModelSchema.superRefine()`.
+   */
+  responsibleFor: z.array(SystemIdSchema.meta({ ref: 'system' })).optional()
+})
+
+// ---------------------------------------------------------------------------
+// Roles domain schema - a collection of roles.
+// ---------------------------------------------------------------------------
+
+export const RolesDomainSchema = z
+  .record(z.string(), RoleSchema)
+  .refine((record) => Object.entries(record).every(([key, entry]) => entry.id === key), {
+    message: 'Each role entry id must match its map key'
+  })
+  .default({})
+
+// ---------------------------------------------------------------------------
+// Seed - empty by default; adapters populate with real role definitions.
+// ---------------------------------------------------------------------------
+
+export const DEFAULT_ORGANIZATION_MODEL_ROLES: z.infer<typeof RolesDomainSchema> = {}
+
+export type RoleId = z.infer<typeof RoleIdSchema>
+export type HumanRoleHolder = z.infer<typeof HumanRoleHolderSchema>
+export type AgentRoleHolder = z.infer<typeof AgentRoleHolderSchema>
+export type TeamRoleHolder = z.infer<typeof TeamRoleHolderSchema>
+export type RoleHolder = z.infer<typeof RoleHolderSchema>
+export type Role = z.infer<typeof RoleSchema>
+export type RolesDomain = z.infer<typeof RolesDomainSchema>