@elevasis/core 0.22.0 → 0.23.0

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

@@ -1,46 +1,203 @@
-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'
 
 // ---------------------------------------------------------------------------
 // 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.
+// 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'])
-export const SystemStatusSchema = z.enum(['active', 'deprecated', 'archived'])
+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 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 SystemUiSchema = z.object({
+  path: PathSchema,
+  surfaces: ReferenceIdsSchema,
+  icon: IconNameSchema.optional(),
+  order: z.number().int().optional()
 })
 
-export const SystemsDomainSchema = z.object({
-  systems: z.array(SystemEntrySchema).default([])
-})
+// ---------------------------------------------------------------------------
+// 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'
 
-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
+  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-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.
+     */
+    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.
+     */
+    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) => {
+    if (system.status === undefined) return system
+
+    console.warn('[organization-model] System.status is deprecated; use System.lifecycle instead.')
+    return system.lifecycle === undefined ? { ...system, lifecycle: system.status } : system
+  })
+
+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>
+// 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,88 +1,75 @@
 import { resolveOrganizationModel } from './resolve'
 import type { OrganizationModelBuiltinIconToken } from './icons'
-import type { DeepPartial, OrganizationModel, OrganizationModelFeature } from './types'
+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'
+  | '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 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[]
-  }
-}
-
-export interface FoundationBranding {
-  organizationName: string
-  productName: string
-  shortName: string
-}
-
-export function createFoundationOrganizationModel(override: DeepPartial<OrganizationModel>): {
-  canonical: OrganizationModel
-  model: FoundationOrganizationModel
-  homeLabel: string
-  quickAccessSurfaceIds: readonly string[]
-  getOrganizationSurface: (surfaceId: string) => FoundationNavigationSurface | undefined
-} {
-  const canonical = resolveOrganizationModel(override)
+    quickAccessSurfaceIds: readonly string[]
+    surfaces: FoundationNavigationSurface[]
+  }
+}
 
-  function requireCoreFeature(featureId: string): OrganizationModelFeature {
-    const feature = canonical.features.find((candidate) => candidate.id === featureId)
+export interface FoundationBranding {
+  organizationName: string
+  productName: string
+  shortName: string
+}
 
-    if (!feature) {
-      throw new Error(`Missing organization surface/feature: ${featureId}`)
-    }
+export function createFoundationOrganizationModel(override: DeepPartial<OrganizationModel>): {
+  canonical: OrganizationModel
+  model: FoundationOrganizationModel
+  homeLabel: string
+  quickAccessSurfaceIds: readonly string[]
+  getOrganizationSurface: (surfaceId: string) => FoundationNavigationSurface | undefined
+} {
+  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)
 
-    return feature
+  const model: FoundationOrganizationModel = {
+    ...canonical,
+    navigation: {
+      defaultSurfaceId: defaultSurface?.id ?? '',
+      homeLabel,
+      quickAccessSurfaceIds: [...quickAccessSurfaceIds],
+      surfaces: navigationSurfaces
+    }
   }
 
-  const operationsFeature = requireCoreFeature('operations')
-  const projectsFeature = requireCoreFeature('projects')
-  const leadGenFeature = requireCoreFeature('sales.lead-gen')
-  const crmFeature = requireCoreFeature('sales.crm')
+  function getOrganizationSurface(surfaceId: string): FoundationNavigationSurface | undefined {
+    return model.navigation.surfaces.find((candidate) => candidate.id === surfaceId)
+  }
 
-  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 model: FoundationOrganizationModel = {
-    ...canonical,
-    navigation: {
-      defaultSurfaceId: 'operations',
-      homeLabel,
-      quickAccessSurfaceIds: [...quickAccessSurfaceIds],
-      surfaces: navigationSurfaces
-    }
-  }
-
-  function getOrganizationSurface(surfaceId: string): FoundationNavigationSurface | undefined {
-    return model.navigation.surfaces.find((candidate) => candidate.id === surfaceId)
-  }
-
-  return {
-    canonical,
-    model,
-    homeLabel,
-    quickAccessSurfaceIds,
-    getOrganizationSurface
-  }
-}
+  return {
+    canonical,
+    model,
+    homeLabel,
+    quickAccessSurfaceIds,
+    getOrganizationSurface
+  }
+}