@elevasis/core 0.22.0 → 0.24.0

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

@@ -1,46 +1,248 @@
-import { z } from 'zod'
-import { DescriptionSchema, LabelSchema, ModelIdSchema, 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 that groups operational
-// resources and carries governance metadata. The shared schema validates the
-// shape and references; each tenant supplies its own catalog.
+export type JsonPrimitive = string | number | boolean | null
+export type JsonValue = JsonPrimitive | JsonValue[] | { [key: string]: JsonValue }
 
-export const SystemKindSchema = z.enum(['product', 'operational', 'platform', 'diagnostic'])
-export const SystemStatusSchema = z.enum(['active', 'deprecated', 'archived'])
-export const SystemIdSchema = ModelIdSchema
+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)
+  ])
+)
 
-export const SystemEntrySchema = z.object({
-  /** Stable tenant-defined system id (e.g. "sys.lead-gen"). */
-  id: SystemIdSchema,
-  /** Human-readable system title shown in governance and operations UI. */
-  title: LabelSchema,
-  /** One-paragraph purpose statement for the bounded context. */
-  description: DescriptionSchema,
-  /** Closed system shape enum; catalog values remain tenant-defined. */
-  kind: SystemKindSchema,
-  /** Optional role responsible for this system. */
-  responsibleRoleId: ModelIdSchema.optional(),
-  /** Optional knowledge nodes that govern this system. */
-  governedByKnowledge: ReferenceIdsSchema,
-  /** Optional goals this system contributes to. */
-  drivesGoals: ReferenceIdsSchema,
-  status: SystemStatusSchema
-})
+export const SystemConfigSchema = z
+  .record(z.string().trim().min(1).max(200), JsonValueSchema)
+  .default({})
+  .optional()
 
-export const SystemsDomainSchema = z.object({
-  systems: z.array(SystemEntrySchema).default([])
-})
-
-export const DEFAULT_ORGANIZATION_MODEL_SYSTEMS: z.infer<typeof SystemsDomainSchema> = {
-  systems: []
+/** 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
+  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(),
+    requiresAdmin: z.boolean().optional(),
+    /** Domain-map iteration order. Convention: multiples of 10 (10, 20, 30, ...) to allow easy insertion. */
+    order: z.number(),
+    /**
+     * 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.
+     */
+    ontology: OntologyScopeSchema.optional(),
+    /**
+     * @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'
+  })
+  .transform((system: SystemEntry) => {
+    const normalizedSystem =
+      system.systems !== undefined && system.subsystems === undefined ? { ...system, subsystems: system.systems } : system
+
+    if (normalizedSystem.status === undefined) return normalizedSystem
 
-export type SystemId = z.infer<typeof SystemIdSchema>
+    console.warn('[organization-model] System.status is deprecated; use System.lifecycle instead.')
+    return normalizedSystem.lifecycle === undefined
+      ? { ...normalizedSystem, lifecycle: normalizedSystem.status }
+      : 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'
+  })
+  .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 SystemEntry = z.infer<typeof SystemEntrySchema>
-export type SystemsDomain = z.infer<typeof SystemsDomainSchema>
+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>

package/src/organization-model/foundation.ts

@@ -1,23 +1,29 @@
-import { resolveOrganizationModel } from './resolve'
-import type { OrganizationModelBuiltinIconToken } from './icons'
-import type { DeepPartial, OrganizationModel, OrganizationModelFeature } from './types'
-
-export type FoundationSurfaceType = 'page' | 'dashboard' | 'graph' | 'detail' | 'list' | 'settings'
-
-export type FoundationSurfaceIcon = Extract<
-  OrganizationModelBuiltinIconToken,
-  'feature.dashboard' | 'feature.crm' | 'feature.lead-gen' | 'feature.projects' | 'feature.operations' | 'feature.settings'
->
-
-export interface FoundationNavigationSurface extends Omit<OrganizationModelFeature, 'icon' | 'uiPosition'> {
-  icon?: FoundationSurfaceIcon
-  surfaceType?: FoundationSurfaceType
-}
-
-export interface FoundationOrganizationModel extends Omit<OrganizationModel, 'navigation'> {
-  navigation: {
-    defaultSurfaceId: string
-    homeLabel: string
+import { resolveOrganizationModel } from './resolve'
+import type { OrganizationModelBuiltinIconToken } from './icons'
+import { projectOrganizationSurfaces, type OrganizationSurfaceProjection } from './surface-projection'
+import type { DeepPartial, OrganizationModel } from './types'
+
+export type FoundationSurfaceType = 'page' | 'dashboard' | 'graph' | 'detail' | 'list' | 'settings'
+
+export type FoundationSurfaceIcon = Extract<
+  OrganizationModelBuiltinIconToken,
+  | 'feature.dashboard'
+  | 'feature.crm'
+  | 'feature.lead-gen'
+  | 'feature.projects'
+  | 'feature.operations'
+  | 'feature.settings'
+>
+
+export type FoundationNavigationSurface = Omit<OrganizationSurfaceProjection, 'icon' | 'surfaceType'> & {
+  icon?: FoundationSurfaceIcon | OrganizationModelBuiltinIconToken | string
+  surfaceType: FoundationSurfaceType
+}
+
+export interface FoundationOrganizationModel extends Omit<OrganizationModel, 'navigation'> {
+  navigation: {
+    defaultSurfaceId: string
+    homeLabel: string
     quickAccessSurfaceIds: readonly string[]
     surfaces: FoundationNavigationSurface[]
   }
@@ -36,38 +42,19 @@ export function createFoundationOrganizationModel(override: DeepPartial<Organiza
   quickAccessSurfaceIds: readonly string[]
   getOrganizationSurface: (surfaceId: string) => FoundationNavigationSurface | undefined
 } {
-  const canonical = resolveOrganizationModel(override)
-
-  function requireCoreFeature(featureId: string): OrganizationModelFeature {
-    const feature = canonical.features.find((candidate) => candidate.id === featureId)
-
-    if (!feature) {
-      throw new Error(`Missing organization surface/feature: ${featureId}`)
-    }
-
-    return feature
-  }
-
-  const operationsFeature = requireCoreFeature('operations')
-  const projectsFeature = requireCoreFeature('projects')
-  const leadGenFeature = requireCoreFeature('sales.lead-gen')
-  const crmFeature = requireCoreFeature('sales.crm')
-
-  const navigationSurfaces: FoundationNavigationSurface[] = [
-    { ...operationsFeature, id: 'operations', path: '/operations', icon: 'feature.operations', surfaceType: 'dashboard' },
-    { ...projectsFeature, icon: 'feature.projects', surfaceType: 'list' },
-    { ...leadGenFeature, id: 'lead-gen', icon: 'feature.lead-gen', surfaceType: 'list' },
-    { ...crmFeature, id: 'crm', icon: 'feature.crm', surfaceType: 'graph' },
-    { ...requireCoreFeature('settings.account'), id: 'settings', icon: 'feature.settings', surfaceType: 'settings' }
-  ]
-
-  const homeLabel = 'Dashboard'
-  const quickAccessSurfaceIds = ['operations', 'projects', 'lead-gen', 'crm'] as const
+  const canonical = resolveOrganizationModel(override)
+  const navigationSurfaces: FoundationNavigationSurface[] = projectOrganizationSurfaces(canonical)
+  const defaultSurface = navigationSurfaces.find((surface) => surface.path === '/') ?? navigationSurfaces[0]
+  const homeLabel = defaultSurface?.label ?? 'Dashboard'
+  const quickAccessSurfaceIds = navigationSurfaces
+    .filter((surface) => surface.id !== defaultSurface?.id && surface.surfaceType !== 'settings')
+    .slice(0, 4)
+    .map((surface) => surface.id)
 
   const model: FoundationOrganizationModel = {
     ...canonical,
     navigation: {
-      defaultSurfaceId: 'operations',
+      defaultSurfaceId: defaultSurface?.id ?? '',
       homeLabel,
       quickAccessSurfaceIds: [...quickAccessSurfaceIds],
       surfaces: navigationSurfaces