Structured models of where things run and how they layer.
Deployment & tier topology
Intent — Structured models of where things run and how they layer (the managed-deployment topology, each service's tier class, and the agent-substrate's layer boundaries), so deploy scripts and layering lints reason about a declared topology, not scattered constants.
| Summary | Structured models of where things run and how they layer. |
| Target | Bridge · System models |
| Form | typed-ir |
| Move | package — a constraint shipped with its sensors |
| Model | is-a-model — a structured model you check a system property against |
| Enforcement | Hard (deterministic) — structured models held true by the deploy-parity + layer-boundary lints |
| Derivation | model-from-code — induced from the code, reconciled at build |
Its place in the environment — a variant / known-use of Executable Source of Truth, under KNOW · Maintain authoritative system knowledge. Preserved here for its technical texture; the construction kit shows how it folds.
Motivation — the failure it kills
Deployment facts (which layer a service is in, its tier, what may depend on what) end up hardcoded in deploy scripts and import checks. Hardcoded, they drift from the real topology: a service moves tier, a layer boundary is quietly crossed, and the deploy or an architectural invariant breaks. And an agent reasoning about "can layer X import layer Y?" needs the boundary declared, not inferred.
Why it's not just "encode the topology in the deploy scripts"
Topology in the deploy scripts is a copy. It drifts from the real service set and from the layering the code actually has. These structured models declare the topology once (managed-deployment loader, tier classification, layer-boundary contracts), and parity lints check the declaration against reality (deploy phase tables, import-layer checks). One declared topology, validated against the running system, means a moved tier or a crossed boundary fails a lint at author time — the scattered constants had no such check, so they drifted until a deploy broke.
Mechanism
The Deployment-topology loader is the typed loader for the managed-deployment topology; the Service-tier registry classifies each service's tier; the Layer-boundary contracts declare the layer boundaries for the agent substrate. Deploy scripts and layering lints (the deploy-phase-table parity lint, the import-layer checks) read them and gate on divergence.
Prerequisites
- A typed topology + tier + layering schema.
- Deploy scripts + layering lints that read it rather than hardcoding.
- Parity lints against the real deploy tables and import graph.
Consequences & costs
- Topology changes are model edits — a moved tier or new layer boundary means a model edit or a parity failure.
- Layering contracts constrain the code — a declared boundary blocks a cross-layer import (deliberately; a real cost to expedient shortcuts).
Known uses
- The Deployment-topology loader · Service-tier registry · Layer-boundary contracts.
- The deploy-phase-table parity lint + the import-layer boundary lints.
Related mechanisms
- Bridge — agents reason about layering/tiers through these models (agent side) ◀──▶ they govern the real deployment + import structure of the codebase (product side).
- Enabler — feeds model-driven-codegen (deploy/env generation).
- Counterpart — drift-parity-gates: the deploy-parity + layer lints.
Governed by
The mechanisms that hold this model true — inverted from their Governs edges at build time, never hand-written. A direct governor names this model; a trunk mechanism governs every model.
- Coverage → model-node mapping (which invariants are actually tested) — Project test coverage onto model nodes (states, seams, invariants) so untested ones are visible. governs every model
- Drift & parity gates — Bidirectional model↔reality checks so models cannot drift. governs every model
- Enforce at the right semantic level — Match a mechanism's enforcement scope to the semantic scope of the property it checks. governs every model
- Executable source-of-truth models — Structured models read every run and generated from; can't drift. governs every model
- Formal invariant verification (temporal form → model checking) — Each invariant's temporal-logic form derives its checker — proven, not sampled. governs every model
- Invariant-DAG execution policy (a typed Scheduler separates correctness from resource + cost) — A DAG holds correctness + cost-gate edges only; a typed Scheduler rations load + budget per host. governs every model
- Meta-model consumption discipline (read, don't hardcode) — Read the model at runtime; never hardcode a snapshot. governs every model
- Model query surface (`repo-query`) — repo-query — the agent-facing read API over the models. governs every model
- Model-derived test-obligation census (derive what should be tested, lint the gap) — Derive the should-be-tested set from the models and lint the gap to the tests that exist. governs every model
- Model-driven codegen — Generate real artifacts from the models, provenance-headed. governs every model
- Model-graded finding severity (distance-graded gate) — A gate grades each finding block/warn/silence by its model-distance from the changed files. governs every model
- Orphan-coverage metric (walk code → governance; score the un-covered remainder) — Walk code → governing model/control; score the orphans; each orphan cluster is candidate work. governs every model
- The agent-first MBSE harness — Structured frozen-record models + five hand-rolled disciplines; adopt the schema, skip the runtime. governs every model