> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mandala.md/llms.txt
> Use this file to discover all available pages before exploring further.

# Connectors and workspace data

> How connectors, capability grants, catalog mappings, sync, health, and freshness work.

Connectors bring external business records into Mandala and expose narrowly defined capabilities to agents. A connector is not considered ready merely because rows were imported once: Mandala tracks its installation, grants, schema version, health, sync state, and data freshness separately.

## Connector layers

| Layer                | Purpose                                                               |
| -------------------- | --------------------------------------------------------------------- |
| Definition           | Stable connector identity and non-secret configuration schema         |
| Version              | Immutable capability and schema contract                              |
| Installation         | Workspace-specific connection record                                  |
| Capability offering  | Read, propose, or execute operation supplied by that version          |
| Grant                | Workspace authorization to use an offered capability                  |
| Field classification | Which fields may be processed by the model                            |
| Health               | Authentication, availability, freshness, and schema compatibility     |
| External records     | Normalized snapshots and links retained inside the workspace boundary |

An agent compiles only when its required capability can be resolved through all of these layers.

## Current connectors

The repository contains:

* **Synthetic commerce:** credential-free Mandala Bean Co. data and mock procurement capabilities for repeatable tests.
* **ShipHero:** catalog, inventory, sales, purchase-order, and vendor data sync.
* **Trello:** supporting business and open-order records used by workspace questions and procurement coverage.

Connector credentials are server-only. They must never appear in terminal output, model prompts, work items, traces, or Context Engine documents.

## Workspace data catalog

Imported records are profiled into a workspace data catalog. The catalog records dataset identity, shape, maintained counts, freshness, source coverage, and a schema fingerprint.

Capability mapping versions connect a skill's declared business fields to concrete catalog datasets. Activated agents bind to an immutable mapping version so a later connector change cannot silently reinterpret an existing workflow.

Before a real-data Sandbox or manual agent run, Mandala checks that the mapping still matches the current catalog. Catalog drift triggers a refresh or blocks the run instead of guessing.

## Sync lifecycle

The connector worker:

1. claims an enabled installation;
2. authenticates with the provider using server-side credentials;
3. fetches a bounded page of records;
4. normalizes records and source links;
5. upserts snapshots with stable external ids;
6. advances a signed pagination cursor;
7. records success, error, and freshness state; and
8. publishes changed-record events for downstream catalog and Context Engine work.

Periodic reconciliation is a backup. Provider changes should normally flow through connector sync and changed-record events.

## Health and freshness

Mandala treats these as different questions:

* **Installed:** does the workspace have a connector record?
* **Authenticated:** can the server use the configured credentials?
* **Granted:** may this workspace use a particular capability?
* **Healthy:** is the provider reachable and schema-compatible?
* **Fresh:** are the required records recent enough for this workflow?
* **Complete:** did every required source participate successfully?

A stale inventory snapshot, incomplete open-order coverage, or rate-limited provider can block a procurement recommendation even when older imported rows exist.

<Warning>
  Never describe an imported snapshot as a live connector unless authentication, continuous sync, worker health, and freshness have been verified.
</Warning>

## Adding a connector

A production connector requires more than an API client:

1. Define a stable connector and versioned capability catalog.
2. Classify fields and explicitly approve model-visible paths.
3. Normalize provider records into the external-record contract.
4. Implement cursor-safe, retry-safe sync and health reporting.
5. Add workspace installation, grant, and policy setup.
6. Add catalog mapping and schema-drift tests.
7. For writes, register a controlled executor with input/output validation, idempotency, timeout, retry, reconciliation, approval, and audit behavior.
8. Prove tenant isolation and secret redaction before enabling the connector.