ReconciliationLink

ReconciliationLink records a single AI-produced assertion that two distinct entity records represent the same real-world object (source → target). Each link carries the reconciliation action (e.g. merge), a confidence score, structured reasoning, and an optional field_contributions breakdown describing how individual field signals contributed to the match. The link is workspace-scoped, soft-deletable, and optionally tied to a human-review Task when the confidence is below auto-accept thresholds. It is written exclusively by the reconciliation pipeline (reconciliation-persister.ts) and is read-only from the user API layer.

Naming	Value
Object	ReconciliationLink
Resource type (JSON:API `type`)	`reconciliation_link`
Collection / records root	— _{(not a records root)}
REST base	`/v1/reconciliation-links`
Entity class	`ReconciliationLink`

Internal object. Not currently exposed on the public REST API. The operations below describe the intended contract.

API operations

Operation	Method & path	Status
List	`GET /v1/reconciliation-links`	🟡 Planned
Retrieve	`GET /v1/reconciliation-links/{id}`	🟡 Planned
Create	`POST /v1/reconciliation-links`	🟡 Planned
Update	`PATCH /v1/reconciliation-links/{id}`	🟡 Planned
Delete	`DELETE /v1/reconciliation-links/{id}`	🟡 Planned

Data model

Attributes

Field	Type	Required	Constraints	Allowed values	Description
reconciliation_link_id	string (UUID)	✅ Yes	unique	—	Public identifier for this reconciliation link, generated by `gen_random_uuid()`. Exposed on all API responses; used as the canonical external reference.
source_type	string	✅ Yes	varchar(100)	—	Entity type string for the source record (e.g. `company`, `people`). Together with `source_id` identifies the left-hand side of the match assertion.
source_id	string	✅ Yes	varchar(255)	—	Public UUID of the source entity record. Used with `source_type` to resolve the entity without a FK constraint, supporting heterogeneous entity graphs.
target_type	string	✅ Yes	varchar(100)	—	Entity type string for the target record — the candidate that the reconciliation pipeline identified as matching the source.
target_id	string	✅ Yes	varchar(255)	—	Public UUID of the target entity record. Used with `target_type` to resolve the candidate entity.
relationship	string	✅ Yes	varchar(100)	—	Semantic label for the nature of the match (e.g. `duplicate`, `same_company`, `alias`). Determined by the reconciliation agent’s strategy.
action	string	✅ Yes	varchar(50)	—	Operational action the pipeline intends to take when the link is applied (e.g. `merge`, `link`). Used as an index dimension for the workspace-scoped tenant lookup index.
confidence	number (numeric)	✅ Yes	numeric(5,4)	—	Reconciliation confidence score in the range [0, 1] expressed to 4 decimal places. Determines whether the link is auto-applied or routed to human review.
reasoning	string (text)	✅ Yes	text	—	Human-readable explanation generated by the reconciliation agent summarising why the source and target were matched.
field_contributions	object[] (JSONB) \| null	⚪ No	jsonb, nullable	—	Ordered list of `FieldContribution` objects, each describing one field signal that contributed to the confidence score. Schema: `{ source_field, candidate_field, claimed_match_type, verified_match_type, signal, weight }`.
status	🔒 system — enum (link_status_enum)	✅ Yes	native enum `link_status_enum`; default `active`	active \| pending_review \| rejected	Lifecycle state of the reconciliation link. Defaults to `active` on creation. Transitions to `pending_review` when confidence falls below the auto-apply threshold; set to `rejected` by the human reviewer or system.
created_at	🔒 system — Date	✅ Yes	timestamptz, not null, default now()	—	Timestamp set by `onCreate` hook when the link is first persisted. Never updated.
updated_at	🔒 system — Date	⚪ No	timestamptz, set by ORM hooks	—	Timestamp refreshed by `onCreate` and `onUpdate` MikroORM hooks on every write. Reflects the last mutation made by the pipeline.
deleted_at	🔒 system — Date \| null	⚪ No	timestamptz, nullable	—	Soft-delete timestamp. Null when active. Set by the reconciliation pipeline when a link is superseded or retracted. All workspace-scoped queries filter `deleted_at IS NULL`.

Relationships

Name	Type	Required	Description
workspace	to-one (ManyToOne)	✅ Yes	Tenant boundary. Every reconciliation link belongs to exactly one Workspace. Cascade delete: the link is hard-deleted when the workspace is deleted. Indexed via `idx_reconciliation_links_workspace` on `workspace_pk`.
review_task	to-one (ManyToOne, nullable)	⚪ No	Optional reference to a Task created for human review of this link. Set when confidence is below the auto-accept threshold. FK delete rule: set null — the link persists if the review task is deleted.

System-computed

reconciliation_link_id — generated via gen_random_uuid() database default on INSERT; never supplied by the caller
created_at — set by MikroORM onCreate hook (new Date()); never updated
updated_at — set by MikroORM onCreate and onUpdate hooks; refreshed on every flush
deleted_at — managed by the reconciliation pipeline; set to a timestamp on soft-delete; queries must always filter deleted_at IS NULL
status — defaults to LinkStatusEnum.ACTIVE (‘active’) at ORM layer; transitioned by the reconciliation persister and review workflow, never by user PATCH
pk — auto-increment serial primary key; internal join key only, never exposed in API responses
field_contributions — populated by the reconciliation scorer at write time; null when the scoring pass did not produce per-field breakdown data

Example

{
  "data": {
    "type": "reconciliation_link",
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "attributes": {
      "reconciliation_link_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "source_type": "company",
      "source_id": "7f3e2a1b-0c4d-5e6f-a7b8-c9d0e1f23456",
      "target_type": "company",
      "target_id": "2b4d6f80-a1c3-e5f7-9012-b3c4d5e67890",
      "relationship": "duplicate",
      "action": "merge",
      "confidence": 0.9312,
      "reasoning": "Both records share the same SIREN number, registered address, and principal email domain. High-confidence deduplication candidate.",
      "field_contributions": [
        {
          "source_field": "tax_id_value",
          "candidate_field": "tax_id_value",
          "claimed_match_type": "exact",
          "verified_match_type": "exact",
          "signal": "siren_match",
          "weight": 0.5
        },
        {
          "source_field": "domain",
          "candidate_field": "domain",
          "claimed_match_type": "exact",
          "verified_match_type": "exact",
          "signal": "domain_match",
          "weight": 0.3
        }
      ],
      "status": "active",
      "created_at": "2026-03-19T12:00:00.000Z",
      "updated_at": "2026-03-19T12:00:00.000Z",
      "deleted_at": null
    },
    "relationships": {
      "workspace": {
        "data": { "type": "workspace", "id": "ws-uuid-0001" }
      },
      "review_task": {
        "data": { "type": "task", "id": "task-uuid-0042" }
      }
    }
  }
}

_{Source: apps/api/src/database/entities/ReconciliationLink.ts · domain: financial-graph · tier: Supporting}

Main objects

Supporting objects

Platform objects

Activity objects

Infrastructure objects

API operations

Data model

Attributes

Relationships

System-computed

Example

​API operations

​Data model

​Attributes

​Relationships

​System-computed

​Example

API operations

Data model

Attributes

Relationships

System-computed

Example