Make Interfaces and Data Explicit

An interface is not explicit because its JSON parses.

A schema can confirm that equipmentId is a string. It cannot tell you whether the value is a trusted unique key, a search hint, a historical identifier, or a value that can match multiple active records. An HTTP response can be 200 OK while a downstream operation later fails. A message can be delivered once while the business effect occurs twice. A version number can change without anyone knowing which consumer assumption broke.

Forward deployed systems fail at these semantic seams.

OpenAPI 3.2.0 and AsyncAPI 3.0.0 provide versioned machine-readable descriptions for HTTP and message-driven interfaces. JSON Schema Draft 2020-12 provides a vocabulary for structural validation. These are valuable. They do not by themselves establish business meaning, ownership, ordering, consistency, timeout, retry, observability, support, or reconciliation. [CLM-041] [CLM-042] [CLM-047]

Turn every material arrow into a contract

Chapter 6 left Orchid with named relationships. Chapter 7 creates an interface catalog, semantic data contract, and reconciliation structure. These are original synthesis tools for this book, not formal standards. [CLM-049]

Each record contains:

• interface ID, purpose, owner, consumers, and support path;
• protocol/transport and specification version;
• operation/message and business intent;
• actor/workload identity and authorization context;
• request/event schema and semantic field definitions;
• response/result and completion meaning;
• consistency, ordering, freshness, and authoritative proposition;
• timeout, retry, rate/capacity, and backpressure behavior;
• idempotency/intent/conflict/retention behavior;
• error taxonomy and user/workflow state;
• observability/correlation/audit;
• compatibility/version/deprecation/migration;
• exception and reconciliation owner;
• test/verification evidence and known gaps.

“GET inventory” is not a contract. A useful relationship might say:

Orchid reads the latest reported availability proposition for selected part/site pairs under the Region West workload identity. The response includes source version and observed-at time. It is evidence, not a reservation guarantee. A timeout or stale result moves the workflow to inventory-uncertain; no automatic order occurs. ERP owns meaning and availability; the adapter owns translation, validation, correlation, and safe state.

Write semantic field definitions

For each material field, record:

• name and type/format;
• business meaning and non-meaning;
• source/owner and derivation;
• units, timezone, precision, locale, encoding;
• required/optional/nullable/unknown distinctions;
• valid domain and invariants;
• freshness/observed/effective time;
• sensitivity/residency/retention;
• missing/invalid/conflicting behavior;
• version/change compatibility;
• examples using synthetic data.

Example:

equipmentId

• Type: string matching the current synthetic format in the companion.
• Meaning: identifier of an equipment candidate as supplied by the equipment registry.
• Non-meaning: not proof that the candidate uniquely matches the ticket.
• Owner: registry team for identifier proposition; service/domain owner for match rule.
• Required for: confirmed equipment state, not raw request ingestion.
• Invalid/multiple: workflow blocks suggestion and enters reconciliation.
• Provenance: registry version and observation timestamp retained.

The companion implements this distinction. A synthetic record can satisfy structural fields and still fail the Region West residency rule. The validator is deliberately small and provider-neutral; it demonstrates that semantic checks sit alongside structure.

Model time explicitly

Distributed customer data frequently has several times:

• event occurred;
• source observed or effective time;
• source recorded time;
• message emitted time;
• consumer received/processed time;
• cache/index updated time.

“Current inventory” is meaningless without the relevant time and decision. A part count observed hours ago may be adequate for planning and inadequate for reservation. A manual version approved last week may be current even if indexed later.

Contracts should state which time governs ordering/freshness, timezone, clock uncertainty, late-arrival behavior, and whether backdated correction is possible.

Separate missing, null, unknown, not applicable, and redacted

These states are often collapsed:

• missing: field absent;
• null: explicit empty value under schema meaning;
• unknown: value exists conceptually but is not known;
• not applicable: proposition does not apply;
• redacted/withheld: value intentionally unavailable under policy;
• invalid: supplied value violates structure/semantics;
• stale: value exceeded decision-specific freshness;
• conflicting: sources/candidates disagree.

Each can require a different workflow action. Coercing all to an empty string creates silent business behavior.

Make idempotency about caller intent

HTTP specifies method semantics, including idempotent methods. Application-level retry safety still depends on business intent and implementation. [CLM-043]

Suppose a client asks to reserve part P-7 for ticket T-9 and receives no response. A retry should represent the same intent only when the caller says it does. The service needs an intent/request identifier and a semantic fingerprint.

The contract defines:

• who creates the intent ID and its scope;
• which fields define semantic equivalence;
• behavior for same ID/same fingerprint;
• behavior for same ID/different fingerprint;
• pending/unknown/completed/rejected states;
• retention/expiry and late arrival;
• replayed result and audit;
• concurrency and race behavior;
• reconciliation after ambiguous completion;
• compensation/cancellation where relevant.

First-party AWS engineering guidance describes client request identifiers and the need to distinguish repeated requests from new intent. The pattern is useful, but no quantitative outcome is claimed here. [CLM-044]

The companion IntentLedger demonstrates:

• first intent begins as pending;
• same ID/same semantics replays state/result;
• same ID/different semantics raises conflict;
• missing response moves state to unknown;
• reconciliation supplies final effect rather than blind retry.

The first Orchid scope keeps ERP integration read-only. The ledger prepares the concept without authorizing a write path.

Do not promise exactly-once business effects

Messaging systems may provide delivery or processing guarantees under defined conditions. Business effect crosses storage, external systems, side effects, consumer state, retries, and human actions.

An “exactly once” label does not establish that:

• the same event was not published twice under different IDs;
• two consumers did not create equivalent effects;
• an external API effect and local commit remained atomic;
• replay did not repeat a non-idempotent action;
• manual reconciliation did not duplicate work;
• a late event did not override newer intent.

Exactly-once business effects are not obtained by labeling delivery exactly once. [CLM-048]

Prefer precise statements: at-least-once delivery with idempotent consumer under these keys; ordered within this partition; deduplicated for this retention window; effect reconciled against this authoritative state; duplicate/late/conflict paths tested.

Define an error taxonomy

Avoid one generic error field.

Classify:

• invalid request/schema;
• semantic validation failure;
• authentication/authorization denial;
• not found versus ambiguous match;
• conflict/version mismatch;
• rate/capacity/backpressure;
• dependency unavailable;
• timeout before/after possible acceptance;
• stale/incomplete evidence;
• policy/control block;
• internal defect;
• unknown operational state.

For each class, state:

• stable code and human-safe message;
• retryability and backoff/limit;
• workflow state and permitted actions;
• correlation/audit fields;
• data disclosure boundary;
• support owner and escalation;
• reconciliation path.

Never tell a client to retry an ambiguous operation without specifying intent and status behavior.

Specify request/response completion step by step

For each operation, draw a completion timeline:

1. caller creates intent and local state;
2. request leaves caller;
3. provider authenticates/authorizes;
4. provider validates structure/semantics;
5. provider accepts or rejects intent;
6. business effect commits, queues, or remains pending;
7. provider records result/status;
8. response returns or is lost;
9. caller records known/unknown state;
10. caller or operator reconciles if necessary.

The client timeout can occur between any two steps. A contract should say which states are possible, not pretend timeout means failure.

For a read, ambiguity may concern freshness or partial results rather than side effects. For a write, it concerns whether an effect occurred. For an asynchronous job, acceptance and completion are deliberately separate.

Define status lookup where practical:

GET /intents/{intentId} might return pending, completed, rejected, unknown, or expired, plus result/error/provenance. The exact endpoint is optional; the semantic capability is not when the caller can lose a completion response.

If the provider cannot expose status, document the reconciliation alternative and risk. Do not invent certainty at the adapter.

Design event contracts around facts, not commands disguised as facts

An event should state what occurred under whose authority and at which time/version.

Compare:

• UpdateInventory: command asking an owner to act;
• InventoryReservationAccepted: fact that an intent was accepted, not necessarily fulfilled;
• InventoryReservationCommitted: fact that the defined effect reached committed state;
• InventoryAvailabilityObserved: evidence of availability at an observation time, not a promise.

An event contract records:

• event ID/type/schema version;
• producer/owner and proposition;
• subject/aggregate key and tenant/region;
• occurred/effective/recorded/emitted time;
• correlation, causation, and intent IDs;
• payload semantics/provenance/sensitivity;
• ordering scope;
• delivery/replay/retention expectations;
• consumer idempotency and unknown-version behavior;
• correction/tombstone/retraction behavior;
• operational support and dead-letter/reconciliation path.

AsyncAPI can describe message-driven interfaces, but the contract still needs these domain/operating decisions. [CLM-041] [CLM-047]

Late and out-of-order evidence

Suppose availability observation A occurred at 10:00 and B at 10:05, but B is processed first. Arrival order should not silently overwrite event-time meaning. State what order matters and how late evidence is handled.

For workflow decisions, a late correction may require reopening or annotating an earlier decision rather than mutating history. The audit record should preserve what evidence was available when the person acted.

Preserve lineage through transformations

Orchid Assist derives evidence from customer records. A data contract should trace:

• source system/record/version;
• extraction/query/adapter version;
• normalization/mapping rules;
• validation results and exceptions;
• retrieval/index version;
• derived field or ranking method;
• observation/effective/processing times;
• downstream decision/audit reference.

Lineage does not require one massive platform. For the bounded slice, stable references and transformation versions may be enough.

If a manual paragraph is presented, record document ID/version/section and retrieval/index version. If inventory is shown, record observed-at/source version and freshness state. If equipment is matched, record candidates and confirmation evidence. This enables a user, tester, incident responder, or auditor to reconstruct the basis of the decision without copying unnecessary sensitive content.

Correction behavior

When source data is corrected, decide:

• Does the derived index/cache update automatically?
• Are prior decisions re-evaluated or only annotated?
• Which active cases must be alerted?
• Can a corrected identifier merge/split histories?
• Who approves correction of an audit or business record?
• How is the original state preserved?

These are workflow decisions, not generic database updates.

Design interface security without hiding it in headers

The interface catalog should describe:

• caller identity and credential type;
• resource/operation/tenant/region authorization;
• field/data filtering by purpose;
• replay/impersonation/confused-deputy risks;
• secret/token rotation and expiry needs;
• audit/correlation;
• denial/error disclosure;
• rate/abuse limits;
• break-glass or support access where relevant.

Do not copy live credentials into examples. The companion remains local and synthetic. Chapter 8 supplies the concrete identity flow; Chapter 10 supplies the control/evidence matrix.

Make capacity and backpressure part of the contract

An interface that works for one request can fail under workflow demand or retry amplification.

Record:

• expected and bounded request/event volume;
• concurrency and burst assumptions;
• rate limits/quotas and response semantics;
• queue capacity/age and overflow behavior;
• client retry/backoff/jitter/limit;
• load shedding and priority;
• timeout budgets across dependencies;
• user-visible wait/fallback;
• capacity owner and review signal.

If an adapter retries every timeout immediately, it can turn dependency degradation into an outage. If it queues indefinitely, users may act on stale evidence. Backpressure must map to workflow state.

Test the contract at several layers

Schema tests

Accept/reject structural fixtures, including unknown fields and versions.

Semantic tests

Validate units, region/tenant, status combinations, freshness, identifier meaning, and policy invariants. The companion’s Region West residency case shows a structurally plausible record failing semantics.

Consumer/provider contract tests

Verify both sides against versioned examples and errors. A mock is useful only if it represents the documented provider behavior.

Failure and timing tests

Inject timeout before acceptance, timeout after possible commit, late/out-of-order event, duplicate, conflicting intent, rate limit, partial result, unavailable status, and reconciliation.

Data-quality tests

Exercise missing, invalid, stale, conflicting, duplicated, and incorrectly mapped records with workflow actions.

Operational tests

Confirm correlation, metrics/logs, alerts/queues, runbook, support access, and recovery. Contract correctness without diagnosis is incomplete.

Compatibility tests

Run old consumer/new provider and new consumer/old provider under the declared promise. Verify rollback and migration state.

Tests are evidence for specified cases, not proof that every production interaction is safe.

Walk through the companion foundation

The companion is intentionally small.

contracts.mjs validates a synthetic equipment record. It checks structure-like rules and semantic rules such as Region West residency. It produces a stable fingerprint only after validation.

reconciliation.mjs preserves:

• no active candidate -> missing;
• one distinct active equipment ID -> confirmed;
• multiple distinct active IDs -> ambiguous;
• missing external response -> completion unknown.

intent-ledger.mjs records intent ID, semantic fingerprint, pending/completed/unknown state, replay, conflict, and reconciliation. It does not claim distributed durability or concurrency safety; it is a deterministic teaching model. Later chapters may replace in-memory storage behind the same behavior while retaining tests.

Seven initial tests prove the bounded behaviors. They do not prove customer ERP semantics, which remain a dependency gap.

Lab sequence

1. Run npm run test:companion.
2. Change a synthetic west record to east residency and observe semantic rejection.
3. Add two active equipment IDs and observe ambiguous rather than arbitrary selection.
4. Begin/complete an intent and replay it.
5. Reuse the ID with a different fingerprint and observe conflict.
6. Mark completion unknown after timeout and reconcile it.
7. Add a late-arrival test and define the expected state before coding.

The exercise is complete only when the learner can explain the workflow consequence of every state.

Review a sample interface record

IF-OA-INV-READ

Purpose. Supply read-only inventory evidence for a confirmed equipment/part/site context.

Owner/consumer. ERP team owns interface and inventory propositions; Orchid adapter consumes/translates; inventory operations owns business semantics; Orchid support owns first diagnosis.

Identity. Region-bound workload identity; read selected fields only; no order/reservation permission.

Request. Part ID, site ID, region/tenant, correlation; equipment/ticket context remains in Orchid audit and is minimized at ERP where not required.

Result. availability state/count where permitted, observed/effective time, source version, status; not a guarantee/reservation.

Freshness. Decision-specific threshold owner required; stale state remains visible and may block/escalate.

Timeout/error. Timeout produces inventory-uncertain; no automatic external effect. Rate/unavailable/denied/invalid are distinct.

Retry. Read may retry under bounded policy; user sees wait/fallback; retry amplification is measured.

Reconciliation. Re-read/status under owner-defined behavior; support queue for persistent conflict/staleness.

Version. Versioned schema and semantic contract; breaking meaning changes require migration/consumer tests.

Evidence. Synthetic contract/failure tests now; customer sandbox/production semantics later.

This record is longer than an endpoint declaration because it prevents each consumer from inventing the missing behavior.

Build data-quality rules from decisions

ISO/IEC 25012 defines a general structured-data quality model. Use such models as a vocabulary for contextual requirements, not universal thresholds. [CLM-045]

Orchid quality rules should trace to workflow consequence:

• equipment match uniqueness/completeness;
• manual approval/version/freshness;
• inventory observed-at/freshness for the decision;
• ticket state/assignment consistency;
• provenance/reference resolvability;
• regional/tenant correctness;
• approval identity/completeness;
• audit correlation/completeness.

Each rule contains definition, population, severity, detection, action, exception owner, measurement, and trend. A schema-valid record can fail any of these.

Design reconciliation as normal operation

Reconciliation is not only incident cleanup. Distributed boundaries can disagree during ordinary timeouts, late updates, manual corrections, and eventual consistency.

A reconciliation plan identifies:

• propositions compared;
• authoritative owner for each;
• comparison key and time/window;
• mismatch categories;
• automatic versus human decision;
• safe state during uncertainty;
• correction source and audit;
• retry/replay rules;
• queue/age/alert/support owner;
• closure evidence.

For equipment candidates, the companion preserves missing, confirmed, and ambiguous states. It does not choose the first valid record. For external completion, it preserves unknown when a response is absent.

Version the public contract

Semantic Versioning communicates compatibility expectations only after a public API is declared. It does not solve deployment or data migration compatibility by itself. [CLM-046]

Record:

• contract version and public compatibility promise;
• provider/consumer versions in use;
• backward/forward compatibility;
• additive field behavior and unknown-field rules;
• default/semantic changes;
• deprecation notice/owner/date;
• dual-read/write or translation window;
• data migration/backfill;
• rollback compatibility;
• contract tests and production evidence.

A change from “equipmentId is unique” to “equipmentId is a candidate” may be semantically breaking even if the JSON type remains string.

Use interface specifications honestly

OpenAPI, AsyncAPI, and JSON Schema can generate docs, clients, validators, mocks, and contract tests. Version them with the implementation.

Do not infer:

• runtime availability from generated docs;
• authorization correctness from a security-scheme declaration;
• semantic compatibility from schema compatibility;
• delivery/ordering guarantees from a message channel name;
• safe retry from a method label;
• support ownership from a contact field.

The interface catalog links formal specs to the missing operational/semantic records. [CLM-047]

Handle contract change without semantic drift

Consider three changes.

Add a field

The registry adds equipmentClass. Structurally, an optional field may be backward compatible. Semantically, consumers may start using it before its coverage, authority, and change process are understood.

Record population/unknown semantics, provenance, owner, quality, version adoption, and what behavior is prohibited when absent. Unknown fields should not crash a tolerant consumer, but tolerated fields do not automatically enter decision logic.

Change meaning without changing type

status: active once meant installed and serviceable. It now means not retired, including equipment awaiting commissioning. The JSON remains valid and the enum remains unchanged. The change is semantically breaking for service eligibility.

Use semantic contract versions, owner notice, consumer impact review, historical/backfill behavior, and dual interpretation/migration where necessary. A schema diff will not find it.

Split one identifier into candidates

The ticket field previously assumed one equipment ID. Discovery proves it can contain an alias that resolves to multiple records.

Do not preserve the illusion through arbitrary selection. Change the workflow contract to candidate set plus confirmed match evidence. This breaks consumers that require one ID, but it repairs a false invariant.

Compatibility should protect valid consumer expectations, not preserve a dangerous meaning.

Minimize data at the interface boundary

An interface can be semantically rich and still transfer too much data.

For each field ask:

• Which operation/decision needs it?
• Can a reference, category, derived signal, customer-run query, or redacted value suffice?
• Does the provider need the caller’s full workflow context?
• Does the consumer need the source payload or only selected propositions/provenance?
• How long must it persist and where?
• Can logs/errors expose it?
• Which region/tenant/purpose applies?

For Orchid, inventory may need part/site identifiers but not full technician notes. Retrieval may need an approved equipment/manual scope but not unrestricted service history. Audit may need decision references and identity/control evidence without copying every retrieved paragraph.

Minimization can complicate diagnosis. Solve that with correlation, customer-controlled evidence, derived state, and approved support access rather than default replication.

Treat reconciliation workload as a capacity decision

An exception queue can grow faster than humans resolve it. A design that safely detects ambiguity but creates an unstaffed queue is not operable.

Estimate or bound:

• arrival by exception family/segment;
• age and consequence;
• handling time and required qualification;
• owner capacity and hours/regions;
• duplicate/related-case grouping;
• escalation and expiry;
• automation permitted for classification versus decision;
• signal/alert thresholds and backlog stop rule.

The fictional case lacks measured arrival/handling values, so OA-05 records them as required before rollout. The first scope can limit cohort volume and block expansion if the queue exceeds the accepted state.

Create a contract review packet

Before accepting an interface, provide:

• specification/schema/version;
• semantic dictionary and examples;
• identity/authorization/data handling;
• time/consistency/ordering;
• errors/timeouts/retry/intent;
• capacity/backpressure;
• quality/lineage/reconciliation;
• compatibility/migration/deprecation;
• ownership/support/operability;
• test evidence and gaps;
• affected workflow/outcome/guardrails;
• reviewer/decision dispositions.

Reviewers should be able to reject “technically valid” behavior that violates workflow meaning.

Orchid OA-05 interface and data section

The dossier now includes:

Interface catalog. Ticket, equipment, manual, inventory, identity/approval, audit, signals/config relationships with owners and support.

Data contract. Equipment/request/evidence/inventory/approval fields with proposition meaning, provenance/time, residency/sensitivity, quality, invalid/unknown/conflict behavior.

Intent and completion. Correlation and idempotent intent model; ERP writes remain deferred; ambiguous completion has explicit unknown/reconciliation state.

Errors. Stable taxonomy mapped to workflow states, retry rules, user messages, audit, support.

Quality/reconciliation. Decision-linked rules and ownered queues/closure evidence.

Versioning. Public contract, consumer compatibility, migration/deprecation/rollback evidence.

Companion. Synthetic validation, candidate reconciliation, completion classification, and intent ledger tests run locally.

Interface failure modes

Schema equals contract

Repair: add proposition meaning, time, owner, failure, operation, and reconciliation.

Retry equals resilience

Repair: define intent, ambiguity, limits, backoff, status, and effect.

Exactly-once label

Repair: state delivery/processing/effect boundary and tests precisely.

Canonical-model overreach

One model tries to represent the enterprise before the bounded workflow is understood.

Repair: define the minimum semantic contract and translations for the selected path.

Null coercion

Repair: preserve missing/unknown/not-applicable/redacted/invalid/stale/conflicting states.

Version is a number only

Repair: declare compatibility promise, consumers, migration, rollback, deprecation, tests.

Reconciliation has no owner

Repair: make uncertain state visible with queue, age, decision, owner, and closure evidence.

The Chapter 7 gate

Before fitting the customer environment, OA-05 must contain:

• complete interface catalog for selected path;
• schema plus semantic field contracts;
• proposition ownership, time, provenance, and quality;
• identity/authorization context requirements;
• timeout/retry/idempotent-intent/completion states;
• error taxonomy and workflow actions;
• ordering/consistency/backpressure where relevant;
• version/compatibility/deprecation/migration;
• reconciliation and support ownership;
• executable companion tests for critical missing/ambiguous/conflict behavior.

The gate passes when a consumer can implement safe behavior without guessing what a string, timeout, duplicate, missing value, or version means.

Chapter 8, Fit the Customer Environment, places these contracts inside real topology, regional/tenant, network, identity, secret, configuration, capacity, and environment constraints.