Object–Arrow Diagram¶
Modeling notation — instantiates Composable Relation Modeling
Draws the domain as objects and typed arrows at a chosen grain, deciding what internal detail to hide behind each object.
An Object–Arrow Diagram is the base picture the whole archetype is drawn on: a set of objects (the roles, states, or types that things can be) connected by typed arrows (the admissible mappings from one to another). Its defining commitment is deliberate blindness — each object is treated as an opaque dot whose internals are off-limits, so that reasoning happens entirely at the level of what maps to what. The diagram does not yet claim any two routes are equal, does not tabulate composites, and does not check types; it is the notation on which those later moves become possible. Its only questions are: which things are the nodes, which arrows are legal, how much internal detail do we refuse to look at, and how fine do we cut the objects? Answer those four and you have a canvas; answer them badly and every downstream diagram inherits the mistake.
Example¶
A team maintaining an audio toolchain keeps arguing about codecs in prose, and the arguments keep going in circles. They draw an Object–Arrow Diagram instead. The objects are formats — WAV, FLAC, MP3, AAC, Opus — each drawn as a single node with no mention of bit-depth, container quirks, or metadata layout. The arrows are transcoders: a lossless WAV → FLAC encoder, a lossy WAV → MP3, a FLAC → WAV decoder, and so on, each drawn only where a real converter exists and pointing only in the direction it actually runs. The team consciously sets the ignorance boundary: a node is "a format," full stop, and anything about how a given file is bit-packed lives inside the dot, invisible.
Then they argue about grain. Should MP3 be one object, or should "128 kbps MP3" and "320 kbps MP3" be separate nodes because a transcoder between them exists and matters? They choose the finer cut only where an arrow distinguishes the two. The finished diagram fits on a whiteboard and immediately settles the original dispute: there is no arrow from Opus back to WAV in their tooling, so the "just round-trip it" plan someone proposed is simply not a path on the picture. Nothing was computed; the missing arrow did the work.
How it works¶
The distinguishing method is the discipline of drawing, not solving:
- Inventory the objects as roles, not instances. A node is a type of thing ("an MP3"), never a particular file. If two candidate nodes are never distinguished by any arrow, collapse them.
- Draw an arrow only where a real mapping exists, label it with its meaning, and give it a direction. An arrow is a claim that the mapping is admissible, so an arrow you cannot name is an arrow you should not draw.
- Fix the ignorance boundary explicitly. State, once, what lives inside a dot and is therefore out of scope. This is the move that makes the model transferable and keeps it small.
- Choose grain against the arrows. Split an object into finer nodes only when an arrow would treat the pieces differently; otherwise keep it whole.
What the diagram deliberately withholds: it names no composites, asserts no equivalences, and runs no checks. Those are the jobs of its siblings.
Tuning parameters¶
- Object grain — how finely the nodes are cut. Finer grain exposes distinctions an arrow depends on but multiplies nodes and can bury the shape; coarser grain is readable but can hide a mapping that only some sub-cases admit.
- Ignorance depth — how much internal structure each dot swallows. A deep boundary maximizes transfer and compression but risks a leaky object whose hidden internals actually change which arrows are valid.
- Arrow admission bar — how sure you must be a mapping exists before drawing it. A strict bar yields a diagram you can trust; a loose one invites arrows that turn out not to run.
- Directionality strictness — whether reverse arrows are drawn only when a genuine inverse exists, or sketched hopefully. Strictness prevents phantom round-trips.
When it helps, and when it misleads¶
Its strength is compression: a domain that resisted a paragraph resolves into a picture where a missing arrow is as informative as a present one, and where internal complexity is quarantined behind opaque nodes. It is the artifact everything else in the archetype consumes.
Its central failure mode is the leaky abstraction: an object drawn as opaque whose hidden internals secretly govern which arrows are legal, so the picture licenses a mapping that fails in reality.[n1] The classic misuse is grain chosen for tidiness rather than for the arrows — collapsing two nodes that some transformation actually distinguishes, so a phantom path appears. A related trap is drawing an arrow because it ought to exist rather than because a mapping does. The guarding discipline is to justify every object boundary and every arrow by pointing at the concrete mapping that motivates it, and to re-cut grain the moment an arrow needs to treat one node's insides as two.
How it implements the components¶
object_role_inventory— its first output: the set of nodes, each a role/type rather than an instance.typed_arrow_inventory— the labeled, directed arrows, drawn only where a real mapping exists.internal_structure_ignorance_boundary— the explicit statement of what each opaque node hides, which is what keeps the model small and transferable.granularity_selection_rule— the rule that objects are split only when an arrow distinguishes the pieces.
It does not tabulate composites (composition_rule — that is Composition Table) and it asserts no route-equality (path_equivalence_claim — that is Commutative Path-Equivalence Diagram, its nearest twin; the diagram merely draws the arrows those claims are made about).
Related¶
- Instantiates: Composable Relation Modeling — the Object–Arrow Diagram is the base representation every other mechanism reads from.
- Sibling mechanisms: Composition Table · Commutative Path-Equivalence Diagram · Source/Target Type Check · Interface-Contract Category Map · Categorical Refactoring Workflow · Functorial Transfer Probe · Identity and Associativity Test Suite · Structure-Preservation Checklist
Editorial Notes¶
Form Classification¶
Form family: Representation, Specification & Plan
Rationale: Object–Arrow Diagram operates as a static representation, map, specification, schema, or prospective plan that externalizes information because it draws the domain as objects and typed arrows at a chosen grain, deciding what internal detail to hide behind each object.
Independent corroboration: The frozen evidence defines Object–Arrow Diagram as 'Draws the domain as objects and typed arrows at a chosen grain, deciding what internal detail to hide behind each object', 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: Multi-domain
Rationale: Category theory and graph-based mathematics developed object-and-arrow notation for representing typed composable relations while abstracting internal structure.
Related originating lineages:
- Computer Science & Software Engineering — Software modeling and dataflow diagrams operationalized object-arrow representations for systems whose components expose interfaces.
- Systems Thinking & Cybernetics — Systems modeling contributes decisions about grain, boundaries, and hidden internal detail.
Review resolution: Both independent reviews agree on primary origin mathematics; reconciliation resolves alternate_origin_disagreement, origin_mode_disagreement, encyclopedia_synthesis_disagreement. Formative alternate lineages retained: computer_science, systems_cybernetics. The broader reach of later applications is kept separate as domain_reach=multi_domain; origin_mode=cross_disciplinary_synthesis describes the historical relationship among lineages. Confidence is conservatively reconciled to high, and encyclopedia_synthesis=true preserves the reviewers' boundary judgment.
Encyclopedia synthesis: The exact catalogued form synthesizes established practice rather than reproducing a single standard historical label.
Review outcome: Reconciled after independent review; high confidence.
Notes¶
The Object–Arrow Diagram is an artifact, not a verdict: it says nothing about whether the arrows compose lawfully or two paths agree. Keeping it that thin is what lets it be reused — the same picture underwrites the composition table, the type check, and the transfer probe without re-drawing.
[n1] The observation, articulated as the Law of Leaky Abstractions, that abstractions meant to hide underlying detail sometimes let that detail "leak" through and govern behavior anyway. An object drawn as opaque is exactly such an abstraction, which is why the ignorance boundary must be justified rather than assumed. ↩