@elevasis/core 0.23.0 → 0.24.0

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

@@ -2,120 +2,136 @@ import { z } from 'zod'
 import { IconNameSchema, ModelIdSchema } from './shared'
 import { NodeIdStringSchema } from './systems'
 import { RoleIdSchema } from './roles'
-
-// ---------------------------------------------------------------------------
-// KnowledgeLink — a typed graph link pointing to another OM node.
-// Uses NodeIdStringSchema (kind:dotted-path) to resolve to a graph node.
-// Phase 1 only emits 'governs' edges from knowledge nodes.
-// ---------------------------------------------------------------------------
-
-export const KnowledgeTargetKindSchema = z
-  .enum([
-    'system',
-    'resource',
-    'knowledge',
-    'stage',
-    'action',
-    'role',
-    'goal',
+import { OntologyIdSchema } from '../ontology'
+
+// ---------------------------------------------------------------------------
+// KnowledgeLink — a typed graph link pointing to another OM node.
+// Uses NodeIdStringSchema (kind:dotted-path) to resolve to a graph node.
+// Phase 1 only emits 'governs' edges from knowledge nodes.
+// ---------------------------------------------------------------------------
+
+export const KnowledgeTargetKindSchema = z
+  .enum([
+    'system',
+    'resource',
+    'knowledge',
+    'stage',
+    'action',
+    'role',
+    'goal',
     'customer-segment',
     'offering',
+    'ontology',
     // D4: content nodes are a valid knowledge target after compound-domain data moved into system.content
     'content-node'
   ])
   .meta({ label: 'Target kind' })
 
-export const KnowledgeTargetRefSchema = z.object({
-  kind: KnowledgeTargetKindSchema,
-  // D4: content-node targets use a qualified id format '<system-path>:<local-content-id>'
-  // which contains a colon separator and cannot satisfy ModelIdSchema. Use a permissive
-  // string schema here; business-logic validation of target existence is done in
-  // OrganizationModelSchema.superRefine (knowledgeTargetExists).
-  id: z.string().trim().min(1).max(300)
-})
-
-const LegacyKnowledgeLinkSchema = z.object({
-  nodeId: NodeIdStringSchema
-})
-
-const CanonicalKnowledgeLinkSchema = z.object({
-  target: KnowledgeTargetRefSchema
-})
-
-function nodeIdFromTarget(target: z.infer<typeof KnowledgeTargetRefSchema>): string {
-  return `${target.kind}:${target.id}`
-}
-
-function targetFromNodeId(nodeId: string): z.infer<typeof KnowledgeTargetRefSchema> {
-  const [kind, ...idParts] = nodeId.split(':')
-  return {
-    kind: KnowledgeTargetKindSchema.parse(kind),
-    id: idParts.join(':')
-  }
-}
+export const KnowledgeTargetRefSchema = z
+  .object({
+    kind: KnowledgeTargetKindSchema,
+    // D4: content-node targets use a qualified id format '<system-path>:<local-content-id>'.
+    // Ontology targets use the canonical '<scope>:<kind>/<local-id>' ontology id format.
+    // Business-logic validation of target existence is done in OrganizationModelSchema.superRefine.
+    id: z.string().trim().min(1).max(300)
+  })
+  .superRefine((target, ctx) => {
+    if (target.kind !== 'ontology') return
 
-export const KnowledgeLinkSchema = z
-  .union([CanonicalKnowledgeLinkSchema, LegacyKnowledgeLinkSchema])
-  .transform((link) => {
-    const target = 'target' in link ? link.target : targetFromNodeId(link.nodeId)
-    return {
-      target,
-      nodeId: nodeIdFromTarget(target)
+    const result = OntologyIdSchema.safeParse(target.id)
+    if (!result.success) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        path: ['id'],
+        message: 'Ontology knowledge targets must use <system-path>:<kind>/<local-id> or global:<kind>/<local-id>'
+      })
     }
   })
 
-// ---------------------------------------------------------------------------
-// OrgKnowledgeNode — single schema, `kind` discriminator drives presentation.
-// Phase 1: body is raw MDX string (lossless migration from operations/ docs).
-// Phase 2 (deferred): structured block format (Supabase-backed authoring).
-// ---------------------------------------------------------------------------
-
-export const OrgKnowledgeKindSchema = z
-  .enum(['playbook', 'strategy', 'reference'])
-  .meta({ label: 'Knowledge kind', color: 'grape' })
-
-export const OrgKnowledgeNodeSchema = z.object({
-  id: ModelIdSchema,
-  kind: OrgKnowledgeKindSchema,
-  title: z.string().trim().min(1).max(200),
-  summary: z.string().trim().min(1).max(1000),
+const LegacyKnowledgeLinkSchema = z.object({
+  nodeId: z.union([NodeIdStringSchema, z.templateLiteral(['ontology:', OntologyIdSchema])])
+})
+
+const CanonicalKnowledgeLinkSchema = z.object({
+  target: KnowledgeTargetRefSchema
+})
+
+function nodeIdFromTarget(target: z.infer<typeof KnowledgeTargetRefSchema>): string {
+  return `${target.kind}:${target.id}`
+}
+
+function targetFromNodeId(nodeId: string): z.infer<typeof KnowledgeTargetRefSchema> {
+  const [kind, ...idParts] = nodeId.split(':')
+  return {
+    kind: KnowledgeTargetKindSchema.parse(kind),
+    id: idParts.join(':')
+  }
+}
+
+export const KnowledgeLinkSchema = z
+  .union([CanonicalKnowledgeLinkSchema, LegacyKnowledgeLinkSchema])
+  .transform((link) => {
+    const target = 'target' in link ? link.target : targetFromNodeId(link.nodeId)
+    return {
+      target,
+      nodeId: nodeIdFromTarget(target)
+    }
+  })
+
+// ---------------------------------------------------------------------------
+// OrgKnowledgeNode — single schema, `kind` discriminator drives presentation.
+// Phase 1: body is raw MDX string (lossless migration from operations/ docs).
+// Phase 2 (deferred): structured block format (Supabase-backed authoring).
+// ---------------------------------------------------------------------------
+
+export const OrgKnowledgeKindSchema = z
+  .enum(['playbook', 'strategy', 'reference'])
+  .meta({ label: 'Knowledge kind', color: 'grape' })
+
+export const OrgKnowledgeNodeSchema = z.object({
+  id: ModelIdSchema,
+  kind: OrgKnowledgeKindSchema,
+  title: z.string().trim().min(1).max(200),
+  summary: z.string().trim().min(1).max(1000),
   icon: IconNameSchema.optional(),
   /** Canonical documentation URL when body content is a local summary. */
   externalUrl: z.string().trim().url().max(500).optional(),
+  /** Optional generated source file path for local MDX-backed knowledge nodes. */
+  sourceFilePath: z.string().trim().min(1).max(500).optional(),
   /** Raw MDX string. Phase 2 will introduce a structured block format. */
   body: z.string().trim().min(1),
-  /**
-   * Graph links to other OM nodes this knowledge node governs.
-   * Each link emits a `governs` edge: knowledge-node -> target node.
-   */
-  links: z.array(KnowledgeLinkSchema).default([]),
-  /** Role identifiers that own this knowledge node. */
-  ownerIds: z.array(RoleIdSchema.meta({ ref: 'role' })).default([]),
-  /** ISO date string (YYYY-MM-DD or full ISO 8601) of last meaningful update. */
-  updatedAt: z.string().trim().min(1).max(50)
-})
-
-// ---------------------------------------------------------------------------
-// Domain schema — flat Record<id, KnowledgeNode> (D3: flatten per Phase 4 cut)
-//
-// Wave 1 shape change: the old wrapper object { version, lastModified, nodes[] }
-// is replaced by a plain id-keyed map. version/lastModified move to
-// domainMetadata.knowledge (D7). The default is an empty map {}.
-//
-// Wave 2 (elevasis-core canonicalOrganizationModel) must produce a value of this
-// shape: Record<KnowledgeId, OrgKnowledgeNode> — i.e., an object keyed by
-// each node's id string, with OrgKnowledgeNode as the value. Example:
-//   knowledge: {
-//     'playbook.crm.discovery': { id: 'playbook.crm.discovery', kind: 'playbook', ... },
-//   }
-// ---------------------------------------------------------------------------
-
-export const KnowledgeDomainSchema = z.record(ModelIdSchema, OrgKnowledgeNodeSchema).default({})
-
-export type OrgKnowledgeNode = z.infer<typeof OrgKnowledgeNodeSchema>
-export type OrgKnowledgeNodeInput = z.input<typeof OrgKnowledgeNodeSchema>
-export type OrgKnowledgeKind = z.infer<typeof OrgKnowledgeKindSchema>
-export type KnowledgeTargetKind = z.infer<typeof KnowledgeTargetKindSchema>
-export type KnowledgeTargetRef = z.infer<typeof KnowledgeTargetRefSchema>
-export type KnowledgeLink = z.infer<typeof KnowledgeLinkSchema>
-export type KnowledgeDomain = z.infer<typeof KnowledgeDomainSchema>
+  /**
+   * Graph links to other OM nodes this knowledge node governs.
+   * Each link emits a `governs` edge: knowledge-node -> target node.
+   */
+  links: z.array(KnowledgeLinkSchema).default([]),
+  /** Role identifiers that own this knowledge node. */
+  ownerIds: z.array(RoleIdSchema.meta({ ref: 'role' })).default([]),
+  /** ISO date string (YYYY-MM-DD or full ISO 8601) of last meaningful update. */
+  updatedAt: z.string().trim().min(1).max(50)
+})
+
+// ---------------------------------------------------------------------------
+// Domain schema — flat Record<id, KnowledgeNode> (D3: flatten per Phase 4 cut)
+//
+// Wave 1 shape change: the old wrapper object { version, lastModified, nodes[] }
+// is replaced by a plain id-keyed map. version/lastModified move to
+// domainMetadata.knowledge (D7). The default is an empty map {}.
+//
+// Wave 2 (elevasis-core canonicalOrganizationModel) must produce a value of this
+// shape: Record<KnowledgeId, OrgKnowledgeNode> — i.e., an object keyed by
+// each node's id string, with OrgKnowledgeNode as the value. Example:
+//   knowledge: {
+//     'playbook.crm.discovery': { id: 'playbook.crm.discovery', kind: 'playbook', ... },
+//   }
+// ---------------------------------------------------------------------------
+
+export const KnowledgeDomainSchema = z.record(ModelIdSchema, OrgKnowledgeNodeSchema).default({})
+
+export type OrgKnowledgeNode = z.infer<typeof OrgKnowledgeNodeSchema>
+export type OrgKnowledgeNodeInput = z.input<typeof OrgKnowledgeNodeSchema>
+export type OrgKnowledgeKind = z.infer<typeof OrgKnowledgeKindSchema>
+export type KnowledgeTargetKind = z.infer<typeof KnowledgeTargetKindSchema>
+export type KnowledgeTargetRef = z.infer<typeof KnowledgeTargetRefSchema>
+export type KnowledgeLink = z.infer<typeof KnowledgeLinkSchema>
+export type KnowledgeDomain = z.infer<typeof KnowledgeDomainSchema>

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

@@ -1,139 +1,139 @@
-import { z, type ZodType } from 'zod'
-import { DescriptionSchema, IconNameSchema, LabelSchema, ModelIdSchema, PathSchema } from './shared'
-
-export const SurfaceTypeSchema = z
-  .enum(['page', 'dashboard', 'graph', 'detail', 'list', 'settings'])
-  .meta({ label: 'Surface type', color: 'blue' })
-
-export const SurfaceDefinitionSchema = z.object({
-  id: ModelIdSchema,
-  label: LabelSchema,
-  path: PathSchema,
-  surfaceType: SurfaceTypeSchema,
-  description: DescriptionSchema.optional(),
-  enabled: z.boolean().default(true),
-  devOnly: z.boolean().optional(),
-  icon: IconNameSchema.optional(),
-  systemIds: z.array(ModelIdSchema.meta({ ref: 'system' })).default([]),
-  entityIds: z.array(ModelIdSchema.meta({ ref: 'entity' })).default([]),
-  resourceIds: z.array(ModelIdSchema.meta({ ref: 'resource' })).default([]),
-  actionIds: z.array(ModelIdSchema.meta({ ref: 'action' })).default([]),
-  parentId: ModelIdSchema.meta({ ref: 'surface' }).optional()
-})
-
-export const SidebarSurfaceTargetsSchema = z
-  .object({
-    systems: z.array(ModelIdSchema.meta({ ref: 'system' })).default([]).optional(),
-    entities: z.array(ModelIdSchema.meta({ ref: 'entity' })).default([]).optional(),
-    resources: z.array(ModelIdSchema.meta({ ref: 'resource' })).default([]).optional(),
-    actions: z.array(ModelIdSchema.meta({ ref: 'action' })).default([]).optional()
-  })
-  .default({})
-
-export interface SidebarSurfaceNode {
-  type: 'surface'
-  label: string
-  path: string
-  surfaceType: z.infer<typeof SurfaceTypeSchema>
-  description?: string
-  icon?: string
-  order?: number
-  targets?: {
-    systems?: string[]
-    entities?: string[]
-    resources?: string[]
-    actions?: string[]
-  }
-  devOnly?: boolean
-  requiresAdmin?: boolean
-}
-
-export interface SidebarGroupNode {
-  type: 'group'
-  label: string
-  description?: string
-  icon?: string
-  order?: number
-  children: Record<string, SidebarNode>
-}
-
-export type SidebarNode = SidebarSurfaceNode | SidebarGroupNode
-
-export const SidebarNodeSchema: ZodType<SidebarNode> = z.lazy(() =>
-  z.discriminatedUnion('type', [
-    z.object({
-      type: z.literal('group'),
-      label: LabelSchema,
-      description: DescriptionSchema.optional(),
-      icon: IconNameSchema.optional(),
-      order: z.number().int().optional(),
-      children: z.record(z.string(), SidebarNodeSchema).default({})
-    }),
-    z.object({
-      type: z.literal('surface'),
-      label: LabelSchema,
-      path: PathSchema,
-      surfaceType: SurfaceTypeSchema,
-      description: DescriptionSchema.optional(),
-      icon: IconNameSchema.optional(),
-      order: z.number().int().optional(),
-      targets: SidebarSurfaceTargetsSchema.optional(),
-      devOnly: z.boolean().optional(),
-      requiresAdmin: z.boolean().optional()
-    })
-  ])
-)
-
-export const SidebarSectionSchema = z.record(z.string(), SidebarNodeSchema).default({})
-
-export const SidebarNavigationSchema = z
-  .object({
-    primary: SidebarSectionSchema,
-    bottom: SidebarSectionSchema
-  })
-  .default({ primary: {}, bottom: {} })
-
-export const OrganizationModelNavigationSchema = z
-  .object({
-    sidebar: SidebarNavigationSchema
-  })
-  .default({ sidebar: { primary: {}, bottom: {} } })
-
-export const DEFAULT_ORGANIZATION_MODEL_NAVIGATION: z.infer<typeof OrganizationModelNavigationSchema> = {
-  sidebar: {
-    primary: {},
-    bottom: {}
-  }
-}
-
-export function getSortedSidebarEntries<TNode extends SidebarNode>(
-  nodes: Record<string, TNode>
-): Array<[string, TNode]> {
-  return Object.entries(nodes).sort(([leftId, left], [rightId, right]) => {
-    const orderDelta = (left.order ?? Number.MAX_SAFE_INTEGER) - (right.order ?? Number.MAX_SAFE_INTEGER)
-    return orderDelta === 0 ? leftId.localeCompare(rightId) : orderDelta
-  })
-}
-
-/**
- * Core placement values: 'primary' | 'secondary' | 'bottom'.
- *
- * `placement` is intentionally open (`z.string()`) so that per-project adapters can
- * introduce additional placement IDs (e.g. 'pinned', 'spotlight', 'contextual') without
- * forking core. Extension pattern: add the new string literal to the project's
- * `foundations/config/organization-model.ts` adapter — no changes to this file required.
- *
- * `surfaceType` and `resourceType` remain closed enums (UI/runtime invariants).
- */
-export const CORE_PLACEMENT_VALUES = ['primary', 'secondary', 'bottom'] as const
-export type CorePlacement = (typeof CORE_PLACEMENT_VALUES)[number]
-
-export const NavigationGroupSchema = z.object({
-  id: ModelIdSchema,
-  label: LabelSchema,
-  placement: z.string().trim().min(1).max(50),
-  surfaceIds: z.array(ModelIdSchema.meta({ ref: 'surface' })).default([])
-})
-
-// SurfaceDefinitionSchema and NavigationGroupSchema remain for derived DTOs and
-// transitional call sites. They are not authored top-level OrganizationModel fields.
+import { z, type ZodType } from 'zod'
+import { DescriptionSchema, IconNameSchema, LabelSchema, ModelIdSchema, PathSchema } from './shared'
+
+export const SurfaceTypeSchema = z
+  .enum(['page', 'dashboard', 'graph', 'detail', 'list', 'settings'])
+  .meta({ label: 'Surface type', color: 'blue' })
+
+export const SurfaceDefinitionSchema = z.object({
+  id: ModelIdSchema,
+  label: LabelSchema,
+  path: PathSchema,
+  surfaceType: SurfaceTypeSchema,
+  description: DescriptionSchema.optional(),
+  enabled: z.boolean().default(true),
+  devOnly: z.boolean().optional(),
+  icon: IconNameSchema.optional(),
+  systemIds: z.array(ModelIdSchema.meta({ ref: 'system' })).default([]),
+  entityIds: z.array(ModelIdSchema.meta({ ref: 'entity' })).default([]),
+  resourceIds: z.array(ModelIdSchema.meta({ ref: 'resource' })).default([]),
+  actionIds: z.array(ModelIdSchema.meta({ ref: 'action' })).default([]),
+  parentId: ModelIdSchema.meta({ ref: 'surface' }).optional()
+})
+
+export const SidebarSurfaceTargetsSchema = z
+  .object({
+    systems: z.array(ModelIdSchema.meta({ ref: 'system' })).default([]).optional(),
+    entities: z.array(ModelIdSchema.meta({ ref: 'entity' })).default([]).optional(),
+    resources: z.array(ModelIdSchema.meta({ ref: 'resource' })).default([]).optional(),
+    actions: z.array(ModelIdSchema.meta({ ref: 'action' })).default([]).optional()
+  })
+  .default({})
+
+export interface SidebarSurfaceNode {
+  type: 'surface'
+  label: string
+  path: string
+  surfaceType: z.infer<typeof SurfaceTypeSchema>
+  description?: string
+  icon?: string
+  order?: number
+  targets?: {
+    systems?: string[]
+    entities?: string[]
+    resources?: string[]
+    actions?: string[]
+  }
+  devOnly?: boolean
+  requiresAdmin?: boolean
+}
+
+export interface SidebarGroupNode {
+  type: 'group'
+  label: string
+  description?: string
+  icon?: string
+  order?: number
+  children: Record<string, SidebarNode>
+}
+
+export type SidebarNode = SidebarSurfaceNode | SidebarGroupNode
+
+export const SidebarNodeSchema: ZodType<SidebarNode> = z.lazy(() =>
+  z.discriminatedUnion('type', [
+    z.object({
+      type: z.literal('group'),
+      label: LabelSchema,
+      description: DescriptionSchema.optional(),
+      icon: IconNameSchema.optional(),
+      order: z.number().int().optional(),
+      children: z.record(z.string(), SidebarNodeSchema).default({})
+    }),
+    z.object({
+      type: z.literal('surface'),
+      label: LabelSchema,
+      path: PathSchema,
+      surfaceType: SurfaceTypeSchema,
+      description: DescriptionSchema.optional(),
+      icon: IconNameSchema.optional(),
+      order: z.number().int().optional(),
+      targets: SidebarSurfaceTargetsSchema.optional(),
+      devOnly: z.boolean().optional(),
+      requiresAdmin: z.boolean().optional()
+    })
+  ])
+)
+
+export const SidebarSectionSchema = z.record(z.string(), SidebarNodeSchema).default({})
+
+export const SidebarNavigationSchema = z
+  .object({
+    primary: SidebarSectionSchema,
+    bottom: SidebarSectionSchema
+  })
+  .default({ primary: {}, bottom: {} })
+
+export const OrganizationModelNavigationSchema = z
+  .object({
+    sidebar: SidebarNavigationSchema
+  })
+  .default({ sidebar: { primary: {}, bottom: {} } })
+
+export const DEFAULT_ORGANIZATION_MODEL_NAVIGATION: z.infer<typeof OrganizationModelNavigationSchema> = {
+  sidebar: {
+    primary: {},
+    bottom: {}
+  }
+}
+
+export function getSortedSidebarEntries<TNode extends SidebarNode>(
+  nodes: Record<string, TNode>
+): Array<[string, TNode]> {
+  return Object.entries(nodes).sort(([leftId, left], [rightId, right]) => {
+    const orderDelta = (left.order ?? Number.MAX_SAFE_INTEGER) - (right.order ?? Number.MAX_SAFE_INTEGER)
+    return orderDelta === 0 ? leftId.localeCompare(rightId) : orderDelta
+  })
+}
+
+/**
+ * Core placement values: 'primary' | 'secondary' | 'bottom'.
+ *
+ * `placement` is intentionally open (`z.string()`) so that per-project adapters can
+ * introduce additional placement IDs (e.g. 'pinned', 'spotlight', 'contextual') without
+ * forking core. Extension pattern: add the new string literal to the project's
+ * `foundations/config/organization-model.ts` adapter — no changes to this file required.
+ *
+ * `surfaceType` and `resourceType` remain closed enums (UI/runtime invariants).
+ */
+export const CORE_PLACEMENT_VALUES = ['primary', 'secondary', 'bottom'] as const
+export type CorePlacement = (typeof CORE_PLACEMENT_VALUES)[number]
+
+export const NavigationGroupSchema = z.object({
+  id: ModelIdSchema,
+  label: LabelSchema,
+  placement: z.string().trim().min(1).max(50),
+  surfaceIds: z.array(ModelIdSchema.meta({ ref: 'surface' })).default([])
+})
+
+// SurfaceDefinitionSchema and NavigationGroupSchema remain for derived DTOs and
+// transitional call sites. They are not authored top-level OrganizationModel fields.