@elevasis/core 0.22.0 → 0.23.0

package/src/organization-model/__tests__/surface-projection.test.ts

@@ -1,76 +1,86 @@
 import { describe, expect, it } from 'vitest'
 import { DEFAULT_ORGANIZATION_MODEL } from '../defaults'
-import {
-  projectOrganizationSurfaces,
-  validateOrganizationSurfaceProjection
-} from '../surface-projection'
-import type { OrganizationModel, OrganizationModelFeature, OrganizationModelSurface } from '../types'
-
-function makeFeature(
-  id: string,
-  overrides: Partial<OrganizationModelFeature> = {}
-): OrganizationModelFeature {
+import { ancestorsOf, childrenOf, topLevel } from '../helpers'
+import { projectOrganizationSurfaces, validateOrganizationSurfaceProjection } from '../surface-projection'
+import type {
+  OrganizationModel,
+  OrganizationModelSidebarNode,
+  OrganizationModelSidebarSurfaceNode,
+  OrganizationModelSystemEntry
+} from '../types'
+
+function makeSystem(id: string, overrides: Partial<OrganizationModelSystemEntry> = {}): OrganizationModelSystemEntry {
   return {
     id,
+    order: 10,
     label: id,
+    lifecycle: 'active',
     enabled: true,
     ...overrides
   }
 }
 
 function makeSurface(
-  id: string,
-  overrides: Partial<OrganizationModelSurface> = {}
-): OrganizationModelSurface {
+  label: string,
+  overrides: Partial<OrganizationModelSidebarSurfaceNode> = {}
+): OrganizationModelSidebarSurfaceNode {
   return {
-    id,
-    label: id,
-    path: `/${id.replaceAll('.', '/')}`,
+    type: 'surface',
+    label,
+    path: `/${label.toLowerCase().replaceAll(' ', '-')}`,
     surfaceType: 'page',
-    enabled: true,
-    featureIds: [],
-    entityIds: [],
-    resourceIds: [],
-    capabilityIds: [],
+    order: 10,
+    targets: {},
     ...overrides
   }
 }
 
 function makeModel(
-  features: OrganizationModelFeature[],
-  surfaces: OrganizationModelSurface[],
-  navigation: Partial<OrganizationModel['navigation']> = {}
+  systems: OrganizationModelSystemEntry[],
+  primary: Record<string, OrganizationModelSidebarNode>,
+  bottom: Record<string, OrganizationModelSidebarNode> = {}
 ): OrganizationModel {
   return {
     ...DEFAULT_ORGANIZATION_MODEL,
-    features,
+    systems: Object.fromEntries(
+      systems.map((system, index) => [system.id, { ...system, order: system.order ?? (index + 1) * 10 }])
+    ),
     navigation: {
-      surfaces,
-      groups: [],
-      ...navigation
+      sidebar: {
+        primary,
+        bottom
+      }
     }
   }
 }
 
 describe('projectOrganizationSurfaces', () => {
-  it('projects navigation surfaces into data-only DTOs with inherited flags', () => {
+  it('projects recursive sidebar surface leaves into data-only DTOs with inherited flags', () => {
     const model = makeModel(
       [
-        makeFeature('sales', { requiresAdmin: true }),
-        makeFeature('sales.crm', { devOnly: true })
+        makeSystem('sales', { requiresAdmin: true }),
+        makeSystem('sales.crm', { parentSystemId: 'sales', devOnly: true })
       ],
-      [
-        makeSurface('crm.pipeline', {
-          label: 'Pipeline',
-          path: '/crm/pipeline',
-          surfaceType: 'graph',
-          featureId: 'sales.crm',
-          featureIds: ['sales.crm'],
-          entityIds: ['crm.deal'],
-          resourceIds: ['workflow.crm-sync'],
-          capabilityIds: ['crm.pipeline.manage']
-        })
-      ]
+      {
+        business: {
+          type: 'group',
+          label: 'Business',
+          order: 20,
+          children: {
+            'crm.pipeline': makeSurface('Pipeline', {
+              path: '/crm/pipeline',
+              surfaceType: 'graph',
+              icon: 'feature.crm',
+              targets: {
+                systems: ['sales.crm'],
+                entities: ['crm.deal'],
+                resources: ['workflow.crm-sync'],
+                actions: ['crm.pipeline.manage']
+              }
+            })
+          }
+        }
+      }
     )
 
     expect(projectOrganizationSurfaces(model)).toEqual([
@@ -79,11 +89,12 @@ describe('projectOrganizationSurfaces', () => {
         label: 'Pipeline',
         path: '/crm/pipeline',
         surfaceType: 'graph',
-        featureId: 'sales.crm',
-        featureIds: ['sales.crm'],
+        icon: 'feature.crm',
+        order: 10,
+        systemIds: ['sales.crm'],
         entityIds: ['crm.deal'],
         resourceIds: ['workflow.crm-sync'],
-        capabilityIds: ['crm.pipeline.manage'],
+        actionIds: ['crm.pipeline.manage'],
         enabled: true,
         devOnly: true,
         requiresAdmin: true
@@ -91,84 +102,183 @@ describe('projectOrganizationSurfaces', () => {
     ])
   })
 
-  it('canonicalizes legacy feature aliases', () => {
+  it('sorts sidebar records by order before projecting leaves', () => {
+    const model = makeModel([makeSystem('a'), makeSystem('b'), makeSystem('c')], {
+      third: makeSurface('Third', { order: 30, targets: { systems: ['c'] } }),
+      first: makeSurface('First', { order: 10, targets: { systems: ['a'] } }),
+      second: makeSurface('Second', { order: 20, targets: { systems: ['b'] } })
+    })
+
+    expect(projectOrganizationSurfaces(model).map((surface) => surface.id)).toEqual(['first', 'second', 'third'])
+  })
+
+  it('uses canonical semantic system IDs directly', () => {
     const model = makeModel(
       [
-        makeFeature('sales'),
-        makeFeature('sales.crm'),
-        makeFeature('sales.lead-gen'),
-        makeFeature('monitoring'),
-        makeFeature('monitoring.submitted-requests')
+        makeSystem('revenue'),
+        makeSystem('revenue.crm'),
+        makeSystem('revenue.lead-gen'),
+        makeSystem('delivery'),
+        makeSystem('delivery.projects')
       ],
-      [
-        makeSurface('legacy.sales', {
-          featureId: 'crm',
-          featureIds: ['crm', 'lead-gen', 'submitted-requests']
+      {
+        'canonical.sales': makeSurface('Canonical Sales', {
+          targets: { systems: ['revenue.crm', 'revenue.lead-gen', 'delivery.projects'] }
         })
-      ]
+      }
     )
 
     expect(projectOrganizationSurfaces(model)[0]).toMatchObject({
-      featureId: 'sales.crm',
-      featureIds: ['sales.crm', 'sales.lead-gen', 'monitoring.submitted-requests']
+      systemIds: ['revenue.crm', 'revenue.lead-gen', 'delivery.projects']
     })
   })
 
-  it('disables projected surfaces when feature lineage is disabled', () => {
+  it('disables projected surfaces when system lineage is disabled', () => {
     const model = makeModel(
-      [
-        makeFeature('sales', { enabled: false }),
-        makeFeature('sales.crm')
-      ],
-      [
-        makeSurface('crm.pipeline', {
-          enabled: true,
-          featureId: 'sales.crm',
-          featureIds: ['sales.crm']
+      [makeSystem('sales', { enabled: false }), makeSystem('sales.crm', { parentSystemId: 'sales' })],
+      {
+        'crm.pipeline': makeSurface('Pipeline', {
+          targets: { systems: ['sales.crm'] }
         })
-      ]
+      }
     )
 
-    expect(projectOrganizationSurfaces(model)[0].enabled).toBe(false)
+    expect(projectOrganizationSurfaces(model)[0]?.enabled).toBe(false)
   })
 })
 
 describe('validateOrganizationSurfaceProjection', () => {
-  it('returns issue codes for duplicate and unknown surface references', () => {
+  it('returns issue codes for duplicate sidebar leaf ids, duplicate paths, and unknown system targets', () => {
     const model = makeModel(
-      [makeFeature('sales'), makeFeature('sales.crm')],
-      [
-        makeSurface('crm.pipeline', {
-          path: '/crm/pipeline',
-          featureId: 'sales.crm',
-          featureIds: ['sales.crm']
-        }),
-        makeSurface('crm.pipeline', {
-          path: '/crm/pipeline/',
-          featureId: 'missing.primary',
-          featureIds: ['missing.related']
-        })
-      ],
+      [makeSystem('sales'), makeSystem('sales.crm')],
       {
-        defaultSurfaceId: 'missing.default',
-        groups: [
-          {
-            id: 'primary',
-            label: 'Primary',
-            placement: 'primary',
-            surfaceIds: ['missing.group']
+        business: {
+          type: 'group',
+          label: 'Business',
+          children: {
+            'crm.pipeline': makeSurface('Pipeline', {
+              path: '/crm/pipeline',
+              targets: { systems: ['sales.crm'] }
+            })
           }
-        ]
+        }
+      },
+      {
+        'crm.pipeline': makeSurface('Pipeline Duplicate Id', {
+          path: '/crm/pipeline/',
+          targets: { systems: ['missing.related'] }
+        })
       }
     )
 
     expect(validateOrganizationSurfaceProjection(model).map((issue) => issue.code)).toEqual([
       'duplicate-surface-id',
       'duplicate-surface-path',
-      'unknown-surface-feature',
-      'unknown-surface-feature-reference',
-      'unknown-default-surface',
-      'unknown-group-surface'
+      'unknown-surface-system'
     ])
   })
+
+  it('emits unknown-surface-system with surfaceId and systemId for unrecognised system references', () => {
+    const model = makeModel([makeSystem('exists')], {
+      'test.surface': makeSurface('Test', {
+        targets: { systems: ['exists', 'does.not.exist'] }
+      })
+    })
+
+    const issues = validateOrganizationSurfaceProjection(model)
+    expect(issues).toHaveLength(1)
+    expect(issues[0]).toMatchObject({
+      code: 'unknown-surface-system',
+      surfaceId: 'test.surface',
+      systemId: 'does.not.exist'
+    })
+  })
+})
+
+describe('projectOrganizationSurfaces - flag inheritance', () => {
+  it('inherits requiresAdmin transitively from grandparent via parentSystemId chain', () => {
+    const model = makeModel(
+      [
+        makeSystem('gp', { requiresAdmin: true }),
+        makeSystem('gp.parent', { parentSystemId: 'gp' }),
+        makeSystem('gp.parent.leaf', { parentSystemId: 'gp.parent' })
+      ],
+      { 'test.surface': makeSurface('Test', { targets: { systems: ['gp.parent.leaf'] } }) }
+    )
+
+    expect(projectOrganizationSurfaces(model)[0]).toMatchObject({ requiresAdmin: true })
+  })
+
+  it('computes devOnly from lifecycle beta even when devOnly is not set', () => {
+    const model = makeModel([makeSystem('beta-sys', { lifecycle: 'beta' })], {
+      'test.surface': makeSurface('Test', { targets: { systems: ['beta-sys'] } })
+    })
+
+    expect(projectOrganizationSurfaces(model)[0]).toMatchObject({ devOnly: true })
+  })
+
+  it('preserves explicit sidebar devOnly and requiresAdmin flags', () => {
+    const model = makeModel([makeSystem('active-sys', { enabled: true, lifecycle: 'active' })], {
+      'test.surface': makeSurface('Test', {
+        devOnly: true,
+        requiresAdmin: true,
+        targets: { systems: ['active-sys'] }
+      })
+    })
+
+    expect(projectOrganizationSurfaces(model)[0]).toMatchObject({ devOnly: true, requiresAdmin: true })
+  })
+
+  it('disables surface and preserves both systemIds when any referenced system is disabled', () => {
+    const model = makeModel([makeSystem('sys-a', { enabled: true }), makeSystem('sys-b', { enabled: false })], {
+      'test.surface': makeSurface('Test', { targets: { systems: ['sys-a', 'sys-b'] } })
+    })
+
+    const projection = projectOrganizationSurfaces(model)[0]
+    expect(projection?.enabled).toBe(false)
+    expect(projection?.systemIds).toEqual(['sys-a', 'sys-b'])
+  })
+
+  it('disables surface for deprecated lifecycle and archived lifecycle even when enabled is true', () => {
+    for (const lifecycle of ['deprecated', 'archived'] as const) {
+      const model = makeModel([makeSystem('gated-sys', { lifecycle, enabled: true })], {
+        'test.surface': makeSurface('Test', { targets: { systems: ['gated-sys'] } })
+      })
+
+      expect(projectOrganizationSurfaces(model)[0]?.enabled, `lifecycle: ${lifecycle}`).toBe(false)
+    }
+  })
+
+  it('filters unknown system references from projection systemIds', () => {
+    const model = makeModel([makeSystem('exists')], {
+      'test.surface': makeSurface('Test', { targets: { systems: ['exists', 'does.not.exist'] } })
+    })
+
+    expect(projectOrganizationSurfaces(model)[0]?.systemIds).toEqual(['exists'])
+  })
+})
+
+describe('helpers - hierarchy traversal', () => {
+  const systems: Record<string, OrganizationModelSystemEntry> = {
+    a: makeSystem('a'),
+    'a.b': makeSystem('a.b'),
+    'a.b.c': makeSystem('a.b.c'),
+    x: makeSystem('x')
+  }
+
+  it('ancestorsOf returns all path-segment ancestors including self in root-to-leaf order', () => {
+    expect(ancestorsOf(systems, 'a.b.c').map((s) => s.id)).toEqual(['a', 'a.b', 'a.b.c'])
+  })
+
+  it('childrenOf returns only direct children, not grandchildren', () => {
+    expect(childrenOf(systems, 'a').map((s) => s.id)).toEqual(['a.b'])
+  })
+
+  it('topLevel returns only root-level systems with no dot in their id', () => {
+    expect(
+      topLevel(systems)
+        .map((s) => s.id)
+        .sort()
+    ).toEqual(['a', 'x'])
+  })
 })

package/src/organization-model/catalogs/lead-gen.ts

@@ -0,0 +1,144 @@
+// ============================================================================
+// Lead-Gen Stage Catalog (OM Spine processing-state model)
+//
+// Canonical set of processing stage keys for acq_companies.processing_state and
+// acq_contacts.processing_state. These keys coordinate build templates, workflow
+// factory validation, API filters, and UI progress projections.
+//
+// State is sparse: absent keys mean "not attempted"; present keys hold terminal
+// status entries such as success, no_result, skipped, or error.
+//
+// Historical sources:
+//   ACQ_LIST_MEMBERS_LEAD_GEN_PIPELINE   -> personalized, uploaded, interested,
+//                                          discovered, verified
+//   ACQ_LIST_COMPANIES_LEAD_GEN_PIPELINE -> populated, extracted, qualified
+//   Design plan hint (lead-gen-domain-cleanup.mdx section 4) -> scraped, enriched
+//
+// ============================================================================
+
+/** One entry in the lead-gen stage catalog. */
+export interface LeadGenStageCatalogEntry {
+  /** Matches the status key written into processing_state jsonb (e.g. 'scraped'). */
+  key: string
+  /** Human-readable label for UI display. */
+  label: string
+  /** Short description of what this stage represents. */
+  description: string
+  /** Canonical pipeline order for UI sorting. Lower = earlier in the funnel. */
+  order: number
+  /** Which entity's processing_state jsonb carries this stage status. */
+  entity: 'company' | 'contact'
+  /** Additional entities allowed to write/read this processing_state key. */
+  additionalEntities?: Array<'company' | 'contact'>
+  /**
+   * Optional read-side override for Records views when a company-scoped step
+   * produces records on a different entity.
+   */
+  recordEntity?: 'company' | 'contact'
+  /** Stage key to read from recordEntity.processing_state for Records views. */
+  recordStageKey?: string
+}
+
+/**
+ * Canonical lead-gen processing stage catalog.
+ * Keys are the stage names written by workflow steps into processing_state jsonb.
+ *
+ * Ordered roughly by pipeline progression (prospecting -> outreach -> qualification).
+ */
+export const LEAD_GEN_STAGE_CATALOG: Record<string, LeadGenStageCatalogEntry> = {
+  // Prospecting - company population
+  scraped: {
+    key: 'scraped',
+    label: 'Scraped',
+    description: 'Company was scraped from a source directory (Apify actor run).',
+    order: 1,
+    entity: 'company'
+  },
+  populated: {
+    key: 'populated',
+    label: 'Companies found',
+    description: 'Companies have been found and added to the lead-gen list.',
+    order: 2,
+    entity: 'company'
+  },
+  crawled: {
+    key: 'crawled',
+    label: 'Websites crawled',
+    description:
+      'Company websites have been crawled (e.g. via Apify) and raw page content stored for downstream LLM analysis.',
+    order: 2.5,
+    entity: 'company'
+  },
+  extracted: {
+    key: 'extracted',
+    label: 'Websites analyzed',
+    description: 'Company websites have been analyzed for business signals.',
+    order: 3,
+    entity: 'company'
+  },
+  enriched: {
+    key: 'enriched',
+    label: 'Enriched',
+    description: 'Company or contact enriched with third-party data (e.g. Tomba, Anymailfinder).',
+    order: 4,
+    entity: 'company'
+  },
+  'decision-makers-enriched': {
+    key: 'decision-makers-enriched',
+    label: 'Decision-makers found',
+    description: 'Decision-maker contacts discovered and attached to a qualified company.',
+    order: 6,
+    entity: 'company',
+    recordEntity: 'contact',
+    recordStageKey: 'discovered'
+  },
+
+  // Prospecting - contact discovery
+  discovered: {
+    key: 'discovered',
+    label: 'Decision-makers found',
+    description: 'Decision-maker contact details have been found.',
+    order: 5,
+    entity: 'contact'
+  },
+  verified: {
+    key: 'verified',
+    label: 'Emails verified',
+    description: 'Contact email addresses have been checked for deliverability.',
+    order: 7,
+    entity: 'contact'
+  },
+
+  // Qualification
+  qualified: {
+    key: 'qualified',
+    label: 'Companies qualified',
+    description: 'Companies have been scored against the qualification criteria.',
+    order: 8,
+    entity: 'company'
+  },
+
+  // Outreach
+  personalized: {
+    key: 'personalized',
+    label: 'Personalized',
+    description: 'Outreach message personalized for the contact (Instantly personalization workflow).',
+    order: 9,
+    entity: 'contact'
+  },
+  uploaded: {
+    key: 'uploaded',
+    label: 'Reviewed and exported',
+    description: 'Approved records have been reviewed and exported for handoff.',
+    order: 10,
+    entity: 'company',
+    additionalEntities: ['contact']
+  },
+  interested: {
+    key: 'interested',
+    label: 'Interested',
+    description: 'Contact replied with a positive signal (Instantly reply-handler transition).',
+    order: 11,
+    entity: 'contact'
+  }
+}

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

@@ -0,0 +1,36 @@
+import { z } from 'zod'
+import { defineContentType } from './registry'
+
+// ---------------------------------------------------------------------------
+// config kinds (Phase 3, Wave 2A)
+// ---------------------------------------------------------------------------
+//
+// `config:kv` — a flat key-value configuration store co-located with a system.
+//               Per L15: single starter config type; feature-flag semantics are
+//               a usage pattern over kv, not a separate type.
+//
+// Per L15: `config` is a first-class registered meta-kind. Scope: NEW
+// tenant-defined settings co-located with a system. Strongly-typed platform
+// fields (system.ui.devOnly, system.ui.requiresAdmin, etc.) stay where they
+// are and are NOT hoisting destinations for existing typed fields.
+
+const ConfigKvPayloadSchema = z.object({
+  /**
+   * Flat key-value entries. Values are JSON primitives.
+   * Keys are short identifiers (e.g. 'maxBatchSize', 'featureEnabled').
+   */
+  entries: z
+    .record(z.string().trim().min(1).max(200), z.union([z.string(), z.number(), z.boolean(), z.null()]))
+    .meta({ label: 'Entries', hint: 'Key-value configuration entries (string, number, boolean, or null values)' })
+})
+
+export type ConfigKvPayload = z.infer<typeof ConfigKvPayloadSchema>
+
+export const configKvKind = defineContentType({
+  kind: 'config',
+  type: 'kv',
+  label: 'Key-Value Config',
+  description: 'A flat key-value configuration store co-located with a system. Values are JSON primitives.',
+  payloadSchema: ConfigKvPayloadSchema,
+  parentTypes: []
+})

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

@@ -0,0 +1,74 @@
+// ---------------------------------------------------------------------------
+// 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'
+
+/**
+ * The populated content-kind registry for all platform-shipped kinds.
+ * Per D8: static const object keyed by `'<kind>:<type>'` composite key.
+ *
+ * Keys:
+ *   'schema:pipeline'      — pipeline applying to an entity type
+ *   'schema:stage'         — stage within a pipeline (parentTypes: ['schema:pipeline'])
+ *   'schema:template'      — named build template
+ *   'schema:template-step' — step within a template (parentTypes: ['schema:template'])
+ *   'schema:status-flow'   — status set for a project/milestone/task scope
+ *   'schema:status'        — single status within a flow (parentTypes: ['schema:status-flow'])
+ *   'config:kv'            — flat key-value config store co-located with a system
+ *
+ * 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]
+}