@elevasis/core 0.23.0 → 0.24.1

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

@@ -1,203 +1,248 @@
-import { z, type ZodType } from 'zod'
-import { ActionRefSchema } from './actions'
-import {
-  ColorTokenSchema,
-  DescriptionSchema,
-  IconNameSchema,
-  LabelSchema,
-  ModelIdSchema,
-  PathSchema,
-  ReferenceIdsSchema
-} from './shared'
+import { z, type ZodType } from 'zod'
+import { ActionRefSchema } from './actions'
+import {
+  ColorTokenSchema,
+  DescriptionSchema,
+  IconNameSchema,
+  LabelSchema,
+  ModelIdSchema,
+  PathSchema,
+  ReferenceIdsSchema
+} from './shared'
 import { ContentNodeSchema } from '../content-kinds/types'
+import { OntologyScopeSchema, type OntologyScope } from '../ontology'
+
+// ---------------------------------------------------------------------------
+// Systems domain
+// ---------------------------------------------------------------------------
+//
+// A System is a tenant-defined bounded context. It can carry UI presence,
+// hierarchy, and governance metadata; non-UI systems simply omit `ui`.
+
+export const SystemKindSchema = z
+  .enum(['product', 'operational', 'platform', 'diagnostic'])
+  .meta({ label: 'System kind', color: 'blue' })
+export const SystemLifecycleSchema = z
+  .enum(['draft', 'beta', 'active', 'deprecated', 'archived'])
+  .meta({ label: 'Lifecycle', color: 'teal' })
+/** @deprecated Use SystemLifecycleSchema. Accepted for one publish cycle. */
+export const SystemStatusSchema = z.enum(['active', 'deprecated', 'archived']).meta({ label: 'Status', color: 'teal' })
+export const SystemIdSchema = ModelIdSchema
+/**
+ * Validates a dot-separated system path (e.g. "sales.lead-gen", "sales.crm").
+ * Each segment is lowercase, starts with a letter or digit, and may contain hyphens.
+ * This is the canonical form used in `resource.systemPath`.
+ */
+export const SystemPathSchema = z
+  .string()
+  .trim()
+  .min(1)
+  .regex(
+    /^[a-z0-9][a-z0-9-]*(?:\.[a-z0-9][a-z0-9-]*)*$/,
+    'must be a dotted lowercase path (e.g. "sales.lead-gen" or "sales.crm")'
+  )
+export const UiPositionSchema = z.enum(['sidebar-primary', 'sidebar-bottom']).meta({ label: 'UI position' })
+export const NodeIdPathSchema = SystemIdSchema
+export const NodeIdStringSchema = z
+  .string()
+  .trim()
+  .min(1)
+  .max(200)
+  // D4: kind prefix allows hyphens (e.g. 'content-node'); id allows colons for
+  // qualified content-node references ('content-node:sales.crm:default-pipeline').
+  .regex(
+    /^[a-z][a-z-]*:([a-z0-9-]+)(\.[a-z0-9-]+)*(:[a-z0-9.-]+)*$/,
+    'Node references must use kind:dotted-path (e.g. system:sales.crm or content-node:sales.crm:pipeline-id)'
+  )
+
+export const SystemUiSchema = z.object({
+  path: PathSchema,
+  surfaces: ReferenceIdsSchema,
+  icon: IconNameSchema.optional(),
+  order: z.number().int().optional()
+})
+
+// ---------------------------------------------------------------------------
+// Recursive SystemEntry schema.
+//
+// TypeScript cannot infer the type of a schema that references itself through
+// z.lazy(). The standard Zod fix is to:
+//   1. Declare the output type as an explicit interface BEFORE the schema.
+//   2. Annotate the schema variable with `ZodType<SystemEntry>` so TS uses
+//      the declared interface instead of trying to infer through the cycle.
+// ---------------------------------------------------------------------------
+
+import type { ContentNode } from '../content-kinds/types'
 
-// ---------------------------------------------------------------------------
-// Systems domain
-// ---------------------------------------------------------------------------
-//
-// A System is a tenant-defined bounded context. It can carry UI presence,
-// hierarchy, and governance metadata; non-UI systems simply omit `ui`.
-
-export const SystemKindSchema = z
-  .enum(['product', 'operational', 'platform', 'diagnostic'])
-  .meta({ label: 'System kind', color: 'blue' })
-export const SystemLifecycleSchema = z
-  .enum(['draft', 'beta', 'active', 'deprecated', 'archived'])
-  .meta({ label: 'Lifecycle', color: 'teal' })
-/** @deprecated Use SystemLifecycleSchema. Accepted for one publish cycle. */
-export const SystemStatusSchema = z.enum(['active', 'deprecated', 'archived']).meta({ label: 'Status', color: 'teal' })
-export const SystemIdSchema = ModelIdSchema
-/**
- * Validates a dot-separated system path (e.g. "sales.lead-gen", "sales.crm").
- * Each segment is lowercase, starts with a letter or digit, and may contain hyphens.
- * This is the canonical form used in `resource.systemPath`.
- */
-export const SystemPathSchema = z
-  .string()
-  .trim()
-  .min(1)
-  .regex(
-    /^[a-z0-9][a-z0-9-]*(?:\.[a-z0-9][a-z0-9-]*)*$/,
-    'must be a dotted lowercase path (e.g. "sales.lead-gen" or "sales.crm")'
-  )
-export const UiPositionSchema = z.enum(['sidebar-primary', 'sidebar-bottom']).meta({ label: 'UI position' })
-export const NodeIdPathSchema = SystemIdSchema
-export const NodeIdStringSchema = z
-  .string()
-  .trim()
-  .min(1)
-  .max(200)
-  // D4: kind prefix allows hyphens (e.g. 'content-node'); id allows colons for
-  // qualified content-node references ('content-node:sales.crm:default-pipeline').
-  .regex(
-    /^[a-z][a-z-]*:([a-z0-9-]+)(\.[a-z0-9-]+)*(:[a-z0-9.-]+)*$/,
-    'Node references must use kind:dotted-path (e.g. system:sales.crm or content-node:sales.crm:pipeline-id)'
-  )
-
-export const SystemUiSchema = z.object({
-  path: PathSchema,
-  surfaces: ReferenceIdsSchema,
-  icon: IconNameSchema.optional(),
-  order: z.number().int().optional()
-})
+export type JsonPrimitive = string | number | boolean | null
+export type JsonValue = JsonPrimitive | JsonValue[] | { [key: string]: JsonValue }
 
-// ---------------------------------------------------------------------------
-// Recursive SystemEntry schema.
-//
-// TypeScript cannot infer the type of a schema that references itself through
-// z.lazy(). The standard Zod fix is to:
-//   1. Declare the output type as an explicit interface BEFORE the schema.
-//   2. Annotate the schema variable with `ZodType<SystemEntry>` so TS uses
-//      the declared interface instead of trying to infer through the cycle.
-// ---------------------------------------------------------------------------
+export const JsonValueSchema: ZodType<JsonValue> = z.lazy(() =>
+  z.union([
+    z.string(),
+    z.number(),
+    z.boolean(),
+    z.null(),
+    z.array(JsonValueSchema),
+    z.record(z.string(), JsonValueSchema)
+  ])
+)
 
-import type { ContentNode } from '../content-kinds/types'
+export const SystemConfigSchema = z
+  .record(z.string().trim().min(1).max(200), JsonValueSchema)
+  .default({})
+  .optional()
 
 /** Explicit interface needed to annotate the recursive SystemEntrySchema. */
 export interface SystemEntry {
-  id: string
-  label?: string
-  title?: string
-  description?: string
-  kind?: 'product' | 'operational' | 'platform' | 'diagnostic'
-  parentSystemId?: string
-  ui?: { path: string; surfaces: string[]; icon?: string; order?: number }
-  lifecycle?: 'draft' | 'beta' | 'active' | 'deprecated' | 'archived'
-  responsibleRoleId?: string
-  governedByKnowledge?: string[]
-  actions?: { actionId: string; intent: 'exposes' | 'consumes'; invocation?: unknown }[]
-  policies?: string[]
-  drivesGoals?: string[]
-  /** @deprecated Use lifecycle. Accepted for one publish cycle. */
-  status?: 'active' | 'deprecated' | 'archived'
-  path?: string
-  icon?: string
-  color?: string
-  uiPosition?: 'sidebar-primary' | 'sidebar-bottom'
-  enabled?: boolean
+  id: string
+  label?: string
+  title?: string
+  description?: string
+  kind?: 'product' | 'operational' | 'platform' | 'diagnostic'
+  parentSystemId?: string
+  ui?: { path: string; surfaces: string[]; icon?: string; order?: number }
+  lifecycle?: 'draft' | 'beta' | 'active' | 'deprecated' | 'archived'
+  responsibleRoleId?: string
+  governedByKnowledge?: string[]
+  actions?: { actionId: string; intent: 'exposes' | 'consumes'; invocation?: unknown }[]
+  policies?: string[]
+  drivesGoals?: string[]
+  /** @deprecated Use lifecycle. Accepted for one publish cycle. */
+  status?: 'active' | 'deprecated' | 'archived'
+  path?: string
+  icon?: string
+  color?: string
+  uiPosition?: 'sidebar-primary' | 'sidebar-bottom'
+  enabled?: boolean
   devOnly?: boolean
   requiresAdmin?: boolean
   order: number
+  config?: Record<string, JsonValue>
+  ontology?: OntologyScope
+  systems?: Record<string, SystemEntry>
+  /**
+   * @deprecated Compatibility-only bridge for old tenant data and migration readers.
+   * Author new semantic catalogs in `ontology` and local settings in `config`.
+   */
   content?: Record<string, ContentNode>
   subsystems?: Record<string, SystemEntry>
 }
-
-export const SystemEntrySchema: ZodType<SystemEntry> = z
-  .object({
-    /** Stable tenant-defined system id (e.g. "sys.lead-gen" or "sales.crm"). */
-    id: SystemIdSchema,
-    /** Human-readable system label shown in UI, governance, and operations surfaces. */
-    label: LabelSchema.optional(),
-    /** @deprecated Use label. Accepted for pre-consolidation System declarations. */
-    title: LabelSchema.optional(),
-    /** One-paragraph purpose statement for the bounded context. */
-    description: DescriptionSchema.optional(),
-    /** Closed system shape enum; catalog values remain tenant-defined. */
-    kind: SystemKindSchema.optional(),
-    /** Optional self-reference for System hierarchy. */
-    parentSystemId: SystemIdSchema.optional(),
-    /** Optional UI presence. Systems without UI omit this. */
-    ui: SystemUiSchema.optional(),
-    /** Canonical lifecycle state. Replaces Feature.enabled/devOnly and System.status. */
-    lifecycle: SystemLifecycleSchema.optional(),
-    /** Optional role responsible for this system. */
-    responsibleRoleId: ModelIdSchema.meta({ ref: 'role' }).optional(),
-    /** Optional knowledge nodes that govern this system. */
-    governedByKnowledge: z
-      .array(ModelIdSchema.meta({ ref: 'knowledge' }))
-      .default([])
-      .optional(),
-    /** Optional actions this system exposes or consumes. */
-    actions: z.array(ActionRefSchema).optional(),
-    /** Optional operational policies that apply to this system. */
-    policies: z
-      .array(ModelIdSchema.meta({ ref: 'policy' }))
-      .default([])
-      .optional(),
-    /** Optional goals this system contributes to. */
-    drivesGoals: z
-      .array(ModelIdSchema.meta({ ref: 'goal' }))
-      .default([])
-      .optional(),
-    /** @deprecated Use lifecycle. Accepted for one publish cycle. */
-    status: SystemStatusSchema.optional(),
-    /** @deprecated Use ui.path. Kept for one-cycle Feature compatibility. */
-    path: PathSchema.optional(),
-    /** @deprecated Use ui.icon. Kept for one-cycle Feature compatibility. */
-    icon: IconNameSchema.optional(),
-    /** @deprecated Feature color token, retained for one-cycle compatibility. */
-    color: ColorTokenSchema.optional(),
-    /** @deprecated UI placement hint, retained for one-cycle compatibility. */
-    uiPosition: UiPositionSchema.optional(),
-    /** @deprecated Use lifecycle. */
-    enabled: z.boolean().optional(),
-    /** @deprecated Use lifecycle: "beta". */
-    devOnly: z.boolean().optional(),
+
+export const SystemEntrySchema: ZodType<SystemEntry> = z
+  .object({
+    /** Stable tenant-defined system id (e.g. "sys.lead-gen" or "sales.crm"). */
+    id: SystemIdSchema,
+    /** Human-readable system label shown in UI, governance, and operations surfaces. */
+    label: LabelSchema.optional(),
+    /** @deprecated Use label. Accepted for pre-consolidation System declarations. */
+    title: LabelSchema.optional(),
+    /** One-paragraph purpose statement for the bounded context. */
+    description: DescriptionSchema.optional(),
+    /** Closed system shape enum; catalog values remain tenant-defined. */
+    kind: SystemKindSchema.optional(),
+    /** Optional self-reference for System hierarchy. */
+    parentSystemId: SystemIdSchema.optional(),
+    /** Optional UI presence. Systems without UI omit this. */
+    ui: SystemUiSchema.optional(),
+    /** Canonical lifecycle state. Replaces Feature.enabled/devOnly and System.status. */
+    lifecycle: SystemLifecycleSchema.optional(),
+    /** Optional role responsible for this system. */
+    responsibleRoleId: ModelIdSchema.meta({ ref: 'role' }).optional(),
+    /** Optional knowledge nodes that govern this system. */
+    governedByKnowledge: z
+      .array(ModelIdSchema.meta({ ref: 'knowledge' }))
+      .default([])
+      .optional(),
+    /** Optional actions this system exposes or consumes. */
+    actions: z.array(ActionRefSchema).optional(),
+    /** Optional operational policies that apply to this system. */
+    policies: z
+      .array(ModelIdSchema.meta({ ref: 'policy' }))
+      .default([])
+      .optional(),
+    /** Optional goals this system contributes to. */
+    drivesGoals: z
+      .array(ModelIdSchema.meta({ ref: 'goal' }))
+      .default([])
+      .optional(),
+    /** @deprecated Use lifecycle. Accepted for one publish cycle. */
+    status: SystemStatusSchema.optional(),
+    /** @deprecated Use ui.path. Kept for one-cycle Feature compatibility. */
+    path: PathSchema.optional(),
+    /** @deprecated Use ui.icon. Kept for one-cycle Feature compatibility. */
+    icon: IconNameSchema.optional(),
+    /** @deprecated Feature color token, retained for one-cycle compatibility. */
+    color: ColorTokenSchema.optional(),
+    /** @deprecated UI placement hint, retained for one-cycle compatibility. */
+    uiPosition: UiPositionSchema.optional(),
+    /** @deprecated Use lifecycle. */
+    enabled: z.boolean().optional(),
+    /** @deprecated Use lifecycle: "beta". */
+    devOnly: z.boolean().optional(),
     requiresAdmin: z.boolean().optional(),
     /** Domain-map iteration order. Convention: multiples of 10 (10, 20, 30, ...) to allow easy insertion. */
     order: z.number(),
     /**
-     * System-scoped operational data, co-located with the owning system.
-     * Per L1, L3, L13: keyed by local NodeId (the key is the local id; qualified
-     * id is `<system-path>:<local-id>`, computed by graph projection).
-     * Per L14: every ContentNode carries both `kind` and `type`.
-     * Per D2: unregistered (kind, type) pairs parse successfully.
+     * System-local JSON settings and defaults. Strongly typed OM fields,
+     * secrets, credentials, and runtime state stay outside this bucket.
+     */
+    config: SystemConfigSchema,
+    /**
+     * System-owned ontology declarations. `systems` is now the canonical child
+     * key; this scope holds the object, action, catalog, link, event, and
+     * shared contract records owned by this system.
      */
-    content: z.record(z.string().trim().min(1).max(200), ContentNodeSchema).optional(),
+    ontology: OntologyScopeSchema.optional(),
     /**
-     * Recursive child systems, authored via nesting (per L11).
-     * The key is the local system id; the full path is computed by joining
-     * ancestor keys with `.` (e.g. parent key `'sales'` + child key `'crm'` → `'sales.crm'`).
-     * Per Phase 4: `id` and `parentSystemId` fields will be removed in favour of
-     * position-derived paths. Both still exist on this schema for backward compat.
+     * @deprecated Compatibility-only bridge for old tenant content nodes and
+     * migration readers. New schema/catalog authoring belongs in ontology;
+     * new system-local settings belong in config. Bridge nodes are keyed by
+     * local NodeId and may still project to content-node:* graph IDs.
      */
+    content: z.record(z.string().trim().min(1).max(200), ContentNodeSchema).optional(),
+    /**
+     * Recursive child systems, authored via nesting (per L11).
+     * The key is the local system id; the full path is computed by joining
+     * ancestor keys with `.` (e.g. parent key `'sales'` + child key `'crm'` → `'sales.crm'`).
+     * Per Phase 4: `id` and `parentSystemId` fields will be removed in favour of
+     * position-derived paths. Both still exist on this schema for backward compat.
+     */
+    systems: z.lazy(() => z.record(z.string().trim().min(1).max(100), SystemEntrySchema)).optional(),
+    /** @deprecated Use systems. Accepted as a compatibility alias during the ontology bridge. */
     subsystems: z.lazy(() => z.record(z.string().trim().min(1).max(100), SystemEntrySchema)).optional()
   })
-  .refine((system: SystemEntry) => system.label !== undefined || system.title !== undefined, {
-    path: ['label'],
-    message: 'System must provide label or title'
-  })
+  .refine((system: SystemEntry) => system.label !== undefined || system.title !== undefined, {
+    path: ['label'],
+    message: 'System must provide label or title'
+  })
   .transform((system: SystemEntry) => {
-    if (system.status === undefined) return system
+    const normalizedSystem =
+      system.systems !== undefined && system.subsystems === undefined ? { ...system, subsystems: system.systems } : system
 
-    console.warn('[organization-model] System.status is deprecated; use System.lifecycle instead.')
-    return system.lifecycle === undefined ? { ...system, lifecycle: system.status } : system
-  })
+    if (normalizedSystem.status === undefined) return normalizedSystem
 
-export const SystemsDomainSchema = z
-  .record(z.string(), SystemEntrySchema)
-  .refine((record) => Object.entries(record).every(([key, entry]) => entry.id === key), {
-    message: 'Each system entry id must match its map key'
+    console.warn('[organization-model] System.status is deprecated; use System.lifecycle instead.')
+    return normalizedSystem.lifecycle === undefined
+      ? { ...normalizedSystem, lifecycle: normalizedSystem.status }
+      : normalizedSystem
   })
-  .default({})
-
-export const DEFAULT_ORGANIZATION_MODEL_SYSTEMS: z.infer<typeof SystemsDomainSchema> = {}
-
-export type SystemId = z.infer<typeof SystemIdSchema>
+
+export const SystemsDomainSchema = z
+  .record(z.string(), SystemEntrySchema)
+  .refine((record) => Object.entries(record).every(([key, entry]) => entry.id === key), {
+    message: 'Each system entry id must match its map key'
+  })
+  .default({})
+
+export const DEFAULT_ORGANIZATION_MODEL_SYSTEMS: z.infer<typeof SystemsDomainSchema> = {}
+
+export type SystemId = z.infer<typeof SystemIdSchema>
 export type SystemKind = z.infer<typeof SystemKindSchema>
 export type SystemLifecycle = z.infer<typeof SystemLifecycleSchema>
 /** @deprecated Use SystemLifecycle. Accepted for one publish cycle. */
 export type SystemStatus = z.infer<typeof SystemStatusSchema>
+export type SystemLocalConfig = z.infer<typeof SystemConfigSchema>
 // SystemEntry is declared as an explicit interface above the schema (required for
-// recursive z.lazy() type inference). Re-export omitted — the interface IS the type.
-export type SystemsDomain = z.infer<typeof SystemsDomainSchema>
+// recursive z.lazy() type inference). Re-export omitted — the interface IS the type.
+export type SystemsDomain = z.infer<typeof SystemsDomainSchema>