Diagrams // illustrative

docs/diagrams/README.md · 22537 B · source sha256 605e8aa8c23a

These diagrams are illustrative. They are not source of truth.

Repo prose remains authoritative. If a diagram and the repo prose disagree, trust the prose and refresh the diagram; do not modify the repo prose to match the diagram.

Each diagram is a structural snapshot of the repo at a point in time. Diagrams age. Repo prose ages too, but more slowly. The diagram should track the repo, not the other way around.

on this page

Authority cadence

Inheritance

The diagram conforms to apexSolarKiss/design-system-ASK Tier 1 + Tier 2 by reference at generation time. The compiled diagrams.css in this folder is render support, not identity source of truth. design-system-ASK remains the visual authority; this folder does not own visual identity.

The four intent-architecture figures

TREE_D10 and TREE_D05–TREE_D07 are one delivery unit against the landed intent-artifact ontology and routed-instance lifecycle (docs/intent-artifacts.md, docs/source-of-intent.md). They are structural maps rendered by the shared tree engine, not bespoke figure.js compositions like the SMGI pair — the subject in each case is a classification or a set of distinctions, which is what the tree engine is for.

They exist to prevent four specific collapses, one per figure:

  • D10 — a source of intent is a locatable ROLE, not a folder or a file; ASK authorship does not make an artifact an intent carrier.
  • D05 — a canonical vN lineage is not a routed-instance lifecycle. Only a fresh routed handoff awaiting first ingestion enters the routed-instance filename lifecycle; terminal -TBI remains orthogonal and may overlay other eligible artifact forms without importing it.
  • D06 — the relay ENVELOPE supplies operative force; the payload supplies content. Ingestion is what results when a feed succeeds, and it is not a disposition.
  • D07 — a PTX is a faithful linear projection of a partially-ordered exchange, not the exchange itself and not an authority converter.

Update cadence

  • topology or method-altitude structural change: refresh the source data file
  • new doctrine doc landing: refresh the source data file (the doctrine-docs group needs to track what has landed)
  • per-PR repo edits: do not refresh
  • per-article work: do not refresh
  • ecology-level structural shift: open a new source-vN

Contents

Live navigation surface

  • index.html — ASK-branded live navigation surface for this folder's diagram set. It consumes the local Tier 1 + Tier 2 mirror and the vendored _dsa-surface/ carriers; its Tier 3 does not propagate into the diagrams. Opened from a clone, its source, doctrine, example, README and method links open the raw files they name. The site build (tools/read/) serves a composed copy, in which those links open the reading pages and source views generated from the same files, a documents route and a documents action in the navigation panel are added, and the breadcrumb's method-ASK links the site's home page.
  • _dsa-surface/ — pinned, byte-identical design-system-ASK carriers, used by two different consumers in this folder.
    • Index navigation. surface-shell.css, surface-panel.css, surface-action.css, surface-text-link.css and the mode-aware ASK wordmark pair, loaded by index.html.
      • surface-shell.js — the shell's responsive-navigation runtime, adopted by index.html. The identity mark is the disclosure: the runtime upgrades the authored anchor in place, so with JavaScript unavailable the mark stays an ordinary home link and no panel, trigger or dead control appears. No diagram page loads the shell, its runtime, surface-action.css or the wordmark pair.
    • Diagram disclosure. surface-panel.css, then surface-treatments.css, loaded by every diagram page that adopts the responsive chrome (Responsive chrome, below). surface-treatments.css supplies the controlled disclosure trigger their About and Legend triggers take.
    • Reading pages. The site build's pages, the home page at the site root and the reading pages under /read/ (tools/read/), also load surface-shell.css, surface-shell.js, surface-panel.css, surface-action.css, the wordmark pair and the _dsa-tokens/ mirror. They take their own document-register carriers from tools/read/carriers/, and never this folder's surface-treatments.css. tools/read/declared.json records the sha256 of each stylesheet and script they load, and the build stops when one of them moves without it.

Topology + intent-architecture trees

Bespoke figures

Responsive chrome

Every diagram page here adopts the design-system-ASK responsive diagram chrome: the five tree pages, the four figures, and the generated system-ASK public projection. Each wraps its caption and, where it has one, its legend in one .diagram-info block with About and Legend triggers, and each figure builder follows the tree engine's Fit rules. The public projection's HTML is generated from its pinned operator shell (system-ASK-topology-public.generation.json), so it carries the chrome because that shell does.

  • Wide. The two panels sit together at the top of the canvas.
  • Compact. When the canvas is narrower than 640px, or the open panels would take more than a third of its height, more width than it gives, or leave the drawing less room above the HUD than the fit needs to keep it clear, the panels close behind their triggers in one control area with the HUD. The header keeps its identity, its title and an illustrative cue; the subtitle and stamp move into About. At most one panel is open, and it scrolls within the space above the control area.
  • Fit. At Fit the drawing is centered vertically between the chrome above and below it. The view stays at Fit until the reader zooms or pans, and a resize or a chrome change refits only a view still at Fit. An open panel moves the drawing only where the drawing keeps its size; otherwise it overlays the drawing until it closes. ⤢ closes a panel that would cover the drawing.
  • Export. PNG page reads the subtitle and stamp wherever they sit, so the page export does not depend on the live layout.
  • Touch. Every engine page and figure hands its gestures to the shared pointer controller (diagrams-pointer.js): one finger pans the drawing from anywhere on it, two pinch the drawing rather than the page, and the panels keep their own taps and scrolling.

When bounded generativity and the SMGI doctrine figure first adopted it, their live composition changed, so their render stamps advanced while their source did not, to source-v5 // render-v6 and source-v1 // render-v3. They advanced again when their Fit began centering the drawing and capping its compact clearance, which moved their at-rest view on narrow or crowded windows: bounded generativity is source-v5 // render-v7, and the SMGI doctrine figure is source-v1 // render-v4. The generated public projection took the chrome and the controller from its operator shell, at the operator canonical's render-v28. The tree pages share the engine's Fit behavior, so a reader's zoom survives a resize, and the four figures follow the same Fit rules.

Shared render support

  • diagrams-chrome.js — DS-owned responsive chrome controller, loaded by every page in Responsive chrome, BEFORE diagrams-fit.js. A page without the .diagram-info block is untouched by it.
  • diagrams-pointer.js — DS-owned shared pointer controller (v2); loads after diagrams-chrome.js and BEFORE diagrams-fit.js, so before the engine and every figure builder, each of which throws a named error without it. The engine itself does not: a page that does not load it keeps the mouse drag and wheel.
  • diagrams-fit.js — DS-owned fit support (v3); loads BEFORE the engine AND before every figure builder — the engine and each builder throw a named error if it is missing or older than v3. Its v3 balance option centers each drawing vertically between the chrome above and below it, and compactClearance caps the clearance while the responsive chrome is compact. Chrome may declare the edge it is anchored to with data-diagram-fit-edge; with nothing declared, the fit reserves exactly the panels it did before.
  • diagrams-text-layout.js — the DS-owned shared text-layout contract: it measures and wraps long node labels for the static tree engines. It loads AFTER diagrams-fit.js and IMMEDIATELY BEFORE the engine.
  • diagrams-static-H-engine.js — layout + pan/zoom engine.

The helper and the engine are indivisible. The engine throws Diagram text-layout support is missing or incomplete. Load diagrams-text-layout.js before the diagram engine. when the carrier is absent, and it further requires DIAGRAM_TEXT_LAYOUT.TARGETS to name its own pattern. Neither file may be re-vendored, moved or upgraded without the other, and a page may not load one alone — the failure is loud by design rather than a silently unwrapped label.

  • _dsa-tokens/ — vendored Tier 1 + Tier 2 token mirror.
  • diagrams.css — compiled Tier 1 + Tier 2 style, including the responsive chrome's layout, which applies only to a page that wraps its panels in .diagram-info.
  • export-png.js — 3840×2880 PNG export. PNG page keeps the caption, the legend and the drawn marks apart.

The two SMGI figures

They are a pair with different jobs, and neither substitutes for the other:

  • doctrine figure (…_seed-mediated-generated-interface) — the instantiation path and the loading-boundary seam. Authored seed >> loading boundary >> grammar grants the aperture >> runtime >> generated interaction >> return, or, at the boundary, fork-at-load. Consumes the Three Functions primitive for one licensed node: the grammar box, where the grammar is operative apparatus in the runtime path.
  • ontology figure (…_seed-mediated-generated-interface-ontology) — the category boundaries. Four orthogonal layers (mechanism · application · authored control · conformance) around one membership node, joined by typed relations. Fully neutral — no function colour, because it classifies concepts rather than diagramming the functions; it does not load three-functions.css.

The SMGI doctrine figure is source-v1 // render-v4; the ontology figure is source-v2 // render-v2.

Responsive behavior. 1440×900 is the reference read-all composition (doctrine about 0.75, ontology about 0.67 on the default screen profile). The doctrine figure takes the responsive chrome (Responsive chrome, above): on a narrow or crowded window its panels close behind triggers, and fit-all gives the drawing the canvas as a navigable overview. The ontology now takes the same responsive chrome; on shorter and narrower windows fit-all is still a navigable overview, its macrostructure and membership gate remain identifiable, and zoom/pan exposes the authored detail. Read-all composition at every aspect ratio would require content reduction, which neither figure takes.

Ontology dual-profile (source-v2). The ontology is height-limited at a normal viewport, so a single fixed canvas cannot both stay read-all at 1440×900 and fill the 3840×2880 page. One semantic model is laid out under two coordinate profiles selected by ?layout=: screen (default) is compact-but-recomposed and stays read-all at 1440×900 without zoom; page (?layout=page) is the taller, page-optimized composition that spends the available 3840×2880 page height below the chrome. The committed dark full-page mirror is generated from the page profile (?layout=page&export=png). Text, categories, held status, branch asymmetry, and typed relations are identical across profiles — only coordinates differ (the recomposition itself — Application's two cards, Conformance's deepened gate / outcomes / test-strip — is present in both).

How to use

  • Open any listed .html figure directly in a browser, or via GitHub Pages if configured.
  • Drag to pan; scroll to zoom; HUD controls in the bottom-left; ⤢ to fit. On every page with the responsive chrome, a narrow or short window gathers About and Legend behind triggers in one control area with the HUD, and a scroll over an open panel scrolls the panel. On a phone one finger pans the drawing from anywhere on it and two pinch it, never the page.
  • Theme follows the OS preference (prefers-color-scheme); the CSS supports explicit data-theme="light" or data-theme="dark" on <html> if a specific theme is needed.
  • The PNG export outputs a 3840×2880 image in the resolved theme.
  • Theme by embedding surface — adopting the design-system-ASK convention (pinned 7921b79): this folder is repository documentation, so its embedded diagrams default to dark. Bespoke figures with an approved committed mirror use one versionless dark full-page raster each, named with the semantic figure stem plus the -dark.png theme suffix. The current mirrors are system-ASK (D11), bounded generativity, the SMGI doctrine figure, and the SMGI ontology figure. Light-page and chrome-free diagram variants remain on-demand exporter outputs, not committed. Most other diagrams here are HTML-only; a bespoke figure gets exactly one supplemental raster when the Markdown needs it.

Lineage

This diagram originated in the v9 operator-side ecology-ASK diagram package and was first absorbed here at source-v2 // render-v9.

The current tuple is source-v9 // render-v23 (2026-10-08). Source advances when the authored topology changes; render advances only when the renderer realization changes.

The operator-side package and historical render iterations remain in ecology-ASK-EXTERNAL/scratch/ and are not repo truth.

Terminology conformance 2026-08-24. The abbreviated authority term was expanded to source of truth throughout the current repo. No topology, semantic model, renderer, or carrier changed; all source and render stamps hold. The three committed dark full-page mirrors were regenerated only to keep their visible caption copy current.

What this folder does not carry

  • TREE_D01 (control-surface architecture tree) — lives in apexSolarKiss/control-surface/docs/diagrams/
  • TREE_D03 (system-ASK topology) — the OPERATOR CANONICAL stays outside this repo, and is not absorbed here. What this folder carries is its governed PUBLIC PROJECTION, TREE_D03_PUBLIC, generated from that canonical with the operator-side branches excluded. The projection is not the canonical, does not stand in for it, and confers no authority over it.
  • Operator-side context architecture payload (private; conform by reference, do not absorb)
  • Tier 3 identity inside the diagram artifacts — excluded by the Tier model. index.html is a separate ASK-branded live navigation surface for this repo and carries the mode-aware ASK wordmark pair; its Tier 3 does not propagate into the diagrams it indexes.
  • Runtime dynamic import from design-system-ASK CSS (no; conform at generation time)
  • Fast-aging state (PR numbers, commit hashes, current grounding-note version stamps, branch names, recent activity chronology)