| enrichment_task_id | UUID (🔒 system) | ✅ Yes | UNIQUE | — | Public stable identifier. Auto-generated by gen_random_uuid() at insert. This is the id exposed in JSON:API responses; the internal pk is never surfaced. |
| entity_type | string (varchar 100) | ✅ Yes | max 100 chars; NOT NULL; composite index with entity_id (enrichment_tasks_entity_idx) | — | Polymorphic discriminator identifying the kind of entity this task targets (e.g. company, person, invoice, document, transaction). Pairs with entity_id to form the generic entity reference introduced in Migration20260323100000 to replace per-type FK columns. |
| entity_id | string (varchar 255) | ✅ Yes | max 255 chars; NOT NULL; composite index with entity_type; partial unique index on (entity_type, entity_id, enrichment_type) WHERE status = 'pending' AND deleted_at IS NULL AND enrichment_type = 'monthly_close' enforces one active monthly_close task per target month | — | Public UUID of the target entity (the *_id column of the referenced row, e.g. company_id, person_id, invoice_id). Stored as a string to support multiple entity types without per-type FK constraints. Composite index with entity_type. |
| status | enum (🔒 system) — native Postgres type enrichment_task_status_enum | ✅ Yes | DEFAULT ‘pending’; NOT NULL | pending | processing | completed | awaiting_approval | failed | rejected | Lifecycle state of the enrichment task. Default pending. Transitions are driven exclusively by the enrichment pipeline workers; users cannot write this field. |
| enrichment_type | string (text) — backed by Postgres type enrichment_type_enum historically but stored as text on the column | ✅ Yes | NOT NULL | logo | ai_company | ai_people | ai_invoice | ocr_extract | reconcile | provider_score | document_reconciliation_backfill | monthly_close | monthly_close_backfill | custom_column | field_rule | Identifies the enrichment worker that should process this task. Determines which Cloud Tasks handler is dispatched. See EnrichmentTypeEnum for the full controlled vocabulary. |
| input | jsonb | ⚪ No | nullable | — | Worker input payload. Shape is worker-specific. For monthly_close the dedup key is input->>'record_id' (month label); a JSONB expression partial index (idx_enrichment_tasks_input_record_id) covers lookups on that path within a workspace + status window. |
| output | jsonb | ⚪ No | nullable | — | Worker output payload written on task completion. Shape is worker-specific. For monthly_close_backfill, holds aggregate fan-out counts and request parameters. |
| target_fields | jsonb (string[]) | ⚪ No | nullable | — | Optional list of field names the enrichment worker should populate or re-evaluate. Used by custom_column and field_rule workers to scope work to a subset of columns. |
| error | text | ⚪ No | nullable | — | Error message or stack trace written by the worker when the task transitions to failed. Null on success. |
| source_channel | enum — native Postgres type source_channel_enum | ⚪ No | nullable | company_create | person_create | document_upload | ocr_completion | bank_sync | email_import | mcp_hub | cell_edit | manual | Records which product surface triggered the task. Used for attribution and observability. Added in Migration20260319120000. |
| input_hash | text | ⚪ No | nullable; index enrichment_tasks_input_hash_idx | — | Deduplication fingerprint of the input payload. Allows workers to detect duplicate enqueues with identical inputs and skip redundant work. Added in Migration20260319120000. |
| description | text | ⚪ No | nullable | — | Human-readable markdown summary of the enrichment task, populated by the worker or the pipeline orchestrator for display in the UI. Added in Migration20260327100000. |
| batch_id | UUID | ⚪ No | nullable; index enrichment_tasks_batch_id_idx; composite index idx_enrichment_tasks_batch_status on (batch_id, status) | — | Groups tasks triggered by a single user action (Magic button press). All tasks sharing a batch_id were enqueued together and can be tracked collectively. Index idx_enrichment_tasks_batch_status covers hot-path batch completion detection. Added in Migration20260327100000. |
| created_at | timestamptz (🔒 system) | ✅ Yes | NOT NULL; set once on insert | — | Row creation timestamp set by MikroORM onCreate hook. Not writable after insert. |
| updated_at | timestamptz (🔒 system) | ⚪ No | nullable; updated on every write | — | Last modification timestamp, maintained automatically by MikroORM onUpdate hook on every flush. |
| deleted_at | timestamptz | ⚪ No | nullable | — | Soft-delete timestamp. When set the row is logically deleted and filtered out of standard queries. The partial unique index on monthly_close tasks is scoped to deleted_at IS NULL. |
| completed_at | timestamptz | ⚪ No | nullable | — | Timestamp written by the worker when the task reaches completed, failed, or rejected. Distinct from updated_at to allow precise pipeline latency measurement. |
