@elevasis/core 0.13.0 → 0.15.0

package/src/_gen/__tests__/__snapshots__/contracts.md.snap

@@ -803,3 +803,2339 @@ export interface DeploymentSpec {
   humanCheckpoints?: HumanCheckpointDefinition[]
 }
 ```
+
+## CRM Platform Primitives
+
+### `AcqCompany`
+
+```typescript
+/**
+ * Company record in the acquisition database.
+ * Contains enriched company data from various sources.
+ * Transformed from AcqCompanyRow with camelCase properties.
+ */
+export interface AcqCompany {
+  id: string
+  organizationId: string
+  name: string
+  domain: string | null
+  linkedinUrl: string | null
+  website: string | null
+  numEmployees: number | null
+  foundedYear: number | null
+  locationCity: string | null
+  locationState: string | null
+  category: string | null
+  categoryPain: string | null
+  segment: string | null
+  pipelineStatus: CompanyPipelineStatus | null
+  enrichmentData: CompanyEnrichmentData | null
+  source: string | null
+  batchId: string | null
+  status: 'active' | 'invalid'
+  verticalResearch: string | null
+  /** Track A: flat qualification score (null until a scoring rubric is defined). Added by W1 migration. */
+  qualificationScore: number | null
+  /** Track A: flat qualification signals jsonb preserving the result payload shape. Added by W1 migration. */
+  qualificationSignals: Record<string, unknown> | null
+  /** Track A: key identifying the rubric used for qualification. Added by W1 migration. */
+  qualificationRubricKey: string | null
+  createdAt: Date
+  updatedAt: Date
+}
+```
+
+### `AcqContact`
+
+```typescript
+/**
+ * Contact record in the acquisition database.
+ * Contains enriched contact data and personalization content.
+ * Transformed from AcqContactRow with camelCase properties.
+ */
+export interface AcqContact {
+  id: string
+  organizationId: string
+  companyId: string | null
+  email: string
+  emailValid: 'VALID' | 'INVALID' | 'RISKY' | 'UNKNOWN' | null
+  firstName: string | null
+  lastName: string | null
+  linkedinUrl: string | null
+  title: string | null
+  headline: string | null
+  filterReason: string | null
+  openingLine: string | null
+  source: string | null
+  sourceId: string | null
+  pipelineStatus: ContactPipelineStatus | null
+  enrichmentData: ContactEnrichmentData | null
+  /** Attio Person record ID - set when contact responds and is added to CRM */
+  attioPersonId: string | null
+  batchId: string | null
+  status: 'active' | 'invalid'
+  createdAt: Date
+  updatedAt: Date
+}
+```
+
+### `DealStage`
+
+```typescript
+export type DealStage = 'interested' | 'proposal' | 'closing' | 'closed_won' | 'closed_lost' | 'nurturing'
+```
+
+### `KanbanStageConfig`
+
+```typescript
+export interface KanbanStageConfig {
+  color: string // Mantine color token (e.g. 'blue', 'teal')
+  label?: string // Optional display label override
+}
+```
+
+### `KanbanBoardConfig`
+
+```typescript
+export type KanbanBoardConfig = Partial<Record<DealStage, KanbanStageConfig>>
+```
+
+### `DealContact`
+
+```typescript
+export interface DealContact {
+  id: string
+  first_name: string | null
+  last_name: string | null
+  email: string
+  title: string | null
+  headline: string | null
+  linkedin_url: string | null
+  pipeline_status: Record<string, unknown> | null
+  enrichment_data: Record<string, unknown> | null
+  company: {
+    id: string
+    name: string
+    domain: string | null
+    website: string | null
+    linkedin_url: string | null
+    segment: string | null
+    category: string | null
+    num_employees: number | null
+  } | null
+}
+```
+
+### `DealFilters`
+
+```typescript
+export interface DealFilters {
+  stage?: DealStage
+  search?: string
+  limit?: number
+  offset?: number
+}
+```
+
+### `DealListItem`
+
+```typescript
+/** Deal list item with joined contact and company data */
+export interface DealListItem extends AcqDealRow {
+  contact: DealContact | null
+}
+```
+
+### `DealDetail`
+
+```typescript
+export type DealDetail = DealListItem
+```
+
+### `AcqDealTaskKind`
+
+```typescript
+/** Task kind options for a deal task (human follow-up action type) */
+export type AcqDealTaskKind = 'call' | 'email' | 'meeting' | 'other'
+```
+
+### `AcqDealTask`
+
+```typescript
+/**
+ * A CRM to-do item attached to a deal representing a human follow-up action.
+ * Transformed from AcqDealTaskRow with camelCase properties.
+ */
+export interface AcqDealTask {
+  id: string
+  organizationId: string
+  dealId: string
+  title: string
+  description: string | null
+  kind: AcqDealTaskKind
+  dueAt: string | null
+  assigneeUserId: string | null
+  completedAt: string | null
+  completedByUserId: string | null
+  createdAt: string
+  updatedAt: string
+  createdByUserId: string | null
+}
+```
+
+### `DealStageSchema`
+
+```typescript
+export const DealStageSchema = z.enum(['interested', 'proposal', 'closing', 'closed_won', 'closed_lost', 'nurturing'])
+```
+
+### `AcqDealTaskKindSchema`
+
+```typescript
+export const AcqDealTaskKindSchema = z.enum(['call', 'email', 'meeting', 'other'])
+```
+
+### `DealIdParamsSchema`
+
+```typescript
+export const DealIdParamsSchema = z.object({
+  dealId: UuidSchema
+})
+```
+
+### `DealTaskIdParamsSchema`
+
+```typescript
+export const DealTaskIdParamsSchema = z.object({
+  dealId: UuidSchema,
+  taskId: UuidSchema
+})
+```
+
+### `ListDealsQuerySchema`
+
+```typescript
+export const ListDealsQuerySchema = z
+  .object({
+    stage: DealStageSchema.optional(),
+    search: z.string().optional(),
+    limit: z.coerce.number().int().positive().default(50),
+    offset: z.coerce.number().int().min(0).default(0)
+  })
+  .strict()
+```
+
+### `DealLookupQuerySchema`
+
+```typescript
+export const DealLookupQuerySchema = z
+  .object({
+    search: z.string().trim().min(1).max(200).optional(),
+    limit: z.coerce.number().int().min(1).max(25).default(10)
+  })
+  .strict()
+```
+
+### `ListDealTasksDueQuerySchema`
+
+```typescript
+export const ListDealTasksDueQuerySchema = z
+  .object({
+    window: z.enum(['overdue', 'today', 'today_and_overdue', 'upcoming']).optional(),
+    assigneeUserId: UuidSchema.optional()
+  })
+  .strict()
+```
+
+### `CreateDealNoteRequestSchema`
+
+```typescript
+export const CreateDealNoteRequestSchema = z
+  .object({
+    body: z.string().trim().min(1).max(10000)
+  })
+  .strict()
+```
+
+### `CreateDealTaskRequestSchema`
+
+```typescript
+export const CreateDealTaskRequestSchema = z
+  .object({
+    title: z.string().trim().min(1).max(255),
+    description: z.string().nullable().optional(),
+    kind: AcqDealTaskKindSchema.optional(),
+    dueAt: z.string().datetime().nullable().optional(),
+    assigneeUserId: UuidSchema.nullable().optional()
+  })
+  .strict()
+```
+
+### `TransitionItemRequestSchema`
+
+```typescript
+export const TransitionItemRequestSchema = z
+  .object({
+    pipelineKey: z.string().min(1),
+    stageKey: z.string().min(1),
+    stateKey: z.string().nullable().optional(),
+    reason: z.string().optional(),
+    expectedUpdatedAt: z.string().datetime().optional()
+  })
+  .strict()
+```
+
+### `ExecuteActionParamsSchema`
+
+```typescript
+export const ExecuteActionParamsSchema = z
+  .object({
+    dealId: UuidSchema,
+    actionKey: NonEmptyStringSchema
+  })
+  .strict()
+```
+
+### `ExecuteActionRequestSchema`
+
+```typescript
+export const ExecuteActionRequestSchema = z
+  .object({
+    payload: z.record(z.string(), z.unknown()).optional()
+  })
+  .strict()
+```
+
+### `DealContactSummarySchema`
+
+```typescript
+/**
+ * Contact summary nested inside DealListItem / DealDetailResponse.
+ * Matches the joined shape returned by useDeals / useDealDetail Supabase queries.
+ */
+export const DealContactSummarySchema = z.object({
+  id: z.string(),
+  first_name: z.string().nullable(),
+  last_name: z.string().nullable(),
+  email: z.string(),
+  title: z.string().nullable(),
+  headline: z.string().nullable(),
+  linkedin_url: z.string().nullable(),
+  pipeline_status: z.record(z.string(), z.unknown()).nullable(),
+  enrichment_data: z.record(z.string(), z.unknown()).nullable(),
+  company: z
+    .object({
+      id: z.string(),
+      name: z.string(),
+      domain: z.string().nullable(),
+      website: z.string().nullable(),
+      linkedin_url: z.string().nullable(),
+      segment: z.string().nullable(),
+      category: z.string().nullable(),
+      num_employees: z.number().nullable()
+    })
+    .nullable()
+})
+```
+
+### `DealListItemSchema`
+
+```typescript
+/**
+ * Deal list item with joined contact (and company via contact).
+ * Matches DealListItem from @repo/core types.
+ */
+export const DealListItemSchema = z.object({
+  // acq_deals columns
+  id: z.string(),
+  organization_id: z.string(),
+  contact_id: z.string().nullable(),
+  contact_email: z.string(),
+  pipeline_key: z.string(),
+  stage_key: z.string().nullable(),
+  state_key: z.string().nullable(),
+  activity_log: z.unknown(),
+  discovery_data: z.unknown().nullable(),
+  discovery_submitted_at: z.string().nullable(),
+  discovery_submitted_by: z.string().nullable(),
+  proposal_data: z.unknown().nullable(),
+  proposal_sent_at: z.string().nullable(),
+  proposal_pdf_url: z.string().nullable(),
+  signature_envelope_id: z.string().nullable(),
+  source_list_id: z.string().nullable(),
+  source_type: z.string().nullable(),
+  initial_fee: z.number().nullable(),
+  monthly_fee: z.number().nullable(),
+  closed_lost_at: z.string().nullable(),
+  closed_lost_reason: z.string().nullable(),
+  created_at: z.string(),
+  updated_at: z.string(),
+  // joined relation
+  contact: DealContactSummarySchema.nullable()
+})
+```
+
+### `DealListResponseSchema`
+
+```typescript
+export const DealListResponseSchema = z.object({
+  data: z.array(DealListItemSchema),
+  total: z.number().int(),
+  limit: z.number().int(),
+  offset: z.number().int()
+})
+```
+
+### `DealDetailResponseSchema`
+
+```typescript
+/**
+ * Deal detail shape — currently the same as a list item (full joined record).
+ * useDealDetail returns DealDetail which is typed as DealListItem.
+ */
+export const DealDetailResponseSchema = DealListItemSchema
+```
+
+### `DealNoteResponseSchema`
+
+```typescript
+/**
+ * Single acq_deal_notes row (camelCase API representation).
+ */
+export const DealNoteResponseSchema = z.object({
+  id: z.string(),
+  dealId: z.string(),
+  organizationId: z.string(),
+  authorUserId: z.string().nullable(),
+  body: z.string(),
+  createdAt: z.string(),
+  updatedAt: z.string()
+})
+```
+
+### `DealNoteListResponseSchema`
+
+```typescript
+export const DealNoteListResponseSchema = z.array(DealNoteResponseSchema)
+```
+
+### `DealTaskResponseSchema`
+
+```typescript
+/**
+ * Single acq_deal_tasks row (camelCase API representation).
+ * Matches AcqDealTask domain type from types.ts.
+ */
+export const DealTaskResponseSchema = z.object({
+  id: z.string(),
+  organizationId: z.string(),
+  dealId: z.string(),
+  title: z.string(),
+  description: z.string().nullable(),
+  kind: AcqDealTaskKindSchema,
+  dueAt: z.string().nullable(),
+  assigneeUserId: z.string().nullable(),
+  completedAt: z.string().nullable(),
+  completedByUserId: z.string().nullable(),
+  createdAt: z.string(),
+  updatedAt: z.string(),
+  createdByUserId: z.string().nullable()
+})
+```
+
+### `DealTaskListResponseSchema`
+
+```typescript
+export const DealTaskListResponseSchema = z.array(DealTaskResponseSchema)
+```
+
+### `DealSchemas`
+
+```typescript
+export const DealSchemas = {
+  // Params
+  DealIdParams: DealIdParamsSchema,
+  DealTaskIdParams: DealTaskIdParamsSchema,
+
+  // Queries
+  ListDealsQuery: ListDealsQuerySchema,
+  DealLookupQuery: DealLookupQuerySchema,
+  ListDealTasksDueQuery: ListDealTasksDueQuerySchema,
+
+  // Request bodies
+  CreateDealNoteRequest: CreateDealNoteRequestSchema,
+  CreateDealTaskRequest: CreateDealTaskRequestSchema,
+  TransitionItemRequest: TransitionItemRequestSchema,
+  TransitionDealStateRequest: TransitionDealStateRequestSchema,
+  ExecuteActionParams: ExecuteActionParamsSchema,
+  ExecuteActionRequest: ExecuteActionRequestSchema,
+
+  // Responses
+  DealListResponse: DealListResponseSchema,
+  DealSummaryResponse: DealSummaryResponseSchema,
+  DealLookupResponse: DealLookupResponseSchema,
+  DealDetailResponse: DealDetailResponseSchema,
+  DealNoteResponse: DealNoteResponseSchema,
+  DealNoteListResponse: DealNoteListResponseSchema,
+  DealTaskResponse: DealTaskResponseSchema,
+  DealTaskListResponse: DealTaskListResponseSchema
+}
+```
+
+### `Action`
+
+```typescript
+export interface Action {
+  key: string
+  label: string
+  payloadSchema?: z.ZodTypeAny
+}
+```
+
+### `ActionDef`
+
+```typescript
+export interface ActionDef {
+  key: string
+  label: string
+  isAvailableFor: (deal: AcqDealRow) => boolean
+  workflowId: string
+  payloadSchema?: z.ZodTypeAny
+}
+```
+
+### `DEFAULT_CRM_ACTIONS`
+
+```typescript
+export const DEFAULT_CRM_ACTIONS: ActionDef[] = [
+  {
+    key: 'move_to_proposal',
+    label: 'Move to Proposal',
+    isAvailableFor: (deal) => deal.stage_key === 'interested',
+    workflowId: 'move_to_proposal-workflow'
+  },
+  {
+    key: 'move_to_closing',
+    label: 'Move to Closing',
+    isAvailableFor: (deal) => deal.stage_key === 'proposal',
+    workflowId: 'move_to_closing-workflow'
+  },
+  {
+    key: 'move_to_closed_won',
+    label: 'Close Won',
+    isAvailableFor: (deal) => deal.stage_key === 'closing',
+    workflowId: 'move_to_closed_won-workflow'
+  },
+  {
+    key: 'move_to_closed_lost',
+    label: 'Close Lost',
+    isAvailableFor: (deal) =>
+      deal.stage_key === 'interested' || deal.stage_key === 'proposal' || deal.stage_key === 'closing',
+    workflowId: 'move_to_closed_lost-workflow'
+  },
+  {
+    key: 'move_to_nurturing',
+    label: 'Move to Nurturing',
+    isAvailableFor: (deal) =>
+      deal.stage_key === 'interested' || deal.stage_key === 'proposal' || deal.stage_key === 'closing',
+    workflowId: 'move_to_nurturing-workflow'
+  },
+  {
+    key: 'send_reply',
+    label: 'Send Reply',
+    isAvailableFor: (deal) =>
+      deal.stage_key === 'interested' &&
+      (deal.state_key === CRM_DISCOVERY_REPLIED_STATE.stateKey ||
+        deal.state_key === CRM_DISCOVERY_LINK_SENT_STATE.stateKey ||
+        deal.state_key === CRM_DISCOVERY_NUDGING_STATE.stateKey),
+    workflowId: 'crm-send-reply-workflow',
+    payloadSchema: SendReplyActionPayloadSchema
+  },
+  {
+    key: 'send_link',
+    label: 'Send Booking Link',
+    isAvailableFor: (deal) =>
+      deal.stage_key === 'interested' && deal.state_key === CRM_DISCOVERY_REPLIED_STATE.stateKey,
+    workflowId: 'crm-send-booking-link-workflow'
+  },
+  {
+    key: 'send_nudge',
+    label: 'Send Nudge',
+    isAvailableFor: (deal) =>
+      deal.stage_key === 'interested' &&
+      (deal.state_key === CRM_DISCOVERY_LINK_SENT_STATE.stateKey ||
+        deal.state_key === CRM_DISCOVERY_NUDGING_STATE.stateKey),
+    workflowId: 'crm-send-nudge-workflow'
+  },
+  {
+    key: 'mark_no_show',
+    label: 'Mark No-Show',
+    isAvailableFor: (deal) =>
+      deal.stage_key === 'interested' && deal.state_key === CRM_DISCOVERY_NUDGING_STATE.stateKey,
+    // Mirrors the auto-timeout precedent in operations/sales/crm/pipeline/timeout-actions.ts:
+    // both manual-click and timeout move the deal to closed_lost. The action_taken activity
+    // event captures operator intent and distinguishes the manual variant from the timed one.
+    workflowId: 'mark_no_show-workflow'
+  },
+  {
+    key: 'rebook',
+    label: 'Rebook',
+    isAvailableFor: (deal) =>
+      deal.stage_key === 'interested' && deal.state_key === CRM_DISCOVERY_BOOKING_CANCELLED_STATE.stateKey,
+    workflowId: 'crm-rebook-workflow'
+  }
+]
+```
+
+### `CrmToolMap`
+
+```typescript
+export type CrmToolMap = {
+  getRecentActivity: { params: CrmRecentActivityParams; result: RecentActivityEntry[] }
+  listDeals: { params: CrmListDealsParams; result: DealListItem[] }
+  getDeal: { params: CrmGetDealParams; result: DealDetail | null }
+  getDealByEmail: { params: CrmGetDealByEmailParams; result: DealDetail | null }
+  createDealNote: { params: CrmDealNoteParams; result: AcqDealNote }
+  listDealNotes: { params: Omit<ListDealNotesParams, 'organizationId'>; result: AcqDealNote[] }
+  createDealTask: { params: CrmDealTaskParams; result: AcqDealTask }
+  listDealTasks: { params: Omit<ListDealTasksParams, 'organizationId'>; result: AcqDealTask[] }
+  listDealTasksDue: { params: CrmTaskDueParams; result: AcqDealTask[] }
+  completeDealTask: { params: Omit<CompleteDealTaskParams, 'organizationId'>; result: AcqDealTask }
+  recordActivity: { params: CrmRecordActivityParams; result: void }
+  deleteDeal: { params: CrmDeleteDealParams; result: void }
+}
+```
+
+## Lead Gen Platform Primitives
+
+### `WebPost`
+
+```typescript
+/**
+ * Represents a web post from company website scraping.
+ * Used for recent blog posts, news, or announcements.
+ */
+export interface WebPost {
+  /** ISO date string of when the post was published */
+  date: string
+  /** Title of the web post */
+  title: string
+  /** Brief summary of the post content */
+  summary: string
+  /** AI-generated insight about the post's relevance */
+  aiInsight?: string
+}
+```
+
+### `CompanyPipelineStatus`
+
+```typescript
+/**
+ * Tracks pipeline status for a company across all processing stages.
+ */
+export interface CompanyPipelineStatus {
+  acquired: boolean
+  enrichment: {
+    [source: string]: {
+      status: 'pending' | 'complete' | 'failed' | 'skipped'
+      completedAt?: string
+      error?: string
+    }
+  }
+}
+```
+
+### `ContactPipelineStatus`
+
+```typescript
+/**
+ * Tracks pipeline status for a contact across all processing stages.
+ */
+export interface ContactPipelineStatus {
+  enrichment: {
+    [source: string]: {
+      status: 'pending' | 'complete' | 'failed' | 'skipped'
+      completedAt?: string
+      error?: string
+    }
+  }
+  personalization: {
+    status: 'pending' | 'complete' | 'failed' | 'skipped'
+    completedAt?: string
+  }
+  outreach: {
+    status: 'pending' | 'sent' | 'replied' | 'bounced' | 'opted-out'
+    sentAt?: string
+    channel?: string
+    campaignId?: string
+  }
+}
+```
+
+### `CompanyEnrichmentData`
+
+```typescript
+/**
+ * Enrichment data collected for a company from various sources.
+ */
+export interface CompanyEnrichmentData {
+  googleMaps?: {
+    placeId?: string
+    totalScore?: number
+    reviewsCount?: number
+    address?: string
+    phone?: string
+    categoryName?: string
+    googleMapsUrl?: string
+    scrapedAt?: string
+  }
+  websiteCrawl?: {
+    companyDescription?: string
+    services?: string[]
+    specialties?: string[]
+    staff?: Array<{ name: string; title?: string; email?: string }>
+    automationGaps?: string[]
+    targetAudience?: string
+    category?: string
+    segment?: string
+    recentWin?: string
+    emailCount?: number
+    pageCount?: number
+    totalChars?: number
+    crawledAt?: string
+    extractedAt?: string
+  }
+  website?: {
+    missionVision?: string
+    uniqueAttributes?: string
+    coreOfferings?: string
+    targetAudience?: string
+    companyValues?: string
+    businessDescription?: string
+    recentPosts?: Array<{ date?: string; title?: string; summary?: string; aiInsight?: string }>
+  }
+  tomba?: {
+    waterfallEmail?: {
+      email: string
+      name?: string
+      title?: string
+      department?: string
+    } | null
+    genericEmail?: string | null
+    totalFound?: number
+    searchedAt?: string
+  }
+}
+```
+
+### `ContactEnrichmentData`
+
+```typescript
+/**
+ * Enrichment data collected for a contact from various sources.
+ */
+export interface ContactEnrichmentData {
+  linkedin?: {
+    summary?: string
+    pastExperience?: string
+    education?: string
+    activity?: Array<{ date?: string; content?: string }>
+  }
+}
+```
+
+### `AcqList`
+
+```typescript
+export interface AcqList {
+  id: string
+  organizationId: string
+  name: string
+  description: string | null
+  batchIds: string[]
+  instantlyCampaignId: string | null
+  status: ListStatus
+  scrapingConfig: ScrapingConfig
+  icp: IcpRubric
+  pipelineConfig: PipelineConfig
+  metadata: Record<string, unknown>
+  launchedAt: Date | null
+  completedAt: Date | null
+  createdAt: Date
+}
+```
+
+### `AcqCompany`
+
+```typescript
+/**
+ * Company record in the acquisition database.
+ * Contains enriched company data from various sources.
+ * Transformed from AcqCompanyRow with camelCase properties.
+ */
+export interface AcqCompany {
+  id: string
+  organizationId: string
+  name: string
+  domain: string | null
+  linkedinUrl: string | null
+  website: string | null
+  numEmployees: number | null
+  foundedYear: number | null
+  locationCity: string | null
+  locationState: string | null
+  category: string | null
+  categoryPain: string | null
+  segment: string | null
+  pipelineStatus: CompanyPipelineStatus | null
+  enrichmentData: CompanyEnrichmentData | null
+  source: string | null
+  batchId: string | null
+  status: 'active' | 'invalid'
+  verticalResearch: string | null
+  /** Track A: flat qualification score (null until a scoring rubric is defined). Added by W1 migration. */
+  qualificationScore: number | null
+  /** Track A: flat qualification signals jsonb preserving the result payload shape. Added by W1 migration. */
+  qualificationSignals: Record<string, unknown> | null
+  /** Track A: key identifying the rubric used for qualification. Added by W1 migration. */
+  qualificationRubricKey: string | null
+  createdAt: Date
+  updatedAt: Date
+}
+```
+
+### `AcqContact`
+
+```typescript
+/**
+ * Contact record in the acquisition database.
+ * Contains enriched contact data and personalization content.
+ * Transformed from AcqContactRow with camelCase properties.
+ */
+export interface AcqContact {
+  id: string
+  organizationId: string
+  companyId: string | null
+  email: string
+  emailValid: 'VALID' | 'INVALID' | 'RISKY' | 'UNKNOWN' | null
+  firstName: string | null
+  lastName: string | null
+  linkedinUrl: string | null
+  title: string | null
+  headline: string | null
+  filterReason: string | null
+  openingLine: string | null
+  source: string | null
+  sourceId: string | null
+  pipelineStatus: ContactPipelineStatus | null
+  enrichmentData: ContactEnrichmentData | null
+  /** Attio Person record ID - set when contact responds and is added to CRM */
+  attioPersonId: string | null
+  batchId: string | null
+  status: 'active' | 'invalid'
+  createdAt: Date
+  updatedAt: Date
+}
+```
+
+### `ListTelemetry`
+
+```typescript
+/**
+ * Live-scan aggregate telemetry for a single list, computed on demand from
+ * the list junction tables and current contact deliverability state.
+ * `stageCounts` are attempted counts from list-row processing_state.
+ */
+export interface ListTelemetry {
+  listId: string
+  totalCompanies: number
+  totalContacts: number
+  stageCounts: {
+    populated: number
+    extracted: number
+    qualified: number
+    discovered: number
+    verified: number
+    personalized: number
+    uploaded: number
+  }
+  deliverability: {
+    valid: number
+    risky: number
+    invalid: number
+    unknown: number
+    bounced: number
+  }
+  /** Reserved -- active workflow IDs associated with this list. */
+  activeWorkflows?: string[]
+}
+```
+
+### `ListStageCountsSchema`
+
+```typescript
+export const ListStageCountsSchema = z.object({
+  // Attempted counts by canonical lead-gen stage. The detailed status
+  // distribution lives on ListProgress; telemetry keeps the overview payload small.
+  stageCounts: z.object({
+    populated: z.number().int(),
+    extracted: z.number().int(),
+    qualified: z.number().int(),
+    discovered: z.number().int(),
+    verified: z.number().int(),
+    personalized: z.number().int(),
+    uploaded: z.number().int()
+  }),
+  deliverability: z.object({
+    valid: z.number().int(),
+    risky: z.number().int(),
+    invalid: z.number().int(),
+    unknown: z.number().int(),
+    bounced: z.number().int()
+  })
+})
+```
+
+### `ListTelemetrySchema`
+
+```typescript
+export const ListTelemetrySchema = z.object({
+  listId: UuidSchema,
+  totalCompanies: z.number().int(),
+  totalContacts: z.number().int(),
+  stageCounts: ListStageCountsSchema.shape.stageCounts,
+  deliverability: ListStageCountsSchema.shape.deliverability,
+  activeWorkflows: z.array(z.string()).optional()
+})
+```
+
+### `ListIdParamsSchema`
+
+```typescript
+export const ListIdParamsSchema = z.object({
+  listId: UuidSchema
+})
+```
+
+### `CreateListRequestSchema`
+
+```typescript
+export const CreateListRequestSchema = z
+  .object({
+    name: z.string().trim().min(1).max(255),
+    description: z.string().trim().nullable().optional(),
+    status: ListStatusSchema.optional(),
+    scrapingConfig: ScrapingConfigSchema.optional(),
+    icp: IcpRubricSchema.optional(),
+    pipelineConfig: PipelineConfigSchema.optional()
+  })
+  .strict()
+```
+
+### `UpdateListRequestSchema`
+
+```typescript
+export const UpdateListRequestSchema = z
+  .object({
+    name: z.string().trim().min(1).max(255).optional(),
+    description: z.string().trim().nullable().optional(),
+    batchIds: z.array(z.string()).optional()
+  })
+  .strict()
+  .refine((data) => data.name !== undefined || data.description !== undefined || data.batchIds !== undefined, {
+    message: 'At least one field (name, description, or batchIds) must be provided'
+  })
+```
+
+### `UpdateListConfigRequestSchema`
+
+```typescript
+/**
+ * Partial patch for the three jsonb config columns. UI sends only the edited
+ * subtree; server writes the field as-is (no deep merge — each column is
+ * replaced atomically when present in the patch).
+ */
+export const UpdateListConfigRequestSchema = z
+  .object({
+    scrapingConfig: ScrapingConfigSchema.partial().optional(),
+    icp: IcpRubricSchema.partial().optional(),
+    pipelineConfig: PipelineConfigSchema.partial().optional()
+  })
+  .strict()
+  .refine((data) => data.scrapingConfig !== undefined || data.icp !== undefined || data.pipelineConfig !== undefined, {
+    message: 'At least one of scrapingConfig, icp, or pipelineConfig must be provided'
+  })
+```
+
+### `AddCompaniesToListRequestSchema`
+
+```typescript
+export const AddCompaniesToListRequestSchema = z
+  .object({
+    companyIds: z.array(UuidSchema).min(1).max(1000)
+  })
+  .strict()
+```
+
+### `RemoveCompaniesFromListRequestSchema`
+
+```typescript
+export const RemoveCompaniesFromListRequestSchema = z
+  .object({
+    companyIds: z.array(UuidSchema).min(1).max(1000)
+  })
+  .strict()
+```
+
+### `AddContactsToListRequestSchema`
+
+```typescript
+export const AddContactsToListRequestSchema = z
+  .object({
+    contactIds: z.array(UuidSchema).min(1).max(1000)
+  })
+  .strict()
+```
+
+### `RecordListExecutionRequestSchema`
+
+```typescript
+export const RecordListExecutionRequestSchema = z
+  .object({
+    executionId: UuidSchema,
+    configSnapshot: z.record(z.string(), z.unknown()).optional()
+  })
+  .strict()
+```
+
+### `AcqListResponseSchema`
+
+```typescript
+/**
+ * Single list as returned by /api/acquisition/lists/:id etc.
+ * Camel-cased domain shape matching AcqList in types.ts.
+ */
+export const AcqListResponseSchema = z.object({
+  id: z.string(),
+  organizationId: z.string(),
+  name: z.string(),
+  description: z.string().nullable(),
+  type: z.string(),
+  batchIds: z.array(z.string()),
+  instantlyCampaignId: z.string().nullable(),
+  /** Lifecycle status (draft | enriching | launched | closing | archived). */
+  status: ListStatusSchema,
+  metadata: z.record(z.string(), z.unknown()),
+  launchedAt: z.string().nullable(),
+  completedAt: z.string().nullable(),
+  createdAt: z.string(),
+  /** Scraping criteria stored as jsonb on the row. */
+  scrapingConfig: ScrapingConfigSchema,
+  /** ICP / qualification rubric stored as jsonb on the row. */
+  icp: IcpRubricSchema,
+  /** Pipeline presentation contract stored as jsonb on the row. */
+  pipelineConfig: PipelineConfigSchema
+})
+```
+
+### `AcqListListResponseSchema`
+
+```typescript
+export const AcqListListResponseSchema = z.array(AcqListResponseSchema)
+```
+
+### `ListTelemetryResponseSchema`
+
+```typescript
+export const ListTelemetryResponseSchema = ListTelemetrySchema
+```
+
+### `ListTelemetryListResponseSchema`
+
+```typescript
+export const ListTelemetryListResponseSchema = z.array(ListTelemetrySchema)
+```
+
+### `ListExecutionSummarySchema`
+
+```typescript
+/**
+ * Row from acq_list_executions joined with the execution summary,
+ * shaped for the /lists/:id/executions response.
+ */
+export const ListExecutionSummarySchema = z.object({
+  executionId: z.string(),
+  resourceId: z.string(),
+  status: z.string(),
+  createdAt: z.string(),
+  completedAt: z.string().nullable(),
+  durationMs: z.number().int().nullable()
+})
+```
+
+### `ListExecutionsResponseSchema`
+
+```typescript
+export const ListExecutionsResponseSchema = z.array(ListExecutionSummarySchema)
+```
+
+### `AcqCompanyStatusSchema`
+
+```typescript
+export const AcqCompanyStatusSchema = z.enum(['active', 'invalid'])
+```
+
+### `AcqContactStatusSchema`
+
+```typescript
+export const AcqContactStatusSchema = z.enum(['active', 'invalid'])
+```
+
+### `AcqEmailValidSchema`
+
+```typescript
+export const AcqEmailValidSchema = z.enum(['VALID', 'INVALID', 'RISKY', 'UNKNOWN'])
+```
+
+### `CompanyIdParamsSchema`
+
+```typescript
+export const CompanyIdParamsSchema = z.object({
+  companyId: UuidSchema
+})
+```
+
+### `ContactIdParamsSchema`
+
+```typescript
+export const ContactIdParamsSchema = z.object({
+  contactId: UuidSchema
+})
+```
+
+### `ListCompaniesQuerySchema`
+
+```typescript
+export const ListCompaniesQuerySchema = z
+  .object({
+    search: z.string().trim().min(1).max(200).optional(),
+    listId: UuidSchema.optional(),
+    domain: z.string().trim().min(1).max(255).optional(),
+    website: z.string().trim().min(1).max(2048).optional(),
+    segment: z.string().trim().min(1).max(255).optional(),
+    category: z.string().trim().min(1).max(255).optional(),
+    batchId: z.string().trim().min(1).max(255).optional(),
+    status: AcqCompanyStatusSchema.optional(),
+    includeAll: QueryBooleanSchema.optional(),
+    limit: z.coerce.number().int().min(1).max(5000).default(50),
+    offset: z.coerce.number().int().min(0).default(0)
+  })
+  .strict()
+```
+
+### `ListContactsQuerySchema`
+
+```typescript
+export const ListContactsQuerySchema = z
+  .object({
+    search: z.string().trim().min(1).max(200).optional(),
+    listId: UuidSchema.optional(),
+    openingLineIsNull: QueryBooleanSchema.optional(),
+    batchId: z.string().trim().min(1).max(255).optional(),
+    contactStatus: AcqContactStatusSchema.optional(),
+    limit: z.coerce.number().int().min(1).max(5000).default(5000),
+    offset: z.coerce.number().int().min(0).default(0)
+  })
+  .strict()
+```
+
+### `CreateCompanyRequestSchema`
+
+```typescript
+export const CreateCompanyRequestSchema = z
+  .object({
+    name: z.string().trim().min(1).max(255),
+    domain: z.string().trim().min(1).max(255).optional(),
+    linkedinUrl: z.string().trim().url().optional(),
+    website: z.string().trim().url().optional(),
+    numEmployees: z.number().int().min(0).optional(),
+    foundedYear: z.number().int().optional(),
+    locationCity: z.string().trim().min(1).max(255).optional(),
+    locationState: z.string().trim().min(1).max(255).optional(),
+    category: z.string().trim().min(1).max(255).optional(),
+    source: z.string().trim().min(1).max(255).optional(),
+    batchId: z.string().trim().min(1).max(255).optional(),
+    verticalResearch: z.string().trim().min(1).max(5000).optional()
+  })
+  .strict()
+```
+
+### `UpdateCompanyRequestSchema`
+
+```typescript
+export const UpdateCompanyRequestSchema = z
+  .object({
+    name: z.string().trim().min(1).max(255).optional(),
+    domain: z.string().trim().min(1).max(255).optional(),
+    linkedinUrl: z.string().trim().url().optional(),
+    website: z.string().trim().url().optional(),
+    numEmployees: z.number().int().min(0).optional(),
+    foundedYear: z.number().int().optional(),
+    locationCity: z.string().trim().min(1).max(255).optional(),
+    locationState: z.string().trim().min(1).max(255).optional(),
+    category: z.string().trim().min(1).max(255).optional(),
+    segment: z.string().trim().min(1).max(255).optional(),
+    pipelineStatus: z.record(z.string(), z.unknown()).optional(),
+    enrichmentData: z.record(z.string(), z.unknown()).optional(),
+    source: z.string().trim().min(1).max(255).optional(),
+    batchId: z.string().trim().min(1).max(255).optional(),
+    status: AcqCompanyStatusSchema.optional(),
+    verticalResearch: z.string().trim().min(1).max(5000).nullable().optional()
+  })
+  .strict()
+  .refine(
+    (data) =>
+      data.name !== undefined ||
+      data.domain !== undefined ||
+      data.linkedinUrl !== undefined ||
+      data.website !== undefined ||
+      data.numEmployees !== undefined ||
+      data.foundedYear !== undefined ||
+      data.locationCity !== undefined ||
+      data.locationState !== undefined ||
+      data.category !== undefined ||
+      data.segment !== undefined ||
+      data.pipelineStatus !== undefined ||
+      data.enrichmentData !== undefined ||
+      data.source !== undefined ||
+      data.batchId !== undefined ||
+      data.status !== undefined ||
+      data.verticalResearch !== undefined,
+    {
+      message: 'At least one field must be provided'
+    }
+  )
+```
+
+### `CreateContactRequestSchema`
+
+```typescript
+export const CreateContactRequestSchema = z
+  .object({
+    email: z.string().trim().email(),
+    companyId: UuidSchema.optional(),
+    firstName: z.string().trim().min(1).max(255).optional(),
+    lastName: z.string().trim().min(1).max(255).optional(),
+    linkedinUrl: z.string().trim().url().optional(),
+    title: z.string().trim().min(1).max(255).optional(),
+    source: z.string().trim().min(1).max(255).optional(),
+    sourceId: z.string().trim().min(1).max(255).optional(),
+    batchId: z.string().trim().min(1).max(255).optional()
+  })
+  .strict()
+```
+
+### `UpdateContactRequestSchema`
+
+```typescript
+export const UpdateContactRequestSchema = z
+  .object({
+    companyId: UuidSchema.optional(),
+    emailValid: AcqEmailValidSchema.optional(),
+    firstName: z.string().trim().min(1).max(255).optional(),
+    lastName: z.string().trim().min(1).max(255).optional(),
+    linkedinUrl: z.string().trim().url().optional(),
+    title: z.string().trim().min(1).max(255).optional(),
+    headline: z.string().trim().min(1).max(5000).optional(),
+    filterReason: z.string().trim().min(1).max(5000).optional(),
+    openingLine: z.string().trim().min(1).max(5000).optional(),
+    pipelineStatus: z.record(z.string(), z.unknown()).optional(),
+    enrichmentData: z.record(z.string(), z.unknown()).optional(),
+    status: AcqContactStatusSchema.optional()
+  })
+  .strict()
+  .refine(
+    (data) =>
+      data.companyId !== undefined ||
+      data.emailValid !== undefined ||
+      data.firstName !== undefined ||
+      data.lastName !== undefined ||
+      data.linkedinUrl !== undefined ||
+      data.title !== undefined ||
+      data.headline !== undefined ||
+      data.filterReason !== undefined ||
+      data.openingLine !== undefined ||
+      data.pipelineStatus !== undefined ||
+      data.enrichmentData !== undefined ||
+      data.status !== undefined,
+    {
+      message: 'At least one field must be provided'
+    }
+  )
+```
+
+### `AcqCompanyResponseSchema`
+
+```typescript
+export const AcqCompanyResponseSchema = z.object({
+  id: z.string(),
+  organizationId: z.string(),
+  name: z.string(),
+  domain: z.string().nullable(),
+  linkedinUrl: z.string().nullable(),
+  website: z.string().nullable(),
+  numEmployees: z.number().nullable(),
+  foundedYear: z.number().nullable(),
+  locationCity: z.string().nullable(),
+  locationState: z.string().nullable(),
+  category: z.string().nullable(),
+  categoryPain: z.string().nullable(),
+  segment: z.string().nullable(),
+  pipelineStatus: z.record(z.string(), z.unknown()).nullable(),
+  enrichmentData: z.record(z.string(), z.unknown()).nullable(),
+  source: z.string().nullable(),
+  batchId: z.string().nullable(),
+  status: AcqCompanyStatusSchema,
+  contactCount: z.number().int().min(0),
+  verticalResearch: z.string().nullable(),
+  createdAt: z.string(),
+  updatedAt: z.string()
+})
+```
+
+### `AcqCompanyListResponseSchema`
+
+```typescript
+export const AcqCompanyListResponseSchema = z.object({
+  data: z.array(AcqCompanyResponseSchema),
+  total: z.number().int(),
+  limit: z.number().int(),
+  offset: z.number().int()
+})
+```
+
+### `AcqCompanyFacetsResponseSchema`
+
+```typescript
+export const AcqCompanyFacetsResponseSchema = z.object({
+  segments: z.array(z.string()),
+  categories: z.array(z.string()),
+  statuses: z.array(AcqCompanyStatusSchema)
+})
+```
+
+### `AcqContactCompanySummarySchema`
+
+```typescript
+export const AcqContactCompanySummarySchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  domain: z.string().nullable(),
+  website: z.string().nullable(),
+  linkedinUrl: z.string().nullable(),
+  segment: z.string().nullable(),
+  category: z.string().nullable(),
+  status: AcqCompanyStatusSchema
+})
+```
+
+### `AcqContactResponseSchema`
+
+```typescript
+export const AcqContactResponseSchema = z.object({
+  id: z.string(),
+  organizationId: z.string(),
+  companyId: z.string().nullable(),
+  email: z.string(),
+  emailValid: AcqEmailValidSchema.nullable(),
+  firstName: z.string().nullable(),
+  lastName: z.string().nullable(),
+  linkedinUrl: z.string().nullable(),
+  title: z.string().nullable(),
+  headline: z.string().nullable(),
+  filterReason: z.string().nullable(),
+  openingLine: z.string().nullable(),
+  source: z.string().nullable(),
+  sourceId: z.string().nullable(),
+  pipelineStatus: z.record(z.string(), z.unknown()).nullable(),
+  enrichmentData: z.record(z.string(), z.unknown()).nullable(),
+  attioPersonId: z.string().nullable(),
+  batchId: z.string().nullable(),
+  status: AcqContactStatusSchema,
+  company: AcqContactCompanySummarySchema.nullable().optional(),
+  createdAt: z.string(),
+  updatedAt: z.string()
+})
+```
+
+### `AcqContactListResponseSchema`
+
+```typescript
+export const AcqContactListResponseSchema = z.object({
+  data: z.array(AcqContactResponseSchema),
+  total: z.number().int(),
+  limit: z.number().int(),
+  offset: z.number().int()
+})
+```
+
+### `AcqArtifactOwnerKindSchema`
+
+```typescript
+export const AcqArtifactOwnerKindSchema = z.enum(['company', 'contact', 'deal', 'list', 'list_member'])
+```
+
+### `ListArtifactsQuerySchema`
+
+```typescript
+export const ListArtifactsQuerySchema = z
+  .object({
+    ownerKind: AcqArtifactOwnerKindSchema,
+    ownerId: UuidSchema
+  })
+  .strict()
+```
+
+### `CreateArtifactRequestSchema`
+
+```typescript
+export const CreateArtifactRequestSchema = z
+  .object({
+    ownerKind: AcqArtifactOwnerKindSchema,
+    ownerId: UuidSchema,
+    kind: z.string().trim().min(1).max(255),
+    content: z.record(z.string(), z.unknown()),
+    sourceExecutionId: UuidSchema.optional()
+  })
+  .strict()
+```
+
+### `AcqArtifactResponseSchema`
+
+```typescript
+export const AcqArtifactResponseSchema = z.object({
+  id: z.string(),
+  organizationId: z.string(),
+  ownerKind: z.string(),
+  ownerId: z.string(),
+  kind: z.string(),
+  content: z.record(z.string(), z.unknown()),
+  sourceExecutionId: z.string().nullable(),
+  createdBy: z.string().nullable(),
+  createdAt: z.string(),
+  version: z.number().int()
+})
+```
+
+### `AcqArtifactListResponseSchema`
+
+```typescript
+export const AcqArtifactListResponseSchema = z.object({
+  artifacts: z.array(AcqArtifactResponseSchema)
+})
+```
+
+### `ListMembersQuerySchema`
+
+```typescript
+export const ListMembersQuerySchema = z
+  .object({
+    limit: z.coerce.number().int().min(1).max(500).default(50),
+    offset: z.coerce.number().int().min(0).default(0)
+  })
+  .strict()
+```
+
+### `MemberIdParamsSchema`
+
+```typescript
+export const MemberIdParamsSchema = z.object({
+  memberId: UuidSchema
+})
+```
+
+### `AcqListMemberContactSummarySchema`
+
+```typescript
+export const AcqListMemberContactSummarySchema = z.object({
+  id: z.string(),
+  email: z.string(),
+  firstName: z.string().nullable(),
+  lastName: z.string().nullable(),
+  title: z.string().nullable(),
+  linkedinUrl: z.string().nullable(),
+  companyId: z.string().nullable()
+})
+```
+
+### `AcqListMemberResponseSchema`
+
+```typescript
+export const AcqListMemberResponseSchema = z.object({
+  id: z.string(),
+  listId: z.string(),
+  contactId: z.string(),
+  pipelineKey: z.string(),
+  stageKey: z.string(),
+  stateKey: z.string(),
+  activityLog: z.unknown(),
+  addedAt: z.string(),
+  addedBy: z.string().nullable(),
+  sourceExecutionId: z.string().nullable(),
+  contact: AcqListMemberContactSummarySchema.nullable()
+})
+```
+
+### `AcqListMembersResponseSchema`
+
+```typescript
+export const AcqListMembersResponseSchema = z.object({
+  members: z.array(AcqListMemberResponseSchema)
+})
+```
+
+### `ListCompanyIdParamsSchema`
+
+```typescript
+export const ListCompanyIdParamsSchema = z.object({
+  listCompanyId: UuidSchema
+})
+```
+
+### `AcqListCompanyResponseSchema`
+
+```typescript
+export const AcqListCompanyResponseSchema = z.object({
+  id: z.string(),
+  listId: z.string(),
+  companyId: z.string(),
+  pipelineKey: z.string(),
+  stageKey: z.string(),
+  stateKey: z.string(),
+  activityLog: z.unknown(),
+  addedAt: z.string(),
+  addedBy: z.string().nullable(),
+  sourceExecutionId: z.string().nullable()
+})
+```
+
+### `AcqCompanySchemas`
+
+```typescript
+export const AcqCompanySchemas = {
+  CompanyIdParams: CompanyIdParamsSchema,
+  ListCompaniesQuery: ListCompaniesQuerySchema,
+  CreateCompanyRequest: CreateCompanyRequestSchema,
+  UpdateCompanyRequest: UpdateCompanyRequestSchema,
+  AcqCompanyResponse: AcqCompanyResponseSchema,
+  AcqCompanyListResponse: AcqCompanyListResponseSchema,
+  AcqCompanyFacetsResponse: AcqCompanyFacetsResponseSchema
+}
+```
+
+### `AcqContactSchemas`
+
+```typescript
+export const AcqContactSchemas = {
+  ContactIdParams: ContactIdParamsSchema,
+  ListContactsQuery: ListContactsQuerySchema,
+  CreateContactRequest: CreateContactRequestSchema,
+  UpdateContactRequest: UpdateContactRequestSchema,
+  AcqContactResponse: AcqContactResponseSchema,
+  AcqContactListResponse: AcqContactListResponseSchema
+}
+```
+
+### `AcqListSchemas`
+
+```typescript
+export const AcqListSchemas = {
+  // Params
+  ListIdParams: ListIdParamsSchema,
+
+  // Primitives (for UI / tests)
+  ListStatus: ListStatusSchema,
+  ScrapingConfig: ScrapingConfigSchema,
+  IcpRubric: IcpRubricSchema,
+  PipelineConfig: PipelineConfigSchema,
+  PipelineStage: PipelineStageSchema,
+  ProcessingStageStatus: ProcessingStageStatusSchema,
+  ListStageCounts: ListStageCountsSchema,
+  ListTelemetry: ListTelemetrySchema,
+
+  // Requests
+  CreateListRequest: CreateListRequestSchema,
+  UpdateListRequest: UpdateListRequestSchema,
+  UpdateListStatusRequest: UpdateListStatusRequestSchema,
+  UpdateListConfigRequest: UpdateListConfigRequestSchema,
+  AddCompaniesToListRequest: AddCompaniesToListRequestSchema,
+  RemoveCompaniesFromListRequest: RemoveCompaniesFromListRequestSchema,
+  AddContactsToListRequest: AddContactsToListRequestSchema,
+  RecordListExecutionRequest: RecordListExecutionRequestSchema,
+
+  // Responses
+  AcqListResponse: AcqListResponseSchema,
+  AcqListListResponse: AcqListListResponseSchema,
+  ListTelemetryResponse: ListTelemetryResponseSchema,
+  ListTelemetryListResponse: ListTelemetryListResponseSchema,
+  ListExecutionsResponse: ListExecutionsResponseSchema,
+  ListProgressResponse: ListProgressResponseSchema
+}
+```
+
+### `AcqSubstrateSchemas`
+
+```typescript
+export const AcqSubstrateSchemas = {
+  // Artifacts
+  ListArtifactsQuery: ListArtifactsQuerySchema,
+  CreateArtifactRequest: CreateArtifactRequestSchema,
+  AcqArtifactResponse: AcqArtifactResponseSchema,
+  AcqArtifactListResponse: AcqArtifactListResponseSchema,
+
+  // List members
+  ListMembersQuery: ListMembersQuerySchema,
+  MemberIdParams: MemberIdParamsSchema,
+  AcqListMemberResponse: AcqListMemberResponseSchema,
+  AcqListMembersResponse: AcqListMembersResponseSchema,
+
+  // List companies
+  ListCompanyIdParams: ListCompanyIdParamsSchema,
+  AcqListCompanyResponse: AcqListCompanyResponseSchema,
+
+  // Transition (shared with deals — TransitionItemRequestSchema)
+  TransitionItemRequest: TransitionItemRequestSchema
+}
+```
+
+### `Stateful`
+
+```typescript
+/**
+ * Stateful trait — the (pipeline_key, stage_key, state_key, activity_log) quartet
+ * applied to acq_deals (CRM HITL, shipped 2026-04-27) and being generalized to
+ * acq_lists / acq_list_members / acq_list_companies via Track B.
+ */
+export interface Stateful {
+  pipeline_key: string
+  stage_key: string
+  state_key: string
+  activity_log: ActivityEvent[]
+}
+```
+
+### `TransitionItem`
+
+```typescript
+/** Generic transition shape — concrete per-entity transitionItem implementations satisfy this. */
+export type TransitionItem<T extends Stateful, TEvent extends ActivityEvent> = (
+  item: T,
+  transition: { stage_key?: string; state_key?: string; event: TEvent }
+) => T
+```
+
+### `DeriveActions`
+
+```typescript
+/** Generic action-derivation shape — concrete per-entity deriveActions implementations satisfy this. */
+export type DeriveActions<T extends Stateful, TAction> = (item: T) => TAction[]
+```
+
+### `StatefulSchema`
+
+```typescript
+export const StatefulSchema = z.object({
+  pipeline_key: z.string(),
+  stage_key: z.string(),
+  state_key: z.string(),
+  activity_log: z.array(ActivityEventSchema)
+})
+```
+
+### `StatefulStateDefinition`
+
+```typescript
+/** One state within a stage — minimal shape: key + display label. */
+export interface StatefulStateDefinition {
+  /** Matches state_key values written by workflow steps. */
+  stateKey: string
+  label: string
+}
+```
+
+### `StatefulStageDefinition`
+
+```typescript
+/** One stage within a pipeline — has a stage_key and an ordered list of valid states. */
+export interface StatefulStageDefinition {
+  /** Matches stage_key values written by workflow steps. */
+  stageKey: string
+  label: string
+  states: StatefulStateDefinition[]
+}
+```
+
+### `StatefulPipelineDefinition`
+
+```typescript
+/**
+ * Pipeline definition for a single entity participating in the Stateful trait.
+ * Parallel to acq_deals' pipeline_key concept but structured for lead-gen entities.
+ */
+export interface StatefulPipelineDefinition {
+  /** Matches pipeline_key values in the database (e.g. 'lead-gen'). */
+  pipelineKey: string
+  label: string
+  /** Entity this pipeline applies to (e.g. 'acq.list', 'acq.list-member', 'acq.list-company'). */
+  entityKey: string
+  stages: StatefulStageDefinition[]
+}
+```
+
+### `ACQ_LIST_MEMBERS_LEAD_GEN_PIPELINE`
+
+```typescript
+/**
+ * Lead-gen pipeline definition for acq_list_members (contacts).
+ * Three stages matching the post-restructure sales subdomain tree.
+ *
+ * Note: members visit outreach and prospecting states depending on which
+ * workflow last processed them. stage_key is set per-transition by the workflow.
+ */
+export const ACQ_LIST_MEMBERS_LEAD_GEN_PIPELINE: StatefulPipelineDefinition = {
+  pipelineKey: 'lead-gen',
+  label: 'Lead Generation',
+  entityKey: 'acq.list-member',
+  stages: [
+    {
+      stageKey: 'outreach',
+      label: 'Outreach',
+      states: [
+        PENDING_STATE,
+        { stateKey: 'personalized', label: 'Personalized' },
+        { stateKey: 'uploaded', label: 'Uploaded' },
+        { stateKey: 'interested', label: 'Interested' }
+      ]
+    },
+    {
+      stageKey: 'prospecting',
+      label: 'Prospecting',
+      states: [
+        PENDING_STATE,
+        { stateKey: 'discovered', label: 'Discovered' },
+        { stateKey: 'verified', label: 'Verified' }
+      ]
+    },
+    {
+      stageKey: 'qualification',
+      label: 'Qualification',
+      states: [PENDING_STATE]
+    }
+  ]
+}
+```
+
+### `ACQ_LIST_COMPANIES_LEAD_GEN_PIPELINE`
+
+```typescript
+/**
+ * Lead-gen pipeline definition for acq_list_companies.
+ * Three stages matching the post-restructure sales subdomain tree.
+ *
+ * Note: companies visit prospecting and qualification states depending on which
+ * workflow last processed them. stage_key is set per-transition by the workflow.
+ */
+export const ACQ_LIST_COMPANIES_LEAD_GEN_PIPELINE: StatefulPipelineDefinition = {
+  pipelineKey: 'lead-gen',
+  label: 'Lead Generation',
+  entityKey: 'acq.list-company',
+  stages: [
+    {
+      stageKey: 'outreach',
+      label: 'Outreach',
+      states: [PENDING_STATE]
+    },
+    {
+      stageKey: 'prospecting',
+      label: 'Prospecting',
+      states: [
+        PENDING_STATE,
+        { stateKey: 'populated', label: 'Populated' },
+        { stateKey: 'extracted', label: 'Extracted' }
+      ]
+    },
+    {
+      stageKey: 'qualification',
+      label: 'Qualification',
+      states: [PENDING_STATE, { stateKey: 'qualified', label: 'Qualified' }]
+    }
+  ]
+}
+```
+
+### `LEAD_GEN_PIPELINE_DEFINITIONS`
+
+```typescript
+/**
+ * All lead-gen pipeline definitions indexed by entity key.
+ * Use findPipeline() to locate a definition by pipeline_key within any of these arrays.
+ */
+export const LEAD_GEN_PIPELINE_DEFINITIONS: Record<string, StatefulPipelineDefinition[]> = {
+  'acq.list-member': [ACQ_LIST_MEMBERS_LEAD_GEN_PIPELINE],
+  'acq.list-company': [ACQ_LIST_COMPANIES_LEAD_GEN_PIPELINE]
+}
+```
+
+### `PaginationParams`
+
+```typescript
+export interface PaginationParams {
+  limit: number
+  offset: number
+}
+```
+
+### `PaginatedResult`
+
+```typescript
+export interface PaginatedResult<T> {
+  data: T[]
+  total: number
+  limit: number
+  offset: number
+}
+```
+
+### `CreateListParams`
+
+```typescript
+export interface CreateListParams {
+  organizationId: string
+  name: string
+  description?: string
+  type?: string
+  batchIds?: string[]
+  instantlyCampaignId?: string
+  status?: ListStatus
+  metadata?: Record<string, unknown>
+  scrapingConfig?: ScrapingConfig
+  icp?: IcpRubric
+  pipelineConfig?: PipelineConfig
+}
+```
+
+### `UpdateListParams`
+
+```typescript
+export interface UpdateListParams {
+  name?: string
+  description?: string
+  batchIds?: string[]
+}
+```
+
+### `CreateCompanyParams`
+
+```typescript
+export interface CreateCompanyParams {
+  organizationId: string
+  name: string
+  domain?: string
+  linkedinUrl?: string
+  website?: string
+  numEmployees?: number
+  foundedYear?: number
+  locationCity?: string
+  locationState?: string
+  category?: string
+  source?: string
+  batchId?: string
+  verticalResearch?: string
+}
+```
+
+### `UpdateCompanyParams`
+
+```typescript
+export interface UpdateCompanyParams {
+  name?: string
+  domain?: string
+  linkedinUrl?: string
+  website?: string
+  numEmployees?: number
+  foundedYear?: number
+  locationCity?: string
+  locationState?: string
+  category?: string
+  segment?: string
+  pipelineStatus?: Record<string, unknown>
+  enrichmentData?: Record<string, unknown>
+  source?: string
+  batchId?: string
+  status?: 'active' | 'invalid'
+  verticalResearch?: string | null
+  /** Track A: flat qualification score column (null until a scoring rubric is defined) */
+  qualificationScore?: number | null
+  /** Track A: flat qualification signals jsonb — mirrors the former pipeline_status.qualification shape */
+  qualificationSignals?: Record<string, unknown> | null
+  /** Track A: key identifying the rubric used for qualification */
+  qualificationRubricKey?: string | null
+}
+```
+
+### `UpsertCompanyParams`
+
+```typescript
+export type UpsertCompanyParams = CreateCompanyParams
+```
+
+### `CompanyFilters`
+
+```typescript
+export interface CompanyFilters {
+  listId?: string // Filter to companies in a specific list (via acq_list_companies)
+  search?: string
+  domain?: string
+  website?: string
+  segment?: string
+  category?: string
+  pipelineStatus?: Record<string, unknown>
+  /** Exclude companies whose pipeline_status contains this value (PostgREST NOT contains) */
+  pipelineStatusNot?: Record<string, unknown>
+  batchId?: string
+  status?: 'active' | 'invalid'
+  includeAll?: boolean
+  excludeColumns?: Array<'enrichmentData' | 'pipelineStatus'>
+}
+```
+
+### `CreateContactParams`
+
+```typescript
+export interface CreateContactParams {
+  organizationId: string
+  email: string
+  companyId?: string
+  firstName?: string
+  lastName?: string
+  linkedinUrl?: string
+  title?: string
+  source?: string
+  sourceId?: string
+  batchId?: string
+}
+```
+
+### `UpdateContactParams`
+
+```typescript
+export interface UpdateContactParams {
+  companyId?: string
+  emailValid?: 'VALID' | 'INVALID' | 'RISKY' | 'UNKNOWN'
+  firstName?: string
+  lastName?: string
+  linkedinUrl?: string
+  title?: string
+  headline?: string
+  filterReason?: string
+  openingLine?: string
+  pipelineStatus?: Record<string, unknown>
+  enrichmentData?: Record<string, unknown>
+  status?: 'active' | 'invalid'
+}
+```
+
+### `UpsertContactParams`
+
+```typescript
+export type UpsertContactParams = CreateContactParams
+```
+
+### `ContactFilters`
+
+```typescript
+export interface ContactFilters {
+  listId?: string // Filter to contacts in a specific list (via acq_list_members)
+  search?: string
+  openingLineIsNull?: boolean // Filter to contacts without personalization
+  pipelineStatus?: Record<string, unknown>
+  batchId?: string
+  contactStatus?: 'active' | 'invalid' // Filter by contact status (soft-delete flag)
+}
+```
+
+### `UpsertSocialPostParams`
+
+```typescript
+export interface UpsertSocialPostParams {
+  organizationId: string
+  platform: string
+  platformPostId: string
+  authorName: string
+  authorUrl?: string | null
+  postTitle: string
+  postText: string
+  postUrl: string
+  engagementCount?: number
+  commentsCount?: number
+  postedAt: string
+  metadata?: Record<string, unknown>
+  relevanceScore?: number
+  matchedKeywords?: string[]
+  matchedQuery?: string | null
+  initialDraft?: string | null
+  finalResponse?: string | null
+  sourceCategory?: string | null
+}
+```
+
+### `UpsertSocialPostsParams`
+
+```typescript
+export interface UpsertSocialPostsParams {
+  organizationId: string
+  posts: Omit<UpsertSocialPostParams, 'organizationId'>[]
+}
+```
+
+### `UpsertSocialPostsResult`
+
+```typescript
+export interface UpsertSocialPostsResult {
+  inserted: number
+  duplicatesSkipped: number
+}
+```
+
+### `AddContactsToListParams`
+
+```typescript
+export interface AddContactsToListParams {
+  organizationId: string
+  listId: string
+  contactIds: string[]
+}
+```
+
+### `AddContactsToListResult`
+
+```typescript
+export interface AddContactsToListResult {
+  added: number
+  alreadyExisted: number
+}
+```
+
+### `UpdateListConfigParams`
+
+```typescript
+export interface UpdateListConfigParams {
+  organizationId: string
+  listId: string
+  scrapingConfig?: ScrapingConfig
+  icp?: IcpRubric
+  pipelineConfig?: PipelineConfig
+}
+```
+
+### `UpdateCompanyStageParams`
+
+```typescript
+export interface UpdateCompanyStageParams {
+  organizationId: string
+  listId: string
+  companyId: string
+  stage: string
+  status?: ProcessingStageStatus
+  executionId?: string
+}
+```
+
+### `UpdateContactStageParams`
+
+```typescript
+export interface UpdateContactStageParams {
+  organizationId: string
+  listId: string
+  contactId: string
+  stage: string
+  status?: ProcessingStageStatus
+  executionId?: string
+}
+```
+
+### `AddCompaniesToListParams`
+
+```typescript
+export interface AddCompaniesToListParams {
+  organizationId: string
+  listId: string
+  companyIds: string[]
+}
+```
+
+### `AddCompaniesToListResult`
+
+```typescript
+export interface AddCompaniesToListResult {
+  added: number
+  alreadyExisted: number
+}
+```
+
+### `RemoveCompaniesFromListParams`
+
+```typescript
+export interface RemoveCompaniesFromListParams {
+  organizationId: string
+  listId: string
+  companyIds: string[]
+}
+```
+
+### `RemoveCompaniesFromListResult`
+
+```typescript
+export interface RemoveCompaniesFromListResult {
+  removed: number
+}
+```
+
+### `RecordListExecutionParams`
+
+```typescript
+export interface RecordListExecutionParams {
+  organizationId: string
+  listId: string
+  executionId: string
+  configSnapshot?: Record<string, unknown>
+}
+```
+
+### `ListExecutionSummary`
+
+```typescript
+export interface ListExecutionSummary {
+  executionId: string
+  resourceId: string
+  status: string
+  createdAt: string
+  completedAt: string | null
+  durationMs: number | null
+}
+```
+
+### `BulkImportParams`
+
+```typescript
+export interface BulkImportParams {
+  organizationId: string
+  contacts: CreateContactParams[]
+  listId?: string
+}
+```
+
+### `BulkImportResult`
+
+```typescript
+export interface BulkImportResult {
+  created: number
+  updated: number
+  errors: Array<{ email: string; error: string }>
+}
+```
+
+### `BulkImportCompanyEntry`
+
+```typescript
+export interface BulkImportCompanyEntry {
+  name: string
+  domain: string
+  website?: string
+  locationCity?: string
+  locationState?: string
+  category?: string
+  source?: string
+  enrichmentData?: Record<string, unknown>
+  pipelineStatus?: Record<string, unknown>
+}
+```
+
+### `BulkImportCompaniesParams`
+
+```typescript
+export interface BulkImportCompaniesParams {
+  organizationId: string
+  batchId: string
+  companies: BulkImportCompanyEntry[]
+}
+```
+
+### `BulkImportCompaniesResult`
+
+```typescript
+export interface BulkImportCompaniesResult {
+  created: number
+  skipped: number
+  errors: Array<{ companyName: string; error: string }>
+}
+```
+
+### `LeadToolMap`
+
+```typescript
+export type LeadToolMap = {
+  // List operations
+  listLists: { params: Record<string, never>; result: AcqList[] }
+  createList: { params: Omit<CreateListParams, 'organizationId'>; result: AcqList }
+  updateList: { params: { id: string } & UpdateListParams; result: AcqList }
+  deleteList: { params: { id: string }; result: void }
+  addContactsToList: { params: Omit<AddContactsToListParams, 'organizationId'>; result: AddContactsToListResult }
+  addCompaniesToList: { params: Omit<AddCompaniesToListParams, 'organizationId'>; result: AddCompaniesToListResult }
+  updateCompanyStage: {
+    params: Omit<UpdateCompanyStageParams, 'organizationId'>
+    result: void
+  }
+  updateContactStage: {
+    params: Omit<UpdateContactStageParams, 'organizationId'>
+    result: void
+  }
+  // Company operations
+  createCompany: { params: Omit<CreateCompanyParams, 'organizationId'>; result: AcqCompany }
+  upsertCompany: { params: Omit<UpsertCompanyParams, 'organizationId'>; result: AcqCompany }
+  updateCompany: { params: { id: string } & UpdateCompanyParams; result: AcqCompany }
+  getCompany: { params: { id: string }; result: AcqCompany | null }
+  listCompanies: { params: CompanyFilters; result: AcqCompany[] }
+  deleteCompany: { params: { id: string }; result: void }
+  // Contact operations
+  createContact: { params: Omit<CreateContactParams, 'organizationId'>; result: AcqContact }
+  upsertContact: { params: Omit<UpsertContactParams, 'organizationId'>; result: AcqContact }
+  updateContact: { params: { id: string } & UpdateContactParams; result: AcqContact }
+  getContact: { params: { id: string }; result: AcqContact | null }
+  getContactByEmail: { params: { email: string }; result: AcqContact | null }
+  listContacts: {
+    params: ContactFilters & { limit?: number; offset?: number }
+    result: PaginatedResult<AcqContact>
+  }
+  deleteContact: { params: { id: string }; result: void }
+  bulkImportContacts: { params: Omit<BulkImportParams, 'organizationId'>; result: BulkImportResult }
+  bulkImportCompanies: {
+    params: Omit<BulkImportCompaniesParams, 'organizationId'>
+    result: BulkImportCompaniesResult
+  }
+  deactivateContactsByCompany: {
+    params: { companyId: string }
+    result: { deactivated: number }
+  }
+  // Deal operations
+  upsertDeal: { params: Omit<UpsertDealParams, 'organizationId'>; result: AcqDeal }
+  getDealByEmail: { params: { email: string }; result: AcqDeal | null }
+  getDealByEnvelopeId: { params: { envelopeId: string }; result: AcqDeal | null }
+  updateDealEnvelopeId: { params: { dealId: string; envelopeId: string }; result: AcqDeal | null }
+  getDealById: { params: Omit<GetDealByIdParams, 'organizationId'>; result: AcqDeal | null }
+  getContactById: { params: Omit<GetContactByIdParams, 'organizationId'>; result: AcqContact | null }
+  getCompanyById: { params: Omit<GetCompanyByIdParams, 'organizationId'>; result: AcqCompany | null }
+  // Deal-sync operations
+  updateDiscoveryData: { params: Omit<UpdateDiscoveryDataParams, 'organizationId'>; result: void }
+  updateProposalData: { params: Omit<UpdateProposalDataParams, 'organizationId'>; result: void }
+  markProposalSent: { params: Omit<MarkProposalSentParams, 'organizationId'>; result: void }
+  markProposalReviewed: { params: Omit<MarkProposalReviewedParams, 'organizationId'>; result: void }
+  updateCloseLostReason: { params: Omit<UpdateCloseLostReasonParams, 'organizationId'>; result: void }
+  updateFees: { params: Omit<UpdateFeesParams, 'organizationId'>; result: void }
+  transitionItem: { params: Omit<TransitionItemParams, 'organizationId'>; result: void }
+  setContactNurture: { params: Omit<SetContactNurtureParams, 'organizationId'>; result: void }
+  cancelSchedulesAndHitlByEmail: {
+    params: Omit<CancelSchedulesAndHitlByEmailParams, 'organizationId'>
+    result: { schedulesCancelled: number; hitlDeleted: number }
+  }
+  cancelHitlByDealId: { params: Omit<CancelHitlByDealIdParams, 'organizationId'>; result: { hitlDeleted: number } }
+  clearDealFields: { params: Omit<ClearDealFieldsParams, 'organizationId'>; result: void }
+  deleteDeal: { params: Omit<DeleteDealParams, 'organizationId'>; result: void }
+  recordDealActivity: {
+    params: Omit<RecordDealActivityParams, 'organizationId'>
+    result: void
+  }
+  // Deal note operations
+  createDealNote: {
+    params: Omit<CreateDealNoteParams, 'organizationId'>
+    result: AcqDealNote
+  }
+  listDealNotes: {
+    params: Omit<ListDealNotesParams, 'organizationId'>
+    result: AcqDealNote[]
+  }
+  // Deal task operations
+  createDealTask: {
+    params: Omit<CreateDealTaskParams, 'organizationId'>
+    result: AcqDealTask
+  }
+  listDealTasks: {
+    params: Omit<ListDealTasksParams, 'organizationId'>
+    result: AcqDealTask[]
+  }
+  listDealTasksDue: {
+    params: Omit<ListDealTasksDueParams, 'organizationId'>
+    result: AcqDealTask[]
+  }
+  completeDealTask: {
+    params: Omit<CompleteDealTaskParams, 'organizationId'>
+    result: AcqDealTask
+  }
+  // Deal query & analytics operations
+  listDeals: { params: DealFilters; result: AcqDeal[] }
+  getDealPipelineAnalytics: { params: { recentLimit?: number }; result: DealPipelineAnalytics }
+  // Enrichment data operations
+  mergeEnrichmentData: {
+    params: { id: string; table: 'acq_companies' | 'acq_contacts'; data: Record<string, unknown> }
+    result: void
+  }
+  // Social monitoring operations
+  upsertSocialPosts: {
+    params: { posts: Omit<UpsertSocialPostParams, 'organizationId'>[] }
+    result: UpsertSocialPostsResult
+  }
+  setDealStateKey: {
+    params: {
+      dealId: string
+      stateKey: string
+    }
+    result: { ok: true }
+  }
+  // CRM workflow helpers
+  transitionDeal: {
+    params: {
+      dealId: string
+      toStage: string
+      toState?: string
+    }
+    result: { deal: AcqDeal }
+  }
+  loadDeal: {
+    params: { dealId: string }
+    result: DealDetail | null
+  }
+}
+```
+
+### `ListToolMap`
+
+```typescript
+export type ListToolMap = {
+  getConfig: {
+    params: { listId: string }
+    result: { scrapingConfig: ScrapingConfig; icp: IcpRubric; pipelineConfig: PipelineConfig }
+  }
+  recordExecution: {
+    params: Omit<RecordListExecutionParams, 'organizationId'>
+    result: void
+  }
+  updateCompanyStage: {
+    params: Omit<UpdateCompanyStageParams, 'organizationId'>
+    result: void
+  }
+  updateContactStage: {
+    params: Omit<UpdateContactStageParams, 'organizationId'>
+    result: void
+  }
+}
+```