AVOO Interfaces | How Roles Exchange State, Authority and Work

Most complex systems do not fail because every part is bad.

They fail because good parts meet badly.

The diagnosis is correct but arrives too late. The plan is sound but the Operator receives only an instruction, not the reason. The Operator completes the action but nobody knows what evidence should return. Two teams use the same word to mean different things. One system reports success while the next system expects a different state. A role changes an assumption without telling the role that depends on it.

AVOO Interfaces is the layer of the Architect, Visionary, Oracle and Operator framework that asks how roles, teams, tools and institutions exchange state, authority, evidence and work without losing meaning at the boundary.

The central question is:

When one part of the system hands something to another, what exactly must cross the boundary so the receiving side can act correctly?

This article continues the AVOO sequence after AVOO Legibility. The boundary is deliberate. Legibility owns whether relevant state is visible and interpretable. Interfaces owns the contract by which that state, responsibility and work move between system parts.

The wider series begins with What Is AVOO? and How AVOO Works.

The short answer

An interface is a controlled boundary through which one system part exchanges information, authority, material, work or state with another.

The Architect defines the interface contract and protects interoperability.
The Visionary ensures that the interface preserves purpose instead of reducing every exchange to a technical transaction.
The Oracle supplies evidence, confidence, interpretation and uncertainty in a form the receiving side can use.
The Operator consumes the interface, performs the work and returns the result through another interface.
Governance determines who may change the interface and which fields or approvals are mandatory.
The Receiver Loop closes the interface by returning evidence about what actually landed.

The core rule is:

A hand-off is safe only when the receiving side knows what object arrived, what state it is in, what authority came with it, what assumptions travel with it, what action is expected and what receipt must return.

Interfaces are where local excellence becomes system performance

A strong Oracle can still fail the system if the evidence arrives in a form the Architect cannot interpret.

A strong Architect can still fail if the Operator receives an elegant design that cannot be executed under real constraints.

A strong Visionary can still fail if future direction cannot be translated into design choices.

A strong Operator can still fail if field friction has no route back into diagnosis and redesign.

System quality is therefore not merely the sum of component quality.

It also depends on boundary quality.

A useful systems-engineering parallel

NASA treats interface management as a formal systems-engineering activity because development is often divided across products, organisations, contractors and geographically distributed technical teams. Its guidance emphasises interface requirements, responsibilities, change control, traceability, validation across both sides of the interface and documentation of interface anomalies and lessons learned.

That principle generalises far beyond spacecraft.

Whenever two parts of a system must interoperate, the interface deserves design rather than assumption.

Research anchors: NASA — Interface Management · NASA — Interface Requirements Document Outline.

Interface versus hand-off

A hand-off is an event.

An interface is the structure that makes repeated hand-offs predictable.

One teacher tells another, “She is weak in algebra.” That is a hand-off.

An interface would define what “weak” means, what evidence supports it, which algebraic structures are affected, what has already been tried, what the next teacher owns and what future evidence should return.

One team says, “The feature is ready.” That is a hand-off.

An interface defines whether ready means coded, reviewed, tested, deployed, verified, documented or accepted by the receiver.

Interfaces replace ambiguous social memory with repeatable structure where repeatability matters.

The seven interface contracts

A mature AVOO interface can be decomposed into seven contracts.

Object contract: what exact thing crosses the boundary?
Semantic contract: what do the fields and words mean?
State contract: what lifecycle state is valid at hand-off?
Authority contract: what permissions and decision rights travel with it?
Timing contract: when must the exchange happen and how long is it valid?
Error contract: what happens when the hand-off is incomplete, invalid, delayed or contradictory?
Receipt contract: what must return to prove the exchange actually worked?

These seven contracts are not bureaucracy for its own sake.

They are the minimum vocabulary for making repeated coordination reliable.

1. Object contract

The receiving side should know exactly what it is receiving.

a diagnosis;
a decision;
a task;
a claim;
a draft;
a dataset;
a release candidate;
a student state;
a risk;
a permission;
a receiver complaint;
a recovery instruction.

If the object is not clear, the receiving side cannot know which rules apply.

“Here is the document” is weaker than “Here is the approved release candidate for Article X, version 3, with evidence packet Y and unresolved blocker Z.”

2. Semantic contract

Two sides can exchange the same words and still exchange different meanings.

“Complete.”

“Approved.”

“Current.”

“High confidence.”

“Urgent.”

“Canonical.”

Every one of these words can hide a semantic mismatch.

The semantic contract defines the meaning that both sides must share.

Where the cost of mismatch is high, important states should be typed rather than left as adjectives.

STATUS ∈ {
  DRAFT,
  REVIEWED,
  APPROVED,
  RELEASE_INTENT_RECORDED,
  REMOTE_OBSERVED,
  RENDER_VERIFIED,
  OUTCOME_UNKNOWN,
  FAILED,
  RETIRED
}

Typed state reduces interpretive freedom where interpretive freedom would be dangerous.

3. State contract

The object must arrive in a valid state.

A draft should not enter a release interface as if it were approved.

A preliminary diagnosis should not arrive as certainty.

An external action should not be represented as complete merely because an attempt was made.

The state contract therefore answers:

What state is required before this boundary can be crossed?
What state is forbidden?
What transition occurs after crossing?
What evidence proves the transition?

This turns hand-offs into state transitions rather than conversational impressions.

4. Authority contract

Information can cross an interface without authority.

Authority can also cross without enough information.

Both are dangerous.

The authority contract answers:

Who may propose?
Who may challenge?
Who may decide?
Who may execute?
Who may stop?
Who must be informed?
What authority expires after the event?

Related: AVOO Governance.

5. Timing contract

A correct hand-off can still fail if it arrives on the wrong clock.

An Oracle warning delivered after the decision is not operationally equivalent to the same warning delivered before it.

A student diagnostic delivered after the exam has different value from the same diagnostic delivered six months earlier.

A dependency discovered after integration has a different cost from the same dependency discovered during design.

NASA’s interface-management guidance explicitly notes that changing interface requirements late in a design or implementation life cycle is more likely to affect cost, schedule and technical design.

The timing contract therefore defines:

deadline;
validity period;
freshness;
review time;
response window;
expiry;
escalation time if no response arrives.

6. Error contract

Interfaces should define failure before failure happens.

What happens if:

a required field is missing;
two sources disagree;
the receiver rejects the object;
the operation times out;
the action may have succeeded but cannot be verified;
the state has changed since the packet was prepared;
permission is missing;
the interface version is incompatible?

A weak system leaves these questions to improvisation.

A stronger system names error states explicitly.

MISSING_REQUIRED_STATE
AUTHORITY_INSUFFICIENT
VERSION_MISMATCH
STALE_PACKET
RECEIVER_REJECTED
OUTCOME_UNKNOWN
CONFLICTING_EVIDENCE
DEPENDENCY_UNAVAILABLE

7. Receipt contract

The interface is not complete merely because something crossed it.

The sender needs evidence about what happened next.

The receipt contract defines:

what success looks like;
what external state proves it;
who observes the result;
when the receipt is due;
what happens if the receipt conflicts with the expected state.

Related: AVOO Receiver Loop.

The canonical AVOO interface packet

A practical AVOO packet can carry twelve fields.

ID: what exact object or task?
From: which role or owner?
To: which role or owner?
State: what is true now?
Purpose: why does this hand-off exist?
Evidence: what supports the state?
Uncertainty: what remains unresolved?
Authority: what may the receiver decide or execute?
Constraints: what limits the next move?
Threshold: what condition changes the route?
Expected action: what should happen next?
Receipt: what evidence must return?

This is not the only possible packet.

It is a useful default because it separates state from purpose, evidence from authority and action from receipt.

Interfaces should expose contracts, not internal implementation

Modern software architecture offers another useful parallel.

Microsoft’s Azure Architecture guidance recommends treating an API as a contract between services and avoiding interfaces that simply expose internal implementation details. It also notes that side-effecting operations benefit from idempotent design because safe retries improve resilience.

The general principle transfers well:

An interface should expose what the other side needs to rely on, not every internal detail of how the producing side works.

Research anchor: Microsoft Azure Architecture Center — API Design.

The interface should survive internal change

If every internal refactor breaks every dependent team, the boundary is too tightly coupled.

A good interface preserves a stable contract while allowing internal improvement.

This is one reason modular systems scale more gracefully.

The interface holds.

The inside can evolve.

Interface versioning

Interfaces change.

The danger is changing them silently.

A field changes meaning.

An approval requirement is added.

A threshold moves.

A receiving team still operates against the old contract.

Versioning makes interface evolution explicit.

current version;
effective date;
changed fields;
migration instructions;
compatibility window;
retirement date;
owner of the change.

This links directly to AVOO Memory.

Change authority

Not everybody who uses an interface should be able to redefine it.

NASA’s interface-requirements guidance explicitly calls for responsibility and change authority to be defined.

AVOO applies the same principle.

Who owns the interface?
Who may propose changes?
Who must validate both sides?
What evidence justifies a breaking change?
What migration obligation exists?
What receiver is affected?

Without change authority, interfaces drift through local convenience.

Interface drift

Interface drift occurs when the practical exchange changes while the documented contract remains the same.

a required field becomes optional in practice;
a temporary workaround becomes normal;
one team begins relying on undocumented information;
the meaning of “complete” shifts;
a manual approval disappears informally;
a receiver starts returning a different receipt;
a threshold changes without updating the hand-off packet.

Interface drift is dangerous because both sides can believe they are compliant while operating under different contracts.

Interface debt

Interface debt accumulates when repeated local exceptions are absorbed without redesigning the boundary.

manual translation between teams;
repeated clarification meetings;
duplicate data entry;
custom adapters everywhere;
unclear escalation paths;
silent retry behaviour;
missing version control;
tribal knowledge about what the hand-off “really means.”

Experienced Operators often hide interface debt by compensating personally.

When they leave, the debt becomes visible.

Semantic mismatch

Semantic mismatch is one of the most common interface failures because it can survive apparently successful communication.

Both sides use the same word.

Both sides believe they agree.

They do not.

Examples:

“approved” means editorial approval to one side and legal release approval to another;
“mastery” means one correct attempt to one teacher and durable transfer to another;
“published” means remote save to one system and rendered public verification to another;
“urgent” means same day to one team and next hour to another.

The repair is not more words.

It is shared definitions tied to observable state.

State-transition mismatch

Two systems can agree on words but disagree on what transition is allowed.

One system permits:

DRAFT → PUBLISHED

Another requires:

DRAFT
→ REVIEWED
→ APPROVED
→ RELEASE_INTENT_RECORDED
→ PUBLISHED
→ VERIFIED

If those systems are joined without an explicit transition contract, one side can create states the other side does not recognise as legitimate.

This is why state machines matter in human processes too.

Authority mismatch

Authority mismatch occurs when the receiving side assumes permission that the sending side did not grant—or when the sender assumes the receiver can act but the receiver lacks authority.

a teacher recommends a change but only the coordinator can approve it;
an analyst identifies a risk but cannot stop release;
an AI model proposes an external write but the tool requires explicit user confirmation;
a local team sees the need to reroute but only central architecture can change the interface.

Authority should travel as an explicit field, not an assumption.

Retry safety

Interfaces become especially dangerous when an action may be repeated after an uncertain outcome.

The first attempt times out.

Did it fail?

Did it succeed but the acknowledgement fail?

If the sender retries blindly, the operation may happen twice.

Software engineering uses idempotency to make some repeated operations safe: performing the same intended operation again does not produce an additional unintended effect.

AVOO extends the principle to operational systems.

stable operation identity;
known expected state;
remote reconciliation;
safe retry only after state is checked;
explicit OUTCOME_UNKNOWN when success cannot be proven.

Never use repetition as a substitute for state reconciliation.

The OUTCOME_UNKNOWN state

OUTCOME_UNKNOWN is one of the most important interface states because it protects the system from inventing certainty after a broken acknowledgement path.

The rule is:

ATTEMPTED
→ no reliable acknowledgement
→ OUTCOME_UNKNOWN
→ inspect remote state
→ reconcile
→ continue or repair

OUTCOME_UNKNOWN is not failure.

It is not success.

It is a legitimate state that requires evidence before the next transition.

Interface observability

An interface should reveal enough about its own health to diagnose failures.

hand-off attempted;
hand-off accepted;
hand-off rejected;
latency;
version;
validation failure;
missing field;
authority failure;
receipt returned;
receiver mismatch.

This is where AVOO Legibility and Interfaces meet.

The interface carries the exchange.

Legibility lets the system see whether the exchange is healthy.

The Architect and interfaces

The Architect’s interface questions are:

Where should boundaries exist?
What crosses each boundary?
What should remain hidden behind the boundary?
What state must be valid before crossing?
What semantics must both sides share?
How will versioning work?
How will errors be represented?
What evidence returns?

A strong interface reduces coupling without destroying necessary context.

The Visionary and interfaces

Interfaces can make systems efficient while gradually stripping purpose from the exchange.

A form captures fields but not meaning.

A workflow captures completion but not receiver harm.

A metric captures output but not why the output matters.

The Visionary asks which parts of meaning must cross the boundary even if they are harder to compress.

Purpose is sometimes interface data.

The Oracle and interfaces

The Oracle must package evidence without pretending interpretation is fact.

A strong Oracle interface distinguishes:

observation;
source;
inference;
confidence;
alternative explanation;
missing evidence;
decision relevance.

This allows the receiving role to understand not merely the answer but the evidence state behind it.

The Operator and interfaces

The Operator experiences interface quality directly.

A good interface answers:

What do I have?
What does it mean?
What may I do?
What must I not do?
What do I do if it fails?
When do I escalate?
What do I return afterward?

If the Operator needs repeated clarification for ordinary cases, the interface is under-specified.

Interfaces and incentives

AVOO Incentives matters because interface design changes behaviour.

If escalation requires a painful form, people escalate less.

If a quality hand-off takes ten minutes while a shallow hand-off takes ten seconds, the system incentivises shallow context transfer.

If the interface makes receiver feedback difficult, internal completion becomes more attractive than receiver success.

Interfaces are therefore behavioural architecture as well as information architecture.

Interfaces and resilience

AVOO Resilience depends on alternate interfaces.

fallback route;
backup owner;
degraded-mode contract;
emergency authority;
recovery interface;
receiver communication.

A backup component is useless if nobody knows how to connect to it.

Resilience requires not only alternate capacity but alternate interfaces that have been defined and tested.

Interfaces and optionality

AVOO Optionality is often created through stable interfaces.

If two components can be replaced independently because their boundary is stable, the system retains future choice.

If every component reaches into every other component’s internals, switching becomes expensive.

Good interfaces are therefore one of the mechanisms by which optionality becomes structural rather than aspirational.

Interfaces and scale

Small teams can survive weak interfaces because people fill gaps socially.

Large systems cannot rely on everyone knowing everyone else.

Scale therefore increases the value of:

stable contracts;
shared identifiers;
typed states;
versioning;
change authority;
error semantics;
receipts;
interface ownership.

This is why AVOO Scale shifts attention from personal relationships toward protocols and interoperability.

Interfaces in education

Education contains many hidden interfaces.

teacher to student;
student to assessment;
teacher to parent;
teacher to teacher;
primary to secondary;
lesson to homework;
diagnosis to intervention;
feedback to revision.

A weak educational interface says:

Practise more.

A stronger interface can say:

Current state: algebraic sign handling unstable. Evidence: three repeated errors across two question forms. Confidence: high. Next action: repair signed-number transformations before returning to equations. Receipt: solve three near-transfer items independently after a delay.

The second hand-off gives the receiving learner, parent or teacher something operational.

Interfaces in teamwork

Team hand-offs fail when responsibility crosses but context does not.

“Can you take this?”

Take what?

With what authority?

By when?

What has already been tried?

What does success mean?

A team interface does not need to become bureaucratic for every trivial task.

But consequential hand-offs benefit from explicit object, owner, state, next action and receipt.

Interfaces in publishing

Publishing at scale depends on interfaces between commission, research, drafting, review, release and verification.

A publication interface should distinguish:

commissioned versus drafted;
drafted versus reviewed;
reviewed versus approved;
approved versus released;
released versus remotely observed;
remotely observed versus rendered correctly;
rendered correctly versus indexed externally.

These are not synonyms.

The interface should also carry:

canonical owner;
collision result;
evidence scope;
approval scope;
protected-page status;
SEO metadata;
publication identity;
receipt.

This is how publishing throughput can increase without pretending every save is a verified release.

Interfaces in AI systems

AI systems make interface design especially important because a model can move between natural language, tools, memory, external systems and human approval.

Each boundary should distinguish:

proposal versus authorised action;
inference versus retrieved fact;
internal plan versus external side effect;
tool attempt versus tool result;
tool result versus verified external state;
temporary context versus durable memory;
high confidence versus permission to act.

The AI interface should be narrow enough to protect authority and broad enough to preserve decision-relevant context.

One critical rule is:

A model’s confidence belongs to the evidence interface. It does not automatically belong to the authority interface.

This prevents fluent output from becoming action permission by accident.

Interfaces in institutions

Institutions are networks of interfaces.

citizen to agency;
frontline to management;
agency to ministry;
professional to regulator;
budget to programme;
research to policy;
law to operation;
complaint to remedy.

Institutional failure often appears at these boundaries.

The evidence exists but cannot enter the decision route.

The policy exists but does not translate into executable procedure.

The complaint exists but cannot identify an owner.

The local Operator sees the problem but the escalation packet cannot cross the hierarchy.

Institutional quality therefore depends not only on good departments but on good boundaries between them.

Interfaces at civilisation scale

Civilisation is full of interfaces between independently governed systems.

law and markets;
science and policy;
education and employment;
finance and production;
cities and transport;
energy and industry;
media and public understanding;
institutions and citizens;
nations and international systems.

No central actor owns every boundary.

Compatibility therefore depends on standards, protocols, law, shared definitions, negotiated authority and public receipts.

Civilisation-grade interface design is one reason standards can have enormous leverage.

A standard does not need to control every internal implementation.

It defines enough of the boundary for independently designed parts to work together.

Related: What Is Civilisation?.

The interface audit

A strong AVOO interface audit asks:

What exact boundary are we examining?
What object crosses it?
Do both sides use the same semantics?
What state is required before crossing?
What authority travels with the object?
What authority remains outside the interface?
What timing or freshness rules apply?
What happens when the exchange fails?
Can uncertain outcomes be represented without guessing?
Who may change the contract?
What version is current?
What receipt proves the exchange worked?

The AVOO Interface Card

For any consequential interface, write:

Name: what boundary is this?
From: who sends?
To: who receives?
Object: what crosses?
Semantics: what do the fields mean?
Required state: what must be true before crossing?
Authority: what may the receiver do?
Timing: when is the packet valid?
Error states: what can go wrong?
Version: which contract applies?
Change owner: who may alter the interface?
Receipt: what must return?

Almost-code: AVOO Interfaces

INTERFACE = {
  name,
  from,
  to,
  object_type,
  semantics,
  required_state,
  authority,
  timing,
  error_contract,
  version,
  change_owner,
  receipt_contract
}

PACKET = {
  id,
  purpose,
  state,
  evidence,
  uncertainty,
  constraints,
  threshold,
  expected_action,
  expected_receipt
}

BEFORE handoff:
  validate(object_type)
  validate(required_state)
  validate(authority)
  validate(version)
  validate(freshness)

IF validation_fails:
  reject_with_typed_error()

IF send_attempted AND acknowledgement_missing:
  state = OUTCOME_UNKNOWN
  reconcile_remote_state()

IF receiver_accepts:
  transition_state()
  execute_within_authority()

receipt = RECEIVER.return()

IF receipt != expected_receipt:
  reopen_diagnosis()

IF interface_change_requested:
  route_to(change_owner)
  assess_compatibility()
  version_if_needed()

MEMORY.save({
  packet_id,
  interface_version,
  prior_state,
  new_state,
  actor,
  timestamp,
  receipt
})

The deepest interface problem: every boundary compresses meaning

An interface exists because two sides cannot share everything.

So the boundary compresses.

A diagnosis becomes a label.

A strategy becomes a task.

A student becomes a score.

A receiver becomes a metric.

A complex institution becomes a form.

Compression is necessary.

But every compression loses information.

The deepest interface skill is deciding what must survive the compression.

The Architect preserves what the next system needs.

The Visionary preserves why it matters.

The Oracle preserves evidence and uncertainty.

The Operator preserves the friction reality creates.

The Receiver Loop preserves consequence.

World Return

The World Return of AVOO Interfaces is simple:

Do not assume a good sender creates a good hand-off. Design the boundary. Define the object, meaning, state, authority, timing, errors and receipt. Then let both sides validate the contract against reality.

Do not let “complete” mean whatever the current team needs it to mean.

Do not move responsibility without moving enough context.

Do not move authority without naming its limits.

Do not retry uncertain external actions until state is reconciled.

Do not change a widely used interface silently.

And do not call the hand-off successful merely because the sender finished sending.

Final definition

AVOO Interfaces is the boundary-contract layer of the Architect, Visionary, Oracle and Operator framework. It defines how state, meaning, authority, evidence, work and receipts move between roles, teams, tools and institutions. It uses explicit object types, shared semantics, valid state transitions, bounded authority, timing rules, error states, versioning, change control and receiver receipts to make repeated hand-offs predictable without overexposing internal implementation. Its purpose is not to make every boundary rigid. Its purpose is to make consequential boundaries reliable enough that local excellence can become system performance.

Research anchors

Continue the AVOO series

Related routes: CivOS Runtime · AVOO Under Pressure · What Is Civilisation?