ConnectorSyncDiagnostic

ConnectorSyncDiagnostic is an infrastructure-layer audit log that captures structured failure and informational signals emitted by SyncConfigService during MCP connector sync execution. Each row records the exact tool invoked, the target entity model being synced, the reason the sync event was notable (a failure class or an informational signal such as jury telemetry or pipeline degradation), and a free-text detail message. Rows are tenant-scoped to a Workspace and linked to the specific WorkspaceConnector that triggered the sync. Retention is opportunistic: ConnectorSyncDiagnosticService.write() prunes rows older than 30 days for the current connector on approximately 1-in-20 writes — no separate scheduled job is needed.

Naming	Value
Object	ConnectorSyncDiagnostic
Resource type (JSON:API `type`)	`connector_sync_diagnostic`
Collection / records root	— _{(not a records root)}
REST base	`/v1/connector-sync-diagnostics`
Entity class	`ConnectorSyncDiagnostic`

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/connector-sync-diagnostics`	🟡 Planned
Retrieve	`GET /v1/connector-sync-diagnostics/{id}`	🟡 Planned
Create	`POST /v1/connector-sync-diagnostics`	🟡 Planned
Update	`PATCH /v1/connector-sync-diagnostics/{id}`	🟡 Planned
Delete	`DELETE /v1/connector-sync-diagnostics/{id}`	🟡 Planned

Data model

Attributes

Field	Type	Required	Constraints	Allowed values	Description
diagnostic_id	string (UUID)	✅ Yes	unique; default gen_random_uuid()	—	Public-facing UUID for this diagnostic row. Generated by the database on insert; never set by the caller.
target_model	enum (TargetModelEnum) — native DB enum target_model_enum	✅ Yes	NOT NULL; values are the native DB enum	company \| people \| invoice \| transaction \| account \| ledger_account \| journal \| journal_entry \| email \| payment_means \| invoice_transaction \| document	The Well entity model the connector was attempting to sync when this diagnostic was recorded.
tool_name	string (text)	⚪ No	nullable	—	Name of the MCP tool that was selected or attempted (e.g. pennylane_get_invoices). Null when the failure occurred before tool selection.
reason	enum (SyncFailureReasonEnum) — native DB enum sync_failure_reason_enum	✅ Yes	NOT NULL; values are the native DB enum	no_suitable_tool \| tool_not_found \| auth_scope_insufficient \| tool_execution_failed \| empty_result \| jsonata_generation_failed \| schema_drift_detected \| jury_run \| jury_partial \| jury_disagreement \| jury_quorum_lost \| blueprint_persistence_failed \| mapped_entities_dropped \| mapped_entities_partial_drop \| fk_parent_missing \| entity_persist_failed \| sync_fk_dag_cycle \| regression_reverted \| target_skipped \| structured_pipeline_degraded \| structured_pipeline_fell_back_to_legacy \| mapping_generation_hard_fail \| tool_selection_pinned	Taxonomy code classifying the sync event. Values in INFORMATIONAL_REASONS (jury_run, jury_disagreement, schema_drift_detected, target_skipped, structured_pipeline_degraded, structured_pipeline_fell_back_to_legacy, tool_selection_pinned) are non-blocking signals; all others are FAILURE class.
http_status	integer	⚪ No	nullable	—	HTTP status code returned by the upstream MCP tool call, when available. Absent for failures that occur before an HTTP round-trip (e.g. mapping generation failures).
detail	string (text)	✅ Yes	NOT NULL	—	Human-readable description of the failure or informational event. Written by SyncConfigService at the point of detection; not machine-parsed.
occurred_at	timestamp with time zone	✅ Yes	NOT NULL; default now(); set by onCreate hook	—	Wall-clock timestamp at which the sync event occurred. Set once on insert; not updated. Distinct from created_at to support future back-dated ingestion of diagnostic events.
created_at	timestamp with time zone	✅ Yes	NOT NULL; default now(); set by onCreate hook	—	Row creation timestamp. Set once by the MikroORM onCreate hook.
updated_at	timestamp with time zone	⚪ No	set by onCreate and onUpdate hooks	—	Row last-updated timestamp. Maintained automatically by MikroORM.
deleted_at	timestamp with time zone	⚪ No	nullable	—	Soft-delete timestamp. When non-null the row is logically deleted. Pruning in ConnectorSyncDiagnosticService.write() hard-deletes rows older than 30 days for the current connector.

Relationships

Name	Type	Required	Description
workspace	to-one (ManyToOne)	✅ Yes	The tenant workspace that owns this diagnostic. FK column workspace_pk references core_api.workspaces(pk) with ON UPDATE CASCADE ON DELETE CASCADE. Used to scope diagnostic queries per tenant.
workspaceConnector	to-one (ManyToOne)	✅ Yes	The specific WorkspaceConnector instance (provider + auth config) whose sync run produced this diagnostic. FK column workspace_connector_pk references core_api.workspace_connectors(pk) with ON UPDATE CASCADE ON DELETE CASCADE. Retention pruning is scoped to this connector's rows.

System-computed

diagnostic_id — generated by gen_random_uuid() at DB level; never supplied by the caller
occurred_at — set to now() by MikroORM onCreate hook at insert time
created_at — set to now() by MikroORM onCreate hook at insert time
updated_at — set to now() by MikroORM onCreate and onUpdate hooks
deleted_at — set by application-level soft-delete; also used as the threshold for opportunistic hard-delete pruning (rows older than 30 days for the current connector are pruned inside ConnectorSyncDiagnosticService.write() on approximately 1-in-20 writes)
pk (internal) — serial auto-increment; not exposed via the public API

Example

{
  "data": {
    "type": "connector_sync_diagnostic",
    "id": "a3f7e812-0c2e-4d1b-9b4a-001122334455",
    "attributes": {
      "diagnostic_id": "a3f7e812-0c2e-4d1b-9b4a-001122334455",
      "target_model": "invoice",
      "tool_name": "pennylane_get_invoices",
      "reason": "mapped_entities_dropped",
      "http_status": 200,
      "detail": "Validator rejected 12/12 mapped entities: required field 'issue_date' null after JSONata mapping for tool pennylane_get_invoices",
      "occurred_at": "2026-06-01T14:32:07.000Z",
      "created_at": "2026-06-01T14:32:07.000Z",
      "updated_at": "2026-06-01T14:32:07.000Z",
      "deleted_at": null
    },
    "relationships": {
      "workspace": {
        "data": { "type": "workspace", "id": "wsp_abc123" }
      },
      "workspace_connector": {
        "data": { "type": "workspace_connector", "id": "wsc_xyz789" }
      }
    }
  }
}

_{Source: apps/api/src/database/entities/ConnectorSyncDiagnostic.ts · domain: ingestion · tier: Infrastructure}