Skip to main content
Sometimes the evidence an operational record needs lives in a tool Driftless does not own: a Notion page, a record in another system. The Broker is how a Collection reaches that evidence through a governed, audited Connection, reads it, and lands it in the right primitive, without ever treating it as Knowledge or as a normal context retrieve. This guide gives you an executable read-only path and a clearly-marked conceptual write path, because writes are not generally available today.
The Broker is gated. It is off by default in production (DRIFTLESS_BROKER_ENABLED), the external OAuth/MCP lane is a separate switch (DRIFTLESS_BROKER_ROLLOUT), and external callers additionally need a per-principal grant. The one production connector is Notion, Beta and read-only. No write operation is invokable in production (the operation-policy registry ships empty).

​
Outcome

A specific external fact pulled into the object that needs it: a Notion page’s content read live and written into a Record or a Note, with its provenance preserved and its status as external evidence (not Knowledge) kept explicit.

​
When to use it

  • A Record has a concrete information gap, and the answer lives in a connected external tool.
  • You have already confirmed the fact is not in Driftless (no Topic, no existing Record, no connector document covers it).
  • You want the evidence in operational state, cited, not silently promoted into the team’s Knowledge.

​
Availability and prerequisites

Setup (connect a provider) happens in the dashboard or CLI, never over MCP, and is a privileged human-led flow. An external OAuth/MCP caller also needs the rollout open and a matching grant; an internal caller (an owned API key or a dashboard session) skips the grant gate but still needs the rest.

​
Objects involved

​
Before you begin

Check whether the Broker surface is even reachable for you. An empty list is ambiguous: it can mean “not rolled out” or “no grant”, not “nothing connected”.
If this returns nothing, stop and resolve the gate (rollout or grant) before assuming the provider is disconnected. A healthy Connection shows status synced.

​
Context preflight

External work still starts with the team’s context. Read the work object’s Knowledge before you reach outside for more:
A Connection can also carry its own criterion: Knowledge topic slugs attached with broker criterion <provider> --add <slug>. The Broker never reads the topic’s content; it points at the slug, and you read it with your context tools before a risky operation. Only after this context confirms a real, specific gap do you go external. Do not pull the whole provider; fetch the one fact the work needs.

​
Step-by-step workflow

​
Read-only path (executable)

1

Confirm the capability is ready

A registered capability is not a usable one. Read the capability directory and use only a capability whose status is ready.
gated and disabled are the states most easily mistaken for available: the capability is real but the environment or your grants keep it closed.
2

Inspect the operation you intend to run

Read the full spec before you call anything: input schema, effect (read / write), risk, idempotency, and criterion.
3

Choose the right read

The reads differ in whether they hit the provider live and what, if anything, they create in Driftless. Pick deliberately:
records returns a synced model from the mirror; page-content reads one page live and bounded, with a citation. Normal context retrieve never queries a provider, so it is not how you reach fresh external data.
4

Land the evidence in the right primitive

Write what you found into operational state, not into Knowledge: a field on the Record or a standalone Note cited to its source.

​
Conceptual write path (gated)

A write would follow the same governed shape, and it is worth understanding even though it is not invokable in production today:
The full shape: inspect the operation, read its criterion, confirm the grant covers it, pass an idempotency key so a retry is a safe manual replay, invoke it (execution is inline, there is no approval queue), read the returned correlation id from the audit ledger, and remember writes never auto-retry. After it runs, verify the result against the provider. None of this is available in production while the operation-policy registry ships empty; treat the block above as illustrative, not a live call.

​
Expected states

​
Knowledge write-back

External evidence updates operational state; it does not become Knowledge on the way in:
  • A current value goes on the Record, cited to the source.
  • A shared identity discovered externally becomes or updates an Entity.
  • An observation worth keeping becomes a Note, not a Topic, unless a person later reviews it.
  • Provenance is preserved only as far as the surface supports it: a connector document carries a citation, provenance, and freshness and reads as trust: "external"; for a raw read, cite the page id or record id in the Note yourself.
A provider snapshot is external evidence, never institutional truth. It stays operational state or a cited Note. Do not merge it into Knowledge because it came from a trusted-looking tool.

​
What not to do

  • Do not confuse connected with usable. A healthy OAuth Connection is the first rung; the capability must be ready, the rollout open, and a grant present.
  • Do not treat external data as Knowledge. Connector documents are opt-in in retrieve, carry trust: "external", and are never Knowledge.
  • Do not expect retrieve to fetch live external data. It reads only Driftless-owned tables (Topics and connector documents), never a provider.
  • Do not author or deploy an operation the Broker does not list. Report the missing capability; never write a script to fill the gap.

​
Troubleshooting

  • broker connections is empty against a healthy connection. The external lane is closed (rollout: off) or no grant matches your principal. Grants are owner/admin managed; an internal caller skips the grant gate.
  • A capability shows gated or disabled. It is registered but withheld by rollout, a missing grant, or a toggle. It is not usable until it reaches ready.
  • A read returns empty rather than an error. By design: when the lane is closed or no grant matches, reads return an empty result, so treat empty as “check the gates”, not “no data”.

​
Limits and truth states