@elevasis/core 0.27.0 → 0.28.0

package/src/organization-model/__tests__/define-domain-record.test.ts

@@ -0,0 +1,289 @@
+import { describe, expect, it } from 'vitest'
+import { z } from 'zod'
+import { defineDomainRecord } from '../helpers'
+import { defineAction, defineActions, ActionSchema } from '../domains/actions'
+import { defineEntity, defineEntities, EntitySchema } from '../domains/entities'
+import { defineSystem, defineSystems, SystemEntrySchema } from '../domains/systems'
+import { definePolicy, definePolicies, PolicySchema } from '../domains/policies'
+import { defineRole, defineRoles, RoleSchema } from '../domains/roles'
+import { defineGoal, defineGoals, ObjectiveSchema } from '../domains/goals'
+import { defineCustomer, defineCustomers, CustomerSegmentSchema } from '../domains/customers'
+import { defineOffering, defineOfferings, ProductSchema } from '../domains/offerings'
+import { defineStatus, defineStatuses, StatusEntrySchema } from '../domains/statuses'
+import { defineKnowledgeNode, defineKnowledgeNodes, OrgKnowledgeNodeSchema } from '../domains/knowledge'
+
+// ---------------------------------------------------------------------------
+// Minimal valid fixtures for each domain
+// ---------------------------------------------------------------------------
+
+const validAction: z.input<typeof ActionSchema> = {
+  id: 'test-action',
+  order: 10,
+  label: 'Test Action',
+  invocations: []
+}
+
+const validEntity: z.input<typeof EntitySchema> = {
+  id: 'test.entity',
+  order: 10,
+  label: 'Test Entity',
+  ownedBySystemId: 'test-system'
+}
+
+const validSystem: z.input<typeof SystemEntrySchema> = {
+  id: 'test-system',
+  order: 10,
+  label: 'Test System'
+}
+
+const validPolicy: z.input<typeof PolicySchema> = {
+  id: 'test-policy',
+  order: 10,
+  label: 'Test Policy',
+  trigger: { kind: 'manual' },
+  actions: [{ kind: 'block' }]
+}
+
+const validRole: z.input<typeof RoleSchema> = {
+  id: 'test-role',
+  order: 10,
+  title: 'Test Role'
+}
+
+const validGoal: z.input<typeof ObjectiveSchema> = {
+  id: 'test-goal',
+  order: 10,
+  description: 'Grow ARR by 2x',
+  periodStart: '2026-01-01',
+  periodEnd: '2026-12-31'
+}
+
+const validCustomer: z.input<typeof CustomerSegmentSchema> = {
+  id: 'test-segment',
+  order: 10,
+  name: 'SMB Agencies'
+}
+
+const validOffering: z.input<typeof ProductSchema> = {
+  id: 'test-product',
+  order: 10,
+  name: 'Starter Plan'
+}
+
+const validStatus: z.input<typeof StatusEntrySchema> = {
+  id: 'test.status',
+  order: 10,
+  label: 'Test Status',
+  semanticClass: 'delivery.task'
+}
+
+const validKnowledgeNode: z.input<typeof OrgKnowledgeNodeSchema> = {
+  id: 'test-knowledge',
+  kind: 'reference',
+  title: 'Test Knowledge',
+  summary: 'A test knowledge node.',
+  body: 'Full body content here.',
+  updatedAt: '2026-01-01'
+}
+
+// ---------------------------------------------------------------------------
+// Generic defineDomainRecord
+// ---------------------------------------------------------------------------
+
+describe('defineDomainRecord', () => {
+  it('produces an id-keyed map for valid entries', () => {
+    const result = defineDomainRecord(ActionSchema, [validAction])
+    expect(result).toHaveProperty('test-action')
+    expect(result['test-action'].id).toBe('test-action')
+    expect(result['test-action'].label).toBe('Test Action')
+  })
+
+  it('produces a map keyed by each entry id when given multiple entries', () => {
+    const second: z.input<typeof ActionSchema> = { ...validAction, id: 'second-action', label: 'Second' }
+    const result = defineDomainRecord(ActionSchema, [validAction, second])
+    expect(Object.keys(result)).toEqual(['test-action', 'second-action'])
+  })
+
+  it('returns an empty map for an empty entries array', () => {
+    const result = defineDomainRecord(ActionSchema, [])
+    expect(result).toEqual({})
+  })
+
+  it('throws ZodError when an entry fails schema validation', () => {
+    const bad = { id: 'bad', order: 'not-a-number', label: 'Bad' } as unknown as z.input<typeof ActionSchema>
+    expect(() => defineDomainRecord(ActionSchema, [bad])).toThrow(z.ZodError)
+  })
+
+  it('applies schema defaults (invocations defaults to [])', () => {
+    const minimal = { id: 'minimal-action', order: 10, label: 'Minimal' } as z.input<typeof ActionSchema>
+    const result = defineDomainRecord(ActionSchema, [minimal])
+    expect(result['minimal-action'].invocations).toEqual([])
+  })
+})
+
+// ---------------------------------------------------------------------------
+// Parameterized per-domain tests
+// ---------------------------------------------------------------------------
+
+describe.each([
+  {
+    domain: 'actions',
+    defineSingle: defineAction,
+    defineMultiple: defineActions,
+    valid: validAction,
+    schema: ActionSchema,
+    idField: 'id' as const,
+    invalidOverride: { order: 'not-a-number' }
+  },
+  {
+    domain: 'entities',
+    defineSingle: defineEntity,
+    defineMultiple: defineEntities,
+    valid: validEntity,
+    schema: EntitySchema,
+    idField: 'id' as const,
+    invalidOverride: { order: 'not-a-number' }
+  },
+  {
+    domain: 'systems',
+    defineSingle: defineSystem,
+    defineMultiple: defineSystems,
+    valid: validSystem,
+    schema: SystemEntrySchema,
+    idField: 'id' as const,
+    invalidOverride: { order: 'not-a-number' }
+  },
+  {
+    domain: 'policies',
+    defineSingle: definePolicy,
+    defineMultiple: definePolicies,
+    valid: validPolicy,
+    schema: PolicySchema,
+    idField: 'id' as const,
+    invalidOverride: { order: 'not-a-number' }
+  },
+  {
+    domain: 'roles',
+    defineSingle: defineRole,
+    defineMultiple: defineRoles,
+    valid: validRole,
+    schema: RoleSchema,
+    idField: 'id' as const,
+    invalidOverride: { order: 'not-a-number' }
+  },
+  {
+    domain: 'goals',
+    defineSingle: defineGoal,
+    defineMultiple: defineGoals,
+    valid: validGoal,
+    schema: ObjectiveSchema,
+    idField: 'id' as const,
+    invalidOverride: { order: 'not-a-number' }
+  },
+  {
+    domain: 'customers',
+    defineSingle: defineCustomer,
+    defineMultiple: defineCustomers,
+    valid: validCustomer,
+    schema: CustomerSegmentSchema,
+    idField: 'id' as const,
+    invalidOverride: { order: 'not-a-number' }
+  },
+  {
+    domain: 'offerings',
+    defineSingle: defineOffering,
+    defineMultiple: defineOfferings,
+    valid: validOffering,
+    schema: ProductSchema,
+    idField: 'id' as const,
+    invalidOverride: { order: 'not-a-number' }
+  },
+  {
+    domain: 'statuses',
+    defineSingle: defineStatus,
+    defineMultiple: defineStatuses,
+    valid: validStatus,
+    schema: StatusEntrySchema,
+    idField: 'id' as const,
+    invalidOverride: { order: 'not-a-number' }
+  },
+  {
+    domain: 'knowledge',
+    defineSingle: defineKnowledgeNode,
+    defineMultiple: defineKnowledgeNodes,
+    valid: validKnowledgeNode,
+    schema: OrgKnowledgeNodeSchema,
+    idField: 'id' as const,
+    invalidOverride: { kind: 'invalid-kind' }
+  }
+])(
+  'define$domain — $domain',
+  ({ domain: _domain, defineSingle, defineMultiple, valid, schema, idField, invalidOverride }) => {
+    it('defineX — validates and returns a parsed entry', () => {
+      const result = defineSingle(valid as never)
+      expect(result).toHaveProperty(idField)
+      expect((result as Record<string, unknown>)[idField]).toBe((valid as Record<string, unknown>)[idField])
+    })
+
+    it('defineX — throws ZodError on invalid input', () => {
+      const bad = { ...valid, ...invalidOverride } as never
+      expect(() => defineSingle(bad)).toThrow(z.ZodError)
+    })
+
+    it('defineXs — produces an id-keyed map', () => {
+      const result = defineMultiple([valid] as never[])
+      const id = (valid as Record<string, unknown>)[idField] as string
+      expect(result).toHaveProperty(id)
+      expect((result[id] as Record<string, unknown>)[idField]).toBe(id)
+    })
+
+    it('defineXs — throws ZodError on invalid input', () => {
+      const bad = { ...valid, ...invalidOverride } as never
+      expect(() => defineMultiple([bad] as never[])).toThrow(z.ZodError)
+    })
+
+    it('defineXs — returns empty map for empty array', () => {
+      const result = defineMultiple([] as never[])
+      expect(result).toEqual({})
+    })
+
+    it('defineXs — validates through schema (no bypass)', () => {
+      // Confirm that defineMultiple uses schema.parse, not a pass-through.
+      // Missing required fields should throw even if the object looks similar.
+      const missingRequired = { [idField]: (valid as Record<string, unknown>)[idField] } as never
+      expect(() => defineMultiple([missingRequired] as never[])).toThrow(z.ZodError)
+    })
+  }
+)
+
+// ---------------------------------------------------------------------------
+// Topology — existing helpers (defineTopology, defineTopologyRelationship)
+// are already tested elsewhere; verified here that they exist and are callable.
+// ---------------------------------------------------------------------------
+
+describe('topology — existing helpers', () => {
+  it('defineTopologyRelationship is importable from domains/topology', async () => {
+    const { defineTopologyRelationship, topologyRef } = await import('../domains/topology')
+    const rel = defineTopologyRelationship({
+      from: topologyRef.system('sales'),
+      kind: 'uses',
+      to: topologyRef.resource('lead-gen.company.qualify')
+    })
+    expect(rel.kind).toBe('uses')
+    expect(rel.from.kind).toBe('system')
+    expect(rel.to.kind).toBe('resource')
+  })
+
+  it('defineTopology is importable and produces a domain object', async () => {
+    const { defineTopology, topologyRef } = await import('../domains/topology')
+    const domain = defineTopology({
+      'rel-1': {
+        from: topologyRef.system('sales'),
+        kind: 'triggers',
+        to: topologyRef.resource('lead-gen.company.qualify')
+      }
+    })
+    expect(domain.version).toBe(1)
+    expect(domain.relationships).toHaveProperty('rel-1')
+  })
+})

package/src/organization-model/__tests__/om-spine-doc-contract.test.ts

@@ -0,0 +1,56 @@
+import { readFileSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+import { describe, expect, it } from 'vitest'
+import { ACTION_REGISTRY } from '../domains/prospecting'
+import { getLeadGenStageCatalog } from '../migration-helpers'
+
+/**
+ * OM Spine doc <-> code contract guard.
+ *
+ * `scripts/monorepo/meta-verify.mjs` only string-greps the primer for symbol
+ * names, so it cannot notice when a documented "constant" has become a
+ * type-only export or an empty stub. This drift actually shipped (the Wave-2
+ * generic/canonical OM split) and went uncaught for that reason. These
+ * assertions tie the primer text to the real code shape so the same class of
+ * drift fails the unit suite. Pure file reads + pure imports — CI-safe.
+ */
+
+const repoRoot = fileURLToPath(new URL('../../../../../', import.meta.url))
+const catalogTypeSrc = fileURLToPath(new URL('../catalogs/lead-gen.ts', import.meta.url))
+
+const PRIMER_PATHS = [
+  'apps/docs/content/docs/technical/development/design/om-spine.mdx',
+  '.claude/skills/org-os/operations/spine.md'
+]
+
+const read = (p: string) => readFileSync(p, 'utf8')
+
+describe('OM Spine doc/code contract', () => {
+  it('keeps the generic core action registry an empty stub (bindings live in @repo/elevasis-core)', () => {
+    expect(ACTION_REGISTRY).toEqual([])
+  })
+
+  it('exposes the lead-gen catalog only as a reader function, not a hand-authored constant', () => {
+    expect(typeof getLeadGenStageCatalog).toBe('function')
+
+    // catalogs/lead-gen.ts must remain type-only — no LEAD_GEN_STAGE_CATALOG value export.
+    const src = read(catalogTypeSrc)
+    expect(src).not.toMatch(/export\s+const\s+LEAD_GEN_STAGE_CATALOG\b/)
+    expect(src).toMatch(/export\s+interface\s+LeadGenStageCatalogEntry\b/)
+  })
+
+  it.each(PRIMER_PATHS)('primer %s describes the post-split reality, not the retired constant', (relPath) => {
+    const text = read(repoRoot + relPath)
+
+    // Negative: the exact stale claims that shipped before this fix must not return.
+    expect(text).not.toMatch(
+      /`LEAD_GEN_STAGE_CATALOG`\s+in\s+`packages\/core\/src\/organization-model\/catalogs\/lead-gen\.ts`/
+    )
+    expect(text).not.toMatch(/LEAD_GEN_STAGE_CATALOG \(vocabulary, catalogs\/lead-gen\.ts\)/)
+
+    // Positive: each primer must point at the real reader + canonical owners.
+    expect(text).toContain('getLeadGenStageCatalog')
+    expect(text).toContain('LEAD_GEN_ACTION_ENTRIES')
+    expect(text).toContain('@repo/elevasis-core')
+  })
+})

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

@@ -1,6 +1,7 @@
 import { z } from 'zod'
 import { EntityIdSchema } from './entities'
 import { DescriptionSchema, LabelSchema, ModelIdSchema } from './shared'
+import { defineDomainRecord } from '../helpers'
 
 export const ActionResourceIdSchema = z
   .string()
@@ -107,6 +108,18 @@ export function findOrganizationActionById(
   return actions[id]
 }
 
+/** Validate and return a single action entry. */
+export function defineAction(entry: z.input<typeof ActionSchema>): z.infer<typeof ActionSchema> {
+  return ActionSchema.parse(entry)
+}
+
+/** Validate and return an id-keyed map of action entries. */
+export function defineActions(
+  entries: readonly z.input<typeof ActionSchema>[]
+): Record<string, z.infer<typeof ActionSchema>> {
+  return defineDomainRecord(ActionSchema, entries)
+}
+
 export type ActionId = z.infer<typeof ActionIdSchema>
 export type ActionScope = z.infer<typeof ActionScopeSchema>
 export type ActionRef = z.infer<typeof ActionRefSchema>

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

@@ -1,78 +1,95 @@
-import { z } from 'zod'
-
-// ---------------------------------------------------------------------------
-// Firmographics — optional demographic/firmographic filters that describe the
-// target customer segment's organizational profile. All fields are optional so
-// a segment can declare only the axes relevant to targeting.
-// ---------------------------------------------------------------------------
-
-export const FirmographicsSchema = z.object({
-  /** Industry vertical (e.g. "Marketing Agency", "Legal", "Real Estate"). */
-  industry: z.string().trim().max(200).optional(),
-  /**
-   * Company headcount band (e.g. "1–10", "11–50", "51–200", "200+").
-   * Free-form string to accommodate any band notation.
-   */
-  companySize: z.string().trim().max(100).optional(),
-  /**
-   * Primary geographic region the segment operates in or is targeted from
-   * (e.g. "North America", "Europe", "Global").
-   */
-  region: z.string().trim().max(200).optional()
-})
-
-// ---------------------------------------------------------------------------
-// Customer segment schema — one entry per distinct buyer archetype.
-// Modeled after Value Proposition Canvas (BMC / VPC) and Business Model Canvas
-// customer-segment language. Fields use plain English throughout.
-// ---------------------------------------------------------------------------
-
-export const CustomerSegmentSchema = z.object({
-  /** Stable unique identifier for the segment (e.g. "segment-smb-agencies"). */
-  id: z.string().trim().min(1).max(100),
-  /** Domain-map iteration order. Convention: multiples of 10 (10, 20, 30, ...) to allow easy insertion. */
-  order: z.number(),
-  /** Human-readable name shown to agents and in UI (e.g. "SMB Marketing Agencies"). */
-  name: z.string().trim().max(200).default(''),
-  /** One or two sentences describing who this segment is. */
-  description: z.string().trim().max(2000).default(''),
-  /**
-   * The primary job(s) this segment is trying to get done — the goal they hire
-   * a product/service to accomplish. Plain-language narrative or bullet list.
-   */
-  jobsToBeDone: z.string().trim().max(2000).default(''),
-  /**
-   * Pains — frustrations, obstacles, and risks the segment experiences
-   * when trying to accomplish their jobs-to-be-done.
-   */
-  pains: z.array(z.string().trim().max(500)).default([]),
-  /**
-   * Gains — outcomes and benefits the segment desires; positive motivators
-   * beyond merely resolving pains.
-   */
-  gains: z.array(z.string().trim().max(500)).default([]),
-  /** Firmographic profile for targeting and filtering. */
-  firmographics: FirmographicsSchema.default({}),
-  /**
-   * Value proposition — one or two sentences stating why this organization's
-   * offering is uniquely suited for this segment's needs.
-   */
-  valueProp: z.string().trim().max(2000).default('')
-})
-
-// ---------------------------------------------------------------------------
-// Customers domain schema — id-keyed map of customer segments.
-// ---------------------------------------------------------------------------
-
-export const CustomersDomainSchema = z
-  .record(z.string(), CustomerSegmentSchema)
-  .refine((record) => Object.entries(record).every(([key, entry]) => entry.id === key), {
-    message: 'Each segment entry id must match its map key'
-  })
-  .default({})
-
-// ---------------------------------------------------------------------------
-// Seed — empty by default; adapters populate with real segment definitions.
-// ---------------------------------------------------------------------------
-
-export const DEFAULT_ORGANIZATION_MODEL_CUSTOMERS: z.infer<typeof CustomersDomainSchema> = {}
+import { z } from 'zod'
+import { defineDomainRecord } from '../helpers'
+
+// ---------------------------------------------------------------------------
+// Firmographics — optional demographic/firmographic filters that describe the
+// target customer segment's organizational profile. All fields are optional so
+// a segment can declare only the axes relevant to targeting.
+// ---------------------------------------------------------------------------
+
+export const FirmographicsSchema = z.object({
+  /** Industry vertical (e.g. "Marketing Agency", "Legal", "Real Estate"). */
+  industry: z.string().trim().max(200).optional(),
+  /**
+   * Company headcount band (e.g. "1–10", "11–50", "51–200", "200+").
+   * Free-form string to accommodate any band notation.
+   */
+  companySize: z.string().trim().max(100).optional(),
+  /**
+   * Primary geographic region the segment operates in or is targeted from
+   * (e.g. "North America", "Europe", "Global").
+   */
+  region: z.string().trim().max(200).optional()
+})
+
+// ---------------------------------------------------------------------------
+// Customer segment schema — one entry per distinct buyer archetype.
+// Modeled after Value Proposition Canvas (BMC / VPC) and Business Model Canvas
+// customer-segment language. Fields use plain English throughout.
+// ---------------------------------------------------------------------------
+
+export const CustomerSegmentSchema = z.object({
+  /** Stable unique identifier for the segment (e.g. "segment-smb-agencies"). */
+  id: z.string().trim().min(1).max(100),
+  /** Domain-map iteration order. Convention: multiples of 10 (10, 20, 30, ...) to allow easy insertion. */
+  order: z.number(),
+  /** Human-readable name shown to agents and in UI (e.g. "SMB Marketing Agencies"). */
+  name: z.string().trim().max(200).default(''),
+  /** One or two sentences describing who this segment is. */
+  description: z.string().trim().max(2000).default(''),
+  /**
+   * The primary job(s) this segment is trying to get done — the goal they hire
+   * a product/service to accomplish. Plain-language narrative or bullet list.
+   */
+  jobsToBeDone: z.string().trim().max(2000).default(''),
+  /**
+   * Pains — frustrations, obstacles, and risks the segment experiences
+   * when trying to accomplish their jobs-to-be-done.
+   */
+  pains: z.array(z.string().trim().max(500)).default([]),
+  /**
+   * Gains — outcomes and benefits the segment desires; positive motivators
+   * beyond merely resolving pains.
+   */
+  gains: z.array(z.string().trim().max(500)).default([]),
+  /** Firmographic profile for targeting and filtering. */
+  firmographics: FirmographicsSchema.default({}),
+  /**
+   * Value proposition — one or two sentences stating why this organization's
+   * offering is uniquely suited for this segment's needs.
+   */
+  valueProp: z.string().trim().max(2000).default('')
+})
+
+// ---------------------------------------------------------------------------
+// Customers domain schema — id-keyed map of customer segments.
+// ---------------------------------------------------------------------------
+
+export const CustomersDomainSchema = z
+  .record(z.string(), CustomerSegmentSchema)
+  .refine((record) => Object.entries(record).every(([key, entry]) => entry.id === key), {
+    message: 'Each segment entry id must match its map key'
+  })
+  .default({})
+
+// ---------------------------------------------------------------------------
+// Seed — empty by default; adapters populate with real segment definitions.
+// ---------------------------------------------------------------------------
+
+export const DEFAULT_ORGANIZATION_MODEL_CUSTOMERS: z.infer<typeof CustomersDomainSchema> = {}
+
+/** Validate and return a single customer segment entry. */
+export function defineCustomer(entry: z.input<typeof CustomerSegmentSchema>): z.infer<typeof CustomerSegmentSchema> {
+  return CustomerSegmentSchema.parse(entry)
+}
+
+/** Validate and return an id-keyed map of customer segment entries. */
+export function defineCustomers(
+  entries: readonly z.input<typeof CustomerSegmentSchema>[]
+): Record<string, z.infer<typeof CustomerSegmentSchema>> {
+  return defineDomainRecord(CustomerSegmentSchema, entries)
+}
+
+export type CustomerSegment = z.infer<typeof CustomerSegmentSchema>
+export type CustomersDomain = z.infer<typeof CustomersDomainSchema>
+export type Firmographics = z.infer<typeof FirmographicsSchema>