@elevasis/core 0.22.0 → 0.24.0

package/src/organization-model/content-kinds/index.ts

@@ -0,0 +1,78 @@
+// ---------------------------------------------------------------------------
+// content-kinds barrel (Phase 3, Wave 2A)
+// ---------------------------------------------------------------------------
+//
+// Per D8 (locked): CONTENT_KIND_REGISTRY is populated via static import, not
+// side-effecting registration. This file is the single source of truth for
+// the populated registry. `registry.ts` exports the EMPTY registry constant
+// (kept for historical/import-chain reasons) — consumers MUST import from
+// this barrel, not from `registry.ts` directly, to get the populated registry.
+//
+// Registry keys follow the `<kind>:<type>` ContentTypeKey format (per L4, D8).
+
+export { defineContentType } from './registry'
+export type { ContentTypeKey, ContentTypeDefinition } from './types'
+export { ContentNodeBaseSchema, ContentNodeSchema, ExtensionNodeSchema } from './types'
+export type { ContentNodeBase, ContentNode, ExtensionNode } from './types'
+
+export { pipelineKind, stageKind } from './pipeline'
+export type { PipelinePayload, StagePayload } from './pipeline'
+
+export { templateKind, templateStepKind } from './template'
+export type { TemplatePayload, TemplateStepPayload } from './template'
+
+export { statusFlowKind, statusKind } from './status'
+export type { StatusFlowPayload, StatusPayload } from './status'
+
+export { configKvKind } from './config'
+export type { ConfigKvPayload } from './config'
+
+import { pipelineKind, stageKind } from './pipeline'
+import { templateKind, templateStepKind } from './template'
+import { statusFlowKind, statusKind } from './status'
+import { configKvKind } from './config'
+import type { ContentTypeDefinition, ContentTypeKey } from './types'
+
+/**
+ * Compatibility registry for bridge-era System.content nodes.
+ * New schema/catalog authoring should use System.ontology, and new
+ * system-local settings should use System.config. These definitions remain so
+ * old tenant content can parse, render, migrate, and project read-only.
+ *
+ * Per D8: static const object keyed by `'<kind>:<type>'` composite key.
+ *
+ * Bridge keys:
+ *   'schema:pipeline'      — projects to ontology catalog records
+ *   'schema:stage'         — projects to ontology catalog entries
+ *   'schema:template'      — projects to ontology/catalog or action metadata
+ *   'schema:template-step' — projects to template metadata or catalog entries
+ *   'schema:status-flow'   — projects to ontology catalog records
+ *   'schema:status'        — projects to ontology catalog entries
+ *   'config:kv'            — projects into resolved System.config
+ *
+ * Wave 3A's `ContentNodeDescribeView` consumes `lookupContentType(kind, type)`
+ * which indexes into this registry. Import `lookupContentType` from this barrel
+ * to get the populated version.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export const CONTENT_KIND_REGISTRY: Readonly<Record<ContentTypeKey, ContentTypeDefinition<any>>> = {
+  'schema:pipeline': pipelineKind,
+  'schema:stage': stageKind,
+  'schema:template': templateKind,
+  'schema:template-step': templateStepKind,
+  'schema:status-flow': statusFlowKind,
+  'schema:status': statusKind,
+  'config:kv': configKvKind
+} as const
+
+/**
+ * Look up a registered content-type definition by (kind, type).
+ * Uses the populated CONTENT_KIND_REGISTRY from this barrel — wave 2A override
+ * of the empty registry exported from registry.ts.
+ * Returns `undefined` when the pair is not registered — per D2, this is not
+ * an error; unregistered pairs render generically and skip payload validation.
+ */
+export function lookupContentType(kind: string, type: string): ContentTypeDefinition | undefined {
+  const key: ContentTypeKey = `${kind}:${type}`
+  return CONTENT_KIND_REGISTRY[key]
+}

package/src/organization-model/content-kinds/pipeline.ts

@@ -0,0 +1,68 @@
+import { z } from 'zod'
+import { defineContentType } from './registry'
+
+// ---------------------------------------------------------------------------
+// pipeline + stage kinds (Phase 3, Wave 2A)
+// ---------------------------------------------------------------------------
+//
+// `schema:pipeline` — a named pipeline that applies to an entity type.
+// `schema:stage`    — a stage within a pipeline; parentTypes constrains it to
+//                     live under a `schema:pipeline` sibling.
+//
+// Per L19: `schema:stage` parents only under `schema:pipeline`.
+// Per L19 (parent kind constraint): both share the same meta-kind `schema`.
+
+const PipelinePayloadSchema = z.object({
+  /**
+   * Local NodeId of the entity this pipeline applies to (e.g. 'crm.deal').
+   * `.meta({ ref: 'entity' })` enables SchemaDrivenFieldList to render a
+   * clickable graph link to the referenced entity node.
+   */
+  entityId: z
+    .string()
+    .trim()
+    .min(1)
+    .max(200)
+    .meta({ label: 'Entity', ref: 'entity', hint: 'The entity type this pipeline tracks' }),
+  /**
+   * Optional Kanban column color token for UI rendering.
+   */
+  kanbanColor: z.string().trim().min(1).max(40).optional().meta({ label: 'Kanban color', hint: 'UI color token' })
+})
+
+export type PipelinePayload = z.infer<typeof PipelinePayloadSchema>
+
+export const pipelineKind = defineContentType({
+  kind: 'schema',
+  type: 'pipeline',
+  label: 'Pipeline',
+  description: 'A named progression pipeline that applies to a specific entity type.',
+  payloadSchema: PipelinePayloadSchema,
+  parentTypes: []
+})
+
+// ---------------------------------------------------------------------------
+
+const StagePayloadSchema = z.object({
+  /**
+   * Semantic classification for this stage.
+   * Drives color, icon, and CRM-priority logic in consuming views.
+   * Optional — prospecting stages use data.entityKind instead.
+   * Enum aligned with SalesStageSemanticClassSchema (sales.ts).
+   */
+  semanticClass: z
+    .enum(['open', 'active', 'nurturing', 'closed_won', 'closed_lost', 'won', 'lost', 'closed'])
+    .optional()
+    .meta({ label: 'Semantic class', hint: 'Semantic meaning of this stage', color: 'blue' })
+})
+
+export type StagePayload = z.infer<typeof StagePayloadSchema>
+
+export const stageKind = defineContentType({
+  kind: 'schema',
+  type: 'stage',
+  label: 'Stage',
+  description: 'A stage within a pipeline. Must be parented under a schema:pipeline content node.',
+  payloadSchema: StagePayloadSchema,
+  parentTypes: ['schema:pipeline']
+})

package/src/organization-model/content-kinds/registry.ts

@@ -0,0 +1,44 @@
+import type { ContentTypeDefinition, ContentTypeKey } from './types'
+
+// ---------------------------------------------------------------------------
+// Content-kind registry (Phase 3, Wave 1A)
+// ---------------------------------------------------------------------------
+//
+// Per D8 (locked): the registry is populated via STATIC IMPORT, not via a
+// side-effecting registration call. `content-kinds/index.ts` exports
+// CONTENT_KIND_REGISTRY as a const object; Wave 2A merges concrete kind
+// definitions into that barrel. This file stays import-free of concrete kinds.
+//
+// Per D2 (locked): unregistered (kind, type) pairs are NOT errors. They pass
+// through parse-time validation (B5 skips) and render generically in the KB UI.
+
+/**
+ * Identity factory for content-type definitions.
+ * Per L16: this is the canonical tenant-extension API.
+ * It is a pure identity function — no side effects, no global state mutation.
+ * Tenants call this in their extension package; the result merges into
+ * CONTENT_KIND_REGISTRY via `content-kinds/index.ts`.
+ */
+export function defineContentType<TData>(def: ContentTypeDefinition<TData>): ContentTypeDefinition<TData> {
+  return def
+}
+
+/**
+ * The kind registry — keyed by `"${kind}:${type}"` composite key.
+ * Initially empty; Wave 2A populates by re-exporting through `content-kinds/index.ts`.
+ *
+ * Consumers should use `lookupContentType` rather than indexing directly,
+ * to keep the lookup logic in one place.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export const CONTENT_KIND_REGISTRY: Readonly<Record<ContentTypeKey, ContentTypeDefinition<any>>> = {} as const
+
+/**
+ * Look up a registered content-type definition by (kind, type).
+ * Returns `undefined` when the pair is not registered — per D2, this is not
+ * an error; unregistered pairs render generically and skip payload validation.
+ */
+export function lookupContentType(kind: string, type: string): ContentTypeDefinition | undefined {
+  const key: ContentTypeKey = `${kind}:${type}`
+  return CONTENT_KIND_REGISTRY[key]
+}

package/src/organization-model/content-kinds/status.ts

@@ -0,0 +1,71 @@
+import { z } from 'zod'
+import { defineContentType } from './registry'
+
+// ---------------------------------------------------------------------------
+// status-flow + status kinds (Phase 3, Wave 2A)
+// ---------------------------------------------------------------------------
+//
+// `schema:status-flow` — a named set of statuses for a given entity scope
+//                        (project, milestone, or task).
+// `schema:status`      — a single status within a flow; parentTypes constrains
+//                        it to live under a `schema:status-flow` sibling.
+//
+// Payload shape informed by `ProjectsDomainStateSchema` in domains/projects.ts
+// which carries `id`, `label`, and `order`. The content-kind payload carries
+// the semantic classification and optional color token; `label` and `order`
+// live on the base `ContentNodeBase` fields.
+//
+// Per L19: `schema:status` parents only under `schema:status-flow`.
+
+const StatusFlowPayloadSchema = z.object({
+  /**
+   * Which entity scope this status flow governs.
+   */
+  appliesTo: z
+    .enum(['project', 'milestone', 'task'])
+    .meta({ label: 'Applies to', hint: 'Entity scope governed by this status flow', color: 'blue' })
+})
+
+export type StatusFlowPayload = z.infer<typeof StatusFlowPayloadSchema>
+
+export const statusFlowKind = defineContentType({
+  kind: 'schema',
+  type: 'status-flow',
+  label: 'Status Flow',
+  description: 'A named set of statuses governing a project, milestone, or task entity.',
+  payloadSchema: StatusFlowPayloadSchema,
+  parentTypes: []
+})
+
+// ---------------------------------------------------------------------------
+
+const StatusPayloadSchema = z.object({
+  /**
+   * Semantic classification string for this status.
+   * Free-form to allow tenant-defined classifications (e.g. 'active', 'blocked',
+   * 'completed'). Used by UI to apply color and icon fallbacks.
+   * Optional — status nodes may omit this when the label is self-descriptive.
+   */
+  semanticClass: z
+    .string()
+    .trim()
+    .min(1)
+    .max(100)
+    .optional()
+    .meta({ label: 'Semantic class', hint: 'Semantic meaning of this status (e.g. active, blocked, completed)' }),
+  /**
+   * Optional UI color token override for this status.
+   */
+  color: z.string().trim().min(1).max(40).optional().meta({ label: 'Color', hint: 'UI color token' })
+})
+
+export type StatusPayload = z.infer<typeof StatusPayloadSchema>
+
+export const statusKind = defineContentType({
+  kind: 'schema',
+  type: 'status',
+  label: 'Status',
+  description: 'A single status within a status flow. Must be parented under a schema:status-flow content node.',
+  payloadSchema: StatusPayloadSchema,
+  parentTypes: ['schema:status-flow']
+})

package/src/organization-model/content-kinds/template.ts

@@ -0,0 +1,83 @@
+import { z } from 'zod'
+import { defineContentType } from './registry'
+
+// ---------------------------------------------------------------------------
+// template + template-step kinds (Phase 3, Wave 2A)
+// ---------------------------------------------------------------------------
+//
+// `schema:template`      — a named build template (e.g. prospecting pipeline).
+// `schema:template-step` — a step within a template; parentTypes constrains it
+//                          to live under a `schema:template` sibling.
+//
+// Payload shape informed by `ProspectingBuildTemplateSchema` /
+// `ProspectingBuildTemplateStepSchema` in domains/prospecting.ts.
+// The content-kind payload is a lightweight descriptor — full step config
+// (batch sizes, credential requirements, record columns) lives in the
+// typed domain schema during Phase 3; this payload carries only the
+// identity fields needed by the KB renderer.
+//
+// Per L19: `schema:template-step` parents only under `schema:template`.
+
+const TemplatePayloadSchema = z.object({
+  /**
+   * Optional description surfaced in the KB describe view and tooling.
+   */
+  description: z
+    .string()
+    .trim()
+    .min(1)
+    .max(2000)
+    .optional()
+    .meta({ label: 'Description', hint: 'What this template is used for' })
+})
+
+export type TemplatePayload = z.infer<typeof TemplatePayloadSchema>
+
+export const templateKind = defineContentType({
+  kind: 'schema',
+  type: 'template',
+  label: 'Template',
+  description: 'A named build template (e.g. a prospecting pipeline sequence).',
+  payloadSchema: TemplatePayloadSchema,
+  parentTypes: []
+})
+
+// ---------------------------------------------------------------------------
+
+const TemplateStepPayloadSchema = z.object({
+  /**
+   * Which entity type this step primarily operates on.
+   */
+  primaryEntity: z
+    .enum(['company', 'contact'])
+    .meta({ label: 'Primary entity', hint: 'Entity type this step processes', color: 'blue' }),
+  /**
+   * Action key identifying the workflow action executed by this step.
+   * `.meta({ ref: 'action' })` enables SchemaDrivenFieldList to render a
+   * clickable graph link.
+   */
+  actionKey: z
+    .string()
+    .trim()
+    .min(1)
+    .max(200)
+    .meta({ label: 'Action', ref: 'action', hint: 'Workflow action executed by this step' }),
+  /**
+   * IDs of sibling step local NodeIds this step depends on.
+   */
+  dependsOn: z
+    .array(z.string().trim().min(1).max(200))
+    .optional()
+    .meta({ label: 'Depends on', hint: 'Local NodeIds of prerequisite steps' })
+})
+
+export type TemplateStepPayload = z.infer<typeof TemplateStepPayloadSchema>
+
+export const templateStepKind = defineContentType({
+  kind: 'schema',
+  type: 'template-step',
+  label: 'Template Step',
+  description: 'A step within a build template. Must be parented under a schema:template content node.',
+  payloadSchema: TemplateStepPayloadSchema,
+  parentTypes: ['schema:template']
+})

package/src/organization-model/content-kinds/types.ts

@@ -0,0 +1,117 @@
+import { z } from 'zod'
+import type { ZodType } from 'zod'
+
+// ---------------------------------------------------------------------------
+// ContentNode primitives (Phase 3, Wave 1A)
+// ---------------------------------------------------------------------------
+//
+// Per L11a: content NodeIds are local strings within a system. The key in
+// `system.content` is the local id; the qualified id (`<system-path>:<local-id>`)
+// is computed by graph projection — it is never stored on the value itself.
+//
+// Per L14: TWO-LEVEL discrimination — every ContentNode carries both `kind`
+// (meta-category) and `type` (specific family). Symmetric across all meta-kinds.
+//
+// Per D2 (locked): unregistered (kind, type) pairs render generically and pass
+// through parse-time validation (B5 skips validation for unknown pairs).
+
+/**
+ * Base fields common to every ContentNode, regardless of (kind, type).
+ * Per L11a, `label` is the only required field — the local id is the map key.
+ */
+export const ContentNodeBaseSchema = z.object({
+  /** Human-readable label for the content node. */
+  label: z.string().trim().min(1).max(120).meta({ label: 'Label' }),
+  /** Optional one-paragraph description. */
+  description: z.string().trim().min(1).max(2000).optional().meta({ label: 'Description' }),
+  /** Optional display order within the system content map. */
+  order: z.number().int().optional().meta({ label: 'Order' }),
+  /**
+   * Local NodeId of the parent content node within the SAME system.
+   * Per B4/L9: MUST resolve to a sibling in the same `system.content` map.
+   * Per L19: parent and child MUST share the same `kind` (meta-category).
+   */
+  parentContentId: z.string().trim().min(1).max(200).optional().meta({ label: 'Parent content id' })
+})
+
+export type ContentNodeBase = z.infer<typeof ContentNodeBaseSchema>
+
+/**
+ * Placeholder discriminated union for ContentNode (Wave 1A).
+ * Wave 2A wires concrete (kind, type) pairs via the registry.
+ *
+ * Per D2: unregistered (kind, type) pairs are allowed and pass through validation.
+ * Per L14: every node carries BOTH `kind` and `type`.
+ */
+export const ContentNodeSchema = ContentNodeBaseSchema.extend({
+  /** Meta-category (e.g. 'schema', 'config', 'knowledge', tenant-defined). */
+  kind: z.string().trim().min(1).max(100).meta({ label: 'Kind' }),
+  /** Specific family within the meta-category (e.g. 'pipeline', 'kv'). */
+  type: z.string().trim().min(1).max(100).meta({ label: 'Type' }),
+  /** Payload data; validated against registered payloadSchema when (kind, type) is known. */
+  data: z.record(z.string(), z.unknown()).optional().meta({ label: 'Data' })
+})
+
+export type ContentNode = z.infer<typeof ContentNodeSchema>
+
+/**
+ * Org-level extension node for tenant-defined business-model concepts.
+ * Per L6: tenants add "Partners", "Audiences", etc. via `org.extensions`.
+ * Unlike ContentNode, ExtensionNode is not system-scoped and has no parentContentId.
+ */
+export const ExtensionNodeSchema = z.object({
+  /** Meta-category (tenant-defined or registry-shipped). */
+  kind: z.string().trim().min(1).max(100).meta({ label: 'Kind' }),
+  /** Specific family within the meta-category. */
+  type: z.string().trim().min(1).max(100).meta({ label: 'Type' }),
+  /** Human-readable label shown in the KB tree and describe views. */
+  label: z.string().trim().min(1).max(120).meta({ label: 'Label' }),
+  /** Optional description. */
+  description: z.string().trim().min(1).max(2000).optional().meta({ label: 'Description' }),
+  /**
+   * Which KB tree group this extension renders in.
+   * Per L6: 'business-model' places it alongside Customers / Offerings / Goals.
+   */
+  treeGroup: z
+    .union([z.enum(['profile', 'business-model', 'systems', 'graph', 'governance-wiring']), z.string().min(1).max(100)])
+    .meta({ label: 'Tree group' }),
+  /** Untyped payload; shape governed by the registered payloadSchema when available. */
+  data: z.record(z.string(), z.unknown()).optional().meta({ label: 'Data' })
+})
+
+export type ExtensionNode = z.infer<typeof ExtensionNodeSchema>
+
+// ---------------------------------------------------------------------------
+// Kind registry types
+// ---------------------------------------------------------------------------
+
+/**
+ * Canonical key for the content-kind registry.
+ * Format: `<kind>:<type>`, e.g. `'schema:pipeline'`, `'config:kv'`.
+ * Per L4, D8: keyed by this composite key in CONTENT_KIND_REGISTRY.
+ */
+export type ContentTypeKey = `${string}:${string}`
+
+/**
+ * A registered content-type definition.
+ * Per L16: `defineContentType` is the canonical tenant-extension API.
+ * Per D8: registry is populated via static import, not side-effecting registration.
+ */
+export interface ContentTypeDefinition<TData = unknown> {
+  /** Meta-category (e.g. 'schema', 'config', tenant-defined). */
+  kind: string
+  /** Specific family within the meta-category (e.g. 'pipeline', 'kv'). */
+  type: string
+  /** Zod schema for the `data` field; validated at OM parse time per B5. */
+  payloadSchema: ZodType<TData>
+  /**
+   * Valid parent (kind, type) pairs for `parentContentId`.
+   * Per L19: child and parent MUST share the same `kind`.
+   * Empty array means this type is top-level (no parent allowed or required).
+   */
+  parentTypes?: ContentTypeKey[]
+  /** Optional display label for this content type. */
+  label?: string
+  /** Optional description for tooling and docs. */
+  description?: string
+}

package/src/organization-model/contracts.ts

@@ -1,17 +1,27 @@
-export const KNOWLEDGE_FEATURE_ID = 'knowledge' as const
-
-export const PROJECTS_FEATURE_ID = 'projects' as const
-export const PROJECTS_INDEX_SURFACE_ID = 'projects.index' as const
-export const PROJECTS_VIEW_CAPABILITY_ID = 'delivery.projects.view' as const
-
-export const SALES_FEATURE_ID = 'crm' as const
-export const PROSPECTING_FEATURE_ID = 'lead-gen' as const
-export const OPERATIONS_FEATURE_ID = 'operations' as const
-export const MONITORING_FEATURE_ID = 'monitoring' as const
-export const SETTINGS_FEATURE_ID = 'settings' as const
-export const SEO_FEATURE_ID = 'seo' as const
-
-export const SALES_PIPELINE_SURFACE_ID = 'crm.pipeline' as const
-export const PROSPECTING_LISTS_SURFACE_ID = 'lead-gen.lists' as const
-export const OPERATIONS_COMMAND_VIEW_SURFACE_ID = 'knowledge.command-view' as const
-export const SETTINGS_ROLES_SURFACE_ID = 'settings.roles' as const
+export const KNOWLEDGE_FEATURE_ID = 'knowledge' as const
+export const KNOWLEDGE_SYSTEM_ID = 'knowledge' as const
+
+export const PROJECTS_SYSTEM_ID = 'projects' as const
+/** @deprecated Use PROJECTS_SYSTEM_ID. Scheduled for removal after one publish cycle. */
+export const PROJECTS_FEATURE_ID = PROJECTS_SYSTEM_ID
+export const PROJECTS_INDEX_SURFACE_ID = 'projects.index' as const
+export const PROJECTS_VIEW_ACTION_ID = 'delivery.projects.view' as const
+
+export const SALES_FEATURE_ID = 'crm' as const
+export const PROSPECTING_FEATURE_ID = 'lead-gen' as const
+export const MONITORING_FEATURE_ID = 'monitoring' as const
+export const SETTINGS_FEATURE_ID = 'settings' as const
+export const SEO_FEATURE_ID = 'seo' as const
+export const SALES_SYSTEM_ID = 'sales.crm' as const
+export const PROSPECTING_SYSTEM_ID = 'sales.lead-gen' as const
+export const OPERATIONS_SYSTEM_ID = 'operations' as const
+/** @deprecated Use OPERATIONS_SYSTEM_ID. Scheduled for removal after one publish cycle. */
+export const OPERATIONS_FEATURE_ID = OPERATIONS_SYSTEM_ID
+export const MONITORING_SYSTEM_ID = 'monitoring' as const
+export const SETTINGS_SYSTEM_ID = 'settings' as const
+export const SEO_SYSTEM_ID = 'seo' as const
+
+export const SALES_PIPELINE_SURFACE_ID = 'crm.pipeline' as const
+export const PROSPECTING_LISTS_SURFACE_ID = 'lead-gen.lists' as const
+export const OPERATIONS_COMMAND_VIEW_SURFACE_ID = 'knowledge.command-view' as const
+export const SETTINGS_ROLES_SURFACE_ID = 'settings.roles' as const