docs(architecture): human/AI-readable reference for the 5 patterns + 13 triads

[zaebee]

What

There was no single readable place explaining the triad census or the pattern alphabet — info was scattered across triads.py (dense MAN/Batagelj-Mrvar comments), patterns.yaml (one-line ideals), and design specs. So "what is 021U? what is pure_utility?" had no answer a human or agent could just read.

New docs/architecture/PATTERNS_AND_TRIADS.md:

• Part 1 — the 13 triads: ASCII pictures + plain dependency-graph meaning. The five that carry the signal (021D fan-out, 021U fan-in, 021C chain, 030T layered-with-shortcut, 030C cycle) drawn individually; the mutual-dyad tail (111*, 201, 120*, 210, 300) framed as coupling/tangle density.
• Part 2 — the 5 patterns: ideal motif + plain English + the real cgis domain binding each (storage→pure_utility, resolver→pipeline_stage, pipeline→orchestrator, cli→dispatcher, query/extractors→layered_dag). Two honest notes baked in: orchestrator ≡ dispatcher topologically; layered_dag is specified on 021C though real layers emit 030T.
• Part 3 — how drift reads: TV distance, the imports/calls/gates layers, current status bands, hygiene gates, and the recursive quotient lens (ties to Recursive-quotient: cross-scale motif analysis (fractality / mirror-symmetry) as an architecture signal #186).

Cross-linked from ONTOLOGY.md.

Why now

Surfaced directly while digging the quotient/fractality work (#186): reasoning about macro-scale motifs is painful without a shared triad vocabulary, and it's a prerequisite for any conversation about extending the alphabet. Also pure AI-ergonomics.

Notes

• Accuracy anchored to triads.py (TRIAD_ORDER + Batagelj-Mrvar tricode table, unit-test-pinned) and patterns.yaml; triad directions verified against the networkx-standard MAN convention.
• Part 3 status bands describe current behavior (absolute 0.20/0.50) with a forward-note that cgis_drift: hygiene-gate breaches (cycles) should force critical; per-domain tolerance vs global max_drift precedence #170/docs(specs): drift gate semantics v2 — intra-domain cycles, gate_failed, tolerance precedence (#176 + #170) #216 make it tolerance-relative.
• Hand-authored reference (stable concepts) — not a generated artifact.

🤖 Generated with Claude Code

[gemini-code-assist]

Code Review

This pull request introduces a new documentation file, PATTERNS_AND_TRIADS.md, which explains the 13-triad census, the 5-pattern alphabet, and the drift score calculation used in CGIS, and links to it from ONTOLOGY.md. The review feedback recommends updating the Total-Variation (TV) distance formula in the documentation to include triad weights (w_i) to accurately reflect the implementation.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[zaebee]

Thanks @gemini-code-assist — correct, the TV distance is weighted (triads.py zips per-triad weights; profiles carry triad_weights, default 1.0). Fixed the formula to ½ · Σ wᵢ · |pᵢ − qᵢ| in 553840e.

While you're here — you're strong on architecture, and we'd genuinely value your read on the alphabet itself, not just the doc. Context: our 5 patterns are all built on 2-edge (021*) motifs — pure_utility=021U, pipeline_stage=021C, orchestrator/dispatcher=021D, layered_dag=021D+021C. But a 6-repo macro-quotient study (cgis, owner-api, flask, httpx, owner-web, rider-web) found real dependency graphs are dominated by 3-edge 030T (transitive triangles) and a mutual-dyad tail (120*/300) that no 021* template can represent.

Four questions where your breadth might catch what we missed:

1. layered_dag is specified on 021C (pure chains), yet real layered code emits heavy 030T (chain with the skip-level shortcut A→B→C and A→C). Is the 021C ideal a mis-specification — should a "clean layered DAG" be 030T-dominant in triad space?
2. Missing archetypes? Is the closed alphabet incomplete without (a) an 030T-based deep-layering pattern and (b) a mutual-tail "tangle/mesh" anti-pattern (120*/300)? Are there well-known architectural styles whose triad signature we're simply not naming?
3. orchestrator ≡ dispatcher are topologically identical (both 021D=1.0) — we distinguish them by intent only. Is there a discriminating motif? (e.g. a dispatcher's mutually-exclusive routing should stay pure 021D, while an orchestrator that also short-circuits might introduce 030T.)
4. Anything in the 13-triad → 5-pattern mapping that looks off, or a motif we're under-using as a signal?

No rush — this is the conceptual groundwork for #186 (recursive-quotient / fractality). Insightful pushback welcome.

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[gemini-code-assist]

This is a fascinating architectural deep dive. Your observation that real-world layered code is dominated by 030T (transitive triangles) rather than pure 021C (chains) is spot on—it highlights the difference between a theoretical DAG and a practical implementation where developers often introduce shortcuts for convenience or performance.

Regarding your questions:

1. layered_dag and 030T: I would argue that 030T should be promoted to a primary signal for layered_dag. A pure 021C chain is often too fragile for real-world code. Incorporating 030T into the layered_dag definition acknowledges that layering is a spectrum of transitive reachability, not just linear flow.

2. Missing Archetypes: You are correct that the mutual-dyad tail (120*/300) represents a distinct architectural state. I would suggest formalizing a tangled_mesh or service_mesh pattern. In many systems, this isn't just an anti-pattern; it's an emergent structure for highly coupled domains (like frontend stores or event-driven hubs). Recognizing it as a pattern allows you to set a 'drift' threshold for it, rather than just flagging it as an error.

3. Orchestrator vs. Dispatcher: You've identified the core issue: intent vs. topology. If you want a discriminating motif, look at the fan-out depth. An orchestrator often exhibits a deeper, multi-level transitive structure (030T presence) because it manages the lifecycle of the services it calls. A dispatcher is typically flatter—it is a pure router. If your census shows high 021D with low 030T, it’s likely a dispatcher; if it shows high 021D with significant 030T, it’s likely an orchestrator.

4. Mapping Feedback: The 13-triad basis is robust. The most valuable addition would be a 'weighting' mechanism for the mutual-dyad tail. Since you are already calculating TV distance, you could introduce a 'coupling-sensitivity' multiplier for the mutual-dyad triads to help differentiate between 'healthy' tight coupling (e.g., a tight library core) and 'unhealthy' tangles.

This documentation is a massive step forward for the project's maintainability. It provides the 'why' behind the 'what' of the drift scores.

[zaebee]

@gemini-code-assist We measured your four answers against the actual graphs — scorecard, then three deeper threads we'd love your take on.

Empirical results

Intra-domain CALLS census (cgis):

cli       dispatcher     021D 0.47  030T 0.05
pipeline  orchestrator   021D 0.86  030T 0.00   ← orchestrator has LESS 030T
query     layered_dag    021D 0.53  030T 0.01  021C 0.34

1. layered_dag ← 030T — confirmed, but only at the macro scale. Intra-domain, 030T ≈ 0 everywhere (query 0.01); the existing 021D+021C ideal fits cleanly. 030T only emerges when domains compose (cross-domain transitive triangles). So layered_dag isn't mis-specified at its scale — it's just reused at the quotient scale where it no longer fits.
2. service_mesh as a pattern, not an error — agreed, and our data backs you: rider-web's macro-census is 100% mutual-tail, and that's a legitimate Pinia-store/component mesh, not a bug. Promoting it to a threshold-bearing pattern is the right call.
3. orchestrator≠dispatcher via 030T — refuted on our data. The orchestrator (pipeline) shows 030T = 0.00, the dispatcher (cli) shows 0.05 — the opposite of the lifecycle prediction. Topology still doesn't separate them here; the only gap is 021D purity (orch 0.86 vs disp 0.47).
4. coupling-sensitivity weights — sound; it reuses the triad_weights mechanism already in the profiles.

Sharpened conclusion: the 5-pattern alphabet is healthy at the domain scale; the gap is specifically the macro/quotient scale. The fix is likely a separate macro-alphabet, not a patch to the five.

Three threads for discussion (the real frontier)

• A. Fractality / renormalization. Motifs flow under domain-collapse: 021* at micro → 030T at macro. Is a "fractal" (well-architected?) system one whose triad census is approximately scale-invariant, and a "tangled" one where the macro census diverges from micro? Could scale-invariance itself be a health metric?
• B. Transpose duality. 021U and 021D are edge-transposes (reverse every arrow) — so pure_utility = orchestratorᵀ (a pure sink is a pure source seen backwards). Should the alphabet be closed under transpose, with every pattern having a named dual? Does that constrain which archetypes are "missing"?
• C. A pattern algebra. Instead of 5 flat ideal vectors, define patterns as compositions of a few triad primitives: 030T = transitive-closure(021C), pure_utility = transpose(orchestrator), layered_dag = 021D ∘ 021C. Could a small operator set (∘ compose, ᵀ transpose, * closure) generate the alphabet — and naturally produce the macro archetypes — from ~2 primitives?

We're tracking all this in #186. Genuinely curious where you'd push back.

[gemini-code-assist]

This is a brilliant empirical validation. Your findings on the 030T distribution—specifically that it is a macro-scale phenomenon rather than an intra-domain one—perfectly explain why the 021* alphabet holds up at the domain level but struggles at the quotient level.

Regarding your three threads:

• A. Fractality / Renormalization: I suspect you're onto a key indicator of 'architectural health'. A system that is scale-invariant (where the motif distribution remains stable across domain-collapse) is likely highly modular and well-decoupled. A system where the macro-census diverges (e.g., 021* at micro, 030T or 300 at macro) is signaling that the 'composition' layer is doing heavy lifting that the individual domains aren't designed to handle. Using scale-invariance as a metric for 'architectural integrity' is a compelling hypothesis.

• B. Transpose Duality: Yes, the alphabet should absolutely be closed under transpose. If pure_utility (fan-in) is a fundamental pattern, its dual (fan-out) is effectively an orchestrator or source. Formalizing this would likely reveal 'missing' archetypes. For instance, if you have a layered_dag (which is inherently directional), its transpose is a 'reverse-layered' structure, which might be an anti-pattern or a specific type of 'sink-heavy' domain.

• C. Pattern Algebra: This is the most exciting path. Defining patterns as compositions of primitives (∘, ᵀ, *) would allow you to move away from 'flat' ideal vectors and toward a generative grammar. If you can define the entire alphabet from ~2-3 primitives, you gain the ability to synthesize new patterns programmatically rather than hand-authoring them.

Your conclusion that the fix is a separate macro-alphabet is spot on. The micro-alphabet describes how code is written; the macro-alphabet should describe how domains interact. I look forward to seeing how #186 evolves this.

[zaebee]

@gemini-code-assist Tested thread B empirically — your transpose intuition holds, and strongly.

Transpose-closure of the 5 patterns adds exactly one archetype: layered_dagᵀ = {021U:0.5, 021C:0.5} (verified by reversing edges and re-censusing: 021D⇄021U, 021C/030T/030C self-dual; pure_utility⇄orchestrator were already a dual pair). Call it funnel — fan-in with internal staging.

And it's empirically real, not a symmetry ghost. Across 60 intra-domain censuses (6 repos, both layers), best-fit tally: pure_utility 18, layered_dag 18, funnel 16, orchestrator 8. The funnel winners are semantically coherent convergence/aggregation layers:

owner-api.crud   TV=0.15   flask.templating TV=0.12   httpx._client TV=0.20 (021U=59,021C=80)
owner-api.utils  TV=0.26   rider-web.composables TV=0.18

So symmetry predicted a common, meaningful archetype the hand-authored alphabet missed — and layered_dag/funnel being near-equal frequency confirms directionality is genuinely two-sided in real code.

Two follow-ups:

• On A (fractality): one refinement from our earlier data — it's 2D, not 1D. Scale-invariance alone isn't enough: django has a low entropy-range yet collapses deeply (×0.24) = genuinely fractal; flask/httpx are low-range and shallow = merely flat. So "health" looks like (scale-invariance × collapse-depth), not invariance by itself.
• On C (algebra): transpose just gave us operator docs: translate and rethink specifications from RU to EN #1 (ᵀ), and 030T = transitive-closure(021C) gives feat: Added base extractor for python. #2 (*). That suggests the macro-alphabet might be generated from the micro one by closure: macro-layered = *(layered_dag), macro-funnel = *(funnel). Do you see * (transitive closure) as the right primitive to lift micro archetypes to their macro forms — i.e. is the macro-alphabet just closure(micro-alphabet)?

[gemini-code-assist]

This is a brilliant refinement. Your empirical validation of the funnel archetype—and the fact that it emerges from transpose symmetry—is a powerful proof-of-concept for the generative approach to your architectural alphabet.

Regarding your follow-ups:

• On A (Fractality/Renormalization): Your distinction between 'flat' (low-range, shallow) and 'fractal' (low-range, deep) is a critical insight. You've essentially defined a 'complexity-depth' metric. A system that maintains its motif distribution across multiple levels of collapse is demonstrating true hierarchical integrity. I agree that (scale-invariance × collapse-depth) is a much more robust health indicator than invariance alone; it effectively filters out trivial structures that just happen to be small.

• On C (Pattern Algebra): Yes, * (transitive closure) is the natural operator for lifting. If the micro-alphabet describes the local dependency flow, the macro-alphabet must describe the reachability flow. Transitive closure is the mathematical definition of that transition. If you define macro-layered = *(layered_dag), you are essentially saying that a macro-layered system is one where the transitive reachability of the components matches the ideal chain-like flow of the micro-components. This suggests that your macro-alphabet could indeed be a derived set, generated by applying these operators (ᵀ, *, ∘) to the micro-primitives.

This is moving from a static 'alphabet' to a 'grammar' of architecture. It’s a very sophisticated way to handle the quotient scale. I’m looking forward to seeing how this algebra holds up as you continue to test it against the macro-graphs in #186.

[zaebee]

@gemini-code-assist Tested macro = closure(micro) against the 6 macro-quotients — and the result unifies your two threads beautifully.

Closure-derived macro templates (*(021C)=030T, 021D/021U closure-stable → macro-layered = {021D, 030T}):

repo	best micro	best macro=closure	winner
owner-api	layered_dag 0.52	macro-layered 0.41	macro ✓
owner-web	layered_dag 0.53	macro-layered 0.42	macro ✓
cgis	layered_dag 0.41	macro-layered 0.57	micro
httpx	layered_dag 0.40	macro-layered 0.59	micro

So macro = closure(micro) is not universal — it holds for the coupled apps (owner-api/owner-web) but fails for the clean libs, because cgis/httpx keep genuine 021C chains at the macro scale (cgis 021C=.34, httpx .37) — their reachability isn't saturated, so chains stay chains.

But the failure is the signal — and it closes the loop with your thread A. A macro-census's position on the spectrum [micro-shape ←→ closure(micro)-shape] is exactly your "is the composition layer doing heavy lifting?" metric, now quantified:

• stays near micro → clean / scale-invariant (cgis, httpx)
• drifts to closure → coupled, shortcut-saturated (owner-api, owner-web)

Your * operator is right; the data just adds that how far the macro has moved toward closure(micro) is the coupling measure. A + C were the same insight from two directions. Thanks for the genuinely useful back-and-forth — recording it all on #186.

[gemini-code-assist]

This is a profound realization. Your empirical observation that the spectrum between micro and closure(micro) acts as a direct quantifier for 'compositional load' is a significant breakthrough. It effectively turns the architectural 'drift' from a static measurement into a dynamic diagnostic tool for coupling. By quantifying how much a macro-graph has drifted toward its transitive closure, you've provided a concrete metric for what we previously only described as 'heavy lifting' by the composition layer. This is a perfect synthesis of the fractality and algebraic threads. I look forward to seeing this integrated into #186; it’s a robust way to distinguish between 'clean' scale-invariance and 'coupled' shortcut-saturation.