Interface-Contract Category Map¶
Domain model map — instantiates Composable Relation Modeling
Models software modules as objects and their interface contracts as typed arrows, with a named owner keeping the contract map authoritative.
An Interface-Contract Category Map is the specialization of the object–arrow idea to software interfaces: the objects are modules or services, the arrows are the contracts by which one calls another, and each arrow carries a promised type discipline — required inputs, guaranteed outputs, and preconditions. What makes it this mechanism and not a generic diagram is that its arrows are enforceable obligations, not just "there is a call here," and that it is a governed artifact: one named owner keeps it authoritative, because a contract map that drifts from reality is worse than none. Its invariant of interest is the contract itself — the property a caller may rely on across the interface — and its central discipline is source/target typing at the boundary: the map declares, for each arrow, exactly what type of thing may be sent and what type comes back, so that incompatible wirings are visible on the map rather than discovered in production.
Example¶
A payments team owns a checkout flow spread across five services — cart, pricing, tax, payment-gateway, and ledger. Integrations keep breaking in ways nobody can locate, because "who promises what to whom" lives only in scattered code and tribal memory. They build an Interface-Contract Category Map. Each service is an object; each inter-service call is a typed arrow labeled with its contract: pricing → tax sends a PricedCart and must receive a TaxedCart, with the precondition that every line item already carries a currency. The invariant of interest is stated on each arrow as the promise a caller can bank on: tax guarantees idempotence, so retrying the call never double-charges.
Crucially, the map has a governance owner — a named engineer accountable for keeping it true — because the first draft is already wrong: it shows payment-gateway → ledger sending a Receipt, but the code actually sends a SettlementBatch, and the type mismatch is exactly why nightly reconciliation fails. The map surfaces the discrepancy as a typing violation at a specific arrow, and the owner drives the fix and updates the map. From then on, a proposed new integration is checked against the map's contracts before it is built, and "we assumed that call returned a Receipt" stops being a class of bug.
How it works¶
- Objects are modules; arrows are contracts. Draw a service as an object and each interface it exposes-and-consumes as a directed arrow, labeled not merely "calls" but with the contract's obligations.
- Type both ends of every arrow. Declare the required input type and guaranteed output type for each contract, plus preconditions. An arrow whose ends are untyped is a promise no one can check.
- State the invariant each contract upholds. Idempotence, ordering guarantees, authentication assumptions — the properties a caller is entitled to rely on, recorded on the arrow.
- Assign one owner. A single accountable party keeps the map synchronized with the deployed reality and adjudicates proposed changes, because an unowned contract map decays into fiction.
The map declares and governs contracts; it does not itself run the composites or prove the algebraic laws — it is the authoritative source those checks read from.
Tuning parameters¶
- Contract granularity — one arrow per service pair vs. one per individual endpoint/method. Fine granularity documents precise obligations but multiplies arrows; coarse granularity is readable but hides which specific call broke.
- Typing strictness — how precisely input/output types and preconditions are pinned. Strict typing catches more mismatches at the map but demands more upkeep as interfaces evolve.
- Invariant richness — how many guarantees each contract records (just types, or also idempotence, ordering, latency). Richer contracts prevent subtler misuse but are harder to keep true.
- Governance cadence — how often the owner reconciles the map against deployed reality. Frequent reconciliation keeps the map trustworthy; infrequent reconciliation is cheap until the map quietly goes stale.
When it helps, and when it misleads¶
Its strength is that it makes interface obligations explicit, typed, and owned, so integration failures that used to appear only "after a chain of individually valid steps is assembled" are caught as visible contract mismatches at design time. It is the archetype's answer to systems where valid composition was assumed rather than declared.[n1]
Its failure mode is the stale map: a contract diagram that no one owns drifts from the running system and becomes actively dangerous, because teams trust a promise the code no longer keeps. The classic misuse is documenting aspirational contracts that nothing enforces — a beautiful map that production ignores — so the map records intentions rather than obligations. A related trap is over-fine granularity that no owner can keep current. The guarding discipline is single-owner accountability with a real reconciliation cadence, and treating any contract on the map as a claim to be verified against the deployed interface, not decoration.
How it implements the components¶
source_target_typing_rule— its core boundary discipline: every contract arrow declares the required input type and guaranteed output type, so incompatible wirings show as typing violations.invariant_of_interest— the guarantee each contract records (idempotence, ordering, auth) that a caller may rely on across the interface.diagram_governance_owner— the single named party accountable for keeping the contract map synchronized with deployed reality and adjudicating changes.
It does not draw the generic, domain-agnostic node-and-arrow picture or set the ignorance boundary (object_role_inventory, typed_arrow_inventory, internal_structure_ignorance_boundary — that is Object–Arrow Diagram), and it does not enumerate composites (composition_rule — that is Composition Table); this map governs typed contracts, it does not compute their chains.
Related¶
- Instantiates: Composable Relation Modeling — the map applies the archetype to software interface contracts.
- Consumes: Source/Target Type Check verifies the arrow typings the map declares.
- Sibling mechanisms: Object–Arrow Diagram · Source/Target Type Check · Composition Table · Commutative Path-Equivalence Diagram · Identity and Associativity Test Suite · Functorial Transfer Probe · Structure-Preservation Checklist · Categorical Refactoring Workflow
Editorial Notes¶
Form Classification¶
Form family: Representation, Specification & Plan
Rationale: Interface-Contract Category Map operates as a non-executable information artifact that externalizes static or prospective structure because it models software modules as objects and their interface contracts as typed arrows, with a named owner keeping the contract map authoritative
Independent corroboration: The frozen evidence defines Interface-Contract Category Map as 'Models software modules as objects and their interface contracts as typed arrows, with a named owner keeping the contract map authoritative', so its operative form is Representation, Specification & Plan.
Review outcome: Independent reviewer agreement; high confidence.
Origin Attribution¶
Primary origin: Mathematics
Origin pattern: Cross-disciplinary synthesis
Present-day reach: Specialized
Rationale: Objects, typed arrows, associative composition, and identities are precisely category theory's formal vocabulary. Software interfaces and Design by Contract provide the concrete module-governance application.
Related originating lineages:
- Computer Science & Software Engineering — Design by Contract and module-interface practice supply the software contracts represented as arrows.
Review resolution: Objects, typed arrows, associative composition, and identities are precisely category theory's formal vocabulary. Software interfaces and Design by Contract provide the concrete module-governance application. The retained alternate domains identify documented formative or independently established origins, not downstream applicability alone. domain_reach=specialized because established use remains concentrated in a bounded professional context. The final marks encyclopedia_synthesis=true because the entry deliberately composes those lineages.
Encyclopedia synthesis: The exact catalogued form synthesizes established practice rather than reproducing a single standard historical label.
Review outcome: Researched adjudication after independent review; high confidence.
Sources consulted:
- https://math.mit.edu/~mckernan/Teaching/07-08/Spring/18.726/l_2.pdf — MIT mathematics notes defining categories by objects, morphisms, composition, and identities.
Notes¶
[n1] Design by Contract, introduced by Bertrand Meyer in the Eiffel language, specifies each interface as a set of obligations and guarantees — preconditions, postconditions, and invariants — that callers and implementers must honor. This map is the relational, whole-system view of those contracts: the arrows are the contracts, and the invariant on each is its postcondition-and-guarantee. ↩