@elevasis/core 0.27.0 → 0.29.0

package/src/execution/engine/index.ts

@@ -326,10 +326,12 @@ export {
   type TransitionDealParams,
   type LoadDealParams,
   // List-oriented lead gen params (Step 3 of list-oriented migration)
-  type UpdateListConfigParams,
-  type UpdateCompanyStageParams,
-  type UpdateContactStageParams,
-  type ListPendingCompanyIdsParams,
+  type UpdateListConfigParams,
+  type UpdateCompanyStageParams,
+  type UpdateContactStageParams,
+  type ClearCompanyStagesParams,
+  type ClearContactStagesParams,
+  type ListPendingCompanyIdsParams,
   type ListPendingContactIdsParams,
   type AddCompaniesToListParams,
   type AddCompaniesToListResult,

package/src/execution/engine/tools/lead-service-types.ts

@@ -529,23 +529,39 @@ export interface UpdateListConfigParams {
   pipelineConfig?: PipelineConfig
 }
 
-export interface UpdateCompanyStageParams {
-  organizationId: string
-  listId: string
-  companyId: string
-  stage: string
-  status?: ProcessingStageStatus
-  executionId?: string
-}
-
-export interface UpdateContactStageParams {
-  organizationId: string
-  listId: string
-  contactId: string
-  stage: string
-  status?: ProcessingStageStatus
-  executionId?: string
-}
+export interface UpdateCompanyStageParams {
+  organizationId: string
+  listId: string
+  companyId: string
+  stage: string
+  status?: ProcessingStageStatus
+  data?: unknown
+  executionId?: string
+}
+
+export interface UpdateContactStageParams {
+  organizationId: string
+  listId: string
+  contactId: string
+  stage: string
+  status?: ProcessingStageStatus
+  data?: unknown
+  executionId?: string
+}
+
+export interface ClearCompanyStagesParams {
+  organizationId: string
+  listId: string
+  companyId: string
+  stages: string[]
+}
+
+export interface ClearContactStagesParams {
+  organizationId: string
+  listId: string
+  contactId: string
+  stages: string[]
+}
 
 export interface ListPendingCompanyIdsParams {
   organizationId: string
@@ -589,14 +605,15 @@ export interface RecordListExecutionParams {
   configSnapshot?: Record<string, unknown>
 }
 
-export interface ListExecutionSummary {
-  executionId: string
-  resourceId: string
-  status: string
-  createdAt: string
-  completedAt: string | null
-  durationMs: number | null
-}
+export interface ListExecutionSummary {
+  executionId: string
+  resourceId: string
+  status: string
+  createdAt: string
+  completedAt: string | null
+  durationMs: number | null
+  input?: unknown
+}
 
 // Bulk import (contacts)
 export interface BulkImportParams {
@@ -712,15 +729,27 @@ export interface ILeadService {
    */
   getListProgress(listId: string, organizationId: string): Promise<ListProgress | null>
 
-  /**
-   * Advance a company row within a list's explicit stage journey.
-   */
-  updateCompanyStage(params: UpdateCompanyStageParams): Promise<void>
-
-  /**
-   * Advance a contact row within a list's explicit stage journey.
-   */
-  updateContactStage(params: UpdateContactStageParams): Promise<void>
+  /**
+   * Advance a company row within a list's explicit stage journey.
+   */
+  updateCompanyStage(params: UpdateCompanyStageParams): Promise<void>
+
+  /**
+   * Advance a contact row within a list's explicit stage journey.
+   */
+  updateContactStage(params: UpdateContactStageParams): Promise<void>
+
+  /**
+   * Clear company stage entries by deleting keys from processing_state.
+   * Missing stage keys represent "not attempted"; never persist null markers.
+   */
+  clearCompanyStages(params: ClearCompanyStagesParams): Promise<void>
+
+  /**
+   * Clear contact stage entries by deleting keys from processing_state.
+   * Missing stage keys represent "not attempted"; never persist null markers.
+   */
+  clearContactStages(params: ClearContactStagesParams): Promise<void>
 
   /**
    * Return the company_ids in acq_list_companies for the given list where

package/src/execution/engine/tools/platform/acquisition/types.ts

@@ -1,6 +1,5 @@
-import { z } from 'zod'
-import { isProspectingBuildTemplateId } from '../../../../../business/acquisition/build-templates'
-import {
+import { z } from 'zod'
+import {
   CompanyProcessingStateSchema,
   ContactProcessingStateSchema
 } from '../../../../../business/acquisition/api-schemas'
@@ -10,11 +9,11 @@ import { EmailSchema } from '../../../../../platform/utils/validation'
 // LIST SCHEMAS
 // ============================================
 
-export const CreateListInputSchema = z.object({
-  name: z.string().min(1),
-  description: z.string().optional(),
-  buildTemplateId: z.string().refine(isProspectingBuildTemplateId).optional()
-})
+export const CreateListInputSchema = z.object({
+  name: z.string().min(1),
+  description: z.string().optional(),
+  buildTemplateId: z.string().trim().min(1).max(100).optional()
+})
 
 export const UpdateListInputSchema = z.object({
   id: z.string().uuid(),

package/src/execution/engine/tools/registry.ts

@@ -587,10 +587,12 @@ export {
   type GetDealByIdParams,
   type GetContactByIdParams,
   type GetCompanyByIdParams,
-  type UpdateListConfigParams,
-  type UpdateCompanyStageParams,
-  type UpdateContactStageParams,
-  type ListPendingCompanyIdsParams,
+  type UpdateListConfigParams,
+  type UpdateCompanyStageParams,
+  type UpdateContactStageParams,
+  type ClearCompanyStagesParams,
+  type ClearContactStagesParams,
+  type ListPendingCompanyIdsParams,
   type ListPendingContactIdsParams,
   type AddCompaniesToListParams,
   type AddCompaniesToListResult,

package/src/execution/engine/tools/tool-maps.ts

@@ -258,6 +258,8 @@ import type {
   RecordListExecutionParams,
   UpdateCompanyStageParams,
   UpdateContactStageParams,
+  ClearCompanyStagesParams,
+  ClearContactStagesParams,
   ListPendingCompanyIdsParams,
   ListPendingContactIdsParams,
   UpsertSocialPostParams,
@@ -589,6 +591,14 @@ export type LeadToolMap = {
     params: Omit<UpdateContactStageParams, 'organizationId'>
     result: void
   }
+  clearCompanyStages: {
+    params: Omit<ClearCompanyStagesParams, 'organizationId'>
+    result: void
+  }
+  clearContactStages: {
+    params: Omit<ClearContactStagesParams, 'organizationId'>
+    result: void
+  }
   // Company operations
   createCompany: { params: Omit<CreateCompanyParams, 'organizationId'>; result: AcqCompany }
   upsertCompany: { params: Omit<UpsertCompanyParams, 'organizationId'>; result: AcqCompany }
@@ -713,7 +723,11 @@ export type LeadToolMap = {
 export type ListToolMap = {
   getConfig: {
     params: { listId: string }
-    result: { scrapingConfig: ScrapingConfig; icp: IcpRubric; pipelineConfig: PipelineConfig }
+    result: {
+      scrapingConfig: ScrapingConfig
+      icp: IcpRubric
+      pipelineConfig: PipelineConfig & { dataMode: 'mock' | 'live' }
+    }
   }
   recordExecution: {
     params: Omit<RecordListExecutionParams, 'organizationId'>
@@ -727,6 +741,14 @@ export type ListToolMap = {
     params: Omit<UpdateContactStageParams, 'organizationId'>
     result: void
   }
+  clearCompanyStages: {
+    params: Omit<ClearCompanyStagesParams, 'organizationId'>
+    result: void
+  }
+  clearContactStages: {
+    params: Omit<ClearContactStagesParams, 'organizationId'>
+    result: void
+  }
   listPendingCompanyIds: {
     params: Omit<ListPendingCompanyIdsParams, 'organizationId'>
     result: string[]

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>