Chapter 14 carried policy context through the agent’s internal path. The path still depends on systems outside that state model. A source supplies film classifications. An identity provider supplies profile claims. An availability service answers a live read. A watchlist API commits an effect.
Calling all four integrations connectors hides the differences that matter. Each role has a distinct trust contract and a distinct safe response to failure.
Give each connector a role
Choose a connector role, select a condition, then evaluate it. Watch the normalized decision change its payload status, next action, and retry rule. A stale ingestion record cannot establish current eligibility. An expired identity claim requires reauthorization. An unavailable optional read can produce a labeled partial answer. A timeout after a watchlist commit has an unknown outcome and must be reconciled before any retry.
Connector role
Condition
Shared envelope
- Schema
- governed-connector-v1
- Authority
- source import policy
- Provenance
- source + record + transformation version
- Times
- observed and source-effective
ingestion payload
- Record
- ratatouille-2007
- Certification
- G · source version fixture-v1
- Sync state
- current · deletion reconciled
ingestion guarantee
Versioned source records, deletion reconciliation, and policy-bounded freshness.
The envelope keeps the role-specific payload intact while exposing authority, provenance, freshness, quota, status, and effect state.
The four roles are:
- Ingestion connectors copy source records into an index or governed store. Their contract owns source identity, schema version, provenance, freshness, deletion, and reconciliation.
- Identity connectors establish verified claims about a principal or workload. Their contract owns issuer, subject, audience, validity, assurance, and revocation behavior.
- Live-read connectors retrieve current external facts during a trajectory. Their contract owns query scope, response freshness, provenance, timeout, rate limit, and whether the task can continue without the result.
- Action connectors create effects. Their contract owns authorization, validation, idempotency, commit status, reconciliation, and audit evidence.
An enterprise system uses the same roles for document synchronization, workforce identity, inventory lookup, and ticket creation. Product names change. The boundary questions do not.
Treat every input as an assertion
A connector response becomes usable only after the application validates the parts needed for its role. Schema validation proves shape rather than truth. Authentication proves which system sent a value rather than whether the value is current enough for this operation. Provenance identifies the source and transformation history. Freshness determines whether the assertion still satisfies policy.
The synthetic classification ingestion fixture records a source id, source record version, observed time, schema version, and policy-relevant classification. The index should retain that provenance beside the derived searchable record. When the source changes or deletes a record, reconciliation can identify which index entries must change.
Identity requires comparable precision. A receiver validates the trusted issuer, intended audience, validity period, subject, actor when delegated, and scopes needed for the proposed operation. A profile label produced by the model or copied through unsigned metadata cannot replace that verification.
Design failure as part of the contract
Connector failures are typed states rather than generic exceptions. The harness needs enough structure to decide whether to proceed, narrow, pause, reauthorize, reconcile, or stop.
| Failure | Safe response |
|---|---|
| stale authorization input | stop or refresh before eligibility is decided |
| expired identity | reauthorize, then reevaluate policy |
| optional live source unavailable | narrow the completion condition and label the result partial |
| required live source unavailable | pause or stop within the trajectory budget |
| response schema mismatch | quarantine the payload and surface connector drift |
| timeout around a write | reconcile the original operation before retrying |
Retries need budgets and semantics. Reads are often safe to retry when requests are bounded and the remaining latency budget permits it. Writes require an idempotency contract or another deduplication mechanism. RFC 9110 distinguishes idempotent methods because a client can repeat them after a communication failure without intending another effect. Application APIs often extend that protection with an idempotency key tied to one exact operation.
If a watchlist request times out after the service commits it, the client does not know whether the effect occurred. Reusing the same key for the same payload lets the service return the original outcome. Reusing a key for a different payload must fail. Issuing a new key and repeating the write can create a second effect.
Make partial completion explicit
A live connector does not always need to succeed for the user to receive value. A film recommendation may remain supported when current streaming availability is unavailable, provided the answer says availability was not verified. A compliance check may have no such fallback.
The completion condition belongs to the product and policy rather than to the connector. It should state which evidence is required, which sources are optional, how stale each assertion may be, and which missing facts force refusal. The agent can then narrow a task without quietly changing what “done” means.
Observe the boundary without copying its secrets
Connector events should record role, operation, target, policy and schema versions, provenance reference, freshness class, attempt count, latency, status, typed error, idempotency reference, and reconciliation state. As in the preceding two chapters, credentials and sensitive payloads stay under separate controls.
Chapter 12’s three evaluation units make those fields actionable. A step assertion checks one connector result for the expected schema, authority, freshness, status, and effect state. A trajectory assertion checks that failures caused the promised response: no stale certification entered ranking, no wrong-audience identity continued, no optional-source fallback became a complete answer, and no ambiguous write was replayed before reconciliation. An outcome assertion checks that the answer and any external effect stayed supported by the surviving evidence and authority. Trace completeness is part of each judgment because an unexplained gap can hide the boundary that changed the result.
These events connect the three parts of the course. Part I established how evidence becomes searchable and measurable. Part II established how a bounded agent chooses and evaluates work. Part III established which evidence may enter the path, how authority remains current, and how external boundaries can change the path’s status.
Governed search is therefore observable system behavior rather than a promise placed around a model. Each boundary supplies a decision the next stage can inspect: candidate eligibility, current authority, or a typed connector outcome. When a boundary cannot establish what the next stage needs, the trajectory narrows, reconciles, or stops.