13 Build interfaces around intent

An intent-oriented operation lets a caller request a meaningful outcome while the system owns the incidental steps required to achieve it. The idea is attractive because agents can otherwise spend many calls reconstructing a workflow that the software already understands.

The danger is that a convenient operation can hide decisions the caller should control.

“Make this model available” could mean download artifacts, choose a version, install a runtime, modify configuration, reserve memory, or start a process. Some of those may be required by the contract. Others may be surprising side effects. The operation is not well designed until those choices are explicit.

Compress choreography without hiding authority

Consider two interfaces. The first exposes every filesystem and catalog action. The caller must sequence them correctly and recover from partial failure. The second accepts a resource identity and readiness requirement, then performs the necessary acquisition and publication under a defined contract.

The second can be simpler for callers because the provider owns a domain invariant. It should still expose consequential choices: allowed substitutions, retention behavior, whether runtime installation is authorized, and what counts as ready.

An intent interface is therefore not a license for the system to infer every preference. It should reduce irrelevant representation knowledge while preserving the decisions that affect the user's outcome.

Add the missing domain transition

The standards engine provides a concrete example. Its authoring workflow could create initial policies for a new standard and revise existing policy scopes. But it lacked a supported way to register a new policy scope inside an existing standard. A legitimate domain transition was missing from the interface.

The repair added a registration edit within the existing proposal mechanism. The author supplies the owner and policy identity and the intended scope. The engine owns placement, registry handling, ordering, and validation. The design did not require a raw file-edit API, another service, or a second graph. Inspected tests check preservation of existing content, stable treatment of identities, grouped validation, and failures that do not mutate the predecessor. Inspected registration tests and replay and mutation-resistance tests provide the direct examples. Historical reports record broader qualification; this book did not rerun it. Registration plan; implementation.

The lesson is about expressibility. A caller should be able to request the domain change it is authorized to make without learning incidental storage mechanics.

Define the success boundary

For acquisition, the operation might return a receipt identifying the attempt, selected resource, published artifact, and readiness claim. The receipt should not imply that all future uses will succeed. It establishes the bounded result promised by the operation.

Partial progress should remain distinguishable. The bytes may be present while checks are pending. A runtime may be installed while loading fails. If the operation returns early, its response should represent an admitted or running task rather than final success.

This matters for composability. A workflow engine may use the response to decide which node can run next. If it mistakes admission for completion, the convenience API has exported a race into every consumer.

Make retry semantics part of the operation

A caller that loses a response needs to know whether repeating the call continues the same intended action or starts another. Stable operation identity can help, but the meaning must be defined. An idempotency key that silently accepts different parameters is dangerous; a key that never expires may create its own retention and collision problems.

A useful design distinguishes same intent retried, changed intent, and a new attempt after a terminal result. It provides an authoritative lookup when the outcome is uncertain. The exact implementation can vary, but the caller should not have to infer these semantics from timing.

Retain an escape path at the correct level

High-level operations do not remove the need for diagnostics or specialized use. A caller may need to inspect why readiness failed or request a narrower artifact-only outcome. Provide those capabilities deliberately rather than exposing internal mutation as an emergency workaround.

The test for an intent interface is whether a new caller can use it correctly from its contract. Ask that caller to perform normal acquisition, handle a missing capability, and resolve a lost response. If each path requires private knowledge, the interface has not yet absorbed the choreography it claims to own.