Description
Sync Binding Management gives users and automation a durable record of what source should synchronize into what Dots destination. A connector binding links a connected account and provider resource to a target Dotabase. A local-directory binding links a physical folder to a Dotabase, while local-repository bindings target the code-graph estate. Each binding owns its schema strategy, field mapping, cadence, cursor checkpoint, health status, and last-run information.
The lifecycle is available through API routes and the dots sync CLI family. Users can create bindings, list or inspect them, run one immediately, pause future work, update health, or delete the relationship. Company-scoped services validate that referenced connections and targets belong to the same tenant, while connector and local-source schedulers read only the binding kinds they own.
Selling Points
- Make recurring imports explicit. A binding records the source, target, mapping, and schedule instead of hiding them in a one-off command.
- Control operations without editing data. Pause, run-now, status, and delete actions manage the relationship independently of imported rows.
- Reuse one lifecycle across source types. Connected providers, local folders, and local repositories share a consistent management vocabulary.
- Resume from durable checkpoints. Cursor state belongs to the binding, allowing engines to restart safely.
- Automate the full workflow. CLI and API surfaces let scripts create and operate bindings end to end.
User Story
A knowledge lead connects a provider, selects one source resource, and binds it to an existing Dotabase with a daily cadence. They check status after the backfill, trigger an immediate run before a review, then pause the binding while reorganizing the source. The imported rows remain available throughout because lifecycle controls act on synchronization, not the destination content.
Extension Surface
This feature is automatable because the complete lifecycle is drivable through packages/cli/src/commands/sync.ts and the routes in packages/api/src/routes/connectors.ts. The validation contract in packages/api/src/schemas/connectors.ts accepts connector, local-directory, and local-repository binding shapes with bounded cadence and mapping options. It does not provide a plugin registration point of its own; new source behavior comes from the Source Connector Framework or local ingestion engines.
Capabilities & Limits
Capabilities include create, list, detail, run-now, pause, health update, and delete operations; schema strategies for mirroring or mapping; manual and scheduled cadence; durable cursor state; and company-scoped validation. Bindings can recover from error or stalled-backfill states through scheduler-owned retry metadata.
Limits are deliberate. Router target mode is rejected, so a connector binding must resolve a concrete Dotabase target, except when mirror_new creates one. Local sources do not carry connection ids, connector sources require them, and pausing prevents future scheduled runs but does not roll back rows already imported. Binding management also does not guarantee a provider run succeeds when credentials, permissions, or quotas fail.
Implementation Map
packages/connectors/src/services/binding-service.tspackages/api/src/schemas/connectors.tspackages/api/src/routes/connectors.tspackages/cli/src/commands/sync.ts