@elevasis/sdk 1.17.0 → 1.19.0

package/reference/scaffold/reference/contracts.md

@@ -198,6 +198,18 @@ export type OrgKnowledgeNode = z.infer<typeof OrgKnowledgeNodeSchema>
 export type OrgKnowledgeKind = z.infer<typeof OrgKnowledgeKindSchema>
 ```
 
+### `KnowledgeSkillBinding`
+
+```typescript
+export type KnowledgeSkillBinding = z.infer<typeof KnowledgeSkillBindingSchema>
+```
+
+### `KnowledgeDomainBinding`
+
+```typescript
+export type KnowledgeDomainBinding = z.infer<typeof KnowledgeDomainBindingSchema>
+```
+
 ### `OrganizationModelIconToken`
 
 ```typescript
@@ -869,7 +881,9 @@ export interface AcqCompany {
   category: string | null
   categoryPain: string | null
   segment: string | null
-  pipelineStatus: CompanyPipelineStatus | null
+  processingState: CompanyProcessingState | null
+  /** @deprecated Use `processingState`. This legacy DB column has been removed; responses return null. */
+  pipelineStatus?: LegacyPipelineStatus | null
   enrichmentData: CompanyEnrichmentData | null
   source: string | null
   batchId: string | null
@@ -909,7 +923,9 @@ export interface AcqContact {
   openingLine: string | null
   source: string | null
   sourceId: string | null
-  pipelineStatus: ContactPipelineStatus | null
+  processingState: ContactProcessingState | null
+  /** @deprecated Use `processingState`. This legacy DB column has been removed; responses return null. */
+  pipelineStatus?: LegacyPipelineStatus | null
   enrichmentData: ContactEnrichmentData | null
   /** Attio Person record ID - set when contact responds and is added to CRM */
   attioPersonId: string | null
@@ -972,7 +988,7 @@ export interface DealContact {
   title: string | null
   headline: string | null
   linkedin_url: string | null
-  pipeline_status: Record<string, unknown> | null
+  processing_state: Record<string, unknown> | null
   enrichment_data: Record<string, unknown> | null
   company: {
     id: string
@@ -1110,7 +1126,7 @@ export const DEFAULT_CRM_PRIORITY_RULE_CONFIG: CrmPriorityRuleConfig = {
 ### `DealStageSchema`
 
 ```typescript
-export const DealStageSchema = z.enum(['interested', 'proposal', 'closing', 'closed_won', 'closed_lost', 'nurturing'])
+export const DealStageSchema = CrmStageKeySchema
 ```
 
 ### `AcqDealTaskKindSchema`
@@ -1202,7 +1218,7 @@ export const TransitionItemRequestSchema = z
   .object({
     pipelineKey: z.string().min(1),
     stageKey: z.string().min(1),
-    stateKey: z.string().nullable().optional(),
+    stateKey: z.string().min(1).nullable().optional(),
     reason: z.string().optional(),
     expectedUpdatedAt: z.string().datetime().optional()
   })
@@ -1245,7 +1261,7 @@ export const DealContactSummarySchema = z.object({
   title: z.string().nullable(),
   headline: z.string().nullable(),
   linkedin_url: z.string().nullable(),
-  pipeline_status: z.record(z.string(), z.unknown()).nullable(),
+  processing_state: ProcessingStateSchema.nullable(),
   enrichment_data: z.record(z.string(), z.unknown()).nullable(),
   company: z
     .object({
@@ -1396,6 +1412,11 @@ export const DealTaskListResponseSchema = z.array(DealTaskResponseSchema)
 
 ```typescript
 export const DealSchemas = {
+  // Primitives
+  CrmStageKey: CrmStageKeySchema,
+  CrmStateKey: CrmStateKeySchema,
+  DealStage: DealStageSchema,
+
   // Params
   DealIdParams: DealIdParamsSchema,
   DealTaskIdParams: DealTaskIdParamsSchema,
@@ -1408,7 +1429,7 @@ export const DealSchemas = {
   // Request bodies
   CreateDealNoteRequest: CreateDealNoteRequestSchema,
   CreateDealTaskRequest: CreateDealTaskRequestSchema,
-  TransitionItemRequest: TransitionItemRequestSchema,
+  TransitionItemRequest: CrmTransitionItemRequestSchema,
   TransitionDealStateRequest: TransitionDealStateRequestSchema,
   ExecuteActionParams: ExecuteActionParamsSchema,
   ExecuteActionRequest: ExecuteActionRequestSchema,
@@ -1573,51 +1594,6 @@ export interface WebPost {
 }
 ```
 
-### `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
@@ -1733,7 +1709,9 @@ export interface AcqCompany {
   category: string | null
   categoryPain: string | null
   segment: string | null
-  pipelineStatus: CompanyPipelineStatus | null
+  processingState: CompanyProcessingState | null
+  /** @deprecated Use `processingState`. This legacy DB column has been removed; responses return null. */
+  pipelineStatus?: LegacyPipelineStatus | null
   enrichmentData: CompanyEnrichmentData | null
   source: string | null
   batchId: string | null
@@ -1773,7 +1751,9 @@ export interface AcqContact {
   openingLine: string | null
   source: string | null
   sourceId: string | null
-  pipelineStatus: ContactPipelineStatus | null
+  processingState: ContactProcessingState | null
+  /** @deprecated Use `processingState`. This legacy DB column has been removed; responses return null. */
+  pipelineStatus?: LegacyPipelineStatus | null
   enrichmentData: ContactEnrichmentData | null
   /** Attio Person record ID - set when contact responds and is added to CRM */
   attioPersonId: string | null
@@ -2084,6 +2064,7 @@ export const ListCompaniesQuerySchema = z
     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(),
+    pipelineStatus: z.unknown().optional(),
     batchId: z.string().trim().min(1).max(255).optional(),
     status: AcqCompanyStatusSchema.optional(),
     includeAll: QueryBooleanSchema.optional(),
@@ -2125,6 +2106,7 @@ export const CreateCompanyRequestSchema = z
     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(),
+    pipelineStatus: z.unknown().optional(),
     verticalResearch: z.string().trim().min(1).max(5000).optional()
   })
   .strict()
@@ -2145,7 +2127,8 @@ export const UpdateCompanyRequestSchema = z
     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(),
+    processingState: CompanyProcessingStateSchema.optional(),
+    pipelineStatus: 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(),
@@ -2165,6 +2148,7 @@ export const UpdateCompanyRequestSchema = z
       data.locationState !== undefined ||
       data.category !== undefined ||
       data.segment !== undefined ||
+      data.processingState !== undefined ||
       data.pipelineStatus !== undefined ||
       data.enrichmentData !== undefined ||
       data.source !== undefined ||
@@ -2190,7 +2174,8 @@ export const CreateContactRequestSchema = z
     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()
+    batchId: z.string().trim().min(1).max(255).optional(),
+    pipelineStatus: z.unknown().optional()
   })
   .strict()
 ```
@@ -2209,7 +2194,8 @@ export const UpdateContactRequestSchema = z
     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(),
+    processingState: ContactProcessingStateSchema.optional(),
+    pipelineStatus: z.unknown().optional(),
     enrichmentData: z.record(z.string(), z.unknown()).optional(),
     status: AcqContactStatusSchema.optional()
   })
@@ -2225,6 +2211,7 @@ export const UpdateContactRequestSchema = z
       data.headline !== undefined ||
       data.filterReason !== undefined ||
       data.openingLine !== undefined ||
+      data.processingState !== undefined ||
       data.pipelineStatus !== undefined ||
       data.enrichmentData !== undefined ||
       data.status !== undefined,
@@ -2251,7 +2238,8 @@ export const AcqCompanyResponseSchema = z.object({
   category: z.string().nullable(),
   categoryPain: z.string().nullable(),
   segment: z.string().nullable(),
-  pipelineStatus: z.record(z.string(), z.unknown()).nullable(),
+  processingState: CompanyProcessingStateSchema.nullable(),
+  pipelineStatus: z.unknown().nullable().optional(),
   enrichmentData: z.record(z.string(), z.unknown()).nullable(),
   source: z.string().nullable(),
   batchId: z.string().nullable(),
@@ -2317,7 +2305,8 @@ export const AcqContactResponseSchema = z.object({
   openingLine: z.string().nullable(),
   source: z.string().nullable(),
   sourceId: z.string().nullable(),
-  pipelineStatus: z.record(z.string(), z.unknown()).nullable(),
+  processingState: ContactProcessingStateSchema.nullable(),
+  pipelineStatus: z.unknown().nullable().optional(),
   enrichmentData: z.record(z.string(), z.unknown()).nullable(),
   attioPersonId: z.string().nullable(),
   batchId: z.string().nullable(),
@@ -2483,6 +2472,7 @@ export const AcqListCompanyResponseSchema = z.object({
 
 ```typescript
 export const AcqCompanySchemas = {
+  CompanyProcessingState: CompanyProcessingStateSchema,
   CompanyIdParams: CompanyIdParamsSchema,
   ListCompaniesQuery: ListCompaniesQuerySchema,
   CreateCompanyRequest: CreateCompanyRequestSchema,
@@ -2497,6 +2487,7 @@ export const AcqCompanySchemas = {
 
 ```typescript
 export const AcqContactSchemas = {
+  ContactProcessingState: ContactProcessingStateSchema,
   ContactIdParams: ContactIdParamsSchema,
   ListContactsQuery: ListContactsQuerySchema,
   CreateContactRequest: CreateContactRequestSchema,
@@ -2522,7 +2513,10 @@ export const AcqListSchemas = {
   BuildPlanSnapshot: BuildPlanSnapshotSchema,
   BuildPlanSnapshotStep: BuildPlanSnapshotStepSchema,
   AcqListMetadata: AcqListMetadataSchema,
+  LeadGenStageKey: LeadGenStageKeySchema,
+  LeadGenCapabilityKey: LeadGenCapabilityKeySchema,
   ProcessingStageStatus: ProcessingStageStatusSchema,
+  ProcessingState: ProcessingStateSchema,
   ListStageCounts: ListStageCountsSchema,
   ListTelemetry: ListTelemetrySchema,
 
@@ -2566,7 +2560,7 @@ export const AcqSubstrateSchemas = {
   ListCompanyIdParams: ListCompanyIdParamsSchema,
   AcqListCompanyResponse: AcqListCompanyResponseSchema,
 
-  // Transition (shared with deals — TransitionItemRequestSchema)
+  // Transition (generic stateful substrate)
   TransitionItemRequest: TransitionItemRequestSchema
 }
 ```
@@ -2634,6 +2628,8 @@ export interface StatefulStageDefinition {
   /** Matches stage_key values written by workflow steps. */
   stageKey: string
   label: string
+  /** UI color token. Consumers may map this to their design system. */
+  color?: string
   states: StatefulStateDefinition[]
 }
 ```
@@ -2815,6 +2811,8 @@ export interface CreateCompanyParams {
   source?: string
   batchId?: string
   verticalResearch?: string
+  /** @deprecated Use processingState. Accepted as a no-op compatibility bridge for external tenants. */
+  pipelineStatus?: unknown
 }
 ```
 
@@ -2832,7 +2830,9 @@ export interface UpdateCompanyParams {
   locationState?: string
   category?: string
   segment?: string
-  pipelineStatus?: Record<string, unknown>
+  processingState?: ProcessingState
+  /** @deprecated Use processingState. Accepted as a no-op compatibility bridge for external tenants. */
+  pipelineStatus?: unknown
   enrichmentData?: Record<string, unknown>
   source?: string
   batchId?: string
@@ -2840,7 +2840,7 @@ export interface UpdateCompanyParams {
   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 */
+  /** Track A: flat qualification signals jsonb */
   qualificationSignals?: Record<string, unknown> | null
   /** Track A: key identifying the rubric used for qualification */
   qualificationRubricKey?: string | null
@@ -2863,13 +2863,15 @@ export interface CompanyFilters {
   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>
+  processingState?: ProcessingState
+  /** @deprecated Use processingState. Accepted as a no-op compatibility bridge for external tenants. */
+  pipelineStatus?: unknown
+  /** Exclude companies whose processing state contains this value (PostgREST NOT contains) */
+  processingStateNot?: ProcessingState
   batchId?: string
   status?: 'active' | 'invalid'
   includeAll?: boolean
-  excludeColumns?: Array<'enrichmentData' | 'pipelineStatus'>
+  excludeColumns?: Array<'enrichmentData' | 'processingState'>
   limit?: number
 }
 ```
@@ -2888,6 +2890,8 @@ export interface CreateContactParams {
   source?: string
   sourceId?: string
   batchId?: string
+  /** @deprecated Use processingState. Accepted as a no-op compatibility bridge for external tenants. */
+  pipelineStatus?: unknown
 }
 ```
 
@@ -2904,7 +2908,9 @@ export interface UpdateContactParams {
   headline?: string
   filterReason?: string
   openingLine?: string
-  pipelineStatus?: Record<string, unknown>
+  processingState?: ProcessingState
+  /** @deprecated Use processingState. Accepted as a no-op compatibility bridge for external tenants. */
+  pipelineStatus?: unknown
   enrichmentData?: Record<string, unknown>
   status?: 'active' | 'invalid'
 }
@@ -2923,7 +2929,9 @@ 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>
+  processingState?: ProcessingState
+  /** @deprecated Use processingState. Accepted as a no-op compatibility bridge for external tenants. */
+  pipelineStatus?: unknown
   batchId?: string
   contactStatus?: 'active' | 'invalid' // Filter by contact status (soft-delete flag)
 }
@@ -3122,7 +3130,7 @@ export interface BulkImportCompanyEntry {
   category?: string
   source?: string
   enrichmentData?: Record<string, unknown>
-  pipelineStatus?: Record<string, unknown>
+  processingState?: ProcessingState
 }
 ```
 
@@ -3303,6 +3311,14 @@ export type ListToolMap = {
     params: Omit<UpdateContactStageParams, 'organizationId'>
     result: void
   }
+  listPendingCompanyIds: {
+    params: Omit<ListPendingCompanyIdsParams, 'organizationId'>
+    result: string[]
+  }
+  listPendingContactIds: {
+    params: Omit<ListPendingContactIdsParams, 'organizationId'>
+    result: string[]
+  }
 }
 ```
 
@@ -3338,6 +3354,10 @@ export const OrgKnowledgeNodeSchema = z.object({
    * Each link emits a `governs` edge: knowledge-node -> target node.
    */
   links: z.array(KnowledgeLinkSchema).default([]),
+  /** Operator skill or command bindings relevant to this node. */
+  skills: z.array(KnowledgeSkillBindingSchema).optional(),
+  /** Domain key used to derive fast graph->skill registries. */
+  domain: KnowledgeDomainBindingSchema.optional(),
   /** Identifiers of the roles or members who own this knowledge node. */
   ownerIds: z.array(ModelIdSchema).default([]),
   /** ISO date string (YYYY-MM-DD or full ISO 8601) of last meaningful update. */

package/reference/scaffold/reference/feature-registry.md

@@ -31,7 +31,7 @@ Feature IDs defined in `DEFAULT_ORGANIZATION_MODEL.features` (`packages/core/src
 
 ```typescript
 // FeatureSchema: { id, label, enabled, color?, icon?, entityIds, surfaceIds, resourceIds, capabilityIds }
-type DefaultFeatureId = 'dashboard' | 'identity' | 'platform' | 'finance' | 'sales' | 'sales.crm' | 'sales.lead-gen' | 'projects' | 'operations' | 'knowledge.command-view' | 'operations.overview' | 'operations.resources' | 'operations.command-queue' | 'operations.sessions' | 'operations.task-scheduler' | 'monitoring' | 'monitoring.activity-log' | 'monitoring.execution-logs' | 'monitoring.execution-health' | 'monitoring.cost-analytics' | 'monitoring.notifications' | 'monitoring.submitted-requests' | 'settings' | 'settings.account' | 'settings.appearance' | 'settings.roles' | 'settings.organization' | 'settings.credentials' | 'settings.api-keys' | 'settings.webhooks' | 'settings.deployments' | 'admin' | 'admin.system-health' | 'admin.organizations' | 'admin.users' | 'admin.design-showcase' | 'admin.debug' | 'archive' | 'archive.agent-chat' | 'archive.execution-runner' | 'seo' | 'knowledge' | 'knowledge.base'
+type DefaultFeatureId = 'dashboard' | 'identity' | 'platform' | 'finance' | 'sales' | 'sales.crm' | 'sales.lead-gen' | 'projects' | 'operations' | 'knowledge.command-view' | 'operations.overview' | 'operations.resources' | 'operations.command-queue' | 'operations.sessions' | 'operations.task-scheduler' | 'monitoring' | 'monitoring.calendar' | 'monitoring.activity-log' | 'monitoring.execution-logs' | 'monitoring.execution-health' | 'monitoring.cost-analytics' | 'monitoring.notifications' | 'monitoring.submitted-requests' | 'settings' | 'settings.account' | 'settings.appearance' | 'settings.roles' | 'settings.organization' | 'settings.credentials' | 'settings.api-keys' | 'settings.webhooks' | 'settings.deployments' | 'admin' | 'admin.system-health' | 'admin.organizations' | 'admin.users' | 'admin.design-showcase' | 'admin.debug' | 'archive' | 'archive.agent-chat' | 'archive.execution-runner' | 'seo' | 'knowledge' | 'knowledge.base'
 ```
 
 These are the built-in feature IDs. The `featureId` field on a `FeatureModule` manifest must match the `id` of a feature in the organization model to enable access-flag gating.

package/reference/spine/spine-primer.md

@@ -0,0 +1,99 @@
+---
+title: Spine Primer
+description: Tenant-facing primer for using an Organization Model catalog as the shared coordination spine between workflow producers, runtime state, API filters, and UI projections.
+---
+<!-- @generated by packages/sdk/scripts/copy-reference-docs.mjs -- DO NOT EDIT -->
+<!-- Regenerate: pnpm scaffold:sync -->
+
+
+# Spine Primer
+
+Use this primer when a tenant domain has a closed set of stages, statuses, or catalog keys that multiple surfaces must share. A spine is the tenant Organization Model vocabulary that coordinates workflows, runtime state, API reads, and UI rendering without forcing those surfaces to import from each other.
+
+The lead-generation pattern is the reference shape: `organizationModel.prospecting.stages` defines the stage vocabulary, workflow templates reference those stages, workflow factories validate stage keys before running, entity state stores sparse per-stage progress, and UI views render progress from the same vocabulary.
+
+## What The Spine Owns
+
+A spine owns the shared vocabulary for one domain. The vocabulary is not just a list of strings. Each key should carry enough metadata for consumers to derive behavior consistently:
+
+- `key` identifies the stage or catalog member.
+- `label` gives a human-readable name.
+- `description` explains the business meaning.
+- `order` gives stable display and workflow ordering.
+- `entity` identifies which tenant entity the stage updates.
+
+The same keys then appear in four places:
+
+| Role | Tenant-facing shape |
+| --- | --- |
+| Vocabulary | `organizationModel.prospecting.stages` |
+| Process | workflow templates and build steps that reference stage keys |
+| Runtime state | entity state maps such as `{ [stageKey]: { status, updatedAt, data } }` |
+| Consumer projection | API filters, progress summaries, and UI step rendering |
+
+## Layering
+
+```text
+tenant Organization Model
+- prospecting stages
+- workflow templates
+- capability bindings
+        |
+        +--> workflow factory
+        |    - validates stage keys
+        |    - runs producers
+        |    - dispatches entity-tagged results
+        |
+        +--> API and query helpers
+        |    - filter pending entities by stage key
+        |    - aggregate progress from state maps
+        |
+        +--> UI projections
+             - render labels and order from the catalog
+             - distinguish known and unknown state keys
+
+entity runtime state
+{ [stageKey]: { status, updatedAt, data } }
+```
+
+The important boundary is that producers and consumers coordinate through the Organization Model vocabulary plus runtime state. They do not coordinate through direct imports, duplicated string constants, or workflow-specific side channels.
+
+## Invariants
+
+1. **The vocabulary is closed and validated.** Workflow factories should reject stage keys that are not present in the tenant Organization Model.
+
+2. **The vocabulary carries metadata.** Labels, descriptions, ordering, and entity ownership should come from the catalog rather than being copied into each consumer.
+
+3. **Runtime state is sparse and additive.** New stages appear in entity state when reached. Adding a catalog member should not require backfilling every entity.
+
+4. **Producers return entity-tagged results.** Workflow steps should return which entity changed, its identifier, status, and optional data. The factory owns writing those results to the correct state map.
+
+5. **Capability binding is separate from stage naming.** Workflow templates should point at capability keys, and the tenant environment can bind those capabilities to concrete workflow resources.
+
+## Applying The Pattern
+
+Use this checklist when adding or changing a tenant domain spine:
+
+1. Define the domain catalog in the tenant Organization Model.
+2. Include labels, descriptions, ordering, and entity ownership in each catalog entry.
+3. Make workflow templates reference catalog keys instead of free-form strings.
+4. Validate template stage keys when constructing workflow factories.
+5. Store progress in sparse entity state maps keyed by catalog member.
+6. Return entity-tagged workflow results and let the factory dispatch state updates.
+7. Read progress through query helpers that use the same catalog keys.
+8. Render UI labels, order, and status from the catalog plus state map.
+
+Promote a vocabulary to a spine when the same catalog coordinates all three surfaces: at least one process definition, at least one workflow producer, and at least one independent consumer such as an API query or UI view.
+
+## Counter-Patterns
+
+Avoid these patterns in spine-governed domains:
+
+- Free-form stage strings in workflow inputs.
+- Duplicated UI-only labels or ordering.
+- Per-workflow skip logic that bypasses the shared pending and progress contract.
+- State writes from individual steps instead of the workflow factory.
+- Hidden side channels for progress, such as ad hoc context keys.
+- Direct coupling between producer code and consumer UI code.
+
+When in doubt, update the Organization Model vocabulary first, then let workflow templates, factories, queries, and views project from it.