Enterprise sync bridge — technical guide

Business framing first: Enterprise Synchronization Fabrix — define the business once, keep systems of record authoritative, reuse the same Business Entity model for Smart RAG and Role Assistants. This page is the Build / integrator companion: how participation is declared and how propagation runs.

This guide explains how Enterprise Synchronization Fabrix works in implementation terms: what you declare on a Business Entity manifest, how runtime propagation resolves participants, and how to activate sync bridge only after the entity is already modeled for AI.

Purpose

Integrators often ask: “We already have sync, field mappings, and CIP — why isn’t point-to-point sync enough?”

Because Enterprise Synchronization Fabrix does not add a parallel sync engine. It adds a participation flag (syncBridge) on datasources that share a resourceType, then reuses:

• CIP get to read authoritative vendor state
• Normalized storage upsert into Enterprise Knowledge
• CIP update, create, and delete where the manifest and trigger type require them
• Existing authentication, trust gates, audit, and certification

Webhooks (optional) are triggers only — they never replace CIP for business data.

Core rule

Webhook / schedule / manual trigger  →  change signal
CIP get + fieldMappings              →  business data (always)
syncBridge participants              →  propagation by resourceType (never point-to-point lists)

Vendor webhook payloads are not mapped field-by-field. The platform extracts a safe subset (event type, object id, timestamp, delivery id), creates a sync intent, coalesces work, then runs the same CIP get path used for governed capabilities.

What you declare (minimal activation)

After a Business Entity is modeled (identity, mappings, CIP, capabilities, certification), enabling enterprise sync bridge is intentionally small.

1. Sync bridge mode (datasource root)

# Illustrative manifest fragment — exact shape follows external-datasource schema
syncBridge: master

There are no target datasource keys. The platform finds every published datasource with the same resourceType and syncBridge != disabled.

2. Optional webhook (change signal)

Integrator How to set (Track B): Configure webhook change signals.

{
  "webhook": {
    "enabled": true,
    "endpointMode": "datasource",
    "events": ["record.updated", "record.created"],
    "deleteEvents": ["record.deleted"],
    "idPath": "$.objectId",
    "eventTypePath": "$.subscriptionType",
    "vendorDeliveryIdPath": "$.deliveryId"
  }
}

JSONPaths extract event type and delivery id from the payload. HTTP header names for inbound validation live on Connected System authentications[] with usage: webhookInbound — not on the webhook object (schema 2.9.2+).

Generated inbound paths (POST only):

Webhook without sync bridge still refreshes local Enterprise Knowledge for that datasource. Sync bridge adds cross-datasource propagation after normalize/upsert.

3. Authentication (Connected System)

Start with one authentication credential block for normal api calls. When you enable webhooks or sync bridge, add dedicated slots with the same credential shape and a usage discriminator (webhookInbound, syncExecution) — see Configure Connected System authentication.

On-behalf-of user OAuth alone is invalid for sync bridge and webhook-triggered background jobs — use service account, client credentials, or API key suited to background execution.

Prerequisites (validation hard requirements)

Validation fails fast if the entity cannot participate safely. Hard requirements when syncBridge != disabled:

Additional rules:

Conflict policy: prefer one sync master per resourceType when multiple datasources participate in sync bridge, unless enterprise policy explicitly allows multiple sync masters. Preferred write/list ownership is a separate product concern — Write and list authority across systems (configure: Configure write and list authority).

Inbound sync (bulk/incremental jobs) is separate from sync bridge — you can run sync.enabled without sync bridge, or enable sync bridge with or without webhooks.

See also: Configure sync, Configure sync bridge, Configure webhook change signals, Configure data flow, Configure metadata and identity.

Capabilities the platform reuses (not a new API)

Enterprise sync bridge reuses the default Business Entity capability set — standard names list, get, create, update, delete on the manifest and in CIP execution.cip.operations — not a parallel sync API.

Cross-datasource propagation centers on get → normalize → upsert → update. When a participant has no linked vendor row, the coordinator may use create. delete applies to local Enterprise Knowledge state on delete signals — not vendor-side delete fan-out.

CIP owns retries, rate limits, idempotency, loop fingerprints, and execution audit — the same paths as governed capability execution. Integrators do not configure sync-bridge idempotency keys; the platform applies them internally. Do not add parallel httpx or custom sync pipelines in application code.

Detail: CIP execution.

Runtime flow (end to end)

Trigger (webhook | schedule | manual | API)
  → validate webhook auth (if webhook)
  → extract object id (idPath)
  → create SyncIntent (coalesced — do not sync inline in request thread)
  → SyncCoordinator:
       lock (resourceType + enterpriseRecordId)
       → CIP get on source datasource
       → normalize + upsert local Enterprise Knowledge record
       → resolve syncBridge participants by resourceType
       → build canonical enterprise record
       → write changed fields only to each participant (CIP update / create as needed)
       → propagation log + loop suppression
       → release lock; limited dirty retry; finding if still dirty

Platform runtime defaults (not manifest fields — applied inside the dataplane coordinator):

These are platform constants, not integrator JSON and not datasource configuration[]. Operators do not set them in env.template for a Connected System.

Participant resolution (resourceType only)

Sync bridge finds every published Business Entity with the same resourceType and syncBridge != disabled. It does not use point-to-point target lists, subscriptionFilter, or per-record dimension rules to skip participants in the current model.

subscriptionFilter on a datasource scopes Role Assistant / subscription generation, not sync-bridge participant selection. Enterprise MCP composed datasources use an explicit datasource selector at read time when multiple children exist — a different layer from sync-bridge writes.

Loop prevention

1. Origin chain — suppress self-originated webhook echo
2. Change fingerprint — hash of resource type, enterprise record id, target, normalized patch
3. No-op detection — skip write when target already matches
4. Max passes — stop and raise finding when still dirty

How to activate “sync bridge only”

Typical integrator path when CRM #1 is already AI-ready:

1. Model CRM #1 — resource type, identity, field mappings, CIP get / update, capabilities, upload, certify.

2. Set participation on CRM #1:

   syncBridge: master
   

3. Model CRM #2 — same resourceType, compatible externalId semantics, mappings, CIP operations; add syncExecution auth when enabling sync bridge.

4. Set participation on CRM #2:

   syncBridge: bidirectional
   

5. Optional — enable webhook on either side for lower latency (not required).

6. Validate and certify:

   aifabrix validate <systemKey>
   aifabrix verify-trust <systemKey>
   aifabrix verify-governance <systemKey> --subject-email scoped-user@example.com
   aifabrix lifecycle <systemKey>
   

7. Upload / publish — trust gates (when enabled) must allow publish and runtime scopes.

No new point-to-point JSON, no ETL mapping project — only join the enterprise resource type with certified CIP operations already on the manifest.

Operator and UI surfaces

Configuration is manifest-first — authored with Builder CLI or Builder API, then published to the dataplane.

Bulk job history stays on Sync; per-record CIP work appears on Logs.

Certification and trust gates

Sync bridge propagation runs through the same operational trust stack as Role Assistant capabilities:

• Continuous trust and lifecycle certification evidence
• TRUST_PUBLISH_GATE_ENABLED — blocks publish when metadata trust fails
• TRUST_RUNTIME_GATE_ENABLED — blocks CIP execution and generation inputs when runtime trust fails

Uncertified or draft datasources do not participate in production-like propagation. See Operational trust gates.

Design boundaries

The platform intentionally does not:

• Map webhook payload fields into storage (always use CIP get)
• Accept per-datasource sync target lists (resolution is by resourceType only)
• Run a separate webhook ingestion engine or point-to-point sync engine
• Invoke vendor delete APIs when processing delete webhooks (local inactive/soft-delete only)

Common mistakes

Example (two Connected Systems, one Customer resource)

CRM A webhook fires → platform validates webhookInbound auth → sync intent → CIP get on CRM A → upsert enterprise customer → CIP update on CRM B for changed mapped fields only → audit + propagation log.

Limits

• Sync bridge applies to recordStorage Business Entities. Document storage, vector stores, and static entities use ingestion sync patterns instead.
• Real-time behavior depends on vendor APIs, webhook coverage, and certification scope.
• Writable propagation requires invertible field mappings and certified update (and create when new rows are needed on a participant).
• Propagation does not filter participants by country, dimension, or subscriptionFilter — architect separate resourceType or system scope when regional fan-out must be excluded.

Related reading

• Configure sync bridge — Track B How to set
• Configure webhook change signals
• Enterprise Synchronization Fabrix — architecture and business case
• Enterprise webhooks
• Data sync and freshness
• Configure sync
• Configure data flow (CIP)
• Operational trust gates