Skip to content

23 Ontology.Algorithms

Jump to bottom
Varietyz edited this page Oct 5, 2026 · 4 revisions

Algorithms — Ontology — Bane's Lab

Every algorithm contract in this domain is listed with its position on the derivation loop, its intent and invariant, the flow it walks and its productions as a…

Canonical: https://banes-lab.com/ontology/algorithms

The Ontology

The ontology is a queryable canon of software architecture. It holds every principle with its relations and its repair, every term with its definition, every algorithm with its contract, the reasoning that derives them, the layers they live in and how every tension between them is resolved, and every reference from one record to another is a link.

Algorithms

452 of 452 shown

Sections

Agent creation

Every algorithm contract in this domain is listed with its position on the derivation loop, its intent and invariant, the flow it walks and its productions as a grammar. Each record also shows what it composes and is composed by, which forces and principles it answers to, what grounds it and what it grounds, and an exemplar where the record carries one. The diagram shows what composes what inside the domain.

Relations diagram

What composes what inside this domain.

flowchart LR
    n_evidence_before_generation["Evidence-Before-Generation"]
    n_semantic_operation_boundary["Semantic Operation Boundary"]
    n_capability_profile["Capability Profile"]
    n_creation_history_collision["Creation History Collision"]
    n_domain_cache_validation["Domain Cache Validation"]
    n_scope_extraction["Scope Extraction"]
    n_non_destructive_domain_investigation["Non-Destructive Domain Investigation"]
    n_domain_knowledge_base["Domain Knowledge Base"]
    n_risk_complexity_reversibility["Risk Complexity Reversibility"]
    n_existing_pattern_extraction["Existing Pattern Extraction"]
    n_knowledge_documentation_relevance["Knowledge Documentation Relevance"]
    n_principle_extraction["Principle Extraction"]
    n_adaptive_phase_boundary["Adaptive Phase Boundary"]
    n_phase_validation_requirement["Phase Validation Requirement"]
    n_portable_contract_composition["Portable Contract Composition"]
    n_validation_strategy_composition["Validation Strategy Composition"]
    n_replacement_safety["Replacement Safety"]
    n_adapter_rendering["Adapter Rendering"]
    n_audit_artifact["Audit Artifact"]
    n_semantic_compliance_validation["Semantic Compliance Validation"]
    n_evidence_grounding_validation["Evidence Grounding Validation"]
    n_algorithmic_embodiment_validation["Algorithmic Embodiment Validation"]
    n_final_generation_report["Final Generation Report"]
    n_agent_generation_completion["Agent Generation Completion"]
    n_agent_creator_kernel["Agent Creator Kernel"]
    n_agent_generation_concern["<Agent Generation Concern>"]
    n_audit_artifact --> n_capability_profile
    n_agent_creator_kernel --> n_capability_profile
    n_agent_creator_kernel --> n_scope_extraction
    n_agent_creator_kernel --> n_domain_knowledge_base
    n_agent_creator_kernel --> n_principle_extraction
    n_agent_creator_kernel --> n_adapter_rendering
    n_agent_creator_kernel --> n_final_generation_report
    n_agent_creator_kernel --> n_agent_generation_completion
    n_agent_creator_kernel --> n_evidence_before_generation
    n_agent_creator_kernel --> n_risk_complexity_reversibility
    n_agent_creator_kernel --> n_adaptive_phase_boundary
    n_agent_creator_kernel --> n_creation_history_collision
    n_agent_creator_kernel --> n_phase_validation_requirement
    n_agent_creator_kernel --> n_evidence_grounding_validation
Loading

Evidence-Before-Generation

Details

Intent Discover available context, inspect target-domain resources, extract concrete facts, construct a knowledge base, and generate only from verified evidence.

Invariant Agent generation must be grounded in inspected domain structure, not assumptions.

Flow

Request → Discover → Inspect → ExtractFacts → KnowledgeBase → Generate

Productions

EvidenceBeforeGeneration ::= <UserRequest> "→" <ResourceDiscovery> "→" <DomainInspection> "→" <FactExtraction> "→" <KnowledgeBase> "→" <GeneratedAgent>
GeneratedAgent ::= "allowed_only_if_evidence_grounded"

Composes none

Named in the derivation of Agent Creator Kernel

Forces runtime_extensibility, model_governance, domain_boundary

Grounds none

Before

An agent generated from the request text and prior model knowledge, never inspecting the target.

After

request → discover resources → inspect domain → extract facts → knowledge base → generate only from verified evidence

How it is checked

Checked by the agent auditor, which walks a generated agent against the agent-quality dimensions, the structured-document validator, which holds every agent to the grammar's node form

Population Every agent the creator generates, and the domain evidence each one cites

Freshness A verdict stands until the agent, its evidence or the grammar changes

Refusal The validator fails an agent with a malformed node or gate, and the creator persists no agent that fails its grounding or embodiment check

Observation None, because an agent contract is text; its runs are observed by the checks it declares

Evidence Watched to fire and to accept: a suite plants a retired head in a real agent document and validates every agent on disk clean, while the auditor's walk is stated as a class

Authoritative side The grammar and the agent-quality dimensions, which every generated agent conforms to

Depends on Not answered

Shape it refuses Not answered

Semantic Operation Boundary

Details

Intent Define required work as semantic operations, defer runtime execution details to adapters, and reject runtime-specific primitives from the portable core contract.

Invariant The core agent contract describes what must happen; the adapter decides how it happens.

Flow

SemanticVerb → AdapterMapping → RuntimeAction → Result

Productions

SemanticBoundary ::= <SemanticOperation> "→" <AdapterMapping> "→" <RuntimeExecution> "→" <EvidenceResult>
SemanticOperation ::= "DECLARE_RESOURCE" | "DISCOVER_RESOURCES" | "READ_RESOURCE" | "SEARCH_CONTENT" | "ANALYZE_CONTENT" | "EXTRACT_FACTS" | "CALCULATE_METRIC" | "COMPOSE_ARTIFACT" | "VALIDATE_ARTIFACT" | "PERSIST_ARTIFACT" | "REPORT_RESULT" | "REQUEST_DECISION"
CoreConstraint ::= "no_runtime_specific_paths_or_commands"

Composes none

Forces modularity, contract_compatibility, semantic_consistency

Grounds none

Before

The agent core hardcodes a specific search command and an absolute path, so it only runs on one runtime.

After

semantic op{DISCOVER/READ/SEARCH/ANALYZE} → adapter maps to the runtime → the core carries no runtime path or command

How it is checked

Checked by the agent auditor, which walks a generated agent against the agent-quality dimensions, the structured-document validator, which holds every agent to the grammar's node form

Population Every agent the creator generates, and the domain evidence each one cites

Freshness A verdict stands until the agent, its evidence or the grammar changes

Refusal The validator fails an agent with a malformed node or gate, and the creator persists no agent that fails its grounding or embodiment check

Observation None, because an agent contract is text; its runs are observed by the checks it declares

Evidence Watched to fire and to accept: a suite plants a retired head in a real agent document and validates every agent on disk clean, while the auditor's walk is stated as a class

Authoritative side The grammar and the agent-quality dimensions, which every generated agent conforms to

Depends on Not answered

Shape it refuses Not answered

Capability Profile

Details

Intent Detect filesystem, search, execution, persistence, validation, and user-interaction capabilities; mark unsupported capabilities; substitute where safe; block where required capability is non-substitutable.

Invariant Generated workflows must know what their runtime can do.

Flow

CapabilitySet → Probe → Available|Unavailable|Substituted → RuntimeMode

Productions

CapabilityProfile ::= <RequiredCapabilitySet> "→" <CapabilityProbeSet> "→" <CapabilityVerdict>
CapabilityVerdict ::= "full" | "degraded" | "blocked"
Capability ::= "filesystem" | "search" | "execution" | "persistence" | "validation" | "user_interaction"

Composes none

Composed by Audit Artifact, Agent Creator Kernel

Forces correctness_verification

Grounds none

Before

The agent assumes it can execute and write, then fails when it cannot.

After

required capabilities{filesystem, search, execution, persistence, validation} → probe each → mode{full | degraded | blocked}

How it is checked

Checked by the agent auditor, which walks a generated agent against the agent-quality dimensions, the structured-document validator, which holds every agent to the grammar's node form

Population Every agent the creator generates, and the domain evidence each one cites

Freshness A verdict stands until the agent, its evidence or the grammar changes

Refusal The validator fails an agent with a malformed node or gate, and the creator persists no agent that fails its grounding or embodiment check

Observation None, because an agent contract is text; its runs are observed by the checks it declares

Evidence Watched to fire and to accept: a suite plants a retired head in a real agent document and validates every agent on disk clean, while the auditor's walk is stated as a class

Authoritative side The grammar and the agent-quality dimensions, which every generated agent conforms to

Depends on Not answered

Shape it refuses Not answered

Creation History Collision

Details

Intent Load existing agent and invocation registries, map existing identities, compare target name and domain, and require the developer's decision before refinement, renaming, replacement, or cancellation.

Invariant Agent creation must not silently duplicate or overwrite prior work.

Flow

TargetAgent → ExistingRegistry → NameCollision? → DomainCollision? → Decision

Productions

CreationCollision ::= <TargetAgentName> "→" <ExistingAgentMap> "→" <CollisionCheck> "→" <AgentOperationMode>
AgentOperationMode ::= "CREATE" | "REFINE" | "RENAME" | "REPLACE" | "CANCEL"
CollisionCheck ::= "name_collision" | "domain_collision" | "none"

Composes none

Named in the derivation of Agent Creator Kernel

Forces semantic_consistency, domain_boundary

Grounds none

Before

A new agent silently overwrites an existing one of the same name.

After

target name → existing registry → name/domain collision? → developer decision{CREATE|REFINE|RENAME|REPLACE|CANCEL}

How it is checked

Checked by the agent auditor, which walks a generated agent against the agent-quality dimensions, the structured-document validator, which holds every agent to the grammar's node form

Population Every agent the creator generates, and the domain evidence each one cites

Freshness A verdict stands until the agent, its evidence or the grammar changes

Refusal The validator fails an agent with a malformed node or gate, and the creator persists no agent that fails its grounding or embodiment check

Observation None, because an agent contract is text; its runs are observed by the checks it declares

Evidence Watched to fire and to accept: a suite plants a retired head in a real agent document and validates every agent on disk clean, while the auditor's walk is stated as a class

Authoritative side The grammar and the agent-quality dimensions, which every generated agent conforms to

Depends on Not answered

Shape it refuses Not answered

Domain Cache Validation

Details

Intent Normalize the domain path, compute a domain hash, search cache entries, fingerprint the domain's sources, and reuse cached knowledge only when the entry's identity matches and its derivation fingerprint equals the current one.

Invariant Prior domain intelligence can be reused only when freshness and identity are verified.

Flow

DomainPath → Normalize → Hash → CacheLookup → FingerprintCheck → UseCache|Investigate

Productions

DomainCache ::= <DomainPath> "→" <DomainHash> "→" <CacheEntry> "→" <SourceFingerprint> "→" <CacheDecision>
CacheDecision ::= "use_cached_domain" | "reject_stale_cache" | "no_cache_investigate"

Composes none

Forces semantic_consistency, correctness_verification, domain_boundary

Grounds none

Before

Stale cached domain intelligence reused as if it were current.

After

domain path → normalize + hash → cache lookup → fingerprint of the domain's sources vs the entry's derivation fingerprint → {use cached | reject stale | investigate}

How it is checked

Checked by the agent auditor, which walks a generated agent against the agent-quality dimensions, the structured-document validator, which holds every agent to the grammar's node form

Population Every agent the creator generates, and the domain evidence each one cites

Freshness A verdict stands until the agent, its evidence or the grammar changes

Refusal The validator fails an agent with a malformed node or gate, and the creator persists no agent that fails its grounding or embodiment check

Observation None, because an agent contract is text; its runs are observed by the checks it declares

Evidence Watched to fire and to accept: a suite plants a retired head in a real agent document and validates every agent on disk clean, while the auditor's walk is stated as a class

Authoritative side The grammar and the agent-quality dimensions, which every generated agent conforms to

Depends on Not answered

Shape it refuses Not answered

Scope Extraction

Details

Intent Determine whether the target is a resource, directory, module, repository, or unknown scope; then extract interfaces, declarations, dependencies, systems, or boundaries appropriate to that scope.

Invariant Investigation depth must match target-domain shape.

Flow

TargetPath → InvestigationType → ScopeModel → ResourceSet → InterfaceFacts

Productions

ScopeExtraction ::= <TargetPath> "→" <InvestigationDepth> "→" <DomainScope>
InvestigationDepth ::= "single-resource" | "directory" | "module" | "repository" | "auto"
DomainScope ::= <ResourceScope> | <DirectoryScope> | <ModuleScope> | <RepositoryScope>

Composes none

Composed by Agent Creator Kernel

Forces modularity, contract_compatibility, domain_boundary

Grounds none

Before

A repository investigated at single-file depth, missing every boundary.

After

target → investigation depth{single-resource|directory|module|repository} → scope-matched facts{interfaces, deps, boundaries}

How it is checked

Checked by the agent auditor, which walks a generated agent against the agent-quality dimensions, the structured-document validator, which holds every agent to the grammar's node form

Population Every agent the creator generates, and the domain evidence each one cites

Freshness A verdict stands until the agent, its evidence or the grammar changes

Refusal The validator fails an agent with a malformed node or gate, and the creator persists no agent that fails its grounding or embodiment check

Observation None, because an agent contract is text; its runs are observed by the checks it declares

Evidence Watched to fire and to accept: a suite plants a retired head in a real agent document and validates every agent on disk clean, while the auditor's walk is stated as a class

Authoritative side The grammar and the agent-quality dimensions, which every generated agent conforms to

Depends on Not answered

Shape it refuses Not answered

Non-Destructive Domain Investigation

Details

Intent Prepare static investigation, optionally prepare safe executable analysis, prohibit source mutation, execute or emulate analysis, and merge observable outputs into domain intelligence.

Invariant Domain discovery may inspect and analyze, but must not mutate the source domain.

Flow

StaticPlan + OptionalExecutablePlan → Analyze → ExtractStructure → CacheResults

Productions

DomainInvestigation ::= <InvestigationPlan> "→" <AnalysisExecution> "→" <DomainKnowledge>
InvestigationPlan ::= <StaticAnalysisPlan> "," <OptionalExecutableAnalysisPlan>
ExecutionConstraint ::= "non_destructive" "," "observable_output_required" "," "source_mutation_forbidden"

Composes none

Forces runtime_extensibility, state_transaction, observability_traceability, domain_boundary

Grounds none

Before

Investigation runs a script that mutates the source it is inspecting.

After

static plan (+ optional safe executable) → analyze, never mutate the source → observable output → domain knowledge

How it is checked

Checked by the agent auditor, which walks a generated agent against the agent-quality dimensions, the structured-document validator, which holds every agent to the grammar's node form

Population Every agent the creator generates, and the domain evidence each one cites

Freshness A verdict stands until the agent, its evidence or the grammar changes

Refusal The validator fails an agent with a malformed node or gate, and the creator persists no agent that fails its grounding or embodiment check

Observation None, because an agent contract is text; its runs are observed by the checks it declares

Evidence Watched to fire and to accept: a suite plants a retired head in a real agent document and validates every agent on disk clean, while the auditor's walk is stated as a class

Authoritative side The grammar and the agent-quality dimensions, which every generated agent conforms to

Depends on Not answered

Shape it refuses Not answered

Domain Knowledge Base

Details

Intent Store target scope, discovered structure, purposes, dependencies, interfaces, patterns, statistics, timestamp, and evidence sources in a reusable knowledge object.

Invariant Agent generation needs an explicit evidence substrate.

Flow

DomainFacts → Statistics → EvidenceSources → KnowledgeBase

Productions

DomainKnowledgeBase ::= <DomainScope> "," <DomainStructure> "," <PurposeSet> "," <DependencyMap> "," <InterfaceSet> "," <PatternSet> "," <Statistics> "," <EvidenceSourceSet>
Statistics ::= "resource_count" "," "interface_count" "," "dependency_count" "," "resource_types" "," "architectural_patterns"

Composes none

Composed by Agent Creator Kernel

Forces contract_compatibility, domain_boundary

Grounds none

Before

Generation proceeds with no explicit evidence substrate to cite.

After

domain facts + structure + purposes + deps + interfaces + patterns + statistics + evidence sources → reusable knowledge base

How it is checked

Checked by the agent auditor, which walks a generated agent against the agent-quality dimensions, the structured-document validator, which holds every agent to the grammar's node form

Population Every agent the creator generates, and the domain evidence each one cites

Freshness A verdict stands until the agent, its evidence or the grammar changes

Refusal The validator fails an agent with a malformed node or gate, and the creator persists no agent that fails its grounding or embodiment check

Observation None, because an agent contract is text; its runs are observed by the checks it declares

Evidence Watched to fire and to accept: a suite plants a retired head in a real agent document and validates every agent on disk clean, while the auditor's walk is stated as a class

Authoritative side The grammar and the agent-quality dimensions, which every generated agent conforms to

Depends on Not answered

Shape it refuses Not answered

Risk Complexity Reversibility

Details

Intent Analyze domain dependencies, side effects, resource count, interface count, dependency patterns, and uncertainty factors to assign risk, complexity, reversibility, and uncertainty.

Invariant Phase rigor should be proportional to domain risk and complexity.

Flow

KnowledgeBase → RiskFactors → ComplexityScore → Reversibility → Uncertainty

Productions

DomainCharacteristics ::= <RiskLevel> "," <ComplexityScore> "," <Reversibility> "," <UncertaintyLevel>
RiskLevel ::= "low" | "medium" | "high"
Reversibility ::= "reversible" | "partially-reversible" | "irreversible"
UncertaintyLevel ::= "low" | "medium" | "high"

Composes none

Named in the derivation of Agent Creator Kernel

Forces contract_compatibility, domain_boundary

Grounds none

Before

Every agent given the same phase count regardless of how risky its domain is.

After

knowledge base → risk{low|medium|high} + complexity + reversibility{reversible|partial|irreversible} + uncertainty

How it is checked

Checked by the agent auditor, which walks a generated agent against the agent-quality dimensions, the structured-document validator, which holds every agent to the grammar's node form

Population Every agent the creator generates, and the domain evidence each one cites

Freshness A verdict stands until the agent, its evidence or the grammar changes

Refusal The validator fails an agent with a malformed node or gate, and the creator persists no agent that fails its grounding or embodiment check

Observation None, because an agent contract is text; its runs are observed by the checks it declares

Evidence Watched to fire and to accept: a suite plants a retired head in a real agent document and validates every agent on disk clean, while the auditor's walk is stated as a class

Authoritative side The grammar and the agent-quality dimensions, which every generated agent conforms to

Depends on Not answered

Shape it refuses Not answered

Existing Pattern Extraction

Details

Intent Inspect existing agent specifications, count phase markers, validation gates, and semantic operations, extract reusable structures, and derive baseline design conventions.

Invariant New agents should conform to proven local agent grammar where evidence exists.

Flow

ExistingSpecs → PhaseCount → GateCount → OperationUsage → ReusablePatterns

Productions

ExistingPatternExtraction ::= <ExistingAgentSpecSet> "→" <StructuralMetricSet> "→" <ReusablePatternSet>
StructuralMetricSet ::= "phase_count" "," "validation_gate_count" "," "semantic_operation_count"

Composes none

Forces semantic_consistency, correctness_verification

Grounds none

Before

A new agent invented in a shape that ignores the local agent grammar.

After

existing specs → count{phases, gates, semantic ops} → reusable structures → baseline conventions

How it is checked

Checked by the agent auditor, which walks a generated agent against the agent-quality dimensions, the structured-document validator, which holds every agent to the grammar's node form

Population Every agent the creator generates, and the domain evidence each one cites

Freshness A verdict stands until the agent, its evidence or the grammar changes

Refusal The validator fails an agent with a malformed node or gate, and the creator persists no agent that fails its grounding or embodiment check

Observation None, because an agent contract is text; its runs are observed by the checks it declares

Evidence Watched to fire and to accept: a suite plants a retired head in a real agent document and validates every agent on disk clean, while the auditor's walk is stated as a class

Authoritative side The grammar and the agent-quality dimensions, which every generated agent conforms to

Depends on Not answered

Shape it refuses Not answered

Knowledge Documentation Relevance

Details

Intent Discover knowledge documents, read descriptions, compare them against domain characteristics, score relevance, and exclude irrelevant documents from core reasoning.

Invariant Supporting documents should influence generation only when relevant to the target domain.

Flow

KnowledgeDocs → RelevanceAnalysis → RelevantDocs → PrincipleInput

Productions

KnowledgeRelevance ::= <KnowledgeDocumentSet> "→" <RelevanceScoreSet> "→" <RelevantKnowledgeSet>
RelevanceDecision ::= "include" | "exclude"

Composes none

Forces runtime_extensibility, domain_boundary

Grounds none

Before

Every knowledge doc fed into reasoning, relevant or not.

After

knowledge docs → read descriptions → score relevance vs domain → include relevant, exclude the rest

How it is checked

Checked by the agent auditor, which walks a generated agent against the agent-quality dimensions, the structured-document validator, which holds every agent to the grammar's node form

Population Every agent the creator generates, and the domain evidence each one cites

Freshness A verdict stands until the agent, its evidence or the grammar changes

Refusal The validator fails an agent with a malformed node or gate, and the creator persists no agent that fails its grounding or embodiment check

Observation None, because an agent contract is text; its runs are observed by the checks it declares

Evidence Watched to fire and to accept: a suite plants a retired head in a real agent document and validates every agent on disk clean, while the auditor's walk is stated as a class

Authoritative side The grammar and the agent-quality dimensions, which every generated agent conforms to

Depends on Not answered

Shape it refuses Not answered

Principle Extraction

Details

Intent Start from structural principles, test applicability against domain characteristics, add domain-specific principles from relevant documents, and exclude runtime-specific principles from the core.

Invariant Generated agents should embody portable design principles selected from evidence.

Flow

StructuralPrinciples + DomainDocs → Applicability → CorePrinciples

Productions

PrincipleExtraction ::= <CandidatePrincipleSet> "→" <ApplicabilityAnalysis> "→" <CorePrincipleSet>
CorePrinciple ::= "phase_gated_execution" | "validation_boundaries" | "declaration_before_use" | "evidence_before_composition" | "adapter_separation" | "auditability"

Composes none

Composed by Agent Creator Kernel

Named in the derivation of Agent Creator Kernel

Forces domain_boundary

Grounds none

Before

Runtime-specific principles baked into the portable core.

After

structural candidates + domain docs → test applicability → core principles{phase-gated, validation-boundaries, declaration-before-use, evidence-before-composition, adapter-separation, auditability}; runtime-specific excluded

How it is checked

Checked by the agent auditor, which walks a generated agent against the agent-quality dimensions, the structured-document validator, which holds every agent to the grammar's node form

Population Every agent the creator generates, and the domain evidence each one cites

Freshness A verdict stands until the agent, its evidence or the grammar changes

Refusal The validator fails an agent with a malformed node or gate, and the creator persists no agent that fails its grounding or embodiment check

Observation None, because an agent contract is text; its runs are observed by the checks it declares

Evidence Watched to fire and to accept: a suite plants a retired head in a real agent document and validates every agent on disk clean, while the auditor's walk is stated as a class

Authoritative side The grammar and the agent-quality dimensions, which every generated agent conforms to

Depends on Not answered

Shape it refuses Not answered

Adaptive Phase Boundary

Details

Intent Select phase count from risk and complexity, assign phase boundaries, and strengthen validation density for high-risk or high-complexity domains.

Invariant Agent structure should scale with domain difficulty.

Flow

Risk + Complexity + Uncertainty → PhaseCount → PhaseBoundaries

Productions

PhaseBoundarySelection ::= <RiskLevel> "," <ComplexityScore> "," <UncertaintyLevel> "→" <PhaseStructure>
PhaseStructure ::= <ThreePhase> | <FivePhase> | <SevenPhase>
ThreePhase ::= "Discovery" "," "Generation" "," "Verification"
FivePhase ::= "Discovery" "," "Analysis" "," "Generation" "," "Verification" "," "Finalization"
SevenPhase ::= "Discovery" "," "Analysis" "," "Planning" "," "Validation" "," "Generation" "," "Verification" "," "Finalization"

Composes none

Named in the derivation of Agent Creator Kernel

Forces modularity, correctness_verification, performance_scaling, domain_boundary

Grounds tel-priority

Before

A high-risk irreversible domain given a 3-phase agent.

After

risk + complexity + uncertainty → phase count{3 | 5 | 7} → validation density proportional to difficulty

How it is checked

Checked by the agent auditor, which walks a generated agent against the agent-quality dimensions, the structured-document validator, which holds every agent to the grammar's node form

Population Every agent the creator generates, and the domain evidence each one cites

Freshness A verdict stands until the agent, its evidence or the grammar changes

Refusal The validator fails an agent with a malformed node or gate, and the creator persists no agent that fails its grounding or embodiment check

Observation None, because an agent contract is text; its runs are observed by the checks it declares

Evidence Watched to fire and to accept: a suite plants a retired head in a real agent document and validates every agent on disk clean, while the auditor's walk is stated as a class

Authoritative side The grammar and the agent-quality dimensions, which every generated agent conforms to

Depends on Not answered

Shape it refuses Not answered

Phase Validation Requirement

Details

Intent For every phase boundary, generate explicit validation requirements from the phase purpose, adapter-separation needs, evidence-grounding needs, and safety constraints.

Invariant Every phase must end with verifiable exit conditions.

Flow

PhaseSet → RequirementDerivation → ValidationGateSet

Productions

PhaseValidation ::= <PhaseSet> "→" <ValidationRequirementSet> "→" <ValidationGateSet>
PhaseValidationGate ::= <PhaseName> ":" <RequirementSet>
RequirementSet ::= <Requirement> | <Requirement> "," <RequirementSet>

Composes none

Named in the derivation of Agent Creator Kernel

Forces modularity, correctness_verification, model_governance

Grounds none

Before

A phase ends with no verifiable exit condition.

After

phase → derive requirements{purpose, adapter-separation, evidence-grounding, safety} → a validation gate per phase

How it is checked

Checked by the agent auditor, which walks a generated agent against the agent-quality dimensions, the structured-document validator, which holds every agent to the grammar's node form

Population Every agent the creator generates, and the domain evidence each one cites

Freshness A verdict stands until the agent, its evidence or the grammar changes

Refusal The validator fails an agent with a malformed node or gate, and the creator persists no agent that fails its grounding or embodiment check

Observation None, because an agent contract is text; its runs are observed by the checks it declares

Evidence Watched to fire and to accept: a suite plants a retired head in a real agent document and validates every agent on disk clean, while the auditor's walk is stated as a class

Authoritative side The grammar and the agent-quality dimensions, which every generated agent conforms to

Depends on Not answered

Shape it refuses Not answered

Portable Contract Composition

Details

Intent Compose identity, purpose, methodology, domain scope, characteristics, capabilities, phases, validation strategy, constraints, and required outputs into a runtime-neutral agent contract.

Invariant The portable contract is the canonical artifact; adapter outputs are renderings.

Flow

KnowledgeBase + Principles + Phases → PortableContract

Productions

PortableAgentContract ::= <Identity> "," <Purpose> "," <DomainModel> "," <CapabilityRequirements> "," <PhaseSpecifications> "," <ValidationStrategy> "," <SafetyConstraints> "," <OutputContract>
OutputContract ::= "portable_agent_contract" | "invocation_contract" | "audit_report" | "final_report"

Composes none

Forces contract_compatibility, semantic_consistency, correctness_verification, domain_boundary

Grounds none

Before

The agent authored directly as a runtime artifact, welded to one runtime.

After

knowledge base + principles + phases → runtime-neutral contract{identity, purpose, domain model, capabilities, phase specs, validation strategy, constraints, outputs} = the canonical artifact

How it is checked

Checked by the agent auditor, which walks a generated agent against the agent-quality dimensions, the structured-document validator, which holds every agent to the grammar's node form

Population Every agent the creator generates, and the domain evidence each one cites

Freshness A verdict stands until the agent, its evidence or the grammar changes

Refusal The validator fails an agent with a malformed node or gate, and the creator persists no agent that fails its grounding or embodiment check

Observation None, because an agent contract is text; its runs are observed by the checks it declares

Evidence Watched to fire and to accept: a suite plants a retired head in a real agent document and validates every agent on disk clean, while the auditor's walk is stated as a class

Authoritative side The grammar and the agent-quality dimensions, which every generated agent conforms to

Depends on Not answered

Shape it refuses Not answered

Validation Strategy Composition

Details

Intent Define pre-generation, during-generation, and post-generation checks that enforce capabilities, creation history, evidence grounding, adapter separation, schema validity, and absence of unsupported assumptions.

Invariant Generated artifacts must be validated throughout composition, not only afterward.

Flow

PreChecks → DuringChecks → PostChecks → ValidationStrategy

Productions

GenerationValidationStrategy ::= <PreGenerationChecks> "," <DuringGenerationChecks> "," <PostGenerationChecks>
PreGenerationChecks ::= "capabilities_detected" "," "history_checked" "," "domain_knowledge_available"
DuringGenerationChecks ::= "phase_gates_enforced" "," "evidence_grounded_content" "," "adapter_separated"
PostGenerationChecks ::= "schema_valid" "," "audit_complete" "," "unsupported_assumptions_absent"

Composes none

Forces modularity, correctness_verification, model_governance

Grounds none

Before

The artifact validated only after it is written, never during.

After

pre{capabilities detected, history checked, knowledge available} + during{phase gates, evidence-grounded, adapter-separated} + post{schema valid, audit complete, no unsupported assumptions}

How it is checked

Checked by the agent auditor, which walks a generated agent against the agent-quality dimensions, the structured-document validator, which holds every agent to the grammar's node form

Population Every agent the creator generates, and the domain evidence each one cites

Freshness A verdict stands until the agent, its evidence or the grammar changes

Refusal The validator fails an agent with a malformed node or gate, and the creator persists no agent that fails its grounding or embodiment check

Observation None, because an agent contract is text; its runs are observed by the checks it declares

Evidence Watched to fire and to accept: a suite plants a retired head in a real agent document and validates every agent on disk clean, while the auditor's walk is stated as a class

Authoritative side The grammar and the agent-quality dimensions, which every generated agent conforms to

Depends on Not answered

Shape it refuses Not answered

Replacement Safety

Details

Intent If replacing an existing artifact, require prior approval, archive existing artifacts, verify archive persistence, and block new persistence if archival cannot be confirmed.

Invariant Destructive generation requires recoverability before mutation.

Flow

ReplaceIntent → Approval → ArchiveExisting → VerifyArchive → Persist|Block

Productions

ReplacementSafety ::= <AgentOperationMode> "→" <ArchivePolicy> "→" <SafetyCheck> "→" <PersistenceDecision>
ArchivePolicy ::= "archive_required_if_replace" | "archive_not_required"
PersistenceDecision ::= "safe_to_persist" | "blocked"

Composes none

Forces state_transaction, correctness_verification

Grounds none

Before

An existing agent overwritten with no archive — the original is lost.

After

REPLACE → require approval → archive existing → verify the archive → persist only if recoverable, else block

How it is checked

Checked by the agent auditor, which walks a generated agent against the agent-quality dimensions, the structured-document validator, which holds every agent to the grammar's node form

Population Every agent the creator generates, and the domain evidence each one cites

Freshness A verdict stands until the agent, its evidence or the grammar changes

Refusal The validator fails an agent with a malformed node or gate, and the creator persists no agent that fails its grounding or embodiment check

Observation None, because an agent contract is text; its runs are observed by the checks it declares

Evidence Watched to fire and to accept: a suite plants a retired head in a real agent document and validates every agent on disk clean, while the auditor's walk is stated as a class

Authoritative side The grammar and the agent-quality dimensions, which every generated agent conforms to

Depends on Not answered

Shape it refuses Not answered

Adapter Rendering

Details

Intent Render the portable contract into runtime-specific agent specification, invocation contract, and audit artifacts only through adapter-defined schemas and destinations.

Invariant Runtime-specific artifacts are projections of the portable contract, not replacements for it.

Flow

PortableContract → AdapterSchema → RenderedArtifact → Validate → Persist

Productions

AdapterRendering ::= <PortableContract> "→" <AdapterConfig> "→" <ArtifactSet> "→" <AdapterValidation> "→" <Persistence>
ArtifactSet ::= "agent_specification" "," "invocation_contract" "," "audit_report"
AdapterConstraint ::= "adapter_may_add_metadata_but_not_alter_core_intent"

Composes none

Composed by Agent Creator Kernel

Named in the derivation of Agent Creator Kernel

Forces contract_compatibility

Grounds none

Before

The runtime artifact edited directly, diverging from the portable contract.

After

portable contract → adapter schema → artifacts{agent spec, invocation contract, audit} → adapter may add metadata, never alter core intent

How it is checked

Checked by the agent auditor, which walks a generated agent against the agent-quality dimensions, the structured-document validator, which holds every agent to the grammar's node form

Population Every agent the creator generates, and the domain evidence each one cites

Freshness A verdict stands until the agent, its evidence or the grammar changes

Refusal The validator fails an agent with a malformed node or gate, and the creator persists no agent that fails its grounding or embodiment check

Observation None, because an agent contract is text; its runs are observed by the checks it declares

Evidence Watched to fire and to accept: a suite plants a retired head in a real agent document and validates every agent on disk clean, while the auditor's walk is stated as a class

Authoritative side The grammar and the agent-quality dimensions, which every generated agent conforms to

Depends on Not answered

Shape it refuses Not answered

Audit Artifact

Details

Intent Record agent name, domain, operation mode, runtime environment, risk, complexity, reversibility, uncertainty, phase count, validation gates, evidence sources, capability profile, adapter identity, portability status, and timestamp.

Invariant Generated agents require an inspectable provenance trail.

Flow

GenerationState → AuditFields → AuditReport

Productions

AuditReport ::= <AgentIdentity> "," <DomainReference> "," <AgentOperationMode> "," <RuntimeEnvironment> "," <RiskMetrics> "," <ValidationGateSet> "," <EvidenceSourceSet> "," <CapabilityProfile> "," <AdapterIdentity> "," <PortabilityStatus>

Composes Capability Profile

Forces correctness_verification, domain_boundary

Grounds none

Before

A generated agent with no provenance — no record of how or from what it was built.

After

generation state → audit{identity, domain, mode, risk metrics, gates, evidence sources, capability profile, adapter identity, portability status}

How it is checked

Checked by the agent auditor, which walks a generated agent against the agent-quality dimensions, the structured-document validator, which holds every agent to the grammar's node form

Population Every agent the creator generates, and the domain evidence each one cites

Freshness A verdict stands until the agent, its evidence or the grammar changes

Refusal The validator fails an agent with a malformed node or gate, and the creator persists no agent that fails its grounding or embodiment check

Observation None, because an agent contract is text; its runs are observed by the checks it declares

Evidence Watched to fire and to accept: a suite plants a retired head in a real agent document and validates every agent on disk clean, while the auditor's walk is stated as a class

Authoritative side The grammar and the agent-quality dimensions, which every generated agent conforms to

Depends on Capability Profile

Shape it refuses Not answered

Semantic Compliance Validation

Details

Intent Re-read the persisted agent specification, search for semantic operations, phase markers, validation gates, and runtime-specific leakage, then mark compliant only when required counts pass and leakage is absent.

Invariant Persistence is not enough; the stored artifact must still satisfy semantic structure.

Flow

PersistedSpec → MarkerSearch → CountMetrics → LeakageCheck → ComplianceVerdict

Productions

SemanticCompliance ::= <PersistedArtifact> "→" <SemanticMarkerSet> "→" <MetricCheck> "→" <RuntimeLeakageCheck> "→" <ComplianceVerdict>
ComplianceVerdict ::= "compliant" | "non_compliant"

Composes none

Forces semantic_consistency, correctness_verification

Grounds none

Before

The in-memory plan judged compliant, but the stored artifact never re-checked.

After

re-read persisted spec → search{semantic ops, phase markers, gates} + leakage check → compliant only if counts pass and zero runtime leakage

How it is checked

Checked by the agent auditor, which walks a generated agent against the agent-quality dimensions, the structured-document validator, which holds every agent to the grammar's node form

Population Every agent the creator generates, and the domain evidence each one cites

Freshness A verdict stands until the agent, its evidence or the grammar changes

Refusal The validator fails an agent with a malformed node or gate, and the creator persists no agent that fails its grounding or embodiment check

Observation None, because an agent contract is text; its runs are observed by the checks it declares

Evidence Watched to fire and to accept: a suite plants a retired head in a real agent document and validates every agent on disk clean, while the auditor's walk is stated as a class

Authoritative side The grammar and the agent-quality dimensions, which every generated agent conforms to

Depends on Not answered

Shape it refuses Not answered

Evidence Grounding Validation

Details

Intent Search generated output for unsupported claims and evidence references, compare generated claims against the knowledge base, calculate grounding score, and reject artifacts below threshold.

Invariant Generated architecture claims must trace back to evidence.

Flow

GeneratedSpec → UnsupportedClaimSearch → EvidenceReferenceCheck → GroundingScore → Accept|Reject

Productions

EvidenceGrounding ::= <GeneratedArtifact> "→" <ClaimAnalysis> "→" <KnowledgeBaseComparison> "→" <GroundingVerdict>
GroundingVerdict ::= "grounded" | "unsupported_claims_present" | "insufficient_evidence_references"

Composes none

Named in the derivation of Agent Creator Kernel

Forces correctness_verification, observability_traceability, model_governance

Grounds ver-evidence

Before

The generated agent asserts architecture claims that trace to nothing.

After

generated spec → find claims → compare against the knowledge base → grounding score → reject below threshold

How it is checked

Checked by the agent auditor, which walks a generated agent against the agent-quality dimensions, the structured-document validator, which holds every agent to the grammar's node form

Population Every agent the creator generates, and the domain evidence each one cites

Freshness A verdict stands until the agent, its evidence or the grammar changes

Refusal The validator fails an agent with a malformed node or gate, and the creator persists no agent that fails its grounding or embodiment check

Observation None, because an agent contract is text; its runs are observed by the checks it declares

Evidence Watched to fire and to accept: a suite plants a retired head in a real agent document and validates every agent on disk clean, while the auditor's walk is stated as a class

Authoritative side The grammar and the agent-quality dimensions, which every generated agent conforms to

Depends on Not answered

Shape it refuses Not answered

Algorithmic Embodiment Validation

Details

Intent Verify that generated agents contain phase gates, declaration-before-use structure, calculated metrics, exact thresholds or comparisons, and iterative discovery patterns.

Invariant The generated agent must embody the intended reasoning architecture, not merely describe it.

Flow

GeneratedSpec → EmbodimentMarkers → Score → Pass|Fail

Productions

AlgorithmicEmbodiment ::= <GeneratedArtifact> "→" <EmbodimentMarkerSet> "→" <EmbodimentScore> "→" <EmbodimentVerdict>
EmbodimentMarkerSet ::= "phase_gates" "," "declaration_before_use" "," "calculated_metrics" "," "thresholds" "," "iterative_discovery"
EmbodimentVerdict ::= "embodied" | "insufficiently_embodied"

Composes none

Forces runtime_extensibility, correctness_verification

Grounds none

Before

The agent describes phase gates in prose but does not embody them.

After

generated spec → markers{phase gates, declaration-before-use, calculated metrics, thresholds, iterative discovery} → embodied | insufficiently-embodied

How it is checked

Checked by the agent auditor, which walks a generated agent against the agent-quality dimensions, the structured-document validator, which holds every agent to the grammar's node form

Population Every agent the creator generates, and the domain evidence each one cites

Freshness A verdict stands until the agent, its evidence or the grammar changes

Refusal The validator fails an agent with a malformed node or gate, and the creator persists no agent that fails its grounding or embodiment check

Observation None, because an agent contract is text; its runs are observed by the checks it declares

Evidence Watched to fire and to accept: a suite plants a retired head in a real agent document and validates every agent on disk clean, while the auditor's walk is stated as a class

Authoritative side The grammar and the agent-quality dimensions, which every generated agent conforms to

Depends on Not answered

Shape it refuses Not answered

Final Generation Report

Details

Intent Summarize generated agent, target domain, operation mode, adapter, risk, complexity, reversibility, uncertainty, phase count, validation-gate count, compliance results, artifact references, degraded mode, and unsupported capabilities.

Invariant The final report must distinguish generated artifacts, validation status, and limitations.

Flow

ValidationResults + ArtifactRefs + Limitations → FinalReport

Productions

FinalGenerationReport ::= <GenerationSummary> "," <RiskSummary> "," <ComplianceSummary> "," <ArtifactReferences> "," <LimitationSet>
ComplianceSummary ::= "semantic_operations" "," "adapter" "," "evidence_grounding" "," "algorithmic_embodiment"

Composes none

Composed by Agent Creator Kernel

Named in the derivation of Agent Creator Kernel

Forces correctness_verification, domain_boundary

Grounds none

Before

A report that conflates the artifact, its validation status, and its limitations.

After

validation results + artifact refs + limitations{degraded mode, unsupported capabilities} → report distinguishing all three

How it is checked

Checked by the agent auditor, which walks a generated agent against the agent-quality dimensions, the structured-document validator, which holds every agent to the grammar's node form

Population Every agent the creator generates, and the domain evidence each one cites

Freshness A verdict stands until the agent, its evidence or the grammar changes

Refusal The validator fails an agent with a malformed node or gate, and the creator persists no agent that fails its grounding or embodiment check

Observation None, because an agent contract is text; its runs are observed by the checks it declares

Evidence Watched to fire and to accept: a suite plants a retired head in a real agent document and validates every agent on disk clean, while the auditor's walk is stated as a class

Authoritative side The grammar and the agent-quality dimensions, which every generated agent conforms to

Depends on Not answered

Shape it refuses Not answered

Agent Generation Completion

Details

Intent Accept the generated agent as complete only when semantic-compliance, evidence-grounding above threshold, and algorithmic-embodiment all pass and the audit trail is recorded; otherwise route to regeneration or a blocked report.

Invariant Agent generation terminates as accepted only on a full validation pass — never a claim while any compliance, grounding, or embodiment gate is unmet.

Flow

ValidationVerdicts → AuditPresence → Accept|Regenerate|Blocked

Productions

AgentGenerationCompletion ::= <ValidationVerdictSet> "→" <AuditCheck> "→" <AcceptanceVerdict>
AcceptanceVerdict ::= "agent_accepted" | "regenerate_required" | "blocked"

Composes none

Composed by Agent Creator Kernel

Named in the derivation of Agent Creator Kernel

Forces correctness_verification, model_governance

Grounds ter-stop

Before

A generated agent declared ready while its evidence-grounding failed and its algorithmic embodiment was insufficient.

After

semantic compliance passed + evidence grounded above threshold + algorithmically embodied + audit recorded → agent_accepted; else regenerate | blocked

How it is checked

Checked by the agent auditor, which walks a generated agent against the agent-quality dimensions, the structured-document validator, which holds every agent to the grammar's node form

Population Every agent the creator generates, and the domain evidence each one cites

Freshness A verdict stands until the agent, its evidence or the grammar changes

Refusal The validator fails an agent with a malformed node or gate, and the creator persists no agent that fails its grounding or embodiment check

Observation None, because an agent contract is text; its runs are observed by the checks it declares

Evidence Watched to fire and to accept: a suite plants a retired head in a real agent document and validates every agent on disk clean, while the auditor's walk is stated as a class

Authoritative side The grammar and the agent-quality dimensions, which every generated agent conforms to

Depends on Not answered

Shape it refuses Not answered

Agent Creator Kernel

Details

Intent Load configuration, detect capabilities, check creation history, validate cache, discover domain evidence, build knowledge base, analyze characteristics, extract principles, define phases, compose portable contract, render adapter artifacts, validate outputs, audit, and report.

Invariant Agent creation is an evidence-gated compiler from target-domain structure into portable agent contracts.

Flow

Config → Capabilities → History → Cache → Discovery → Knowledge → Analysis → Principles → Phases → Contract → AdapterRender → Validate → Audit → Report

Productions

AgentCreatorKernel ::= <ConfigurationLoad> "→" <CapabilityProfile> "→" <CreationCollision> "→" <DomainCache> "→" <ScopeExtraction> "→" <DomainInvestigation> "→" <DomainKnowledgeBase> "→" <DomainCharacteristics> "→" <PrincipleExtraction> "→" <PhaseBoundarySelection> "→" <PortableAgentContract> "→" <AdapterRendering> "→" <SemanticCompliance> "→" <EvidenceGrounding> "→" <AlgorithmicEmbodiment> "→" <AuditReport> "→" <FinalGenerationReport>

Composes Capability Profile, Scope Extraction, Domain Knowledge Base, Principle Extraction, Adapter Rendering, Final Generation Report, Agent Generation Completion

Forces contract_compatibility, runtime_extensibility, correctness_verification, domain_boundary

Principle Ungrounded Content

Grounds derivation-loop

Derivation map

orient Evidence-Before-Generation

see Risk Complexity Reversibility

derive Principle Extraction

intent Adaptive Phase Boundary

constrain Creation History Collision

project Phase Validation Requirement

act Adapter Rendering

verify Evidence Grounding Validation

commit Final Generation Report

terminate Agent Generation Completion

Before

A target domain turned straight into an agent by assumption, ungated.

After

config → capabilities → history → cache → discover evidence → knowledge → risk analysis → principles → phases → portable contract → adapter render → validate{semantic/grounding/embodiment} → audit → report

How it is checked

Checked by the agent auditor, which walks a generated agent against the agent-quality dimensions, the structured-document validator, which holds every agent to the grammar's node form

Population Every agent the creator generates, and the domain evidence each one cites

Freshness A verdict stands until the agent, its evidence or the grammar changes

Refusal The validator fails an agent with a malformed node or gate, and the creator persists no agent that fails its grounding or embodiment check

Observation None, because an agent contract is text; its runs are observed by the checks it declares

Evidence Watched to fire and to accept: a suite plants a retired head in a real agent document and validates every agent on disk clean, while the auditor's walk is stated as a class

Authoritative side The grammar and the agent-quality dimensions, which every generated agent conforms to

Depends on Capability Profile, Scope Extraction, Domain Knowledge Base, Principle Extraction, Adapter Rendering, Final Generation Report, Agent Generation Completion

Shape it refuses Not answered

Details

Intent → → → → → → → → → → →

Invariant Any generated agent should be treated as a compiled artifact whose source is inspected domain evidence and whose target is a portable, adapter-renderable contract.

Flow

Context → Capability → History → Evidence → Knowledge → Risk → Phases → Contract → Adapter → Validation → Audit → Report

Productions

AgentGenerationConcern ::= <ContextContract> "→" <CapabilityContract> "→" <CollisionPolicy> "→" <EvidenceModel> "→" <KnowledgeBase> "→" <PhaseDesign> "→" <PortableContract> "→" <AdapterArtifactSet> "→" <ValidationSet> "→" <AuditTrail> "→" <FinalReport>
ValidationSet ::= "semantic_compliance" "," "adapter_compliance" "," "evidence_grounding" "," "algorithmic_embodiment" "," "runtime_specific_leakage_absent"

Composes none

Forces contract_compatibility, runtime_extensibility, correctness_verification, model_governance, domain_boundary

Grounds none

How it is checked

Checked by the agent auditor, which walks a generated agent against the agent-quality dimensions, the structured-document validator, which holds every agent to the grammar's node form

Population Every agent the creator generates, and the domain evidence each one cites

Freshness A verdict stands until the agent, its evidence or the grammar changes

Refusal The validator fails an agent with a malformed node or gate, and the creator persists no agent that fails its grounding or embodiment check

Observation None, because an agent contract is text; its runs are observed by the checks it declares

Evidence Watched to fire and to accept: a suite plants a retired head in a real agent document and validates every agent on disk clean, while the auditor's walk is stated as a class

Authoritative side The grammar and the agent-quality dimensions, which every generated agent conforms to

Depends on Not answered

Shape it refuses Not answered

Agent workflow

Every algorithm contract in this domain is listed with its position on the derivation loop, its intent and invariant, the flow it walks and its productions as a grammar. Each record also shows what it composes and is composed by, which forces and principles it answers to, what grounds it and what it grounds, and an exemplar where the record carries one. The diagram shows what composes what inside the domain.

Relations diagram

What composes what inside this domain.

flowchart LR
    n_hybrid_workflow_orchestration["Hybrid Workflow Orchestration"]
    n_dsl_compliance_loading["DSL Compliance Loading"]
    n_agent_workflow_file_modification_recovery["Agent Workflow File Modification Recovery"]
    n_context_forking_configuration["Context Forking Configuration"]
    n_verb_based_execution_classification["Verb-Based Execution Classification"]
    n_workspace_configuration_discovery["Workspace Configuration Discovery"]
    n_shared_document_workspace["Shared Document Workspace"]
    n_workflow_type_document_selection["Workflow Type Document Selection"]
    n_agent_sequence_definition["Agent Sequence Definition"]
    n_agent_document_responsibility["Agent Document Responsibility"]
    n_agent_activation_invocation["Agent Activation Invocation"]
    n_parallel_batch_execution["Parallel Batch Execution"]
    n_sequential_agent_execution["Sequential Agent Execution"]
    n_four_dimensional_agent_graph["Four-Dimensional Agent Graph"]
    n_handoff_signal["Handoff Signal"]
    n_orchestrator_action["Orchestrator Action"]
    n_workflow_coordination_sequence["Workflow Coordination Sequence"]
    n_workflow_recovery_loop["Workflow Recovery Loop"]
    n_checklist_integration["Checklist Integration"]
    n_phase_documentation_template["Phase Documentation Template"]
    n_workflow_principles_mapping["Workflow Principles Mapping"]
    n_capability_invocation_protocol["Capability Invocation Protocol"]
    n_template_assembly["Template Assembly"]
    n_first_time_initiation["First-Time Initiation"]
    n_workflow_validation_gate["Workflow Validation Gate"]
    n_workflow_creation_kernel["Workflow Creation Kernel"]
    n_workflow_orchestration_concern["<Workflow Orchestration Concern>"]
    n_handoff_signal --> n_orchestrator_action
    n_orchestrator_action --> n_handoff_signal
    n_workflow_creation_kernel --> n_dsl_compliance_loading
    n_workflow_creation_kernel --> n_agent_workflow_file_modification_recovery
    n_workflow_creation_kernel --> n_context_forking_configuration
    n_workflow_creation_kernel --> n_workspace_configuration_discovery
    n_workflow_creation_kernel --> n_shared_document_workspace
    n_workflow_creation_kernel --> n_agent_sequence_definition
    n_workflow_creation_kernel --> n_handoff_signal
    n_workflow_creation_kernel --> n_workflow_coordination_sequence
    n_workflow_creation_kernel --> n_checklist_integration
    n_workflow_creation_kernel --> n_phase_documentation_template
    n_workflow_creation_kernel --> n_capability_invocation_protocol
    n_workflow_creation_kernel --> n_template_assembly
    n_workflow_creation_kernel --> n_workflow_validation_gate
    n_workflow_creation_kernel --> n_workflow_type_document_selection
    n_workflow_creation_kernel --> n_agent_activation_invocation
    n_workflow_creation_kernel --> n_first_time_initiation
Loading

Hybrid Workflow Orchestration

Details

Intent Classify workflow phases by execution verb, run discovery and investigation agents in parallel forked contexts, run action and mutation agents sequentially, and coordinate all agents through shared artifacts and handoff signals.

Invariant Multi-agent workflows should parallelize independent knowledge gathering while serializing state-changing work.

Flow

WorkflowObjective → AgentPhases → ExecutionClassification → ParallelDiscovery → SequentialAction → Handoff

Productions

HybridWorkflowOrchestration ::= <WorkflowObjective> "→" <AgentSequence> "→" <ExecutionModeClassification> "→" <ParallelBatchSet> "→" <SequentialActionSet> "→" <WorkflowCompletion>
ExecutionMode ::= "PARALLEL" | "SEQUENTIAL"
ParallelPhase ::= "DISCOVERY" | "INVESTIGATION" | "RESEARCH" | "ANALYSIS" | "EXPLORATION"
SequentialPhase ::= "CREATE" | "WRITE" | "EXECUTE" | "VERIFY" | "IMPLEMENT" | "REFACTOR"

Composes none

Forces runtime_extensibility, state_transaction, model_governance, event_messaging, control_coordination

Grounds none

Before

Every agent runs sequentially, even independent discovery — the workflow crawls.

After

objective → agent sequence → classify by verb → parallel discovery (forked context) + sequential action (normal context) → handoff

How it is checked

Checked by the workflow validation gate, which checks the orchestration, artifact, context and validation contracts, the structured-document validator over the workflow template

Population Every workflow template and every agent it sequences

Freshness A verdict stands until the template, an agent it sequences or the workspace configuration changes

Refusal The gate refuses to mark a template complete while any of its contracts fails

Observation The coordination record each run writes, which locates a failed handoff

Evidence None, because the catalog states this check as a class, so a watched run belongs to each system that adopts it

Authoritative side The workflow template's contracts, which each run's coordination record is compared against

Depends on Not answered

Shape it refuses Not answered

DSL Compliance Loading

Details

Intent Load grammar, keyword, operator, workflow, and checklist references before workflow generation, then require generated content to follow the declared DSL, naming, handoff, execution, forking, spawning, and capability rules.

Invariant Workflow generation must begin by loading the language and orchestration contracts that constrain output.

Flow

DSLSources → Requirements → ComplianceGate → Proceed|Block

Productions

DSLComplianceLoading ::= <DSLSpecSet> "→" <WorkflowRequirementSet> "→" <ComplianceValidationGate>
WorkflowRequirementSet ::= "agent_dsl_syntax" "," "agent_oriented_content" "," "stable_filename_convention" "," "handoff_protocol" "," "hybrid_parallel_sequential" "," "context_isolation" "," "agent_spawn_mechanism" "," "capability_invocation"

Composes none

Composed by Workflow Creation Kernel

Named in the derivation of Workflow Creation Kernel

Forces contract_compatibility, runtime_extensibility, correctness_verification, model_governance, event_messaging, metaprogramming_modeling, architecture_evolution

Grounds none

Before

Workflow generated free-form, ignoring the DSL and handoff contracts.

After

load DSL + keyword + workflow + checklist specs → require{agent-DSL syntax, handoff protocol, hybrid execution, context isolation, agent spawn} → compliance gate

How it is checked

Checked by the workflow validation gate, which checks the orchestration, artifact, context and validation contracts, the structured-document validator over the workflow template

Population Every workflow template and every agent it sequences

Freshness A verdict stands until the template, an agent it sequences or the workspace configuration changes

Refusal The gate refuses to mark a template complete while any of its contracts fails

Observation The coordination record each run writes, which locates a failed handoff

Evidence None, because the catalog states this check as a class, so a watched run belongs to each system that adopts it

Authoritative side The workflow template's contracts, which each run's coordination record is compared against

Depends on Not answered

Shape it refuses Not answered

Agent Workflow File Modification Recovery

Details

Intent When a file modification conflict occurs, detect the error, re-read the current file, merge the intended delta into the current content, write the complete new version, verify persistence, and log recovery automatically without asking the developer.

Invariant State-mutation conflicts are synchronization failures and should trigger deterministic recovery, not a prompt to the developer.

Flow

ModificationError → RereadMerge → CompleteRewrite → Verify

Productions

FileModificationRecovery ::= <FileModificationError> "→" <RecoveryProtocolSelection> "→" <RereadAndMerge> "→" <CompleteRewrite> "→" <RecoveryLog>
RecoveryProtocol ::= "reread-merge-complete-rewrite" | "snapshot-restore-on-failure"
ForbiddenRecovery ::= "retry_edit_without_recovery" | "ask_user_for_tool_error_recovery"

Composes none

Composed by Workflow Creation Kernel

Forces state_transaction, correctness_verification, resilience_recovery

Grounds none

Before

A stale-write conflict re-reads the file and retries the same edit, or stops to ask the developer.

After

modification error → re-read current → merge the delta into full state → write complete version → verify → log; never retry-without-recovery, never ask for a tool error

How it is checked

Checked by the workflow validation gate, which checks the orchestration, artifact, context and validation contracts, the structured-document validator over the workflow template

Population Every workflow template and every agent it sequences

Freshness A verdict stands until the template, an agent it sequences or the workspace configuration changes

Refusal The gate refuses to mark a template complete while any of its contracts fails

Observation The coordination record each run writes, which locates a failed handoff

Evidence None, because the catalog states this check as a class, so a watched run belongs to each system that adopts it

Authoritative side The workflow template's contracts, which each run's coordination record is compared against

Depends on Not answered

Shape it refuses Not answered

Context Forking Configuration

Details

Intent Assign forked context to discovery, investigation, and documentation agents; assign normal context to action and validation agents; preserve model and parallel eligibility metadata per agent class.

Invariant Context isolation improves independent analysis, while normal context preserves continuity for mutation and validation.

Flow

AgentClass → ContextMode → ParallelEligibility → ExecutionPolicy

Productions

ContextForkingConfiguration ::= <AgentClass> "→" <ContextMode> "→" <ParallelPolicy> "→" <ExecutionConfiguration>
AgentClass ::= "discovery" | "investigation" | "documentation" | "action" | "validation"
ContextMode ::= "fork" | "normal"
ParallelPolicy ::= "parallel_true" | "parallel_false"

Composes none

Composed by Workflow Creation Kernel

Forces runtime_extensibility, state_transaction, correctness_verification, model_governance, control_coordination

Grounds none

Before

Every agent shares one context — discovery pollutes the action agent's state.

After

agent class → discovery/investigation/documentation → fork ; action/validation → normal → per-class parallel eligibility preserved

How it is checked

Checked by the workflow validation gate, which checks the orchestration, artifact, context and validation contracts, the structured-document validator over the workflow template

Population Every workflow template and every agent it sequences

Freshness A verdict stands until the template, an agent it sequences or the workspace configuration changes

Refusal The gate refuses to mark a template complete while any of its contracts fails

Observation The coordination record each run writes, which locates a failed handoff

Evidence None, because the catalog states this check as a class, so a watched run belongs to each system that adopts it

Authoritative side The workflow template's contracts, which each run's coordination record is compared against

Depends on Not answered

Shape it refuses Not answered

Verb-Based Execution Classification

Details

Intent Extract the primary verb from each agent purpose, classify it against parallel or sequential verb sets, and bind execution mode, context, and parallel eligibility.

Invariant Execution mode should be derived from action semantics, not arbitrary phase numbering.

Flow

AgentPurpose → PrimaryVerb → VerbClass → ExecutionMode

Productions

VerbExecutionClassification ::= <AgentPurpose> "→" <PrimaryVerb> "→" <VerbSetMatch> "→" <AgentExecutionMode>
ParallelVerb ::= "ANALYZE" | "FIND" | "EXTRACT" | "READ" | "DISCOVER" | "INVESTIGATE" | "RESEARCH" | "EXPLORE" | "TRACE"
SequentialVerb ::= "CREATE" | "WRITE" | "EXECUTE" | "VERIFY" | "IMPLEMENT" | "LINK" | "ITERATE" | "REFACTOR" | "DEPLOY"

Composes none

Forces model_governance, control_coordination

Grounds none

Before

Execution mode assigned by phase number, not by what the agent does.

After

agent purpose → primary verb → {ANALYZE/FIND/DISCOVER → PARALLEL(fork)} | {CREATE/WRITE/VERIFY → SEQUENTIAL(normal)}

How it is checked

Checked by the workflow validation gate, which checks the orchestration, artifact, context and validation contracts, the structured-document validator over the workflow template

Population Every workflow template and every agent it sequences

Freshness A verdict stands until the template, an agent it sequences or the workspace configuration changes

Refusal The gate refuses to mark a template complete while any of its contracts fails

Observation The coordination record each run writes, which locates a failed handoff

Evidence None, because the catalog states this check as a class, so a watched run belongs to each system that adopts it

Authoritative side The workflow template's contracts, which each run's coordination record is compared against

Depends on Not answered

Shape it refuses Not answered

Workspace Configuration Discovery

Details

Intent Read workspace configuration, extract zones, semantic extensions, root path, agent definitions, shared zone, workflow zone, and task zone before generating any workflow artifacts.

Invariant Workflow artifacts must be placed by discovered workspace configuration, not hardcoded paths.

Flow

WorkspaceConfig → Zones → AgentDefinitions → ArtifactBasePath

Productions

WorkspaceConfigurationDiscovery ::= <WorkspaceConfigFile> "→" <WorkspaceConfig> "→" <ZoneConfig> "→" <AgentDefinitionSet> "→" <ArtifactPathPolicy>
ArtifactPathPolicy ::= "shared_zone/workflow_name" "," "workflow_zone" "," "task_zone" "," "no_hardcoded_paths"

Composes none

Composed by Workflow Creation Kernel

Forces semantic_consistency, runtime_extensibility, model_governance

Grounds none

Before

Artifact paths hardcoded — the workflow only runs in one layout.

After

workspace-config → zones + root + agent defs → artifact base = shared_zone/workflow_name; no hardcoded paths

How it is checked

Checked by the workflow validation gate, which checks the orchestration, artifact, context and validation contracts, the structured-document validator over the workflow template

Population Every workflow template and every agent it sequences

Freshness A verdict stands until the template, an agent it sequences or the workspace configuration changes

Refusal The gate refuses to mark a template complete while any of its contracts fails

Observation The coordination record each run writes, which locates a failed handoff

Evidence None, because the catalog states this check as a class, so a watched run belongs to each system that adopts it

Authoritative side The workflow template's contracts, which each run's coordination record is compared against

Depends on Not answered

Shape it refuses Not answered

Shared Document Workspace

Details

Intent Pre-create workflow documents once, require every agent to read and edit the same documents, prohibit duplicate versions, and enforce single source of truth across phases.

Invariant Multi-agent coordination should refine shared artifacts rather than create divergent outputs.

Flow

CoreDocuments → PreCreate → AgentReadEdit → SingleSourceValidation

Productions

SharedDocumentWorkspace ::= <CoreDocumentSet> "→" <PreCreation> "→" <SharedAccessProtocol> "→" <IterativeRefinement> "→" <SingleSourceOfTruthGate>
SharedAccessProtocol ::= "all_agents_same_documents" "," "orchestrator_creates" "," "agents_refine" "," "append_mode_false"

Composes none

Composed by Workflow Creation Kernel

Forces semantic_consistency, model_governance, control_coordination

Grounds none

Before

Each agent writes its own output file; findings diverge across N versions.

After

pre-create core documents once → every agent reads + edits the same set → no duplicate versions → single source of truth

How it is checked

Checked by the workflow validation gate, which checks the orchestration, artifact, context and validation contracts, the structured-document validator over the workflow template

Population Every workflow template and every agent it sequences

Freshness A verdict stands until the template, an agent it sequences or the workspace configuration changes

Refusal The gate refuses to mark a template complete while any of its contracts fails

Observation The coordination record each run writes, which locates a failed handoff

Evidence None, because the catalog states this check as a class, so a watched run belongs to each system that adopts it

Authoritative side The workflow template's contracts, which each run's coordination record is compared against

Depends on Not answered

Shape it refuses Not answered

Workflow Type Document Selection

Details

Intent Analyze workflow objective, classify workflow type, select five to eight semantically distinct core documents, and map each document to a non-overlapping purpose.

Invariant Workflow coordination needs the right shared document set for the work type.

Flow

WorkflowObjective → WorkflowType → CoreDocuments → PurposeMap

Productions

WorkflowDocumentSelection ::= <WorkflowObjective> "→" <WorkflowType> "→" <CoreDocumentSet> "→" <DocumentPurposeMap>
WorkflowType ::= "cleanup" | "analysis" | "refactoring" | "documentation" | "implementation" | "security" | "performance" | "infrastructure" | "migration"
CoreDocumentConstraint ::= "document_count_between_5_and_8" "," "distinct_logical_purpose" "," "semantic_names_only"

Composes none

Named in the derivation of Workflow Creation Kernel

Forces model_governance, control_coordination

Grounds none

Before

Generic output.md / results.md documents with overlapping purpose.

After

objective → workflow_type{cleanup|analysis|refactoring|security|migration} → 5-8 distinct-purpose documents → one non-overlapping purpose each

How it is checked

Checked by the workflow validation gate, which checks the orchestration, artifact, context and validation contracts, the structured-document validator over the workflow template

Population Every workflow template and every agent it sequences

Freshness A verdict stands until the template, an agent it sequences or the workspace configuration changes

Refusal The gate refuses to mark a template complete while any of its contracts fails

Observation The coordination record each run writes, which locates a failed handoff

Evidence None, because the catalog states this check as a class, so a watched run belongs to each system that adopts it

Authoritative side The workflow template's contracts, which each run's coordination record is compared against

Depends on Not answered

Shape it refuses Not answered

Agent Sequence Definition

Details

Intent For each agent slot, create an agent object with name, type, phase, purpose, methodology, inputs, outputs, validation gates, document responsibilities, focus areas, edit protocol, agent activation, and 4D graph.

Invariant An orchestration plan requires agent objects with executable metadata, not just agent names.

Flow

AgentCount → AgentObjectSet → AgentSequence

Productions

AgentSequenceDefinition ::= <AgentCount> "→" <AgentObjectSet> "→" <AgentSequence>
AgentObject ::= <AgentName> "," <AgentType> "," <PhaseNumber> "," <Purpose> "," <Methodology> "," <InputArtifacts> "," <OutputArtifacts> "," <ValidationGates> "," <DocumentResponsibilities> "," <ExecutionMode> "," <Graph4D>

Composes none

Composed by Workflow Creation Kernel

Named in the derivation of Workflow Creation Kernel

Forces modularity, correctness_verification, model_governance, control_coordination

Grounds none

Before

A plan that is just a list of agent names, no executable metadata.

After

agent_count → agent objects{name, type, phase, purpose, inputs, outputs, validation gates, doc responsibilities, execution mode, 4D graph}

How it is checked

Checked by the workflow validation gate, which checks the orchestration, artifact, context and validation contracts, the structured-document validator over the workflow template

Population Every workflow template and every agent it sequences

Freshness A verdict stands until the template, an agent it sequences or the workspace configuration changes

Refusal The gate refuses to mark a template complete while any of its contracts fails

Observation The coordination record each run writes, which locates a failed handoff

Evidence None, because the catalog states this check as a class, so a watched run belongs to each system that adopts it

Authoritative side The workflow template's contracts, which each run's coordination record is compared against

Depends on Not answered

Shape it refuses Not answered

Agent Document Responsibility

Details

Intent For each core document, require every agent to read current state, identify outdated or incorrect content, remove stale sections, replace with new discoveries, avoid duplicate findings, and maintain single source of truth.

Invariant Shared-document workflows should use surgical refinement rather than additive accumulation.

Flow

Document → Read → DetectStale → Remove → Replace → Deduplicate

Productions

AgentDocumentResponsibility ::= <CoreDocument> "→" <ReadCurrentState> "→" <ContradictionDetection> "→" <StaleContentRemoval> "→" <AccurateReplacement> "→" <SingleSourceValidation>
ProhibitedDocumentOperation ::= "append_only" | "duplicate_findings" | "new_version_file"

Composes none

Forces modularity, semantic_consistency, model_governance

Grounds none

Before

Agents append findings, accumulating duplicates and contradictions.

After

document → read current state → detect contradictions → remove stale → replace with new → single source of truth (never append, never a new version file)

How it is checked

Checked by the workflow validation gate, which checks the orchestration, artifact, context and validation contracts, the structured-document validator over the workflow template

Population Every workflow template and every agent it sequences

Freshness A verdict stands until the template, an agent it sequences or the workspace configuration changes

Refusal The gate refuses to mark a template complete while any of its contracts fails

Observation The coordination record each run writes, which locates a failed handoff

Evidence None, because the catalog states this check as a class, so a watched run belongs to each system that adopts it

Authoritative side The workflow template's contracts, which each run's coordination record is compared against

Depends on Not answered

Shape it refuses Not answered

Agent Activation Invocation

Details

Intent For every agent activation, construct a spawn invocation with agent type, prompt, description, model, and context; use forked context for parallel agents and normal context for sequential agents.

Invariant Orchestrators must execute agents through the runtime spawn primitive, not simulate agent behavior in the main session.

Flow

AgentObject → SpawnInvocation → AgentExecution

Productions

AgentActivationInvocation ::= <AgentObject> "→" <SpawnCall> "→" <ExecutionResult>
SpawnCall ::= "agent_type" "," "prompt" "," "description" "," "model" "," "context_if_parallel"
ForbiddenOrchestration ::= "simulate_agent_execution_in_orchestrator"

Composes none

Named in the derivation of Workflow Creation Kernel

Forces model_governance, control_coordination

Grounds none

Before

The orchestrator simulates the agent's work in its own session.

After

agent object → spawn primitive{agent_type, prompt, model, context-if-parallel} → real activation; never simulate in the orchestrator

How it is checked

Checked by the workflow validation gate, which checks the orchestration, artifact, context and validation contracts, the structured-document validator over the workflow template

Population Every workflow template and every agent it sequences

Freshness A verdict stands until the template, an agent it sequences or the workspace configuration changes

Refusal The gate refuses to mark a template complete while any of its contracts fails

Observation The coordination record each run writes, which locates a failed handoff

Evidence None, because the catalog states this check as a class, so a watched run belongs to each system that adopts it

Authoritative side The workflow template's contracts, which each run's coordination record is compared against

Depends on Not answered

Shape it refuses Not answered

Parallel Batch Execution

Details

Intent Accumulate adjacent parallel agents into a batch, invoke all spawns in a single concurrent batch, wait for all completions, and merge findings through shared documents.

Invariant Parallel agents should execute concurrently only when their work is investigation-safe and state-isolated.

Flow

ParallelAgents → ConcurrentSpawnBatch → WaitAll → MergeFindings

Productions

ParallelBatchExecution ::= <ParallelAgentSet> "→" <ConcurrentSpawnBatch> "→" <CompletionWait> "→" <SharedDocumentMerge>
ConcurrentSpawnBatch ::= "single_batch_concurrent_spawn"
ParallelSafety ::= "context_fork" "," "discovery_or_investigation_only" "," "shared_artifact_refinement"

Composes none

Forces model_governance, event_messaging, control_coordination

Grounds none

Before

Parallel agents launched in separate messages, so they run one after another anyway.

After

adjacent parallel agents → one concurrent batch of forked-context spawns → wait for all → merge via shared documents

How it is checked

Checked by the workflow validation gate, which checks the orchestration, artifact, context and validation contracts, the structured-document validator over the workflow template

Population Every workflow template and every agent it sequences

Freshness A verdict stands until the template, an agent it sequences or the workspace configuration changes

Refusal The gate refuses to mark a template complete while any of its contracts fails

Observation The coordination record each run writes, which locates a failed handoff

Evidence None, because the catalog states this check as a class, so a watched run belongs to each system that adopts it

Authoritative side The workflow template's contracts, which each run's coordination record is compared against

Depends on Not answered

Shape it refuses Not answered

Sequential Agent Execution

Details

Intent Execute state-changing or validation agents one at a time in normal context, pass handoff context from the previous phase, wait for completion signal, then activate the next agent.

Invariant Mutating workflow phases must serialize to prevent conflicting edits and ambiguous state.

Flow

PreviousHandoff → SpawnCall → WaitCompletion → NextHandoff

Productions

SequentialAgentExecution ::= <HandoffContext> "→" <SequentialSpawnInvocation> "→" <CompletionSignal> "→" <NextAgentActivation>
SequentialConstraint ::= "one_spawn_at_a_time" "," "wait_for_completion" "," "context_normal"

Composes none

Forces state_transaction, correctness_verification, model_governance, event_messaging, control_coordination

Grounds none

Before

Two mutating agents launched at once, producing conflicting edits.

After

prior handoff → one normal-context spawn at a time → wait for completion → activate the next

How it is checked

Checked by the workflow validation gate, which checks the orchestration, artifact, context and validation contracts, the structured-document validator over the workflow template

Population Every workflow template and every agent it sequences

Freshness A verdict stands until the template, an agent it sequences or the workspace configuration changes

Refusal The gate refuses to mark a template complete while any of its contracts fails

Observation The coordination record each run writes, which locates a failed handoff

Evidence None, because the catalog states this check as a class, so a watched run belongs to each system that adopts it

Authoritative side The workflow template's contracts, which each run's coordination record is compared against

Depends on Not answered

Shape it refuses Not answered

Four-Dimensional Agent Graph

Details

Intent For each agent, build sequential dependencies, lateral parallel peers, diagonal artifact/data dependencies, and propagation effects including superseded state, propagated contracts, and breakage risks.

Invariant Multi-agent workflows need topology, not only order.

Flow

Agent → Z + X + Y + W Graph

Productions

FourDAgentGraph ::= <AgentObject> "→" <SequentialAxis> "," <LateralAxis> "," <DiagonalAxis> "," <PropagationAxis>
SequentialAxis ::= "Z: prior_required_agents"
LateralAxis ::= "X: peer_parallel_agents"
DiagonalAxis ::= "Y: cross_phase_artifact_dependencies"
PropagationAxis ::= "W: superseded_state, propagated_contracts, breaks_if_changed"

Composes none

Forces contract_compatibility, model_governance, control_coordination

Grounds none

Before

An agent records only its order, not its cross-phase data or downstream ripple.

After

agent → Z{prior required agents} + X{peer parallel} + Y{cross-phase artifact deps} + W{superseded state, propagated contracts, breaks-if-changed}

How it is checked

Checked by the workflow validation gate, which checks the orchestration, artifact, context and validation contracts, the structured-document validator over the workflow template

Population Every workflow template and every agent it sequences

Freshness A verdict stands until the template, an agent it sequences or the workspace configuration changes

Refusal The gate refuses to mark a template complete while any of its contracts fails

Observation The coordination record each run writes, which locates a failed handoff

Evidence None, because the catalog states this check as a class, so a watched run belongs to each system that adopts it

Authoritative side The workflow template's contracts, which each run's coordination record is compared against

Depends on Not answered

Shape it refuses Not answered

Handoff Signal

Details

Intent Require every agent to end with a structured handoff signal containing completed agent, phase status, artifact location, next agent, execution mode, context used, findings, files, validation status, parallel results, 4D graph, and orchestrator action.

Invariant Handoffs are control messages that preserve workflow state across agent boundaries.

Flow

AgentCompletion → HandoffContext → OrchestratorAction

Productions

HandoffSignal ::= <AgentCompleted> "," <PhaseStatus> "," <ArtifactsLocation> "," <NextAgent> "," <ExecutionMode> "," <ContextUsed> "," <KeyFindings> "," <CriticalFiles> "," <ValidationGatesPassed> "," <ParallelResults> "," <Graph4D> "," <OrchestratorAction>
OrchestratorAction ::= "ACTIVATE_NEXT_AGENT" | "PAUSE_FOR_USER" | "WORKFLOW_COMPLETE"

Composes Orchestrator Action

Composed by Orchestrator Action, Workflow Creation Kernel

Forces modularity, correctness_verification, model_governance, event_messaging, control_coordination

Grounds none

Before

An agent finishes with a prose summary the orchestrator cannot route on.

After

agent completion → handoff{completed, phase status, artifacts, next agent, execution mode, context, findings, validation, 4D graph, orchestrator_action}

How it is checked

Checked by the workflow validation gate, which checks the orchestration, artifact, context and validation contracts, the structured-document validator over the workflow template

Population Every workflow template and every agent it sequences

Freshness A verdict stands until the template, an agent it sequences or the workspace configuration changes

Refusal The gate refuses to mark a template complete while any of its contracts fails

Observation The coordination record each run writes, which locates a failed handoff

Evidence None, because the catalog states this check as a class, so a watched run belongs to each system that adopts it

Authoritative side The workflow template's contracts, which each run's coordination record is compared against

Depends on Orchestrator Action

Shape it refuses Not answered

Orchestrator Action

Details

Intent Interpret handoff action as activate next agent, pause for the developer, or complete workflow; automatically continue unless a critical decision or repeated recovery failure requires the developer's involvement.

Invariant The orchestrator is a control loop driven by structured handoff actions.

Flow

HandoffSignal → ActionType → Execute|Pause|Complete

Productions

OrchestratorActionHandling ::= <HandoffSignal> "→" <ActionType> "→" <OrchestrationDecision>
ActionType ::= "ACTIVATE_NEXT_AGENT" | "PAUSE_FOR_USER" | "WORKFLOW_COMPLETE"
ContinuationRule ::= "never_ask_should_I_continue" "," "use_orchestrator_action"

Composes Handoff Signal

Composed by Handoff Signal

Forces state_transaction, resilience_recovery, model_governance, event_messaging, control_coordination

Grounds none

Before

The orchestrator asks the developer 'should I continue?' after every agent.

After

handoff → orchestrator_action{ACTIVATE_NEXT_AGENT | PAUSE_FOR_USER | WORKFLOW_COMPLETE} → auto-continue unless a critical decision or repeated recovery failure

How it is checked

Checked by the workflow validation gate, which checks the orchestration, artifact, context and validation contracts, the structured-document validator over the workflow template

Population Every workflow template and every agent it sequences

Freshness A verdict stands until the template, an agent it sequences or the workspace configuration changes

Refusal The gate refuses to mark a template complete while any of its contracts fails

Observation The coordination record each run writes, which locates a failed handoff

Evidence None, because the catalog states this check as a class, so a watched run belongs to each system that adopts it

Authoritative side The workflow template's contracts, which each run's coordination record is compared against

Depends on Handoff Signal

Shape it refuses Not answered

Workflow Coordination Sequence

Details

Intent Pre-create documents, execute parallel batches where eligible, execute sequential agents one at a time, update checkpoints, validate single source of truth, and mark workflow completion.

Invariant Coordination is the explicit execution trace for the whole workflow.

Flow

PreCreateDocs → ParallelBatch|SequentialTask → Handoff → Checkpoint → Complete

Productions

WorkflowCoordinationSequence ::= <DocumentPreCreation> "→" <AgentExecutionStepSet> "→" <CheckpointUpdateSet> "→" <WorkflowCompletionState>
WorkflowCompletionState ::= "WORKFLOW_PROGRESS_100_percent" "," "core_documents_refined" "," "final_output_ready"

Composes none

Composed by Workflow Creation Kernel

Forces semantic_consistency, correctness_verification, observability_traceability, model_governance, control_coordination

Grounds none

Before

Coordination left implicit — no record states the spawn order.

After

pre-create docs → parallel batches where eligible + sequential tasks one at a time → handoffs → checkpoint updates → 100% complete

How it is checked

Checked by the workflow validation gate, which checks the orchestration, artifact, context and validation contracts, the structured-document validator over the workflow template

Population Every workflow template and every agent it sequences

Freshness A verdict stands until the template, an agent it sequences or the workspace configuration changes

Refusal The gate refuses to mark a template complete while any of its contracts fails

Observation The coordination record each run writes, which locates a failed handoff

Evidence None, because the catalog states this check as a class, so a watched run belongs to each system that adopts it

Authoritative side The workflow template's contracts, which each run's coordination record is compared against

Depends on Not answered

Shape it refuses Not answered

Workflow Recovery Loop

Details

Intent If an agent fails validation, read shared documents, identify unmet expectation, research the error pattern, relaunch the agent with adapted context, and pause for the developer after bounded recovery attempts.

Invariant Agent failure should trigger bounded evidence-based recovery, not silent continuation.

Flow

ValidationFail → Diagnose → Research → Relaunch → RetryLimit|Recover

Productions

WorkflowRecoveryLoop ::= <FailedAgentResult> "→" <SharedDocumentRead> "→" <UnmetExpectationAnalysis> "→" <ResolutionResearch> "→" <AgentRelaunch> "→" <RecoveryDecision>
RecoveryDecision ::= "continue_after_recovery" | "pause_for_user_after_limit"

Composes none

Forces state_transaction, correctness_verification, resilience_recovery, model_governance

Grounds none

Before

A failed agent is silently skipped and the workflow continues.

After

validation fail → read shared docs → diagnose unmet expectation → research the error → relaunch with adapted context → pause for the developer after the bound

How it is checked

Checked by the workflow validation gate, which checks the orchestration, artifact, context and validation contracts, the structured-document validator over the workflow template

Population Every workflow template and every agent it sequences

Freshness A verdict stands until the template, an agent it sequences or the workspace configuration changes

Refusal The gate refuses to mark a template complete while any of its contracts fails

Observation The coordination record each run writes, which locates a failed handoff

Evidence None, because the catalog states this check as a class, so a watched run belongs to each system that adopts it

Authoritative side The workflow template's contracts, which each run's coordination record is compared against

Depends on Not answered

Shape it refuses Not answered

Checklist Integration

Details

Intent Create a workflow progress checklist in the artifact workspace, include execution model metadata, phases in linear dependency order with severity metadata, task checkboxes, progress bars, success criteria, and agent-edit coordination rules.

Invariant Workflow state must persist independently of any one agent context.

Flow

Workflow → Checklist → AgentUpdates → ResumableProgress

Productions

ChecklistIntegration ::= <WorkflowName> "→" <ChecklistFrontmatter> "→" <PhaseStructure> "→" <TaskBreakdown> "→" <ProgressTracking> "→" <SuccessCriteria>
ChecklistCoordinationRule ::= "orchestrator_precreates" "," "all_agents_edit_same_checklist" "," "phase_complete_before_handoff" "," "resume_by_reading_checklist"

Composes none

Composed by Workflow Creation Kernel

Forces model_governance, control_coordination, architecture_evolution

Grounds none

Before

Workflow state lives only in the orchestrator context; a restart loses it.

After

workflow → progress checklist{execution model, linear phases + severity metadata, task checkboxes, success criteria} → any agent resumes by reading it

How it is checked

Checked by the workflow validation gate, which checks the orchestration, artifact, context and validation contracts, the structured-document validator over the workflow template

Population Every workflow template and every agent it sequences

Freshness A verdict stands until the template, an agent it sequences or the workspace configuration changes

Refusal The gate refuses to mark a template complete while any of its contracts fails

Observation The coordination record each run writes, which locates a failed handoff

Evidence None, because the catalog states this check as a class, so a watched run belongs to each system that adopts it

Authoritative side The workflow template's contracts, which each run's coordination record is compared against

Depends on Not answered

Shape it refuses Not answered

Phase Documentation Template

Details

Intent For each agent phase, render phase header, execution mode, context mode, methodology, 4D graph, artifact flow, focus areas, deliverable, and agent activation example.

Invariant Workflow templates must document how each agent is activated and what it contributes.

Flow

AgentPhase → DocumentationSection → InvocationExample

Productions

PhaseDocumentationTemplate ::= <AgentObject> "→" <PhaseHeader> "→" <ExecutionModeDescription> "→" <MethodologySummary> "→" <Graph4DRendering> "→" <ArtifactSection> "→" <FocusSection> "→" <OutputSection> "→" <AgentActivationExample>

Composes none

Composed by Workflow Creation Kernel

Forces model_governance, metaprogramming_modeling, control_coordination

Grounds none

Before

A phase documented with no execution mode, graph, or invocation example.

After

agent phase → header + execution mode + context + methodology + 4D graph + artifacts + focus + deliverable + agent activation example

How it is checked

Checked by the workflow validation gate, which checks the orchestration, artifact, context and validation contracts, the structured-document validator over the workflow template

Population Every workflow template and every agent it sequences

Freshness A verdict stands until the template, an agent it sequences or the workspace configuration changes

Refusal The gate refuses to mark a template complete while any of its contracts fails

Observation The coordination record each run writes, which locates a failed handoff

Evidence None, because the catalog states this check as a class, so a watched run belongs to each system that adopts it

Authoritative side The workflow template's contracts, which each run's coordination record is compared against

Depends on Not answered

Shape it refuses Not answered

Workflow Principles Mapping

Details

Intent Derive workflow principles from the agent sequence, first agent grounding role, final agent quality guarantee, intermediate agent contributions, automation, context awareness, recovery, scalability, hybrid execution, context forking, and workspace integration.

Invariant A workflow should state the qualities guaranteed by its orchestration structure.

Flow

AgentSequence → PrincipleSet → WorkflowValueStatement

Productions

WorkflowPrinciplesMapping ::= <AgentSequence> "→" <AgentContributionSet> "→" <WorkflowPrincipleSet>
WorkflowPrinciple ::= "grounded_in_codebase_reality" | "fully_automated" | "context_aware" | "self_recovering" | "dynamically_scalable" | "hybrid_execution" | "context_forking" | "workspace_integrated"

Composes none

Forces state_transaction, resilience_recovery, model_governance

Grounds none

Before

A workflow that never states what its structure guarantees.

After

agent sequence → per-agent contribution{first grounds, final guarantees quality} → principles{grounded, automated, context-aware, self-recovering, scalable}

How it is checked

Checked by the workflow validation gate, which checks the orchestration, artifact, context and validation contracts, the structured-document validator over the workflow template

Population Every workflow template and every agent it sequences

Freshness A verdict stands until the template, an agent it sequences or the workspace configuration changes

Refusal The gate refuses to mark a template complete while any of its contracts fails

Observation The coordination record each run writes, which locates a failed handoff

Evidence None, because the catalog states this check as a class, so a watched run belongs to each system that adopts it

Authoritative side The workflow template's contracts, which each run's coordination record is compared against

Depends on Not answered

Shape it refuses Not answered

Capability Invocation Protocol

Details

Intent Define specialized capability invocation patterns, classify which capabilities run forked or normal, include examples, and allow workflows to call capabilities for research, validation, calculation, and specialized subroutines.

Invariant Workflows should support specialized capabilities without embedding every capability into every agent.

Flow

CapabilityNeed → CapabilityPattern → ContextMode → Invocation

Productions

CapabilityInvocationProtocol ::= <CapabilityNeed> "→" <CapabilitySelection> "→" <CapabilityInvocation> "→" <CapabilityResultIntegration>
CapabilityInvocation ::= "invoke(capability=name, args=args)"
CapabilityContextRule ::= "discovery_capability_context_fork" | "validation_capability_context_normal"

Composes none

Composed by Workflow Creation Kernel

Forces correctness_verification, model_governance

Grounds none

Before

Every capability baked into every agent instead of a shared, invocable one.

After

capability need → select → invoke(capability, args){discovery → forked, validation → normal} → integrate result

How it is checked

Checked by the workflow validation gate, which checks the orchestration, artifact, context and validation contracts, the structured-document validator over the workflow template

Population Every workflow template and every agent it sequences

Freshness A verdict stands until the template, an agent it sequences or the workspace configuration changes

Refusal The gate refuses to mark a template complete while any of its contracts fails

Observation The coordination record each run writes, which locates a failed handoff

Evidence None, because the catalog states this check as a class, so a watched run belongs to each system that adopts it

Authoritative side The workflow template's contracts, which each run's coordination record is compared against

Depends on Not answered

Shape it refuses Not answered

Template Assembly

Details

Intent Assemble frontmatter, workspace config, overview, phase documentation, checklist requirements, orchestration protocol, handoff format, coordination sequence, capability integration, workflow principles, and domain notes into one workflow artifact.

Invariant The workflow template is a compiled orchestration contract.

Flow

Sections → FinalTemplate → OutputPath → Write

Productions

TemplateAssembly ::= <WorkflowFrontmatter> "→" <WorkspaceConfigSection> "→" <WorkflowOverview> "→" <PhaseDocumentationSet> "→" <ChecklistRequirements> "→" <AgentOrchestrationProtocol> "→" <HandoffSignalFormat> "→" <WorkflowCoordination> "→" <CapabilityIntegrationProtocol> "→" <WorkflowPrinciples> "→" <OutputArtifact>
OutputArtifact ::= "{workflow_output_dir}/{workflow_name}-WORKFLOW.{workflow_ext}"

Composes none

Composed by Workflow Creation Kernel

Named in the derivation of Workflow Creation Kernel

Forces contract_compatibility, model_governance, event_messaging, metaprogramming_modeling, control_coordination, architecture_evolution

Grounds none

Before

Workflow sections written ad hoc, missing the handoff format or coordination.

After

assemble{frontmatter, workspace config, overview, phase docs, checklist, orchestration protocol, handoff format, coordination, capabilities, principles} → {name}-WORKFLOW file

How it is checked

Checked by the workflow validation gate, which checks the orchestration, artifact, context and validation contracts, the structured-document validator over the workflow template

Population Every workflow template and every agent it sequences

Freshness A verdict stands until the template, an agent it sequences or the workspace configuration changes

Refusal The gate refuses to mark a template complete while any of its contracts fails

Observation The coordination record each run writes, which locates a failed handoff

Evidence None, because the catalog states this check as a class, so a watched run belongs to each system that adopts it

Authoritative side The workflow template's contracts, which each run's coordination record is compared against

Depends on Not answered

Shape it refuses Not answered

First-Time Initiation

Details

Intent After generating the workflow template, present a summary and request explicit first-run action: execute workflow, edit template, or cancel.

Invariant Generation and first execution are separate approval states.

Flow

GeneratedWorkflow → UserChoice → Execute|Edit|Cancel

Productions

FirstTimeInitiation ::= <GeneratedWorkflow> "→" <WorkflowSummary> "→" <UserChoice> "→" <InitialAction>
UserChoice ::= "Execute Workflow" | "Edit Template" | "Cancel"

Composes none

Named in the derivation of Workflow Creation Kernel

Forces model_governance, metaprogramming_modeling

Grounds ter-stop

Before

The generated workflow auto-executes without the developer's go-ahead.

After

generated workflow → summary → developer choice{Execute | Edit Template | Cancel} → generation and first execution are separate approvals

How it is checked

Checked by the workflow validation gate, which checks the orchestration, artifact, context and validation contracts, the structured-document validator over the workflow template

Population Every workflow template and every agent it sequences

Freshness A verdict stands until the template, an agent it sequences or the workspace configuration changes

Refusal The gate refuses to mark a template complete while any of its contracts fails

Observation The coordination record each run writes, which locates a failed handoff

Evidence None, because the catalog states this check as a class, so a watched run belongs to each system that adopts it

Authoritative side The workflow template's contracts, which each run's coordination record is compared against

Depends on Not answered

Shape it refuses Not answered

Workflow Validation Gate

Details

Intent Validate DSL compliance, workspace discovery, dynamic agent count, execution classification, context configuration, 4D graphs, handoff protocol, hybrid execution, checklist integration, capability integration, template assembly, dynamic paths, uppercase filenames, and agent-oriented content.

Invariant A workflow template is complete only when orchestration, artifact, context, and validation contracts all pass.

Flow

WorkflowTemplate → GateSet → Valid|Invalid

Productions

WorkflowValidationGate ::= <GeneratedWorkflow> "→" <DSLComplianceCheck> "→" <WorkspaceConfigCheck> "→" <AgentSequenceCheck> "→" <ExecutionModeCheck> "→" <Graph4DCheck> "→" <HandoffProtocolCheck> "→" <ChecklistIntegrationCheck> "→" <CapabilityIntegrationCheck> "→" <ArtifactPathCheck> "→" <CompletionVerdict>
CompletionVerdict ::= "workflow_template_valid" | "workflow_template_invalid"

Composes none

Composed by Workflow Creation Kernel

Named in the derivation of Workflow Creation Kernel

Forces contract_compatibility, runtime_extensibility, correctness_verification, model_governance, event_messaging, metaprogramming_modeling, architecture_evolution

Grounds ver-evidence

Before

A workflow shipped without checking its handoff, 4D graphs, or dynamic paths.

After

template → checks{DSL, workspace, agent sequence, execution mode, 4D graph, handoff, checklist, capabilities, artifact paths} → valid | invalid

How it is checked

Checked by the workflow validation gate, which checks the orchestration, artifact, context and validation contracts, the structured-document validator over the workflow template

Population Every workflow template and every agent it sequences

Freshness A verdict stands until the template, an agent it sequences or the workspace configuration changes

Refusal The gate refuses to mark a template complete while any of its contracts fails

Observation The coordination record each run writes, which locates a failed handoff

Evidence None, because the catalog states this check as a class, so a watched run belongs to each system that adopts it

Authoritative side The workflow template's contracts, which each run's coordination record is compared against

Depends on Not answered

Shape it refuses Not answered

Workflow Creation Kernel

Details

Intent Load DSL and orchestration references, configure file recovery and context forking, discover workspace zones and agents, select shared documents, define dynamic agent sequence, classify execution mode, build 4D graphs, define handoff protocol, assemble coordination sequence, integrate checklist and capabilities, generate phase documentation, assemble template, and validate success criteria.

Invariant Workflow creation is a compiler from objective and workspace configuration into an executable multi-agent orchestration contract.

Flow

Specs → Workspace → Documents → Agents → Graphs → Handoffs → Coordination → Checklist → Capabilities → Template → Validation

Productions

WorkflowCreationKernel ::= <DSLComplianceLoading> "→" <FileModificationRecovery> "→" <ContextForkingConfiguration> "→" <WorkspaceConfigurationDiscovery> "→" <WorkflowDocumentSelection> "→" <SharedDocumentWorkspace> "→" <AgentSequenceDefinition> "→" <VerbExecutionClassification> "→" <FourDAgentGraph> "→" <HandoffSignal> "→" <WorkflowCoordinationSequence> "→" <ChecklistIntegration> "→" <PhaseDocumentationTemplate> "→" <CapabilityInvocationProtocol> "→" <TemplateAssembly> "→" <WorkflowValidationGate>

Composes DSL Compliance Loading, Agent Workflow File Modification Recovery, Context Forking Configuration, Workspace Configuration Discovery, Shared Document Workspace, Agent Sequence Definition, Handoff Signal, Workflow Coordination Sequence, Checklist Integration, Phase Documentation Template, Capability Invocation Protocol, Template Assembly, Workflow Validation Gate

Forces contract_compatibility, runtime_extensibility, state_transaction, correctness_verification, resilience_recovery, model_governance, event_messaging, metaprogramming_modeling, control_coordination, architecture_evolution

Principle Orchestration

Grounds derivation-loop

Derivation map

orient DSL Compliance Loading

derive Workflow Type Document Selection

project Agent Sequence Definition

act Agent Activation Invocation

verify Workflow Validation Gate

commit Template Assembly

terminate First-Time Initiation

Before

An objective turned straight into a hardcoded, single-threaded agent script.

After

load specs → discover workspace → select docs → define agents → classify execution → 4D graphs → handoffs → coordinate → checklist + capabilities → assemble → validate

How it is checked

Checked by the workflow validation gate, which checks the orchestration, artifact, context and validation contracts, the structured-document validator over the workflow template

Population Every workflow template and every agent it sequences

Freshness A verdict stands until the template, an agent it sequences or the workspace configuration changes

Refusal The gate refuses to mark a template complete while any of its contracts fails

Observation The coordination record each run writes, which locates a failed handoff

Evidence None, because the catalog states this check as a class, so a watched run belongs to each system that adopts it

Authoritative side The workflow template's contracts, which each run's coordination record is compared against

Depends on DSL Compliance Loading, Agent Workflow File Modification Recovery, Context Forking Configuration, Workspace Configuration Discovery, Shared Document Workspace, Agent Sequence Definition, Handoff Signal, Workflow Coordination Sequence, Checklist Integration, Phase Documentation Template, Capability Invocation Protocol, Template Assembly, Workflow Validation Gate

Shape it refuses Not answered

Details

Intent → → → → → → → <Build 4D graphs> → → → →

Invariant Any multi-agent workflow should be generated as an executable orchestration contract where discovery is parallel, mutation is sequential, state is shared through documents, and handoffs preserve graph-aware context.

Flow

Grammar → Workspace → Documents → Agents → ExecutionMode → Context → Graph → Handoff → Coordination → Validation

Productions

WorkflowOrchestrationConcern ::= <GrammarContract> "→" <WorkspaceContract> "→" <SharedArtifactContract> "→" <AgentSequenceContract> "→" <HybridExecutionContract> "→" <ContextForkingContract> "→" <Graph4DContract> "→" <HandoffContract> "→" <ChecklistContract> "→" <CapabilityContract> "→" <ValidationGate>
HybridExecutionContract ::= "parallel_discovery" "," "sequential_actions" "," "spawn_primitive_required" "," "no_orchestrator_simulation" "," "single_source_of_truth_documents"

Composes Validation Gate

Forces contract_compatibility, runtime_extensibility, state_transaction, correctness_verification, model_governance, event_messaging, metaprogramming_modeling, control_coordination, architecture_evolution

Grounds none

How it is checked

Checked by the workflow validation gate, which checks the orchestration, artifact, context and validation contracts, the structured-document validator over the workflow template

Population Every workflow template and every agent it sequences

Freshness A verdict stands until the template, an agent it sequences or the workspace configuration changes

Refusal The gate refuses to mark a template complete while any of its contracts fails

Observation The coordination record each run writes, which locates a failed handoff

Evidence None, because the catalog states this check as a class, so a watched run belongs to each system that adopts it

Authoritative side The workflow template's contracts, which each run's coordination record is compared against

Depends on Validation Gate

Shape it refuses Not answered

Anti-patterns

Every algorithm contract in this domain is listed with its position on the derivation loop, its intent and invariant, the flow it walks and its productions as a grammar. Each record also shows what it composes and is composed by, which forces and principles it answers to, what grounds it and what it grounds, and an exemplar where the record carries one. The diagram shows what composes what inside the domain.

Relations diagram

What composes what inside this domain.

flowchart LR
    n_anti_pattern_inversion["Anti-Pattern Inversion"]
    n_anti_pattern_propagation_kernel["Anti-Pattern Propagation Kernel"]
    n_anti_pattern_remediation_algebra["Anti-Pattern Remediation Algebra"]
    n_architecture_smell_record["Architecture Smell Record"]
    n_anti_pattern_rule_compiler["Anti-Pattern Rule Compiler"]
    n_smell_taxonomy["Smell Taxonomy"]
    n_anti_pattern_relationship_record["Anti-Pattern Relationship Record"]
    n_architecture_anti_pattern["<Architecture Anti-Pattern>"]
Loading

Anti-Pattern Inversion

Details

Intent Take any desired architectural principle, invert its invariants, identify the recurring violation shape, model its propagation mechanism, define detection signals, and derive its remediation inverse.

Invariant Every anti-pattern is a stable failure algorithm created by repeated violation of an architectural contract.

Flow

Principle → Invariant → Violation → Propagation → Detection → Remediation

Productions

AntiPatternInversion ::= <HealthyPrinciple> "→" <RequiredInvariant> "→" <InvariantViolation> "→" <FailurePropagation> "→" <DetectionSignalSet> "→" <RemediationInverse>
AntiPatternRecord ::= <Name> "," <TriggerCondition> "," <DegenerationPath> "," <DetectionSignals> "," <DamageModel> "," <RemediationInverse>

Composes none

Forces contract_compatibility, correctness_verification, model_governance

Grounds none

Before

Principle: Low Coupling — stated as a goal only; its violations are noticed ad hoc, named inconsistently, and caught late, with no derived failure algorithm.

After

Low Coupling → invariant{no bidirectional dependency} → violation{Cyclic Dependency} → propagation{a convenience import closes a cycle, then spreads across modules} → detection{dependency-cycle scan} → remediation{invert the dependency / introduce a port}

How it is checked

Checked by the quality rules compiled from the smell catalog, the cross-file quality gate

Population Every source file the rules lint

Freshness A verdict stands until the linted source or a rule changes

Refusal A compiled rule fails the lint stage on the smell's signature

Observation None, because these records describe decay paths found in source, not signals of a running system

Evidence None, because the catalog states this check as a class, so a watched run belongs to each system that adopts it

Authoritative side The smell catalog, which the compiled rules are derived from and the source is held to

Depends on Not answered

Shape it refuses Not answered

Anti-Pattern Propagation Kernel

Details

Intent Start with a local shortcut, repeat it under delivery pressure, normalize it as convention, allow dependent code to form around it, then make remediation expensive through coupling and hidden assumptions.

Invariant Most architecture anti-patterns become dangerous when a shortcut becomes infrastructure.

Flow

Shortcut → Repetition → Normalization → DependencyFormation → Institutionalization → HighCostRepair

Productions

AntiPatternPropagation ::= <LocalShortcut> "→" <RepeatedUse> "→" <ImplicitConvention> "→" <DependentCodeFormation> "→" <ArchitecturalDebt> "→" <RemediationCostIncrease>
DebtAmplifier ::= "copy_paste" | "missing_contract" | "missing_owner" | "missing_metric" | "missing_boundary" | "missing_version" | "missing_observability"

Composes none

Forces modularity, semantic_consistency, correctness_verification

Grounds none

Before

A one-off shortcut — inline a secret to ship a fix — treated as an isolated, cheap, local choice.

After

Shortcut{inline secret} → repetition{reused under deadline} → normalization{becomes the team convention} → dependency-formation{configs read it directly} → institutionalization{deploy scripts assume it} → high-cost-repair{rotate the secret and rewire every dependent}

How it is checked

Checked by the quality rules compiled from the smell catalog, the cross-file quality gate

Population Every source file the rules lint

Freshness A verdict stands until the linted source or a rule changes

Refusal A compiled rule fails the lint stage on the smell's signature

Observation None, because these records describe decay paths found in source, not signals of a running system

Evidence None, because the catalog states this check as a class, so a watched run belongs to each system that adopts it

Authoritative side The smell catalog, which the compiled rules are derived from and the source is held to

Depends on Not answered

Shape it refuses Not answered

Anti-Pattern Remediation Algebra

Details

Intent For each anti-pattern, identify the missing architectural control, introduce the inverse control, migrate existing dependents, verify absence of the old failure shape, and enforce recurrence prevention.

Invariant Anti-pattern repair is not complete until the propagation path is blocked.

Flow

AntiPattern → MissingControl → InverseControl → Migration → AbsenceCheck → PreventionGate

Productions

AntiPatternRemediationAlgebra ::= <AntiPatternRecord> "→" <MissingControl> "→" <InverseArchitecturalControl> "→" <MigrationPlan> "→" <EliminationVerification> "→" <RecurrencePrevention>
MissingControl ::= "boundary" | "contract" | "owner" | "version" | "telemetry" | "schema" | "policy" | "state_isolation" | "dependency_rule"
RecurrencePrevention ::= "static_check" | "contract_test" | "schema_gate" | "architecture_test" | "policy_as_code" | "review_gate" | "runtime_monitor"

Composes none

Forces correctness_verification

Grounds none

Before

The anti-pattern is deleted at one call site; the propagation path stays open, so it reappears elsewhere next sprint.

After

Secret Sprawl → missing-control{no secret authority} → inverse-control{central store + injected access} → migration{repoint every reader} → absence-check{scan finds zero inline secrets} → prevention-gate{lint rule rejects new inline secrets}

How it is checked

Checked by the quality rules compiled from the smell catalog, the cross-file quality gate

Population Every source file the rules lint

Freshness A verdict stands until the linted source or a rule changes

Refusal A compiled rule fails the lint stage on the smell's signature

Observation None, because these records describe decay paths found in source, not signals of a running system

Evidence None, because the catalog states this check as a class, so a watched run belongs to each system that adopts it

Authoritative side The smell catalog, which the compiled rules are derived from and the source is held to

Depends on Not answered

Shape it refuses Not answered

Architecture Smell Record

Details

Intent Model every smell as a recurring degeneration path with trigger conditions, enabling conditions, detection signals, damage model, remediation inverse, and prevention gate.

Invariant A smell becomes enforceable when it is represented as a measurable failure contract.

Flow

Smell → Trigger → Degeneration → Detection → Measurement → Remediation → Prevention

Productions

ArchitectureSmellRecord ::= <SmellName> "," <TriggerCondition> "," <EnablingConditionSet> "," <DegenerationPath> "," <DetectionSignalSet> "," <MetricSet> "," <DamageModel> "," <RemediationInverse> "," <PreventionGate>
PreventionGate ::= "static_check" | "architecture_test" | "contract_test" | "schema_gate" | "review_gate" | "fitness_function" | "runtime_monitor"

Composes none

Forces contract_compatibility, correctness_verification, model_governance

Grounds none

Before

Smell described in prose ('this class is too big') — unmeasurable, unenforceable, re-argued case by case.

After

God Object : trigger{unrelated methods accrete} → degeneration{fan-in/out grows} → detection{LCOM + responsibility count} → measurement{cohesion score below threshold} → remediation{Extract Class} → prevention{architecture test on cohesion}

How it is checked

Checked by the quality rules compiled from the smell catalog, the cross-file quality gate

Population Every source file the rules lint

Freshness A verdict stands until the linted source or a rule changes

Refusal A compiled rule fails the lint stage on the smell's signature

Observation None, because these records describe decay paths found in source, not signals of a running system

Evidence None, because the catalog states this check as a class, so a watched run belongs to each system that adopts it

Authoritative side The smell catalog, which the compiled rules are derived from and the source is held to

Depends on Not answered

Shape it refuses Not answered

Anti-Pattern Rule Compiler

Details

Intent Convert each smell record into detection checks, measurable thresholds, severity policy, remediation hints, and recurrence-prevention gates.

Invariant A smell catalog is enforced only once it compiles into rules.

Flow

SmellRecord → DetectionRule → MetricThreshold → Severity → RefactorHint → Gate

Productions

AntiPatternRuleCompiler ::= <ArchitectureSmellRecordSet> "→" <DetectionRuleSet> "→" <MetricThresholdSet> "→" <SeverityPolicy> "→" <RemediationPlaybookSet> "→" <PreventionGateSet>
CompiledRule ::= <RuleName> "," <Scope> "," <Detector> "," <Threshold> "," <PriorityRank> "," <FailureMessage> "," <RefactorHint> "," <PreventionGate>

Composes Severity Policy

Forces correctness_verification

Grounds none

Before

A smell catalog read by the developer — each entry is advice that nothing executes.

After

SmellRecord{God Object} → detection-rule{find unrelated method clusters} → metric-threshold{LCOM > 0.7} → severity{error} → refactor-hint{Extract Class} → gate{fails the build}

How it is checked

Checked by the quality rules compiled from the smell catalog, the cross-file quality gate

Population Every source file the rules lint

Freshness A verdict stands until the linted source or a rule changes

Refusal A compiled rule fails the lint stage on the smell's signature

Observation None, because these records describe decay paths found in source, not signals of a running system

Evidence None, because the catalog states this check as a class, so a watched run belongs to each system that adopts it

Authoritative side The smell catalog, which the compiled rules are derived from and the source is held to

Depends on Severity Policy

Shape it refuses Not answered

Smell Taxonomy

Details

Intent Group smells by missing control so detection and remediation can be generalized.

Invariant Most bad practices are symptoms of a missing architectural control.

Flow

Smell → MissingControl → RuleFamily → RemediationFamily

Productions

SmellTaxonomy ::= <SmellSet> "→" <MissingControlClassification> "→" <RuleFamilySet> "→" <RemediationFamilySet>
MissingControlClassification ::= "missing_boundary" | "missing_contract" | "missing_type" | "missing_owner" | "missing_version" | "missing_validation" | "missing_observability" | "missing_state_control" | "missing_release_control" | "missing_security_control" | "missing_evidence" | "excessive_abstraction" | "excessive_coupling" | "excessive_manual_process"

Composes none

Forces correctness_verification

Grounds none

Before

Dozens of smells listed flat, each handed its own bespoke, unrelated fix.

After

smell-set{Magic Value, Secret Sprawl, Hardcoded Path} → missing-control{single source of truth} → rule-family{no-inline-authority checks} → remediation-family{centralize then inject}

How it is checked

Checked by the quality rules compiled from the smell catalog, the cross-file quality gate

Population Every source file the rules lint

Freshness A verdict stands until the linted source or a rule changes

Refusal A compiled rule fails the lint stage on the smell's signature

Observation None, because these records describe decay paths found in source, not signals of a running system

Evidence None, because the catalog states this check as a class, so a watched run belongs to each system that adopts it

Authoritative side The smell catalog, which the compiled rules are derived from and the source is held to

Depends on Not answered

Shape it refuses Not answered

Anti-Pattern Relationship Record

Details

Intent Model every anti-pattern as a typed relationship record: name, scope, causal links, conflicts, degradations, enabled failures, detection signals, measurement, remediation inverse, prevention, and severity.

Invariant An anti-pattern is enforceable only when it is represented as a typed relationship record.

Productions

AntiPatternRelationshipRecord ::= <AntiPatternName> ":" "Anti-Pattern" "," <scope> "," <caused_by> "," <conflicts_with> "," <degrades> "," <enables_failure> "," <detected_by> "," <measured_by> "," <refactored_by> "," <prevented_by> "," <severity>

Composes none

Forces architecture_evolution

Grounds none

Before

An anti-pattern named as free text with no typed edges — not resolvable, not gate-checkable, not linkable to the principle it violates.

After

Cyclic Dependency : Anti-Pattern, scope{module}, caused_by{convenience import}, conflicts_with{Low Coupling}, degrades{modularity}, enables_failure{build deadlock}, detected_by{cycle scan}, refactored_by{invert dependency}, prevented_by{dependency rule}, severity{mandatory}

How it is checked

Checked by the quality rules compiled from the smell catalog, the cross-file quality gate

Population Every source file the rules lint

Freshness A verdict stands until the linted source or a rule changes

Refusal A compiled rule fails the lint stage on the smell's signature

Observation None, because these records describe decay paths found in source, not signals of a running system

Evidence None, because the catalog states this check as a class, so a watched run belongs to each system that adopts it

Authoritative side The smell catalog, which the compiled rules are derived from and the source is held to

Depends on Not answered

Shape it refuses Not answered

Details

Intent → → → → <Boundary/contract erosion> → →

Invariant Every architecture anti-pattern is a reproducible decay path caused by the absence of a specific control: boundary, contract, ownership, versioning, observability, state isolation, or enforcement.

Flow

Shortcut → Drift → Coupling → Fragility → Detection → Inversion

Productions

ArchitectureAntiPattern ::= <TriggerCondition> "→" <MissingControl> "→" <DegenerationPath> "→" <DamageModel> "→" <DetectionSignalSet> "→" <RemediationInverse> "→" <PreventionGate>
RemediationInverse ::= "introduce_boundary" | "declare_contract" | "centralize_authority" | "assign_owner" | "version_change" | "add_observability" | "isolate_state" | "enforce_policy"

Composes none

Forces modularity, contract_compatibility, correctness_verification, observability_traceability

Principle Big Ball of Mud

Grounds none

How it is checked

Checked by the quality rules compiled from the smell catalog, the cross-file quality gate

Population Every source file the rules lint

Freshness A verdict stands until the linted source or a rule changes

Refusal A compiled rule fails the lint stage on the smell's signature

Observation None, because these records describe decay paths found in source, not signals of a running system

Evidence None, because the catalog states this check as a class, so a watched run belongs to each system that adopts it

Authoritative side The smell catalog, which the compiled rules are derived from and the source is held to

Depends on Not answered

Shape it refuses Not answered

Architecture

Every algorithm contract in this domain is listed with its position on the derivation loop, its intent and invariant, the flow it walks and its productions as a grammar. Each record also shows what it composes and is composed by, which forces and principles it answers to, what grounds it and what it grounds, and an exemplar where the record carries one. The diagram shows what composes what inside the domain.

Relations diagram

What composes what inside this domain.

flowchart LR
    n_document_truth_alignment["Document Truth Alignment"]
    n_architectural_contract_kernel["Architectural Contract Kernel"]
    n_responsibility_boundary["Responsibility Boundary"]
    n_coupling_control["Coupling Control"]
    n_interface_contract["Interface Contract"]
    n_substitutability["Substitutability"]
    n_canonical_data["Canonical Data"]
    n_domain_boundary["Domain Boundary"]
    n_self_description_manifest["Self-Description Manifest"]
    n_runtime_discovery["Runtime Discovery"]
    n_extension_point["Extension Point"]
    n_construction_boundary["Construction Boundary"]
    n_structural_mediation["Structural Mediation"]
    n_behavioral_dispatch["Behavioral Dispatch"]
    n_architectural_style_boundary["Architectural Style Boundary"]
    n_port_adapter["Port Adapter"]
    n_event_messaging["Event Messaging"]
    n_saga_compensation["Saga Compensation"]
    n_transaction_boundary["Transaction Boundary"]
    n_idempotent_side_effect["Idempotent Side Effect"]
    n_deterministic_core["Deterministic Core"]
    n_verification_fitness["Verification Fitness"]
    n_error_boundary["Error Boundary"]
    n_resilience_control["Resilience Control"]
    n_recovery_deployment["Recovery Deployment"]
    n_observability_trace["Observability Trace"]
    n_causality_ordering["Causality Ordering"]
    n_performance_scaling["Performance Scaling"]
    n_cache_correctness["Cache Correctness"]
    n_portability_environment["Portability Environment"]
    n_security_policy["Security Policy"]
    n_control_plane["Control Plane"]
    n_declarative_metaprogramming["Declarative Metaprogramming"]
    n_streaming_dataflow["Streaming Dataflow"]
    n_rag_knowledge_boundary["RAG Knowledge Boundary"]
    n_architecture_selection_meta_algorithm["Architecture Selection Meta-Algorithm"]
    n_universal_architectural_concern_template["Universal Architectural Concern Template"]
    n_architectural_contract_algebra["Architectural Contract Algebra"]
    n_manifest_driven_documentation["Manifest-Driven Documentation"]
    n_consumer_config_ssot["Consumer Config SSOT"]
    n_finite_state_machine["Finite State Machine"]
    n_statecharts["Statecharts"]
    n_petri_nets["Petri Nets"]
    n_queuing_theory["Queuing Theory"]
    n_architectural_contract_algebra --> n_domain_boundary
    n_architectural_contract_algebra --> n_transaction_boundary
    n_manifest_driven_documentation --> n_document_truth_alignment
    n_manifest_driven_documentation --> n_self_description_manifest
    n_manifest_driven_documentation --> n_extension_point
    n_consumer_config_ssot --> n_architectural_contract_kernel
    n_consumer_config_ssot --> n_responsibility_boundary
    n_statecharts --> n_finite_state_machine
Loading

Document Truth Alignment

Details

Intent For any document that states facts about a codebase, separate invariant facts (counts, paths, names, and the doc-type's structural schema) from variant prose, bind each invariant to a code-derived value through a stable key, compile the document from a template, and gate the output so a stated fact can never drift from the code it describes.

Invariant A document is well-formed iff every rendered invariant equals its resolved code-truth and every doc-type-required meta-concern is present in order; prose is free.

Flow

Concern → Variant → Invariant → TruthKey → Deriver → Template → Compilation → DriftGate

Productions

DocumentTruth ::= <VariantProse> "+" <InvariantSet> "→" <TruthKeyBinding> "→" <DeriverResolution> "→" <TemplateCompilation> "→" <DriftGate>
InvariantBinding ::= <TruthKey> "," <TokenSlot> "," <DerivedValue> "," <DocTypeSchema>

Composes none

Composed by Manifest-Driven Documentation

Forces correctness_verification, contract_compatibility, modularity

Grounds none

Before

A doc states 'the system has 12 modules' — a hand-typed count that drifts the moment a module is added.

After

invariant{moduleCount} → truth-key{modules.length} → deriver{scan workspaces} → template{'... has {moduleCount} modules'} → drift-gate{rendered == derived, else fail}

How it is checked

Checked by the fitness functions, contract tests and architecture tests each contract names, the reviews a contract names where no automated check exists

Population Every module and boundary the contract governs

Freshness A verdict stands until the module, its dependencies or the contract changes

Refusal A failing fitness function or contract test blocks the release

Observation The traces and health signals the observability contracts require, which locate a contract failure in production

Evidence None, because the catalog states this check as a class, so a watched run belongs to each system that adopts it

Authoritative side The contract, which the module and its tests conform to

Depends on Not answered

Shape it refuses Not answered

Architectural Contract Kernel

Details

Intent For any programmatic system, identify architectural concerns, define explicit contracts for each concern, bind implementations to those contracts, validate invariants, observe behavior, and evolve through versioned change.

Invariant Architecture is a graph of bounded contracts whose nodes expose stable intent and whose edges preserve compatibility, causality, and governance.

Flow

Concern → Boundary → Contract → Implementation → Verification → Observation → Evolution

Productions

ArchitectureKernel ::= <ConcernSet> "→" <BoundarySet> "→" <ContractSet> "→" <ImplementationGraph> "→" <VerificationSet> "→" <ObservationSet> "→" <EvolutionPolicy>
ConcernContract ::= <Intent> "," <Responsibility> "," <InputContract> "," <OutputContract> "," <InvariantSet> "," <FailurePolicy> "," <VersionPolicy>

Composes none

Composed by Consumer Config SSOT

Forces contract_compatibility, correctness_verification, security_governance, causality_ordering

Grounds none

Before

class FooService {
  save(f) {
    db.write(f);
    log(f);
    notify(f);
  }
}

After

interface FooPort {
  save(f: Foo): Promise<void>;
}
class FooService implements FooPort {
  constructor(
    private repo: FooRepo,
    private events: EventSink,
  ) {}
  async save(f: Foo) {
    await this.repo.save(f);
    this.events.emit({ type: "FooSaved", f });
  }
}

How it is checked

Checked by the fitness functions, contract tests and architecture tests each contract names, the reviews a contract names where no automated check exists

Population Every module and boundary the contract governs

Freshness A verdict stands until the module, its dependencies or the contract changes

Refusal A failing fitness function or contract test blocks the release

Observation The traces and health signals the observability contracts require, which locate a contract failure in production

Evidence None, because the catalog states this check as a class, so a watched run belongs to each system that adopts it

Authoritative side The contract, which the module and its tests conform to

Depends on Not answered

Shape it refuses Not answered

Responsibility Boundary

Details

Intent Partition behavior into cohesive units, assign each unit one reason to change, hide internal details, expose only intentional interfaces, and reject cross-boundary leakage.

Invariant Modularity is achieved when responsibility, knowledge, and change pressure are localized.

Flow

Behavior → Responsibility → Boundary → Interface → Encapsulation → Replaceability

Productions

ResponsibilityBoundary ::= <BehaviorSet> "→" <ResponsibilityPartition> "→" <ModuleBoundary> "→" <PublicInterface> "→" <PrivateImplementation>
ModuleBoundary ::= "single_responsibility" "," "high_cohesion" "," "low_coupling" "," "information_hiding" "," "replaceable_implementation"

Composes none

Composed by Consumer Config SSOT, Cascade Layer Partition, Placement Isolation, Assembly Composition

Forces modularity, contract_compatibility

Grounds none

Before

class FooUtil {
  parse() {}
  save() {}
  render() {}
  notify() {}
}

After

class FooParser {
  parse() {}
}
class FooRepository {
  save() {}
}
class FooView {
  render() {}
}

How it is checked

Checked by the fitness functions, contract tests and architecture tests each contract names, the reviews a contract names where no automated check exists

Population Every module and boundary the contract governs

Freshness A verdict stands until the module, its dependencies or the contract changes

Refusal A failing fitness function or contract test blocks the release

Observation The traces and health signals the observability contracts require, which locate a contract failure in production

Evidence None, because the catalog states this check as a class, so a watched run belongs to each system that adopts it

Authoritative side The contract, which the module and its tests conform to

Depends on Not answered

Shape it refuses Not answered

Coupling Control

Details

Intent Detect dependency directions, invert dependencies toward abstractions, restrict imports to approved boundaries, and preserve autonomy between modules.

Invariant Low coupling is enforced by making dependencies point at contracts instead of concrete implementations.

Flow

ConcreteDependency → AbstractionBoundary → DependencyRule → ImportValidation

Productions

CouplingControl ::= <DependencyGraph> "→" <AbstractionNodeSet> "→" <AllowedEdgeSet> "→" <ForbiddenEdgeSet> "→" <DependencyValidation>
DependencyRule ::= "depend_on_interface" | "depend_on_port" | "same_boundary_only" | "adapter_required"

Composes none

Composed by Constraints Over Shortcuts, Event Emission Over Parent Callbacks, Least Privilege Over Broad Privilege, Saga Compensation Over Distributed 2PC, Async Events Over Synchronous Cross-Boundary, Injected Dependency Over Hidden, Anti-Corruption Layer Over Cross-Context Leak, Placement Isolation

Forces modularity, contract_compatibility

Grounds none

Before

import { SqlFooStore } from "./infra/sql";
class FooService {
  store = new SqlFooStore();
}

After

interface FooStore {
  save(f: Foo): Promise<void>;
}
class FooService {
  constructor(private store: FooStore) {}
}

How it is checked

Checked by the fitness functions, contract tests and architecture tests each contract names, the reviews a contract names where no automated check exists

Population Every module and boundary the contract governs

Freshness A verdict stands until the module, its dependencies or the contract changes

Refusal A failing fitness function or contract test blocks the release

Observation The traces and health signals the observability contracts require, which locate a contract failure in production

Evidence None, because the catalog states this check as a class, so a watched run belongs to each system that adopts it

Authoritative side The contract, which the module and its tests conform to

Depends on Not answered

Shape it refuses Not answered

Interface Contract

Details

Intent Define explicit interfaces with preconditions, postconditions, invariants, error semantics, version rules, and compatibility guarantees before implementation.

Invariant Interfaces are executable promises between independently changeable parts.

Flow

Intent → Interface → Preconditions → Postconditions → Compatibility → Implementation

Productions

InterfaceContract ::= <InterfaceName> "," <OperationSet> "," <PreconditionSet> "," <PostconditionSet> "," <InvariantSet> "," <ErrorContract> "," <VersionContract>
CompatibilityRule ::= "backward_compatible" | "forward_compatible" | "breaking_change_requires_new_version"

Composes none

Composed by Composed Turn Contract,

Forces contract_compatibility, semantic_consistency

Grounds none

Before

function doFoo(a, b, n) {}

After

interface FooOp {
  (a: Foo, b: Bar, n: number): Result<FooOut, FooError>;
}

How it is checked

Checked by the fitness functions, contract tests and architecture tests each contract names, the reviews a contract names where no automated check exists

Population Every module and boundary the contract governs

Freshness A verdict stands until the module, its dependencies or the contract changes

Refusal A failing fitness function or contract test blocks the release

Observation The traces and health signals the observability contracts require, which locate a contract failure in production

Evidence None, because the catalog states this check as a class, so a watched run belongs to each system that adopts it

Authoritative side The contract, which the module and its tests conform to

Depends on Not answered

Shape it refuses Not answered

Substitutability

Details

Intent Validate that every implementation of an abstraction preserves the abstraction’s behavior, accepts valid parent inputs, returns valid parent outputs, and does not strengthen forbidden constraints.

Invariant Polymorphism is safe only when behavioral subtyping holds.

Flow

Interface → Implementation → ContractCheck → Substitute|Reject

Productions

Substitutability ::= <BaseContract> "→" <CandidateImplementation> "→" <BehavioralCompatibilityCheck> "→" <SubstitutionVerdict>
BehavioralCompatibilityCheck ::= "preconditions_not_stronger" "," "postconditions_not_weaker" "," "invariants_preserved" "," "errors_compatible"

Composes none

Forces contract_compatibility, correctness_verification

Grounds none

Before

class ReadOnlyFooStore extends FooStore {
  save() {
    throw new Error("unsupported");
  }
}

After

interface FooReader {
  find(id: FooId): Foo | undefined;
}
interface FooWriter extends FooReader {
  save(f: Foo): void;
}
class ReadOnlyFooStore implements FooReader {
  find(id: FooId) {
    return fooCache.get(id);
  }
}

How it is checked

Checked by the fitness functions, contract tests and architecture tests each contract names, the reviews a contract names where no automated check exists

Population Every module and boundary the contract governs

Freshness A verdict stands until the module, its dependencies or the contract changes

Refusal A failing fitness function or contract test blocks the release

Observation The traces and health signals the observability contracts require, which locate a contract failure in production

Evidence None, because the catalog states this check as a class, so a watched run belongs to each system that adopts it

Authoritative side The contract, which the module and its tests conform to

Depends on Not answered

Shape it refuses Not answered

Canonical Data

Details

Intent Normalize incoming data into a canonical schema, validate types and semantics, preserve one source of truth, and translate at system boundaries only.

Invariant Semantic consistency requires one canonical model and controlled translation at edges.

Flow

RawData → Validate → Normalize → CanonicalModel → BoundaryTranslation

Productions

CanonicalDataFlow ::= <ExternalData> "→" <SchemaValidation> "→" <Canonicalization> "→" <CanonicalModel> "→" <BoundaryAdapter>
CanonicalModel ::= <Schema> "," <TypeRules> "," <SemanticRules> "," <NormalizationRules> "," <SourceOfTruth>

Composes none

Composed by Seed Composition, Canonical Config Resolution, Composed Turn Contract, , Token Source-of-Truth, Type-Keyed Appearance

Forces modularity, semantic_consistency, correctness_verification, model_governance

Grounds none

Before

function useFoo(raw) {
  const name = raw.name ?? raw.Name ?? raw.title;
}

After

function toCanonicalFoo(raw: unknown): Foo {
  return { id: fooId(raw), name: pickName(raw) };
}

How it is checked

Checked by the fitness functions, contract tests and architecture tests each contract names, the reviews a contract names where no automated check exists

Population Every module and boundary the contract governs

Freshness A verdict stands until the module, its dependencies or the contract changes

Refusal A failing fitness function or contract test blocks the release

Observation The traces and health signals the observability contracts require, which locate a contract failure in production

Evidence None, because the catalog states this check as a class, so a watched run belongs to each system that adopts it

Authoritative side The contract, which the module and its tests conform to

Depends on Not answered

Shape it refuses Not answered

Domain Boundary

Details

Intent Identify bounded contexts, define the ubiquitous language and the owner of each context's model, map the relationships between contexts, and use anti-corruption layers where semantics differ.

Invariant Domain architecture protects meaning by making semantic boundaries explicit.

Flow

Domain → BoundedContext → Language → ContextMap → TranslationBoundary

Productions

DomainBoundary ::= <DomainModel> "→" <BoundedContextSet> "→" <UbiquitousLanguageSet> "→" <ContextMap> "→" <IntegrationPolicy>
IntegrationPolicy ::= "shared_kernel" | "customer_supplier" | "anti_corruption_layer" | "published_language" | "separate_ways"

Composes none

Composed by Architectural Contract Algebra, Type-Keyed Appearance

Forces modularity, semantic_consistency, domain_boundary

Grounds none

Before

fooContext.use(sharedBaz);
barContext.use(sharedBaz);

After

function toBarBaz(f: FooBaz): BarBaz {
  return { id: f.id };
}

How it is checked

Checked by the fitness functions, contract tests and architecture tests each contract names, the reviews a contract names where no automated check exists

Population Every module and boundary the contract governs

Freshness A verdict stands until the module, its dependencies or the contract changes

Refusal A failing fitness function or contract test blocks the release

Observation The traces and health signals the observability contracts require, which locate a contract failure in production

Evidence None, because the catalog states this check as a class, so a watched run belongs to each system that adopts it

Authoritative side The contract, which the module and its tests conform to

Depends on Not answered

Shape it refuses Not answered

Self-Description Manifest

Details

Intent Require every component to declare identity, capabilities, contracts, dependencies, configuration, health model, and version metadata in a machine-readable manifest.

Invariant Runtime systems become discoverable and governable when components describe themselves.

Flow

Component → Manifest → CapabilityDeclaration → Discovery → Validation

Productions

SelfDescription ::= <Component> "→" <Manifest> "→" <CapabilitySet> "→" <ContractReferenceSet> "→" <RuntimeRegistration>
Manifest ::= "identity" "," "version" "," "capabilities" "," "dependencies" "," "contracts" "," "configuration" "," "health"

Composes none

Composed by Manifest-Driven Documentation, , Custom Type Registration

Forces contract_compatibility, model_governance

Grounds none

Before

export class FooPlugin {
  transform(x) {
    return x;
  }
}

After

export const manifest = {
  identity: "foo-plugin",
  version: "1.2.0",
  capabilities: ["transform"],
  contracts: ["FooPort@1"],
  dependencies: [],
};

How it is checked

Checked by the fitness functions, contract tests and architecture tests each contract names, the reviews a contract names where no automated check exists

Population Every module and boundary the contract governs

Freshness A verdict stands until the module, its dependencies or the contract changes

Refusal A failing fitness function or contract test blocks the release

Observation The traces and health signals the observability contracts require, which locate a contract failure in production

Evidence None, because the catalog states this check as a class, so a watched run belongs to each system that adopts it

Authoritative side The contract, which the module and its tests conform to

Depends on Not answered

Shape it refuses Not answered

Runtime Discovery

Details

Intent Discover available components by manifest, convention, registry, or service endpoint; validate discovered candidates against contracts; bind dynamically only after compatibility checks.

Invariant Dynamic binding is safe only when discovery is filtered by explicit contracts.

Flow

DiscoverySource → CandidateSet → ContractValidation → Binding → RuntimeUse

Productions

RuntimeDiscovery ::= <DiscoveryMechanism> "→" <CandidateComponentSet> "→" <CapabilityMatch> "→" <ContractValidation> "→" <BindingDecision>
DiscoveryMechanism ::= "manifest" | "registry" | "service_discovery" | "convention" | "configuration"

Composes none

Composed by Runtime Extensibility,

Forces contract_compatibility, runtime_extensibility, correctness_verification

Principle Runtime Discovery

Grounds none

Before

const plugin = new KnownFooPlugin();

After

const candidates = registry.discover({ capability: "transform" });
const bound = candidates.filter((c) => satisfies(c.contract, FooPortV1));

How it is checked

Checked by the fitness functions, contract tests and architecture tests each contract names, the reviews a contract names where no automated check exists

Population Every module and boundary the contract governs

Freshness A verdict stands until the module, its dependencies or the contract changes

Refusal A failing fitness function or contract test blocks the release

Observation The traces and health signals the observability contracts require, which locate a contract failure in production

Evidence None, because the catalog states this check as a class, so a watched run belongs to each system that adopts it

Authoritative side The contract, which the module and its tests conform to

Depends on Not answered

Shape it refuses Not answered

Extension Point

Details

Intent Define stable extension contracts, register implementations through IoC or plugin registries, isolate plugin failures, and expose deterministic loading order.

Invariant Extensibility requires stable hooks, controlled registration, and observable binding.

Flow

ExtensionContract → PluginRegistration → DependencyInjection → Isolation → Dispatch

Productions

ExtensionArchitecture ::= <ExtensionPoint> "→" <PluginContract> "→" <PluginRegistry> "→" <BindingPolicy> "→" <FailureIsolation>
BindingPolicy ::= "dependency_injection" | "service_registry" | "service_locator" | "manual_registration" | "auto_discovery"

Composes none

Composed by Manifest-Driven Documentation, Composed Turn Contract, , Custom Type Registration

Forces contract_compatibility, runtime_extensibility, correctness_verification, observability_traceability

Grounds none

Before

switch (kind) {
  case "foo":
    doFoo();
    break;
  case "bar":
    doBar();
    break;
}

After

registry.register("foo", fooHandler);
registry.register("bar", barHandler);
registry.get(kind)?.handle(input);

How it is checked

Checked by the fitness functions, contract tests and architecture tests each contract names, the reviews a contract names where no automated check exists

Population Every module and boundary the contract governs

Freshness A verdict stands until the module, its dependencies or the contract changes

Refusal A failing fitness function or contract test blocks the release

Observation The traces and health signals the observability contracts require, which locate a contract failure in production

Evidence None, because the catalog states this check as a class, so a watched run belongs to each system that adopts it

Authoritative side The contract, which the module and its tests conform to

Depends on Not answered

Shape it refuses Not answered

Construction Boundary

Details

Intent Hide object creation behind factories, builders, prototypes, or abstract factories so callers depend on creation contracts rather than concrete constructors.

Invariant Creation logic is a boundary and should be replaceable independently from usage logic.

Flow

CreationRequest → ConstructionContract → Factory|Builder|Prototype → Instance

Productions

ConstructionBoundary ::= <CreationIntent> "→" <ConstructionStrategy> "→" <InstanceContract> "→" <ConstructedObject>
ConstructionStrategy ::= "factory" | "factory_method" | "abstract_factory" | "builder" | "prototype"

Composes none

Composed by Governed Construction Boundary

Forces modularity, contract_compatibility, object_creation

Grounds none

Before

const c = new FooConnection(host, port, user, pw);

After

const c = fooConnectionFactory.create(config);

How it is checked

Checked by the fitness functions, contract tests and architecture tests each contract names, the reviews a contract names where no automated check exists

Population Every module and boundary the contract governs

Freshness A verdict stands until the module, its dependencies or the contract changes

Refusal A failing fitness function or contract test blocks the release

Observation The traces and health signals the observability contracts require, which locate a contract failure in production

Evidence None, because the catalog states this check as a class, so a watched run belongs to each system that adopts it

Authoritative side The contract, which the module and its tests conform to

Depends on Not answered

Shape it refuses Not answered

Structural Mediation

Details

Intent Insert adapters, facades, proxies, bridges, or decorators where incompatible structure, access control, abstraction separation, or behavior layering is required.

Invariant Structural patterns reshape access without corrupting the core contract.

Flow

ClientNeed → StructuralMismatch → MediatingPattern → CompatibleInterface

Productions

StructuralMediation ::= <ClientContract> "→" <MismatchType> "→" <StructuralPattern> "→" <CompatibleBoundary>
StructuralPattern ::= "adapter" | "facade" | "proxy" | "bridge" | "decorator"

Composes none

Forces modularity, contract_compatibility

Grounds none

Before

legacyFooApi.call(new FooXmlPayload(foo));

After

class FooAdapter implements FooPort {
  constructor(private legacy: FooXmlApi) {}
  save(f: Foo) {
    return this.legacy.call(toFooXml(f));
  }
}

How it is checked

Checked by the fitness functions, contract tests and architecture tests each contract names, the reviews a contract names where no automated check exists

Population Every module and boundary the contract governs

Freshness A verdict stands until the module, its dependencies or the contract changes

Refusal A failing fitness function or contract test blocks the release

Observation The traces and health signals the observability contracts require, which locate a contract failure in production

Evidence None, because the catalog states this check as a class, so a watched run belongs to each system that adopts it

Authoritative side The contract, which the module and its tests conform to

Depends on Not answered

Shape it refuses Not answered

Behavioral Dispatch

Details

Intent Externalize variable behavior into strategies, template hooks, observers, or mediators while preserving stable orchestration contracts.

Invariant Behavioral variation belongs behind dispatch contracts, not scattered conditionals.

Flow

StableFlow → VariationPoint → DispatchPattern → RuntimeBehavior

Productions

BehavioralDispatch ::= <StableOperation> "→" <VariationPoint> "→" <BehaviorPattern> "→" <SelectedBehavior>
BehaviorPattern ::= "strategy" | "template_method" | "observer" | "mediator" | "polymorphic_dispatch"

Composes none

Forces contract_compatibility, control_coordination

Grounds none

Before

function handleFoo(f) {
  if (f.kind === "a") {
    return runA(f);
  } else if (f.kind === "b") {
    return runB(f);
  }
}

After

const strategies: Record<FooKind, FooStrategy> = {
  a: fooStrategyA,
  b: fooStrategyB,
};
function handleFoo(f: Foo) {
  return strategies[f.kind].run(f);
}

How it is checked

Checked by the fitness functions, contract tests and architecture tests each contract names, the reviews a contract names where no automated check exists

Population Every module and boundary the contract governs

Freshness A verdict stands until the module, its dependencies or the contract changes

Refusal A failing fitness function or contract test blocks the release

Observation The traces and health signals the observability contracts require, which locate a contract failure in production

Evidence None, because the catalog states this check as a class, so a watched run belongs to each system that adopts it

Authoritative side The contract, which the module and its tests conform to

Depends on Not answered

Shape it refuses Not answered

Architectural Style Boundary

Details

Intent Select an architectural style, from a monolith or modular monolith to layered, hexagonal or microservices, by dependency direction, deployment autonomy, domain complexity, team topology, operational maturity and change isolation needs, then enforce the style through boundary rules.

Invariant Architecture style is a macro-contract for dependency flow and deployment shape.

Flow

SystemForces → StyleSelection → BoundaryRules → FitnessValidation

Productions

ArchitectureStyle ::= <SystemForces> "→" <Style> "→" <BoundaryRuleSet> "→" <FitnessFunctionSet>
Style ::= "hexagonal" | "ports_and_adapters" | "clean_architecture" | "layered" | "component_based" | "package_by_feature" | "microservices" | "modular_monolith" | "monolith"
SystemForces ::= "domain_complexity" "," "team_topology" "," "deployment_autonomy" "," "consistency_requirement" "," "operational_maturity" "," "scaling_pressure"

Composes none

Composed by Cascade Layer Partition

Forces modularity, contract_compatibility, domain_boundary

Grounds none

Before

import { SqlDriver } from "../infra/sql";

After

export const boundaries = { ui: ["app"], app: ["domain"], domain: [] };

How it is checked

Checked by the fitness functions, contract tests and architecture tests each contract names, the reviews a contract names where no automated check exists

Population Every module and boundary the contract governs

Freshness A verdict stands until the module, its dependencies or the contract changes

Refusal A failing fitness function or contract test blocks the release

Observation The traces and health signals the observability contracts require, which locate a contract failure in production

Evidence None, because the catalog states this check as a class, so a watched run belongs to each system that adopts it

Authoritative side The contract, which the module and its tests conform to

Depends on Not answered

Shape it refuses Not answered

Port Adapter

Details

Intent Place domain logic behind inbound and outbound ports, implement external technology through adapters, and forbid domain dependence on infrastructure.

Invariant The domain remains stable by depending on ports, not delivery or persistence mechanisms.

Flow

UseCase → InboundPort → DomainLogic → OutboundPort → Adapter

Productions

PortAdapterFlow ::= <ExternalDriver> "→" <InboundAdapter> "→" <InboundPort> "→" <UseCase> "→" <OutboundPort> "→" <OutboundAdapter>
DependencyDirection ::= "adapter_depends_on_port" "," "domain_depends_on_abstraction" "," "infrastructure_outside_core"

Composes none

Composed by Persistence Fork

Forces domain_boundary

Grounds none

Before

class FooUseCase {
  run(f) {
    new FooHttpClient().send(f);
  }
}

After

interface FooOutPort {
  send(f: Foo): Promise<void>;
}
class FooUseCase {
  constructor(private out: FooOutPort) {}
}

How it is checked

Checked by the fitness functions, contract tests and architecture tests each contract names, the reviews a contract names where no automated check exists

Population Every module and boundary the contract governs

Freshness A verdict stands until the module, its dependencies or the contract changes

Refusal A failing fitness function or contract test blocks the release

Observation The traces and health signals the observability contracts require, which locate a contract failure in production

Evidence None, because the catalog states this check as a class, so a watched run belongs to each system that adopts it

Authoritative side The contract, which the module and its tests conform to

Depends on Not answered

Shape it refuses Not answered

Event Messaging

Details

Intent Convert state changes into events, classify domain versus integration events, publish through durable channels, consume idempotently, and preserve ordering where required.

Invariant Event-driven systems trade immediate consistency for decoupled causal propagation.

Flow

StateChange → Event → Publish → Consume → IdempotentEffect → Consistency

Productions

EventMessaging ::= <StateChange> "→" <EventClassification> "→" <MessageEnvelope> "→" <BrokerOrBus> "→" <Consumer> "→" <EffectPolicy>
EventClassification ::= "domain_event" | "integration_event" | "stream_event"
EffectPolicy ::= "idempotent" "," "retryable" "," "observable" "," "ordered_if_required"

Composes none

Forces event_messaging, domain_boundary, causality_ordering

Grounds none

Before

async function doFoo(f) {
  await stepBar(f);
  await stepBaz(f);
  await stepQux(f);
}

After

async function doFoo(f) {
  await fooStore.save(f);
  await bus.publish({ type: "FooHappened", f });
}

How it is checked

Checked by the fitness functions, contract tests and architecture tests each contract names, the reviews a contract names where no automated check exists

Population Every module and boundary the contract governs

Freshness A verdict stands until the module, its dependencies or the contract changes

Refusal A failing fitness function or contract test blocks the release

Observation The traces and health signals the observability contracts require, which locate a contract failure in production

Evidence None, because the catalog states this check as a class, so a watched run belongs to each system that adopts it

Authoritative side The contract, which the module and its tests conform to

Depends on Not answered

Shape it refuses Not answered

Saga Compensation

Details

Intent For long-running distributed workflows, split work into steps, persist progress, define compensating actions, and recover from partial failure through forward or backward correction.

Invariant Distributed transactions require explicit process state and compensation.

Flow

Workflow → StepGraph → LocalTransaction → Event → Compensation|Continue

Productions

Saga ::= <SagaState> "→" <Step> "→" <LocalTransaction> "→" <ProgressEvent> "→" (<NextStep> | <CompensatingTransaction>)
SagaStep ::= <Command> "," <SuccessEvent> "," <FailureEvent> "," <CompensationCommand>

Composes none

Forces event_messaging

Grounds none

Refused by rules saga-compensation

Before

await reserveFoo(x);
await reserveBar(x);

After

const saga = [
  { do: reserveFoo, undo: releaseFoo },
  { do: reserveBar, undo: releaseBar },
];
runSaga(saga);

How it is checked

Checked by the fitness functions, contract tests and architecture tests each contract names, the reviews a contract names where no automated check exists

Population Every module and boundary the contract governs

Freshness A verdict stands until the module, its dependencies or the contract changes

Refusal A failing fitness function or contract test blocks the release

Observation The traces and health signals the observability contracts require, which locate a contract failure in production

Evidence None, because the catalog states this check as a class, so a watched run belongs to each system that adopts it

Authoritative side The contract, which the module and its tests conform to

Depends on Not answered

Shape it refuses Not answered

Transaction Boundary

Details

Intent Define atomic state-change boundaries, isolate concurrent mutation, enforce consistency rules, and commit or roll back as a unit.

Invariant Correct state change requires explicit transaction scope and isolation semantics.

Flow

Command → UnitOfWork → Invariant → Commit|Rollback

Productions

TransactionBoundary ::= <Command> "→" <TransactionScope> "→" <InvariantCheck> "→" <ConcurrencyControl> "→" <CommitDecision>
ConcurrencyControl ::= "optimistic_locking" | "pessimistic_locking" | "serial_execution" | "state_isolation"

Composes none

Composed by Architectural Contract Algebra, State and Transaction Safety

Forces modularity, semantic_consistency, state_transaction

Principle Transaction Boundary

Grounds none

Before

decFoo(a, n);
incBar(b, n);

After

await unitOfWork(async (tx) => {
  await decFoo(tx, a, n);
  await incBar(tx, b, n);
});

How it is checked

Checked by the fitness functions, contract tests and architecture tests each contract names, the reviews a contract names where no automated check exists

Population Every module and boundary the contract governs

Freshness A verdict stands until the module, its dependencies or the contract changes

Refusal A failing fitness function or contract test blocks the release

Observation The traces and health signals the observability contracts require, which locate a contract failure in production

Evidence None, because the catalog states this check as a class, so a watched run belongs to each system that adopts it

Authoritative side The contract, which the module and its tests conform to

Depends on Not answered

Shape it refuses Not answered

Idempotent Side Effect

Details

Intent Assign a stable operation identity, check whether the effect was already applied, execute only once, and return the same semantic result for repeated requests.

Invariant External side effects must be repeat-safe under retries.

Flow

Request → IdempotencyKey → PriorResultCheck → ExecuteOnce → PersistOutcome

Productions

Idempotency ::= <Request> "→" <IdempotencyKey> "→" <DeduplicationStore> "→" (<PriorResult> | <SideEffectExecution>) "→" <StableResponse>
StableResponse ::= "same_key_same_effect_same_semantic_result"

Composes none

Composed by Idempotent Merge

Forces semantic_consistency, state_transaction, resilience_recovery

Grounds none

Before

async function applyFoo(req) {
  await external.apply(req.value);
}

After

async function applyFoo(req) {
  if (await seen(req.key)) return priorResult(req.key);
  const r = await external.apply(req.value);
  await persist(req.key, r);
  return r;
}

How it is checked

Checked by the fitness functions, contract tests and architecture tests each contract names, the reviews a contract names where no automated check exists

Population Every module and boundary the contract governs

Freshness A verdict stands until the module, its dependencies or the contract changes

Refusal A failing fitness function or contract test blocks the release

Observation The traces and health signals the observability contracts require, which locate a contract failure in production

Evidence None, because the catalog states this check as a class, so a watched run belongs to each system that adopts it

Authoritative side The contract, which the module and its tests conform to

Depends on Not answered

Shape it refuses Not answered

Deterministic Core

Details

Intent Push nondeterminism to system edges, keep core logic pure where possible, use immutable inputs, and make outputs reproducible under identical inputs.

Invariant Correctness improves when the core is deterministic and side effects are controlled.

Flow

ExternalInput → Normalize → PureCore → DeterministicOutput → ControlledEffect

Productions

DeterministicCore ::= <Input> "→" <Canonicalization> "→" <PureFunctionSet> "→" <Output> "→" <EffectBoundary>
PurityConstraint ::= "no_hidden_state" "," "no_hidden_time" "," "no_hidden_randomness" "," "referential_transparency"

Composes none

Composed by Correctness Verification, Deterministic Merge Core

Forces correctness_verification

Grounds none

Before

function scoreFoo(f) {
  return f.base * (Date.now() % 2 ? 1.1 : 1);
}

After

function scoreFoo(f: Foo, now: Date) {
  return f.base * rateAt(now);
}

How it is checked

Checked by the fitness functions, contract tests and architecture tests each contract names, the reviews a contract names where no automated check exists

Population Every module and boundary the contract governs

Freshness A verdict stands until the module, its dependencies or the contract changes

Refusal A failing fitness function or contract test blocks the release

Observation The traces and health signals the observability contracts require, which locate a contract failure in production

Evidence None, because the catalog states this check as a class, so a watched run belongs to each system that adopts it

Authoritative side The contract, which the module and its tests conform to

Depends on Not answered

Shape it refuses Not answered

Verification Fitness

Details

Intent Define executable architecture rules, validate with static analysis, specification tests, property tests, and runtime checks, then block release when critical rules fail.

Invariant Architecture must be continuously verified by fitness functions.

Flow

Rule → Test → Evidence → Pass|Fail → Gate

Productions

VerificationFitness ::= <SpecificationSet> "→" <VerificationMethodSet> "→" <EvidenceSet> "→" <FitnessVerdict>
VerificationMethod ::= "type_check" | "static_analysis" | "schema_validation" | "contract_test" | "property_based_test" | "specification_test" | "formal_verification" | "runtime_validation"

Composes none

Composed by Layer Fitness Enforcement

Forces runtime_extensibility, correctness_verification, architecture_evolution

Grounds none

Before

reviewChecklist.push("domain must not import infra");

After

test("domain imports no infra", () =>
  expect(importsOf("domain")).not.toContain("infra"));

How it is checked

Checked by the fitness functions, contract tests and architecture tests each contract names, the reviews a contract names where no automated check exists

Population Every module and boundary the contract governs

Freshness A verdict stands until the module, its dependencies or the contract changes

Refusal A failing fitness function or contract test blocks the release

Observation The traces and health signals the observability contracts require, which locate a contract failure in production

Evidence None, because the catalog states this check as a class, so a watched run belongs to each system that adopts it

Authoritative side The contract, which the module and its tests conform to

Depends on Not answered

Shape it refuses Not answered

Error Boundary

Details

Intent Detect invalid state early, fail fast for programmer errors, fail safe for recoverable runtime faults, fail secure for security-sensitive failures, and return typed errors.

Invariant Error handling is a contract for containment, disclosure, and recovery.

Flow

Operation → Guard → ErrorClass → BoundaryPolicy → RecoveryOrAbort

Productions

ErrorBoundary ::= <Operation> "→" <PreconditionCheck> "→" <ErrorClassification> "→" <FailurePolicy> "→" <ResultContract>
FailurePolicy ::= "fail_fast" | "fail_safe" | "fail_secure" | "graceful_degradation" | "fallback"

Composes none

Composed by Governed Construction Boundary

Forces modularity, contract_compatibility, resilience_recovery, security_governance

Grounds none

Before

try {
  doFoo();
} catch (e) {
  return null;
}

After

try {
  return ok(doFoo());
} catch (e) {
  if (isProgrammerError(e)) throw e;
  Logger.error("doFoo failed", e);
  return err("foo.retry");
}

How it is checked

Checked by the fitness functions, contract tests and architecture tests each contract names, the reviews a contract names where no automated check exists

Population Every module and boundary the contract governs

Freshness A verdict stands until the module, its dependencies or the contract changes

Refusal A failing fitness function or contract test blocks the release

Observation The traces and health signals the observability contracts require, which locate a contract failure in production

Evidence None, because the catalog states this check as a class, so a watched run belongs to each system that adopts it

Authoritative side The contract, which the module and its tests conform to

Depends on Not answered

Shape it refuses Not answered

Resilience Control

Details

Intent Wrap remote or unreliable calls with timeout, retry, circuit breaker, bulkhead isolation, fallback, and backpressure policies.

Invariant Resilience is controlled failure under resource and dependency stress.

Flow

Call → Timeout → RetryPolicy → CircuitBreaker → Bulkhead → Fallback

Productions

ResilienceControl ::= <ExternalCall> "→" <TimeoutPolicy> "→" <RetryPolicy> "→" <CircuitBreaker> "→" <Bulkhead> "→" <FallbackPolicy> "→" <BackpressurePolicy>
RetryPolicy ::= "bounded_attempts" "," "jittered_backoff" "," "idempotency_required"

Composes none

Composed by Quality Governance Loop

Forces resilience_recovery

Grounds none

Before

const r = await callFoo(url);

After

const r = await breaker.run(() => withTimeout(callFoo(url), 2000), {
  retries: 3,
  backoff: jitter,
});

How it is checked

Checked by the fitness functions, contract tests and architecture tests each contract names, the reviews a contract names where no automated check exists

Population Every module and boundary the contract governs

Freshness A verdict stands until the module, its dependencies or the contract changes

Refusal A failing fitness function or contract test blocks the release

Observation The traces and health signals the observability contracts require, which locate a contract failure in production

Evidence None, because the catalog states this check as a class, so a watched run belongs to each system that adopts it

Authoritative side The contract, which the module and its tests conform to

Depends on Not answered

Shape it refuses Not answered

Recovery Deployment

Details

Intent Continuously health-check services, isolate failed instances, fail over to redundancy, roll back unsafe releases, and use canary or blue-green deployment for controlled exposure.

Invariant Deployment safety requires observable health and reversible rollout.

Flow

Deploy → HealthCheck → TrafficShift → DetectFailure → Rollback|Promote

Productions

RecoveryDeployment ::= <ReleaseCandidate> "→" <DeploymentStrategy> "→" <HealthSignalSet> "→" <PromotionDecision>
DeploymentStrategy ::= "blue_green" | "canary" | "rolling" | "rollback" | "auto_remediation"

Composes none

Forces resilience_recovery, observability_traceability

Grounds none

Before

deployAll(fooV2);

After

canary(fooV2, { percent: 5, healthCheck });

How it is checked

Checked by the fitness functions, contract tests and architecture tests each contract names, the reviews a contract names where no automated check exists

Population Every module and boundary the contract governs

Freshness A verdict stands until the module, its dependencies or the contract changes

Refusal A failing fitness function or contract test blocks the release

Observation The traces and health signals the observability contracts require, which locate a contract failure in production

Evidence None, because the catalog states this check as a class, so a watched run belongs to each system that adopts it

Authoritative side The contract, which the module and its tests conform to

Depends on Not answered

Shape it refuses Not answered

Observability Trace

Details

Intent Attach correlation and causation identifiers to every operation, emit structured logs, metrics, traces, and audit records, then connect them into an explainable execution graph.

Invariant A system is operable only when behavior can be reconstructed from evidence.

Flow

Request → CorrelationID → Logs/Metrics/Traces → Audit → CausalGraph

Productions

ObservabilityTrace ::= <Operation> "→" <CorrelationId> "→" <CausationId> "→" <TelemetryEventSet> "→" <TraceGraph> "→" <AuditRecord>
TelemetryEvent ::= "log" | "metric" | "trace_span" | "alert" | "audit_log"

Composes none

Composed by Event and Messaging Consistency

Forces observability_traceability

Grounds none

Before

console.log("processing foo");

After

logger.info("foo.process", {
  correlationId: ctx.cid,
  causationId: ctx.parentId,
  fooId: foo.id,
});

How it is checked

Checked by the fitness functions, contract tests and architecture tests each contract names, the reviews a contract names where no automated check exists

Population Every module and boundary the contract governs

Freshness A verdict stands until the module, its dependencies or the contract changes

Refusal A failing fitness function or contract test blocks the release

Observation The traces and health signals the observability contracts require, which locate a contract failure in production

Evidence None, because the catalog states this check as a class, so a watched run belongs to each system that adopts it

Authoritative side The contract, which the module and its tests conform to

Depends on Not answered

Shape it refuses Not answered

Causality Ordering

Details

Intent Model events as a dependency graph, assign causal metadata, preserve happens-before relationships with sequence numbers, Lamport clocks or vector clocks where physical timestamps are insufficient, and reject or compensate for invalid ordering.

Invariant Distributed correctness depends on causal ordering, not just timestamps.

Flow

Event → CausalMetadata → DependencyGraph → OrderingValidation

Productions

CausalityOrdering ::= <EventSet> "→" <CausalMetadataSet> "→" <DependencyGraph> "→" <OrderingPolicy>
CausalMetadata ::= "correlation_id" | "causation_id" | "sequence_number" | "lamport_clock" | "vector_clock"
DependencyGraph ::= "DAG"

Composes none

Forces correctness_verification, observability_traceability, model_governance, event_messaging, causality_ordering

Grounds none

Before

events.sort((a, b) => a.timestamp - b.timestamp);

After

events.sort(byVectorClock);

How it is checked

Checked by the fitness functions, contract tests and architecture tests each contract names, the reviews a contract names where no automated check exists

Population Every module and boundary the contract governs

Freshness A verdict stands until the module, its dependencies or the contract changes

Refusal A failing fitness function or contract test blocks the release

Observation The traces and health signals the observability contracts require, which locate a contract failure in production

Evidence None, because the catalog states this check as a class, so a watched run belongs to each system that adopts it

Authoritative side The contract, which the module and its tests conform to

Depends on Not answered

Shape it refuses Not answered

Performance Scaling

Details

Intent Measure workload, identify bottlenecks, choose vertical or horizontal scaling, partition load, cache safe data, enforce rate limits, and benchmark continuously.

Invariant Scalability is achieved by measured bottleneck removal, not speculative optimization.

Flow

Workload → Profile → Bottleneck → ScaleStrategy → Benchmark → Feedback

Productions

PerformanceScaling ::= <WorkloadModel> "→" <ProfilingResult> "→" <BottleneckAnalysis> "→" <ScalingStrategy> "→" <OptimizationPolicy> "→" <BenchmarkResult>
ScalingStrategy ::= "vertical_scaling" | "horizontal_scaling" | "load_balancing" | "sharding" | "partitioning" | "caching" | "stateless_replication"

Composes none

Forces performance_scaling

Grounds none

Before

optimizeEverywhere(app);

After

const hot = profile(load).topBottleneck();
scale(hot, hot.isCpuBound ? "horizontal" : "cache");
benchmark();

How it is checked

Checked by the fitness functions, contract tests and architecture tests each contract names, the reviews a contract names where no automated check exists

Population Every module and boundary the contract governs

Freshness A verdict stands until the module, its dependencies or the contract changes

Refusal A failing fitness function or contract test blocks the release

Observation The traces and health signals the observability contracts require, which locate a contract failure in production

Evidence None, because the catalog states this check as a class, so a watched run belongs to each system that adopts it

Authoritative side The contract, which the module and its tests conform to

Depends on Not answered

Shape it refuses Not answered

Cache Correctness

Details

Intent Cache only data with defined freshness, key identity, invalidation triggers, consistency expectations, and fallback behavior.

Invariant Caching is safe only when staleness and invalidation are explicit.

Flow

Data → CacheKey → FreshnessPolicy → Invalidation → ReadThrough|Bypass

Productions

CacheContract ::= <CacheableData> "→" <CacheKey> "→" <FreshnessPolicy> "→" <InvalidationPolicy> "→" <ConsistencyPolicy>
ConsistencyPolicy ::= "strong" | "eventual" | "read_your_writes" | "bounded_staleness"

Composes none

Forces correctness_verification, resilience_recovery

Grounds none

Before

cache.set(key, value);

After

cache.set(fingerprint(inputs, deriverVersion), value, {
  invalidateOn: ["FooChanged"],
  consistency: "read_your_writes",
});

How it is checked

Checked by the fitness functions, contract tests and architecture tests each contract names, the reviews a contract names where no automated check exists

Population Every module and boundary the contract governs

Freshness A verdict stands until the module, its dependencies or the contract changes

Refusal A failing fitness function or contract test blocks the release

Observation The traces and health signals the observability contracts require, which locate a contract failure in production

Evidence None, because the catalog states this check as a class, so a watched run belongs to each system that adopts it

Authoritative side The contract, which the module and its tests conform to

Depends on Not answered

Shape it refuses Not answered

Portability Environment

Details

Intent Externalize configuration, standardize protocols, isolate platform assumptions behind adapters, package runtime dependencies, and validate parity across environments.

Invariant Portable systems separate behavior from deployment substrate.

Flow

Code → ExternalConfig → StandardProtocol → Container|Package → EnvironmentParity

Productions

PortabilityContract ::= <ApplicationCore> "→" <ConfigurationExternalization> "→" <ProtocolBoundary> "→" <InfrastructureAdapter> "→" <EnvironmentValidation>
EnvironmentValidation ::= "dev" "," "test" "," "staging" "," "production" "," "parity_check"

Composes none

Forces correctness_verification

Grounds none

Before

const db = connect("driver://prod-host:5432");

After

const db = connect(config.databaseUrl);

How it is checked

Checked by the fitness functions, contract tests and architecture tests each contract names, the reviews a contract names where no automated check exists

Population Every module and boundary the contract governs

Freshness A verdict stands until the module, its dependencies or the contract changes

Refusal A failing fitness function or contract test blocks the release

Observation The traces and health signals the observability contracts require, which locate a contract failure in production

Evidence None, because the catalog states this check as a class, so a watched run belongs to each system that adopts it

Authoritative side The contract, which the module and its tests conform to

Depends on Not answered

Shape it refuses Not answered

Security Policy

Details

Intent Threat-model the system, reduce attack surface, authenticate identity, authorize actions, validate input, encode output, encrypt data, protect secrets, and enforce policy continuously.

Invariant Security is a default-deny contract over identity, data, and operations.

Flow

ThreatModel → Identity → Authorization → Validation → Protection → Audit

Productions

SecurityPolicy ::= <ThreatModel> "→" <IdentityProof> "→" <AccessDecision> "→" <InputOutputGuard> "→" <DataProtection> "→" <PolicyEnforcement> "→" <SecurityAudit>
AccessDecision ::= "RBAC" | "ABAC" | "least_privilege" | "zero_trust"
DataProtection ::= "encryption_at_rest" "," "encryption_in_transit" "," "secrets_management"

Composes none

Composed by Governed Construction Boundary

Forces contract_compatibility, correctness_verification, security_governance, model_governance

Grounds none

Before

if (user) allowFoo();

After

if (!policy.can(user, "foo:write", resource)) throw forbidden();
const foo = validate(FooSchema, input);

How it is checked

Checked by the fitness functions, contract tests and architecture tests each contract names, the reviews a contract names where no automated check exists

Population Every module and boundary the contract governs

Freshness A verdict stands until the module, its dependencies or the contract changes

Refusal A failing fitness function or contract test blocks the release

Observation The traces and health signals the observability contracts require, which locate a contract failure in production

Evidence None, because the catalog states this check as a class, so a watched run belongs to each system that adopts it

Authoritative side The contract, which the module and its tests conform to

Depends on Not answered

Shape it refuses Not answered

Control Plane

Details

Intent Separate control concerns from data execution, centralize policy/configuration/authentication/logging where beneficial, and decentralize runtime execution where autonomy is required.

Invariant A control plane coordinates policy while data planes execute work.

Flow

Policy → ControlPlane → DistributedExecution → Feedback

Productions

ControlPlane ::= <PolicySet> "→" <CentralizedCoordination> "→" <DataPlaneSet> "→" <TelemetryFeedback> "→" <PolicyAdjustment>
CentralizedCoordination ::= "configuration" | "authentication" | "authorization" | "logging" | "orchestration"

Composes none

Composed by Control Plane Coordination

Forces semantic_consistency, security_governance, control_coordination

Principle Control Plane

Grounds none

Before

Every service reads its own ad-hoc config and does its own auth — policy is scattered and drifts.

After

policy{central} → control-plane{config, auth, orchestration} → data-planes{Foo, Bar execute work} → telemetry-feedback → policy-adjustment

How it is checked

Checked by the fitness functions, contract tests and architecture tests each contract names, the reviews a contract names where no automated check exists

Population Every module and boundary the contract governs

Freshness A verdict stands until the module, its dependencies or the contract changes

Refusal A failing fitness function or contract test blocks the release

Observation The traces and health signals the observability contracts require, which locate a contract failure in production

Evidence None, because the catalog states this check as a class, so a watched run belongs to each system that adopts it

Authoritative side The contract, which the module and its tests conform to

Depends on Not answered

Shape it refuses Not answered

Declarative Metaprogramming

Details

Intent Represent behavior as data, validate the model or DSL, compile or interpret it into runtime behavior, and restrict reflection or code generation behind safety contracts.

Invariant Metaprogramming is safe when code-as-data has schema, validation, and bounded execution.

Flow

Model → Schema → Compile|Interpret → RuntimeBehavior → SafetyCheck

Productions

DeclarativeMetaprogramming ::= <ProgramModel> "→" <ModelSchema> "→" <TransformationEngine> "→" <GeneratedOrInterpretedBehavior> "→" <SafetyBoundary>
TransformationEngine ::= "reflection" | "introspection" | "compile_time_evaluation" | "runtime_code_generation" | "DSL_interpreter"

Composes none

Forces contract_compatibility, correctness_verification, model_governance, metaprogramming_modeling

Grounds none

Before

eval(fooExpression);

After

const ast = parse(fooDsl, GRAMMAR);
validate(ast, SCHEMA);
run(compile(ast), sandbox);

How it is checked

Checked by the fitness functions, contract tests and architecture tests each contract names, the reviews a contract names where no automated check exists

Population Every module and boundary the contract governs

Freshness A verdict stands until the module, its dependencies or the contract changes

Refusal A failing fitness function or contract test blocks the release

Observation The traces and health signals the observability contracts require, which locate a contract failure in production

Evidence None, because the catalog states this check as a class, so a watched run belongs to each system that adopts it

Authoritative side The contract, which the module and its tests conform to

Depends on Not answered

Shape it refuses Not answered

Streaming Dataflow

Details

Intent Process data sequentially through bounded pipeline stages, preserve forward-only semantics where required, apply backpressure, checkpoint state where needed, and keep stages stateless unless state is explicitly modeled.

Invariant Streaming systems are contracts over flow, order, pressure, and bounded memory.

Flow

Source → Stage → Stage → Sink → Checkpoint

Productions

StreamingDataflow ::= <Source> "→" <PipelineStageSet> "→" <BackpressurePolicy> "→" <CheckpointPolicy> "→" <Sink>
PipelineStage ::= <InputStream> "→" <Transform> "→" <OutputStream>
ProcessingMode ::= "single_pass" | "lazy_evaluation" | "sequential_access" | "forward_only" | "stateless" | "stateful_with_checkpoint"

Composes none

Forces contract_compatibility, semantic_consistency, resilience_recovery, streaming_dataflow, causality_ordering

Grounds none

Before

const all = await loadAllFoo();
return all.map(toBar).filter(isBaz);

After

fooSource
  .pipe(mapStage(toBar))
  .pipe(filterStage(isBaz))
  .pipe(sink, { backpressure: true });

How it is checked

Checked by the fitness functions, contract tests and architecture tests each contract names, the reviews a contract names where no automated check exists

Population Every module and boundary the contract governs

Freshness A verdict stands until the module, its dependencies or the contract changes

Refusal A failing fitness function or contract test blocks the release

Observation The traces and health signals the observability contracts require, which locate a contract failure in production

Evidence None, because the catalog states this check as a class, so a watched run belongs to each system that adopts it

Authoritative side The contract, which the module and its tests conform to

Depends on Not answered

Shape it refuses Not answered

RAG Knowledge Boundary

Details

Intent Retrieve knowledge from indexed sources, validate relevance and freshness, ground generation in retrieved evidence, and distinguish known, inferred, and unsupported output.

Invariant Retrieval-augmented systems must separate source evidence from generated synthesis.

Flow

Query → Retrieve → Rank → Ground → Generate → Cite|Reject

Productions

RAGBoundary ::= <UserQuery> "→" <Retriever> "→" <CandidateEvidenceSet> "→" <RelevanceValidation> "→" <GroundedGeneration> "→" <EvidenceDisclosure>
EvidenceDisclosure ::= "supported" | "partially_supported" | "unsupported_reject_or_disclose"

Composes none

Composed by Profile Compose, Delta Capture

Forces modularity, correctness_verification, model_governance

Grounds none

Before

const answer = model.generate(query);

After

const ev = retrieve(query);
const g = generate(query, ev);
return g.supported ? cite(g, ev) : disclose("unsupported");

How it is checked

Checked by the fitness functions, contract tests and architecture tests each contract names, the reviews a contract names where no automated check exists

Population Every module and boundary the contract governs

Freshness A verdict stands until the module, its dependencies or the contract changes

Refusal A failing fitness function or contract test blocks the release

Observation The traces and health signals the observability contracts require, which locate a contract failure in production

Evidence None, because the catalog states this check as a class, so a watched run belongs to each system that adopts it

Authoritative side The contract, which the module and its tests conform to

Depends on Not answered

Shape it refuses Not answered

Architecture Selection Meta-Algorithm

Details

Intent Given a concern, classify its force type, select the corresponding contract family, compose required invariants, bind implementation patterns, and attach validation gates.

Invariant Architectural patterns are reusable only when selected by force, not by name.

Flow

Concern → ForceType → ContractFamily → PatternSet → ValidationGate

Productions

ArchitectureSelection ::= <Concern> "→" <ForceFamily> "→" <ContractFamily> "→" <ImplementationPatternSet> "→" <ValidationGateSet>
ForceFamily ::= "modularity" | "compatibility" | "semantics" | "extension" | "state" | "correctness" | "resilience" | "security" | "scale" | "governance"

Composes none

Forces contract_compatibility, correctness_verification

Grounds none

Before

A pattern chosen by name ('let's use Foo') before the force it must resolve is known.

After

concern → force{change-isolation} → contract-family{deployment-boundary} → pattern{selected by force, not by name} → validation-gate

How it is checked

Checked by the fitness functions, contract tests and architecture tests each contract names, the reviews a contract names where no automated check exists

Population Every module and boundary the contract governs

Freshness A verdict stands until the module, its dependencies or the contract changes

Refusal A failing fitness function or contract test blocks the release

Observation The traces and health signals the observability contracts require, which locate a contract failure in production

Evidence None, because the catalog states this check as a class, so a watched run belongs to each system that adopts it

Authoritative side The contract, which the module and its tests conform to

Depends on Not answered

Shape it refuses Not answered

Universal Architectural Concern Template

Details

Intent For any architectural concern, define its intent, boundary, contract, invariants, allowed variation, forbidden leakage, validation strategy, observability model, and evolution policy.

Invariant Every architecture principle can be operationalized as a bounded contract with verification and change rules.

Flow

Intent → Boundary → Contract → Invariant → Variation → Validation → Evolution

Productions

UniversalConcern ::= <Intent> "→" <Boundary> "→" <Contract> "→" <InvariantSet> "→" <AllowedVariationSet> "→" <ForbiddenLeakageSet> "→" <ValidationStrategy> "→" <ObservabilityModel> "→" <EvolutionPolicy>
Contract ::= <Input> "," <Output> "," <Preconditions> "," <Postconditions> "," <FailureModes> "," <CompatibilityRules>

Composes none

Forces modularity, contract_compatibility, correctness_verification, observability_traceability, model_governance, architecture_evolution

Grounds none

Before

A principle stated as prose ('be modular') with no operational contract.

After

intent → boundary → contract{in, out, pre, post} → invariants → allowed-variation → forbidden-leakage → validation → observability → evolution

How it is checked

Checked by the fitness functions, contract tests and architecture tests each contract names, the reviews a contract names where no automated check exists

Population Every module and boundary the contract governs

Freshness A verdict stands until the module, its dependencies or the contract changes

Refusal A failing fitness function or contract test blocks the release

Observation The traces and health signals the observability contracts require, which locate a contract failure in production

Evidence None, because the catalog states this check as a class, so a watched run belongs to each system that adopts it

Authoritative side The contract, which the module and its tests conform to

Depends on Not answered

Shape it refuses Not answered

Architectural Contract Algebra

Details

Intent → → → → → → →

Invariant Architecture becomes reproducible when every named principle is reduced to a force, every force becomes a contract, every contract has invariants, and every invariant has validation.

Flow

Force → Contract → Pattern → Implementation → Verification → Operation → Evolution

Productions

ArchitecturalContractAlgebra ::= <Force> "→" <Boundary> "→" <Contract> "→" <Pattern> "→" <Implementation> "→" <Verification> "→" <Observation> "→" <Evolution>
Force ::= "change" | "dependency" | "semantic_consistency" | "runtime_extension" | "state_mutation" | "failure" | "scale" | "security" | "governance" | "intelligence"
Boundary ::= <ModuleBoundary> | <DomainBoundary> | <InterfaceBoundary> | <TransactionBoundary> | <SecurityBoundary> | <DeploymentBoundary> | <ObservationBoundary>
Pattern ::= <CreationalPattern> | <StructuralPattern> | <BehavioralPattern> | <ArchitecturalStyle> | <MessagingPattern> | <ResiliencePattern> | <GovernancePattern>
Verification ::= <StaticCheck> | <ContractTest> | <SchemaValidation> | <PropertyTest> | <FitnessFunction> | <RuntimeHealthCheck> | <AuditReview>
Evolution ::= <VersioningPolicy> | <CompatibilityPolicy> | <MigrationPolicy> | <RollbackPolicy> | <ADRPolicy> | <ContinuousCompliancePolicy>

Composes Domain Boundary, Transaction Boundary

Forces modularity, contract_compatibility, correctness_verification, architecture_evolution

Principle Design by Contract

Grounds none

How it is checked

Checked by the fitness functions, contract tests and architecture tests each contract names, the reviews a contract names where no automated check exists

Population Every module and boundary the contract governs

Freshness A verdict stands until the module, its dependencies or the contract changes

Refusal A failing fitness function or contract test blocks the release

Observation The traces and health signals the observability contracts require, which locate a contract failure in production

Evidence None, because the catalog states this check as a class, so a watched run belongs to each system that adopts it

Authoritative side The contract, which the module and its tests conform to

Depends on Domain Boundary, Transaction Boundary

Shape it refuses Not answered

Manifest-Driven Documentation

Details

Intent For a module whose public surface is machine-derivable, make its metadata manifest the single documentation source of truth: authored narrative lives in mandated, shape-validated manifest fields (with self-expanding custom fields), the API surface is collected deterministically from the built type-declarations, one marker-layered document is compiled per module from both, and a governance router runs the context-detection rules on the manifest strings where a manifest governs (rendering each field to its markdown fragment first) and on the document itself where none exists. Beyond the module document, a manifest may declare typed documents — each a form plus concern that routes through the pure location function to a computed path — generated and drift-checked the same way, so the manifest is the single content generator with no separate template mechanism.

Invariant A module's document is well-formed iff it recompiles byte-identical from its manifest docs-block plus its derived surface, its docs-block satisfies the mandated schema with every custom field a renderable shape, and every governed string passes the context rules reported at its manifest field; the manifest, where present, is the governed surface and the document is exempt and drift-checked.

Flow

Manifest → AuthoredField → DerivedSurface → SectionDeriver → MarkerLayer → Compilation → GovernanceRouter → DriftGate

Productions

ModuleDocument ::= <ManifestAuthoredFields> "+" <DerivedSurface> "→" <SectionDeriverResolution> "→" <MarkerLayerTemplate> "→" <Compilation> "→" <DriftGate>
GovernanceRouter ::= <ManifestPresent> "→" <RenderFieldToFragment> <ScanFragment> | <ManifestAbsent> "→" <ScanDocument>
TypedDocument ::= <FormConcernName> "→" <LocationRouter> "→" <BodySections> "→" <Compilation> "→" <DriftGate>

Composes Document Truth Alignment, Self-Description Manifest, Extension Point

Forces correctness_verification, contract_compatibility, modularity

Grounds none

Before

A README hand-authored as prose that drifts from the exports it claims to document.

After

manifest.docs{authored} + derivedSurface{from .d.ts} → section-derivers → marker-template → compile → drift-gate{recompiles byte-identical, else fail}

How it is checked

Checked by the fitness functions, contract tests and architecture tests each contract names, the reviews a contract names where no automated check exists

Population Every module and boundary the contract governs

Freshness A verdict stands until the module, its dependencies or the contract changes

Refusal A failing fitness function or contract test blocks the release

Observation The traces and health signals the observability contracts require, which locate a contract failure in production

Evidence None, because the catalog states this check as a class, so a watched run belongs to each system that adopts it

Authoritative side The contract, which the module and its tests conform to

Depends on Document Truth Alignment, Self-Description Manifest, Extension Point

Shape it refuses Not answered

Consumer Config SSOT

Details

Intent For any reusable package that must stay agnostic of the applications consuming it, hardcode zero consumer-specific truths in package source; declare every consumer-specific value in one consumer-owned config of typed sections, load it through a framework the leaf packages never import, and hand each package only the section it needs through an injection surface — so a package drops into any consumer without a literal about that consumer leaking through its source.

Invariant A package is consumer-agnostic iff every consumer-specific value it depends on arrives by injection at wiring time and no consumer token, path, or config-location appears in its source; the one consumer config is the single reader-visible source of those values and a static gate rejects any re-hardcoding.

Flow

ConsumerValue → ConfigSection → FrameworkLoad → InjectionSurface → PackageConsumption → CouplingGate

Productions

ConsumerConfigSSOT ::= <ConsumerValueSet> "→" <ConfigSectionSet> "→" <FrameworkLoad> "→" <InjectionSurface> "→" <PackageConsumption> "+" <CouplingGate>
InjectionSurface ::= <SettingsChannel> "|" <OptionsChannel> "|" <ArgvEnvChannel> "|" <FactoryOptionChannel>

Composes Architectural Contract Kernel, Responsibility Boundary

Forces modularity, contract_compatibility, correctness_verification

Grounds none

Before

const ROOT = "my-app";
const cfg = read("../config/app.json");

After

export function createFoo(opts: { root: string; store: FooStore }) {
  return new Foo(opts);
}

How it is checked

Checked by the fitness functions, contract tests and architecture tests each contract names, the reviews a contract names where no automated check exists

Population Every module and boundary the contract governs

Freshness A verdict stands until the module, its dependencies or the contract changes

Refusal A failing fitness function or contract test blocks the release

Observation The traces and health signals the observability contracts require, which locate a contract failure in production

Evidence None, because the catalog states this check as a class, so a watched run belongs to each system that adopts it

Authoritative side The contract, which the module and its tests conform to

Depends on Architectural Contract Kernel, Responsibility Boundary

Shape it refuses Not answered

Finite State Machine

Details

Intent Model behavior as a finite set of states with explicit legal transitions, so illegal state combinations are unrepresentable.

Invariant Every runtime state is one of the declared states and every transition is a declared edge.

Flow

EnumerateStates → DefineEvents → DeclareTransitions → RejectUndeclared

Productions

FiniteStateMachine ::= <EnumerateStates> "→" <DefineEvents> "→" <DeclareTransitions> "→" <RejectUndeclared>

Composes State Pattern, Structural Core

Composed by Statecharts

Forces boolean-flag-soup (illegal-states)

Principle Finite State Machine

Grounds none

Before

let isOpen = false,
  isLoading = false,
  isError = false;
function onClick() {
  isLoading = true;
  if (isOpen) isOpen = false;
}

After

type FooState = "closed" | "loading" | "open" | "error";
const transitions: Record<FooState, Partial<Record<FooEvent, FooState>>> = {
  closed: { open: "loading" },
  loading: { ready: "open", fail: "error" },
  open: { close: "closed" },
  error: { retry: "loading" },
};
function next(state: FooState, event: FooEvent): FooState {
  return transitions[state][event] ?? state;
}

How it is checked

Checked by the fitness functions, contract tests and architecture tests each contract names, the reviews a contract names where no automated check exists

Population Every module and boundary the contract governs

Freshness A verdict stands until the module, its dependencies or the contract changes

Refusal A failing fitness function or contract test blocks the release

Observation The traces and health signals the observability contracts require, which locate a contract failure in production

Evidence None, because the catalog states this check as a class, so a watched run belongs to each system that adopts it

Authoritative side The contract, which the module and its tests conform to

Depends on State Pattern, Structural Core

Shape it refuses Not answered

Statecharts

Details

Intent Extend a flat state machine with hierarchy and parallel regions, so independent concerns compose without state explosion.

Invariant Independent behavioral concerns live in separate parallel regions rather than a cross product of flat states.

Flow

IdentifyIndependentConcerns → NestRelatedStates → SeparateParallelRegions → GuardTransitions

Productions

Statecharts ::= <IdentifyIndependentConcerns> "→" <NestRelatedStates> "→" <SeparateParallelRegions> "→" <GuardTransitions>

Composes Finite State Machine, Separation of Concerns

Forces flat-state-explosion (combinatorial-growth)

Principle Statecharts

Grounds none

Before

type S = "idleMuted" | "idleLoud" | "playingMuted" | "playingLoud";

After

const fooChart = {
  initial: "idle",
  states: { idle: {}, playing: {} },
  parallel: { volume: { states: { muted: {}, loud: {} } } },
};

How it is checked

Checked by the fitness functions, contract tests and architecture tests each contract names, the reviews a contract names where no automated check exists

Population Every module and boundary the contract governs

Freshness A verdict stands until the module, its dependencies or the contract changes

Refusal A failing fitness function or contract test blocks the release

Observation The traces and health signals the observability contracts require, which locate a contract failure in production

Evidence None, because the catalog states this check as a class, so a watched run belongs to each system that adopts it

Authoritative side The contract, which the module and its tests conform to

Depends on Finite State Machine, Separation of Concerns

Shape it refuses Not answered

Petri Nets

Details

Intent Model concurrent flow as places, tokens, and transitions, so reachability and deadlock are analyzable before runtime.

Invariant Concurrent progress is expressed as token flow through transitions whose enabling conditions are explicit.

Flow

DefinePlaces → PlaceTokens → DefineTransitions → AnalyzeReachability → AssertNoDeadlock

Productions

PetriNet ::= <DefinePlaces> "→" <PlaceTokens> "→" <DefineTransitions> "→" <AnalyzeReachability> "→" <AssertNoDeadlock>

Composes Concurrency Correctness, Correctness Core

Forces ad-hoc-lock-ordering (deadlock)

Principle Petri Nets

Grounds none

Before

acquire(a);
acquire(b);
work();
release(b);
release(a);

After

const net = petriNet({
  places: { idle: 1, aHeld: 0, bHeld: 0 },
  transitions: [
    { name: "takeA", consume: { idle: 1 }, produce: { aHeld: 1 } },
    { name: "takeB", consume: { aHeld: 1 }, produce: { bHeld: 1 } },
  ],
});
assertNoDeadlock(reachableMarkings(net));

How it is checked

Checked by the fitness functions, contract tests and architecture tests each contract names, the reviews a contract names where no automated check exists

Population Every module and boundary the contract governs

Freshness A verdict stands until the module, its dependencies or the contract changes

Refusal A failing fitness function or contract test blocks the release

Observation The traces and health signals the observability contracts require, which locate a contract failure in production

Evidence None, because the catalog states this check as a class, so a watched run belongs to each system that adopts it

Authoritative side The contract, which the module and its tests conform to

Depends on Concurrency Correctness, Correctness Core

Shape it refuses Not answered

Queuing Theory

Details

Intent Size a system from arrival and service rates, so capacity and wait time are predicted rather than guessed.

Invariant Utilization stays below one and predicted wait time is derived from the arrival/service-rate model.

Flow

MeasureArrivalRate → MeasureServiceRate → ComputeUtilization → PredictWaitTime → SizeServers

Productions

QueuingModel ::= <MeasureArrivalRate> "→" <MeasureServiceRate> "→" <ComputeUtilization> "→" <PredictWaitTime> "→" <SizeServers>

Composes Capacity Planning, Performance Core

Forces guess-based-capacity (saturation)

Principle Queuing Theory

Grounds none

Before

const workers = 4;

After

const rho = arrivalRate / (workers * serviceRate);
if (rho >= 1) throw new Error("unstable queue: utilization >= 1");
const avgWaitMs = mm1WaitTime({ arrivalRate, serviceRate, servers: workers });

How it is checked

Checked by the fitness functions, contract tests and architecture tests each contract names, the reviews a contract names where no automated check exists

Population Every module and boundary the contract governs

Freshness A verdict stands until the module, its dependencies or the contract changes

Refusal A failing fitness function or contract test blocks the release

Observation The traces and health signals the observability contracts require, which locate a contract failure in production

Evidence None, because the catalog states this check as a class, so a watched run belongs to each system that adopts it

Authoritative side The contract, which the module and its tests conform to

Depends on Capacity Planning, Performance Core

Shape it refuses Not answered

Architecture relationships

Every algorithm contract in this domain is listed with its position on the derivation loop, its intent and invariant, the flow it walks and its productions as a grammar. Each record also shows what it composes and is composed by, which forces and principles it answers to, what grounds it and what it grounds, and an exemplar where the record carries one. The diagram shows what composes what inside the domain.

Relations diagram

What composes what inside this domain.

flowchart LR
    n_architectural_relationship_record["Architectural Relationship Record"]
    n_architecture_knowledge_graph["Architecture Knowledge Graph"]
    n_architectural_force_classification["Architectural Force Classification"]
    n_dependency_closure["Dependency Closure"]
    n_reinforcement_propagation["Reinforcement Propagation"]
    n_conflict_and_tension_resolution["Conflict and Tension Resolution"]
    n_severity_policy["Severity Policy"]
    n_violation_detection["Violation Detection"]
    n_measurement_normalization["Measurement Normalization"]
    n_refactor_selection["Refactor Selection"]
    n_enforcement_gate["Enforcement Gate"]
    n_architecture_assessment["Architecture Assessment"]
    n_modular_boundary_compliance["Modular Boundary Compliance"]
    n_contract_compatibility["Contract Compatibility"]
    n_canonical_semantics["Canonical Semantics"]
    n_self_description_and_discovery["Self-Description and Discovery"]
    n_runtime_extensibility["Runtime Extensibility"]
    n_pattern_selection["Pattern Selection"]
    n_event_and_messaging_consistency["Event and Messaging Consistency"]
    n_state_and_transaction_safety["State and Transaction Safety"]
    n_correctness_verification["Correctness Verification"]
    n_resilience_policy["Resilience Policy"]
    n_observability_and_auditability["Observability and Auditability"]
    n_performance_and_scalability["Performance and Scalability"]
    n_security_governance["Security Governance"]
    n_architecture_evolution_governance["Architecture Evolution Governance"]
    n_control_plane_coordination["Control Plane Coordination"]
    n_metaprogramming_safety["Metaprogramming Safety"]
    n_model_lifecycle_governance["Model Lifecycle Governance"]
    n_architectural_recommendation["Architectural Recommendation"]
    n_architecture_fitness_function_generation["Architecture Fitness Function Generation"]
    n_architecture_refactoring_roadmap["Architecture Refactoring Roadmap"]
    n_concept_cluster_extraction["Concept Cluster Extraction"]
    n_architecture_decision_support["Architecture Decision Support"]
    n_relationship_schema_validation["Relationship Schema Validation"]
    n_architecture_catalog_compiler["Architecture Catalog Compiler"]
    n_master_architecture_governance_kernel["Master Architecture Governance Kernel"]
    n_architectural_relationship_algebra["Architectural Relationship Algebra"]
    n_architecture_assessment --> n_dependency_closure
    n_architecture_assessment --> n_violation_detection
    n_architecture_assessment --> n_measurement_normalization
    n_architecture_evolution_governance --> n_architecture_assessment
    n_architectural_recommendation --> n_dependency_closure
    n_architecture_fitness_function_generation --> n_architectural_relationship_record
    n_architecture_fitness_function_generation --> n_enforcement_gate
    n_architecture_fitness_function_generation --> n_severity_policy
    n_master_architecture_governance_kernel --> n_relationship_schema_validation
    n_master_architecture_governance_kernel --> n_concept_cluster_extraction
    n_master_architecture_governance_kernel --> n_dependency_closure
    n_master_architecture_governance_kernel --> n_violation_detection
    n_master_architecture_governance_kernel --> n_measurement_normalization
    n_master_architecture_governance_kernel --> n_refactor_selection
    n_master_architecture_governance_kernel --> n_enforcement_gate
    n_master_architecture_governance_kernel --> n_architecture_decision_support
    n_architectural_relationship_algebra --> n_dependency_closure
    n_architectural_relationship_algebra --> n_violation_detection
    n_architectural_relationship_algebra --> n_measurement_normalization
    n_architectural_relationship_algebra --> n_refactor_selection
    n_architectural_relationship_algebra --> n_enforcement_gate
    n_architectural_relationship_algebra --> n_architecture_evolution_governance
Loading

Architectural Relationship Record

Details

Intent Represent every architectural concept as a typed relationship record containing scope, dependencies, reinforcing effects, enabled capabilities, conflicts, tensions, violations, detection signals, metrics, refactor actions, enforcement mechanisms, and severity.

Invariant An architecture principle becomes operational when it is converted from a name into a measurable, enforceable relationship contract.

Flow

Concept → Type → Scope → Requires → Violations → Detection → Measurement → Refactor → Enforcement → Severity

Productions

ArchitecturalRelationshipRecord ::= <ConceptName> ":" <RecordType> "," <ScopeSet> "," <RequiresSet> "," <ReinforcesSet> "," <EnablesSet> "," <ConflictSet> "," <TensionSet> "," <ViolationSet> "," <DetectionSet> "," <MetricSet> "," <RefactorSet> "," <EnforcementSet> "," <EnforcementSeverity>
RecordType ::= "Principle" | "Quality Attribute" | "Contract" | "Architecture Style" | "Pattern" | "Mechanism" | "Metric" | "Practice"
EnforcementSeverity ::= "mandatory" | "recommended" | "contextual" | "discouraged"
MandatoryFor ::= "contextual" "+" <SystemCondition>

Composes none

Composed by Architecture Fitness Function Generation

Forces contract_compatibility

Grounds none

Before

'Low Coupling' as a bare name in a list — not measurable, not enforceable.

After

Low Coupling : Quality-Attribute, scope{module}, requires{Abstraction}, conflicts_with{Tight Coupling}, detected_by{cycle scan}, measured_by{coupling metric}, refactored_by{invert dependency}, enforced_by{dependency rule}, severity{mandatory}

How it is checked

Checked by the ontology resolution gate, which validates every relationship record's fields, relations and references

Population Every architecture record in the catalog

Freshness A verdict stands until a record or the relation ranges change

Refusal The gate fails on a dangling edge, an out-of-range relation, an unknown severity or an empty required field

Observation None, because the catalog is data; the checks its records name observe the systems

Evidence Watched to fire and to accept: a suite plants an unchecked principle, a blank required field, a severity outside the closed levels and a definition that opens as another kind, and the bundled records pass

Authoritative side The relation ranges and the closed field vocabularies, which every record conforms to

Depends on Not answered

Shape it refuses Not answered

Architecture Knowledge Graph

Details

Intent Parse all relationship records into a directed multigraph where concepts are nodes and fields such as requires, reinforces, enables, conflicts, tensions, detects, measures, refactors, and enforces are typed edges.

Invariant The architecture catalog becomes reusable when its relationships can be traversed as a graph.

Flow

Records → Nodes → TypedEdges → Graph → QueryableArchitectureModel

Productions

ArchitectureGraph ::= <ConceptNodeSet> "," <RelationshipEdgeSet>
ConceptNode ::= <ConceptName> "," <RecordType> "," <ScopeSet> "," <EnforcementSeverity>
RelationshipEdge ::= <SourceConcept> "→" <RelationType> "→" <TargetConceptOrSignal>
RelationType ::= "requires" | "reinforces" | "enables" | "conflicts_with" | "tensions_with" | "violated_by" | "detected_by" | "measured_by" | "refactored_by" | "enforced_by"

Composes none

Forces architecture_evolution

Grounds none

Before

A flat list of relationship records — no way to ask 'what does Foo require, transitively?'

After

records → nodes{concepts} + typed-edges{requires, reinforces, enables, conflicts_with} → traversable graph

How it is checked

Checked by the ontology resolution gate, which validates every relationship record's fields, relations and references

Population Every architecture record in the catalog

Freshness A verdict stands until a record or the relation ranges change

Refusal The gate fails on a dangling edge, an out-of-range relation, an unknown severity or an empty required field

Observation None, because the catalog is data; the checks its records name observe the systems

Evidence Watched to fire and to accept: a suite plants an unchecked principle, a blank required field, a severity outside the closed levels and a definition that opens as another kind, and the bundled records pass

Authoritative side The relation ranges and the closed field vocabularies, which every record conforms to

Depends on Not answered

Shape it refuses Not answered

Architectural Force Classification

Details

Intent Given a design issue or desired quality, classify it into a force family, then select all concepts whose scope, type, violation signals, and enabled capabilities match that force.

Invariant Architectural decisions should be selected by force and evidence, not by pattern name recognition.

Flow

Issue → ForceFamily → CandidateConcepts → ApplicableContracts

Productions

ForceClassification ::= <DesignIssue> "→" <ForceFamily> "→" <ConceptQuery> "→" <ApplicableConceptSet>
ForceFamily ::= "modularity" | "contract_compatibility" | "semantic_consistency" | "domain_boundary" | "runtime_extensibility" | "object_creation" | "structural_mediation" | "behavioral_variation" | "event_messaging" | "state_transaction" | "correctness_verification" | "resilience_recovery" | "observability_traceability" | "causality_ordering" | "performance_scaling" | "security_governance" | "architecture_evolution" | "control_coordination" | "metaprogramming_modeling" | "streaming_dataflow" | "model_governance"

Composes none

Forces architecture_evolution

Grounds none

Before

A design issue answered by pattern-name recall ('use a Factory').

After

issue{concrete constructor everywhere} → force{object_creation} → concept-query → applicable{Construction Boundary}

How it is checked

Checked by the ontology resolution gate, which validates every relationship record's fields, relations and references

Population Every architecture record in the catalog

Freshness A verdict stands until a record or the relation ranges change

Refusal The gate fails on a dangling edge, an out-of-range relation, an unknown severity or an empty required field

Observation None, because the catalog is data; the checks its records name observe the systems

Evidence Watched to fire and to accept: a suite plants an unchecked principle, a blank required field, a severity outside the closed levels and a definition that opens as another kind, and the bundled records pass

Authoritative side The relation ranges and the closed field vocabularies, which every record conforms to

Depends on Not answered

Shape it refuses Not answered

Dependency Closure

Details

Intent For any target architectural concept, recursively collect its required concepts until no new requirements remain, then order the closure by dependency depth before implementation.

Invariant A principle cannot be adopted safely unless its prerequisites are also satisfied.

Flow

TargetConcept → RequiresEdges → TransitiveClosure → DependencyOrder

Productions

DependencyClosure ::= <TargetConcept> "→" <RequiresTraversal> "→" <RequiredConceptSet> "→" <TopologicalOrder>
RequiresTraversal ::= "follow requires edges until fixed point"
TopologicalOrder ::= "prerequisites_before_dependents"

Composes none

Composed by Architecture Assessment, Architectural Recommendation, Master Architecture Governance Kernel, Architectural Relationship Algebra

Forces architecture_evolution

Grounds none

Before

Adopt Foo without checking what Foo needs — its prerequisites are silently unmet.

After

target{Foo} → follow requires-edges to fixed point → {Bar, Baz} → topological order{Baz, Bar, Foo}

How it is checked

Checked by the ontology resolution gate, which validates every relationship record's fields, relations and references

Population Every architecture record in the catalog

Freshness A verdict stands until a record or the relation ranges change

Refusal The gate fails on a dangling edge, an out-of-range relation, an unknown severity or an empty required field

Observation None, because the catalog is data; the checks its records name observe the systems

Evidence Watched to fire and to accept: a suite plants an unchecked principle, a blank required field, a severity outside the closed levels and a definition that opens as another kind, and the bundled records pass

Authoritative side The relation ranges and the closed field vocabularies, which every record conforms to

Depends on Not answered

Shape it refuses Not answered

Reinforcement Propagation

Details

Intent When a concept is implemented or strengthened, traverse its reinforces and enables edges to identify secondary quality gains and architecture capabilities unlocked.

Invariant Architecture improvements produce second-order effects through reinforcing relationships.

Flow

ImplementedConcept → Reinforces + Enables → CapabilityImpact

Productions

ReinforcementPropagation ::= <SatisfiedConcept> "→" <ReinforcesTraversal> "→" <EnablesTraversal> "→" <ImpactSet>
ImpactSet ::= <QualityGainSet> "," <CapabilityGainSet>
QualityGain ::= <ReinforcedConcept> "," <Confidence> "," <EvidenceRequired>

Composes none

Forces architecture_evolution

Grounds none

Before

Foo implemented; its second-order gains go unnoticed and unclaimed.

After

satisfied{Foo} → reinforces → {Bar quality} → enables → {Baz capability} → impact set with confidence

How it is checked

Checked by the ontology resolution gate, which validates every relationship record's fields, relations and references

Population Every architecture record in the catalog

Freshness A verdict stands until a record or the relation ranges change

Refusal The gate fails on a dangling edge, an out-of-range relation, an unknown severity or an empty required field

Observation None, because the catalog is data; the checks its records name observe the systems

Evidence Watched to fire and to accept: a suite plants an unchecked principle, a blank required field, a severity outside the closed levels and a definition that opens as another kind, and the bundled records pass

Authoritative side The relation ranges and the closed field vocabularies, which every record conforms to

Depends on Not answered

Shape it refuses Not answered

Conflict and Tension Resolution

Details

Intent For each selected concept, collect conflicts and tensions, classify conflicts as prohibitive or resolvable, classify tensions as trade-offs, and require an explicit decision when severity or impact is high.

Invariant Architecture is not only principle application; it is trade-off governance.

Flow

CandidateConcept → Conflicts + Tensions → TradeoffAnalysis → Decision

Productions

ConflictTensionResolution ::= <CandidateConceptSet> "→" <ConflictSet> "→" <TensionSet> "→" <ResolutionPolicy>
ResolutionPolicy ::= "reject_combination" | "accept_with_mitigation" | "document_tradeoff" | "require_architecture_decision" | "contextual_override"

Composes none

Forces security_governance

Grounds none

Before

Two chosen concepts silently conflict at runtime; the developer never decided the trade-off.

After

candidates{Foo, Bar} → conflict{prohibitive} → tension{trade-off} → policy{require architecture decision}

How it is checked

Checked by the ontology resolution gate, which validates every relationship record's fields, relations and references

Population Every architecture record in the catalog

Freshness A verdict stands until a record or the relation ranges change

Refusal The gate fails on a dangling edge, an out-of-range relation, an unknown severity or an empty required field

Observation None, because the catalog is data; the checks its records name observe the systems

Evidence Watched to fire and to accept: a suite plants an unchecked principle, a blank required field, a severity outside the closed levels and a definition that opens as another kind, and the bundled records pass

Authoritative side The relation ranges and the closed field vocabularies, which every record conforms to

Depends on Not answered

Shape it refuses Not answered

Severity Policy

Details

Intent Interpret severity as an enforcement policy: mandatory concepts become gates, recommended concepts become review findings, contextual concepts require scope justification, and discouraged concepts require explicit exception approval.

Invariant Severity converts architecture knowledge into governance behavior.

Flow

Severity → EnforcementMode → GateBehavior

Productions

SeverityPolicy ::= <EnforcementSeverity> "→" <EnforcementMode>
EnforcementMode ::= "blocking_gate" | "review_warning" | "context_required" | "exception_required" | "informational"
SeverityMapping ::= "mandatory → blocking_gate" | "recommended → review_warning" | "contextual → context_required" | "discouraged → exception_required"

Composes none

Composed by Anti-Pattern Rule Compiler, Architecture Fitness Function Generation

Forces security_governance

Grounds none

Before

Every finding treated the same — a style nit blocks like a critical flaw.

After

severity{mandatory} → blocking-gate ; severity{recommended} → review-warning ; severity{contextual} → context-required

How it is checked

Checked by the ontology resolution gate, which validates every relationship record's fields, relations and references

Population Every architecture record in the catalog

Freshness A verdict stands until a record or the relation ranges change

Refusal The gate fails on a dangling edge, an out-of-range relation, an unknown severity or an empty required field

Observation None, because the catalog is data; the checks its records name observe the systems

Evidence Watched to fire and to accept: a suite plants an unchecked principle, a blank required field, a severity outside the closed levels and a definition that opens as another kind, and the bundled records pass

Authoritative side The relation ranges and the closed field vocabularies, which every record conforms to

Depends on Not answered

Shape it refuses Not answered

Violation Detection

Details

Intent For each concept applicable to the current scope, execute its detected_by signals against the implementation, map observations to violated_by patterns, and produce evidence-backed violation records.

Invariant A principle violation must be grounded in observable implementation signals.

Flow

ApplicableConcept → DetectionSignals → Observations → ViolationRecords

Productions

ViolationDetection ::= <ApplicableConceptSet> "→" <DetectionSignalSet> "→" <ObservedEvidenceSet> "→" <ViolationRecordSet>
ViolationRecord ::= <Concept> "," <ViolationPattern> "," <EvidenceLocationSet> "," <MetricValueSet> "," <EnforcementSeverity> "," <RecommendedRefactorSet>

Composes none

Composed by Architecture Assessment, Master Architecture Governance Kernel, Architectural Relationship Algebra

Forces observability_traceability, model_governance

Grounds none

Before

'Foo is violated' asserted from opinion, with no observable signal.

After

concept{Foo} → detected_by signals run on code → observations → violation-record{concept, pattern, evidence, severity}

How it is checked

Checked by the ontology resolution gate, which validates every relationship record's fields, relations and references

Population Every architecture record in the catalog

Freshness A verdict stands until a record or the relation ranges change

Refusal The gate fails on a dangling edge, an out-of-range relation, an unknown severity or an empty required field

Observation None, because the catalog is data; the checks its records name observe the systems

Evidence Watched to fire and to accept: a suite plants an unchecked principle, a blank required field, a severity outside the closed levels and a definition that opens as another kind, and the bundled records pass

Authoritative side The relation ranges and the closed field vocabularies, which every record conforms to

Depends on Not answered

Shape it refuses Not answered

Measurement Normalization

Details

Intent Convert each concept’s measured_by field into executable or reviewable metrics, collect metric values, normalize them to comparable scores, and attach confidence based on measurement quality.

Invariant Architectural assessment requires metrics with provenance, not free-form judgment.

Flow

MeasuredBy → MetricDefinition → Measurement → NormalizedScore → Confidence

Productions

MeasurementNormalization ::= <MetricDescriptorSet> "→" <MetricDefinitionSet> "→" <MetricValueSet> "→" <NormalizedScoreSet>
MetricDefinition ::= <MetricName> "," <Scope> "," <CollectionMethod> "," <ThresholdPolicy> "," <ConfidencePolicy>

Composes none

Composed by Architecture Assessment, Master Architecture Governance Kernel, Architectural Relationship Algebra

Forces semantic_consistency

Grounds none

Before

Architecture judged by free-form opinion, no comparable numbers.

After

measured_by{coupling} → metric-definition{scope, method, threshold} → values → normalized score + confidence

How it is checked

Checked by the ontology resolution gate, which validates every relationship record's fields, relations and references

Population Every architecture record in the catalog

Freshness A verdict stands until a record or the relation ranges change

Refusal The gate fails on a dangling edge, an out-of-range relation, an unknown severity or an empty required field

Observation None, because the catalog is data; the checks its records name observe the systems

Evidence Watched to fire and to accept: a suite plants an unchecked principle, a blank required field, a severity outside the closed levels and a definition that opens as another kind, and the bundled records pass

Authoritative side The relation ranges and the closed field vocabularies, which every record conforms to

Depends on Not answered

Shape it refuses Not answered

Refactor Selection

Details

Intent Given a violation record, select refactor actions from the concept’s refactored_by field, rank actions by severity, dependency closure, blast radius, and expected reinforcement gain.

Invariant Refactoring should be selected from the violated concept’s remediation contract.

Flow

Violation → RefactorCandidates → RiskRank → SelectedPlan

Productions

RefactorSelection ::= <ViolationRecord> "→" <RefactorActionSet> "→" <RefactorRanking> "→" <RefactorPlan>
RefactorRanking ::= "severity" "," "required_dependency_count" "," "blast_radius" "," "reinforcement_gain" "," "rollback_feasibility"

Composes none

Composed by Master Architecture Governance Kernel, Architectural Relationship Algebra

Forces contract_compatibility, correctness_verification

Grounds none

Before

A fix chosen ad hoc, unrelated to the violated concept's remediation contract.

After

violation{Foo} → refactored_by candidates → rank{severity, blast-radius, reinforcement-gain} → refactor plan

How it is checked

Checked by the ontology resolution gate, which validates every relationship record's fields, relations and references

Population Every architecture record in the catalog

Freshness A verdict stands until a record or the relation ranges change

Refusal The gate fails on a dangling edge, an out-of-range relation, an unknown severity or an empty required field

Observation None, because the catalog is data; the checks its records name observe the systems

Evidence Watched to fire and to accept: a suite plants an unchecked principle, a blank required field, a severity outside the closed levels and a definition that opens as another kind, and the bundled records pass

Authoritative side The relation ranges and the closed field vocabularies, which every record conforms to

Depends on Not answered

Shape it refuses Not answered

Enforcement Gate

Details

Intent Translate each concept’s enforced_by field into static checks, contract tests, schema validation, CI gates, policy rules, runtime monitors, review gates, or architecture fitness functions.

Invariant Enforcement converts architectural intent into repeatable control.

Flow

EnforcementDescriptor → GateType → ValidationProcedure → Pass|Fail

Productions

EnforcementGate ::= <Concept> "→" <EnforcementDescriptorSet> "→" <GateSet> "→" <GateResultSet>
GateType ::= "static_analysis" | "architecture_test" | "schema_validation" | "contract_test" | "lint_rule" | "fitness_function" | "runtime_monitor" | "policy_as_code" | "review_gate"

Composes none

Composed by Architecture Fitness Function Generation, Master Architecture Governance Kernel, Architectural Relationship Algebra

Forces contract_compatibility, runtime_extensibility, correctness_verification, architecture_evolution

Grounds none

Before

'enforced_by: review' — a reviewer's promise that erodes under deadline.

After

enforced_by{Foo} → gate-type{static-analysis | contract-test | fitness-function} → pass/fail in CI

How it is checked

Checked by the ontology resolution gate, which validates every relationship record's fields, relations and references

Population Every architecture record in the catalog

Freshness A verdict stands until a record or the relation ranges change

Refusal The gate fails on a dangling edge, an out-of-range relation, an unknown severity or an empty required field

Observation None, because the catalog is data; the checks its records name observe the systems

Evidence Watched to fire and to accept: a suite plants an unchecked principle, a blank required field, a severity outside the closed levels and a definition that opens as another kind, and the bundled records pass

Authoritative side The relation ranges and the closed field vocabularies, which every record conforms to

Depends on Not answered

Shape it refuses Not answered

Architecture Assessment

Details

Intent Select concepts relevant to a target scope, compute dependency closure, detect violations, measure evidence, rank findings by severity, and emit a prioritized architecture assessment.

Invariant Assessment is graph query plus evidence collection plus severity policy.

Flow

Scope → RelevantConcepts → DependencyClosure → Detection → Measurement → Findings

Productions

ArchitectureAssessment ::= <TargetScope> "→" <RelevantConceptSelection> "→" <DependencyClosure> "→" <ViolationDetection> "→" <MeasurementNormalization> "→" <FindingPrioritization> "→" <AssessmentReport>
FindingPrioritization ::= "mandatory_first" "," "high_blast_radius" "," "high_reinforcement_gain" "," "low_refactor_cost"

Composes Dependency Closure, Violation Detection, Measurement Normalization

Composed by Architecture Evolution Governance

Forces architecture_evolution

Grounds none

Before

'The architecture is fine' — an unscoped, evidence-free claim.

After

scope → relevant concepts → dependency-closure → violation-detection → measurement → prioritized findings

How it is checked

Checked by the ontology resolution gate, which validates every relationship record's fields, relations and references

Population Every architecture record in the catalog

Freshness A verdict stands until a record or the relation ranges change

Refusal The gate fails on a dangling edge, an out-of-range relation, an unknown severity or an empty required field

Observation None, because the catalog is data; the checks its records name observe the systems

Evidence Watched to fire and to accept: a suite plants an unchecked principle, a blank required field, a severity outside the closed levels and a definition that opens as another kind, and the bundled records pass

Authoritative side The relation ranges and the closed field vocabularies, which every record conforms to

Depends on Dependency Closure, Violation Detection, Measurement Normalization

Shape it refuses Not answered

Modular Boundary Compliance

Details

Intent Evaluate SRP, separation of concerns, cohesion, coupling, encapsulation, information hiding, abstraction, modularity, composability, replaceability, and autonomy as a connected boundary cluster.

Invariant Modular design is not one principle; it is a mutually reinforcing cluster around responsibility, dependency, and visibility.

Flow

Module → Responsibility → Cohesion → Coupling → Visibility → BoundaryHealth

Productions

ModularBoundaryCompliance ::= <ModuleSet> "→" <ResponsibilityAnalysis> "→" <CohesionMetric> "→" <CouplingMetric> "→" <VisibilityLeakCheck> "→" <BoundaryScore>
BoundaryScore ::= <ResponsibilityScore> "," <CohesionScore> "," <CouplingScore> "," <EncapsulationScore> "," <ReplaceabilityScore>

Composes none

Forces modularity, correctness_verification

Grounds none

Before

Modularity judged as one vague impression.

After

modules → responsibility + cohesion + coupling + visibility-leak → boundary score{per-dimension}

How it is checked

Checked by the ontology resolution gate, which validates every relationship record's fields, relations and references

Population Every architecture record in the catalog

Freshness A verdict stands until a record or the relation ranges change

Refusal The gate fails on a dangling edge, an out-of-range relation, an unknown severity or an empty required field

Observation None, because the catalog is data; the checks its records name observe the systems

Evidence Watched to fire and to accept: a suite plants an unchecked principle, a blank required field, a severity outside the closed levels and a definition that opens as another kind, and the bundled records pass

Authoritative side The relation ranges and the closed field vocabularies, which every record conforms to

Depends on Not answered

Shape it refuses Not answered

Contract Compatibility

Details

Intent For APIs, services, data, schemas, and protocols, validate explicit contracts, preconditions, postconditions, invariants, versioning, backward compatibility, forward compatibility, and interoperability.

Invariant Compatibility is the contract cluster that allows independent evolution.

Flow

Boundary → Contract → Version → CompatibilityMatrix → Gate

Productions

ContractCompatibility ::= <BoundaryContract> "→" <SchemaOrInterfaceValidation> "→" <SemanticValidation> "→" <VersionPolicy> "→" <CompatibilityMatrix> "→" <CompatibilityVerdict>
CompatibilityMatrix ::= "producer_current_consumer_current" | "producer_new_consumer_old" | "producer_old_consumer_new" | "unknown_field_handling" | "breaking_diff_check"

Composes none

Composed by Loop-Owned Mode Selection,

Forces contract_compatibility, correctness_verification, architecture_evolution

Grounds none

Before

A schema changed and downstreams broke — compatibility was never checked.

After

boundary-contract → schema/semantic validation → version-policy → compatibility-matrix{new-producer/old-consumer} → verdict

How it is checked

Checked by the ontology resolution gate, which validates every relationship record's fields, relations and references

Population Every architecture record in the catalog

Freshness A verdict stands until a record or the relation ranges change

Refusal The gate fails on a dangling edge, an out-of-range relation, an unknown severity or an empty required field

Observation None, because the catalog is data; the checks its records name observe the systems

Evidence Watched to fire and to accept: a suite plants an unchecked principle, a blank required field, a severity outside the closed levels and a definition that opens as another kind, and the bundled records pass

Authoritative side The relation ranges and the closed field vocabularies, which every record conforms to

Depends on Not answered

Shape it refuses Not answered

Canonical Semantics

Details

Intent Detect duplicated or conflicting models, schemas, terms, rules, and data definitions; select or create canonical authority; normalize variants; enforce single source of truth.

Invariant Semantic consistency requires canonical authority and explicit translation where contexts differ.

Flow

Concepts → Conflicts → CanonicalAuthority → Normalization → Enforcement

Productions

CanonicalSemantics ::= <SemanticArtifactSet> "→" <ConflictDetection> "→" <CanonicalAuthoritySelection> "→" <NormalizationPolicy> "→" <TranslationBoundary> "→" <GovernanceGate>
SemanticArtifact ::= "schema" | "domain_model" | "field" | "term" | "rule" | "configuration"

Composes none

Composed by Composed Turn Contract

Forces semantic_consistency, model_governance

Grounds none

Before

Three models of 'Foo' drift apart; no single authority.

After

artifacts{Foo-a, Foo-b} → conflict-detection → canonical authority → normalize variants → SSOT gate

How it is checked

Checked by the ontology resolution gate, which validates every relationship record's fields, relations and references

Population Every architecture record in the catalog

Freshness A verdict stands until a record or the relation ranges change

Refusal The gate fails on a dangling edge, an out-of-range relation, an unknown severity or an empty required field

Observation None, because the catalog is data; the checks its records name observe the systems

Evidence Watched to fire and to accept: a suite plants an unchecked principle, a blank required field, a severity outside the closed levels and a definition that opens as another kind, and the bundled records pass

Authoritative side The relation ranges and the closed field vocabularies, which every record conforms to

Depends on Not answered

Shape it refuses Not answered

Self-Description and Discovery

Details

Intent Require components, services, APIs, plugins, and runtime structures to declare metadata, capabilities, contracts, dependencies, configuration, and health so they can be discovered and validated.

Invariant Dynamic architecture requires self-description before runtime binding.

Flow

Component → Manifest → CapabilityDeclaration → Discovery → ContractValidation → Binding

Productions

SelfDescribingDiscovery ::= <RuntimeEntity> "→" <Manifest> "→" <CapabilityDeclaration> "→" <DiscoveryMechanism> "→" <ConformanceValidation> "→" <BindingDecision>
Manifest ::= "identity" "," "version" "," "capabilities" "," "dependencies" "," "contracts" "," "configuration" "," "health"

Composes none

Forces contract_compatibility, runtime_extensibility

Grounds none

Before

A runtime component's capabilities are unknowable without reading its source.

After

entity → manifest{identity, capabilities, contracts} → discovery → conformance-validation → bind only if it matches

How it is checked

Checked by the ontology resolution gate, which validates every relationship record's fields, relations and references

Population Every architecture record in the catalog

Freshness A verdict stands until a record or the relation ranges change

Refusal The gate fails on a dangling edge, an out-of-range relation, an unknown severity or an empty required field

Observation None, because the catalog is data; the checks its records name observe the systems

Evidence Watched to fire and to accept: a suite plants an unchecked principle, a blank required field, a severity outside the closed levels and a definition that opens as another kind, and the bundled records pass

Authoritative side The relation ranges and the closed field vocabularies, which every record conforms to

Depends on Not answered

Shape it refuses Not answered

Runtime Extensibility

Details

Intent Detect repeated core modification for variants, define extension points, create plugin contracts, register implementations, discover them dynamically, and isolate failures.

Invariant Extensibility is controlled variation behind stable runtime contracts.

Flow

VariantPressure → ExtensionPoint → PluginContract → Registry → Discovery → Isolation

Productions

RuntimeExtensibility ::= <VariantPressure> "→" <ExtensionPointDesign> "→" <PluginContract> "→" <RegistrationPolicy> "→" <RuntimeDiscovery> "→" <FailureIsolation>
RegistrationPolicy ::= "manual_registration" | "manifest_based" | "service_registry" | "convention_based" | "configuration_based"

Composes Runtime Discovery

Forces contract_compatibility, runtime_extensibility

Principle Runtime Extensibility

Grounds none

Before

Every new variant edits the core switch statement.

After

variant-pressure → extension-point → plugin-contract → registry → runtime-discovery → failure-isolation

How it is checked

Checked by the ontology resolution gate, which validates every relationship record's fields, relations and references

Population Every architecture record in the catalog

Freshness A verdict stands until a record or the relation ranges change

Refusal The gate fails on a dangling edge, an out-of-range relation, an unknown severity or an empty required field

Observation None, because the catalog is data; the checks its records name observe the systems

Evidence Watched to fire and to accept: a suite plants an unchecked principle, a blank required field, a severity outside the closed levels and a definition that opens as another kind, and the bundled records pass

Authoritative side The relation ranges and the closed field vocabularies, which every record conforms to

Depends on Runtime Discovery

Shape it refuses Not answered

Pattern Selection

Details

Intent Select creational, structural, or behavioral patterns based on the problem force: creation variation, interface mismatch, access control, behavior variation, notification, workflow reuse, or coordination complexity.

Invariant Design patterns are remedies for specific force shapes, not generic decorations.

Flow

ProblemForce → PatternFamily → CandidatePattern → ApplicabilityCheck

Productions

PatternSelection ::= <ProblemForce> "→" <PatternFamily> "→" <CandidatePatternSet> "→" <ApplicabilityVerdict>
PatternFamily ::= "creational" | "structural" | "behavioral"
CandidatePattern ::= "factory" | "factory_method" | "abstract_factory" | "builder" | "prototype" | "adapter" | "facade" | "proxy" | "bridge" | "decorator" | "strategy" | "template_method" | "observer" | "mediator"

Composes none

Forces contract_compatibility, control_coordination

Grounds none

Before

A pattern applied as decoration ('let's add a Facade') with no force to justify it.

After

force{interface mismatch} → family{structural} → candidate{Adapter} → applicability verdict

How it is checked

Checked by the ontology resolution gate, which validates every relationship record's fields, relations and references

Population Every architecture record in the catalog

Freshness A verdict stands until a record or the relation ranges change

Refusal The gate fails on a dangling edge, an out-of-range relation, an unknown severity or an empty required field

Observation None, because the catalog is data; the checks its records name observe the systems

Evidence Watched to fire and to accept: a suite plants an unchecked principle, a blank required field, a severity outside the closed levels and a definition that opens as another kind, and the bundled records pass

Authoritative side The relation ranges and the closed field vocabularies, which every record conforms to

Depends on Not answered

Shape it refuses Not answered

Event and Messaging Consistency

Details

Intent For asynchronous systems, validate event contracts, message schemas, idempotent consumers, outbox publication, correlation metadata, ordering guarantees, retry behavior, and dead-letter handling.

Invariant Event-driven architecture is safe only when messages are contracts and consumers are replay-safe.

Flow

StateChange → EventContract → Outbox → Broker → IdempotentConsumer → Trace

Productions

EventMessagingConsistency ::= <StateChange> "→" <EventClassification> "→" <MessageContract> "→" <PublicationReliability> "→" <ConsumerIdempotency> "→" <OrderingPolicy> "→" <ObservabilityTrace>
EventClassification ::= "domain_event" | "integration_event" | "stream_event"
PublicationReliability ::= "transactional_outbox" | "append_only_log" | "broker_acknowledgement"

Composes Observability Trace

Forces contract_compatibility, state_transaction, correctness_verification, resilience_recovery, observability_traceability, event_messaging, causality_ordering

Grounds none

Distinct from Event Messaging: Event messaging describes how state changes are published and consumed; this record validates that the published messages are contracts and that consumers are safe to replay.

Before

Events published ad hoc; a consumer replays and double-applies.

After

state-change → event-contract → transactional-outbox → broker → idempotent-consumer → ordering + trace

How it is checked

Checked by the ontology resolution gate, which validates every relationship record's fields, relations and references

Population Every architecture record in the catalog

Freshness A verdict stands until a record or the relation ranges change

Refusal The gate fails on a dangling edge, an out-of-range relation, an unknown severity or an empty required field

Observation None, because the catalog is data; the checks its records name observe the systems

Evidence Watched to fire and to accept: a suite plants an unchecked principle, a blank required field, a severity outside the closed levels and a definition that opens as another kind, and the bundled records pass

Authoritative side The relation ranges and the closed field vocabularies, which every record conforms to

Depends on Observability Trace

Shape it refuses Not answered

State and Transaction Safety

Details

Intent Identify state mutation boundaries, enforce unit-of-work scope, validate invariants, apply concurrency control, guarantee idempotency where retries exist, and isolate side effects.

Invariant State correctness depends on explicit mutation boundaries and repeat-safe effects.

Flow

Command → TransactionBoundary → Invariant → Concurrency → Commit|Rollback → Idempotency

Productions

StateTransactionSafety ::= <Command> "→" <TransactionBoundary> "→" <InvariantCheck> "→" <ConcurrencyControl> "→" <CommitDecision> "→" <SideEffectPolicy>
ConcurrencyControl ::= "optimistic_locking" | "pessimistic_locking" | "serial_execution" | "state_isolation"
SideEffectPolicy ::= "idempotent" | "outbox_published" | "compensatable" | "controlled_side_effect"

Composes Transaction Boundary

Forces modularity, contract_compatibility, state_transaction, correctness_verification, resilience_recovery

Grounds none

Before

Two mutations with no boundary; a crash between them corrupts state.

After

command → transaction-boundary → invariant-check → concurrency-control → commit/rollback → idempotent side-effect

How it is checked

Checked by the ontology resolution gate, which validates every relationship record's fields, relations and references

Population Every architecture record in the catalog

Freshness A verdict stands until a record or the relation ranges change

Refusal The gate fails on a dangling edge, an out-of-range relation, an unknown severity or an empty required field

Observation None, because the catalog is data; the checks its records name observe the systems

Evidence Watched to fire and to accept: a suite plants an unchecked principle, a blank required field, a severity outside the closed levels and a definition that opens as another kind, and the bundled records pass

Authoritative side The relation ranges and the closed field vocabularies, which every record conforms to

Depends on Transaction Boundary

Shape it refuses Not answered

Correctness Verification

Details

Intent Push nondeterminism to boundaries, prefer pure deterministic core logic, validate specifications with static analysis, type checks, property tests, contract tests, formal methods where useful, and reproducible test environments.

Invariant Correctness is achieved by deterministic design plus evidence-based verification.

Flow

Input → Canonicalize → DeterministicCore → Spec → Verification → Evidence

Productions

CorrectnessVerification ::= <InputSet> "→" <Canonicalization> "→" <DeterministicCore> "→" <SpecificationSet> "→" <VerificationMethodSet> "→" <CorrectnessEvidence>
VerificationMethod ::= "type_check" | "static_analysis" | "schema_validation" | "contract_test" | "property_based_test" | "specification_test" | "formal_verification" | "runtime_validation"

Composes Deterministic Core

Forces modularity, contract_compatibility, runtime_extensibility, correctness_verification

Grounds none

Before

Correctness asserted by 'it worked on my machine'.

After

input → canonicalize → deterministic-core → spec → {type-check, property-test, contract-test} → evidence

How it is checked

Checked by the ontology resolution gate, which validates every relationship record's fields, relations and references

Population Every architecture record in the catalog

Freshness A verdict stands until a record or the relation ranges change

Refusal The gate fails on a dangling edge, an out-of-range relation, an unknown severity or an empty required field

Observation None, because the catalog is data; the checks its records name observe the systems

Evidence Watched to fire and to accept: a suite plants an unchecked principle, a blank required field, a severity outside the closed levels and a definition that opens as another kind, and the bundled records pass

Authoritative side The relation ranges and the closed field vocabularies, which every record conforms to

Depends on Deterministic Core

Shape it refuses Not answered

Resilience Policy

Details

Intent Classify failure modes, apply fail-fast, fail-safe, fail-secure, retry, timeout, circuit breaker, fallback, bulkhead, backpressure, health check, failover, and rollback policies according to dependency criticality.

Invariant Resilience is controlled degradation under known failure modes.

Flow

FailureMode → Criticality → PolicySet → RuntimeGuard → Recovery

Productions

ResiliencePolicy ::= <FailureModeSet> "→" <CriticalityClassification> "→" <ResiliencePatternSet> "→" <RuntimeGuardSet> "→" <RecoveryActionSet>
ResiliencePattern ::= "timeout" | "retry" | "circuit_breaker" | "fallback" | "bulkhead" | "backpressure" | "health_check" | "failover" | "rollback" | "auto_remediation"

Composes none

Forces state_transaction, resilience_recovery

Grounds none

Before

A remote call with no failure policy takes the whole system down.

After

failure-modes → criticality → {timeout, retry, circuit-breaker, bulkhead} → runtime-guard → recovery

How it is checked

Checked by the ontology resolution gate, which validates every relationship record's fields, relations and references

Population Every architecture record in the catalog

Freshness A verdict stands until a record or the relation ranges change

Refusal The gate fails on a dangling edge, an out-of-range relation, an unknown severity or an empty required field

Observation None, because the catalog is data; the checks its records name observe the systems

Evidence Watched to fire and to accept: a suite plants an unchecked principle, a blank required field, a severity outside the closed levels and a definition that opens as another kind, and the bundled records pass

Authoritative side The relation ranges and the closed field vocabularies, which every record conforms to

Depends on Not answered

Shape it refuses Not answered

Observability and Auditability

Details

Intent Attach correlation and causation identifiers, emit logs, metrics, traces, alerts, audit records, and runtime health signals, then reconstruct behavior as a causal execution graph.

Invariant Operability requires reconstructable evidence across runtime boundaries.

Flow

Operation → Correlation → Telemetry → Audit → TraceGraph → Diagnosis

Productions

ObservabilityAuditability ::= <Operation> "→" <CorrelationId> "→" <CausationId> "→" <TelemetryEventSet> "→" <AuditRecordSet> "→" <TraceGraph>
TelemetryEvent ::= "structured_log" | "metric" | "trace_span" | "alert" | "audit_log" | "health_signal"

Composes none

Forces modularity, observability_traceability, causality_ordering

Grounds none

Before

An incident with no correlation ids — behavior can't be reconstructed.

After

operation → correlation-id + causation-id → {logs, metrics, traces, audit} → trace-graph → diagnosis

How it is checked

Checked by the ontology resolution gate, which validates every relationship record's fields, relations and references

Population Every architecture record in the catalog

Freshness A verdict stands until a record or the relation ranges change

Refusal The gate fails on a dangling edge, an out-of-range relation, an unknown severity or an empty required field

Observation None, because the catalog is data; the checks its records name observe the systems

Evidence Watched to fire and to accept: a suite plants an unchecked principle, a blank required field, a severity outside the closed levels and a definition that opens as another kind, and the bundled records pass

Authoritative side The relation ranges and the closed field vocabularies, which every record conforms to

Depends on Not answered

Shape it refuses Not answered

Performance and Scalability

Details

Intent Establish workload model, profile runtime behavior, benchmark repeatably, identify bottlenecks, analyze time and space complexity, select scaling strategy, optimize only measured bottlenecks, and enforce SLO gates.

Invariant Performance engineering is evidence-driven bottleneck control, not speculative optimization.

Flow

Workload → Profile → Benchmark → Bottleneck → Complexity → Scale|Optimize → SLO

Productions

PerformanceScalability ::= <WorkloadModel> "→" <ProfilingEvidence> "→" <BenchmarkResultSet> "→" <BottleneckAnalysis> "→" <ComplexityAnalysis> "→" <ScalingOrOptimizationPlan> "→" <PerformanceGate>
ScalingOrOptimizationPlan ::= "vertical_scale" | "horizontal_scale" | "load_balance" | "shard" | "partition" | "cache" | "stream" | "rate_limit" | "algorithm_replacement"

Composes none

Forces performance_scaling, model_governance

Grounds none

Before

Optimize by guesswork; add capacity and hope.

After

workload → profile → benchmark → bottleneck → complexity → scale/optimize the measured bottleneck → SLO gate

How it is checked

Checked by the ontology resolution gate, which validates every relationship record's fields, relations and references

Population Every architecture record in the catalog

Freshness A verdict stands until a record or the relation ranges change

Refusal The gate fails on a dangling edge, an out-of-range relation, an unknown severity or an empty required field

Observation None, because the catalog is data; the checks its records name observe the systems

Evidence Watched to fire and to accept: a suite plants an unchecked principle, a blank required field, a severity outside the closed levels and a definition that opens as another kind, and the bundled records pass

Authoritative side The relation ranges and the closed field vocabularies, which every record conforms to

Depends on Not answered

Shape it refuses Not answered

Security Governance

Details

Intent Threat-model the system, reduce attack surface, authenticate identity, authorize actions, validate input, encode output, encrypt data, manage secrets, enforce policy as code, and continuously audit compliance.

Invariant Security is an enforced policy graph over identity, data, operations, and infrastructure.

Flow

ThreatModel → ControlSet → Policy → Enforcement → Audit

Productions

SecurityGovernance ::= <ThreatModel> "→" <SecurityControlSet> "→" <PolicySet> "→" <PolicyEnforcement> "→" <ContinuousCompliance> "→" <RiskReview>
SecurityControl ::= "authentication" | "authorization" | "least_privilege" | "zero_trust" | "input_validation" | "output_encoding" | "encryption_at_rest" | "encryption_in_transit" | "secrets_management" | "audit_logging"

Composes none

Forces correctness_verification, security_governance, model_governance

Grounds none

Before

Security added as a late checklist, not a policy graph.

After

threat-model → controls{authn, authz, validation, encryption, secrets} → policy-as-code → enforcement → continuous audit

How it is checked

Checked by the ontology resolution gate, which validates every relationship record's fields, relations and references

Population Every architecture record in the catalog

Freshness A verdict stands until a record or the relation ranges change

Refusal The gate fails on a dangling edge, an out-of-range relation, an unknown severity or an empty required field

Observation None, because the catalog is data; the checks its records name observe the systems

Evidence Watched to fire and to accept: a suite plants an unchecked principle, a blank required field, a severity outside the closed levels and a definition that opens as another kind, and the bundled records pass

Authoritative side The relation ranges and the closed field vocabularies, which every record conforms to

Depends on Not answered

Shape it refuses Not answered

Architecture Evolution Governance

Details

Intent Assess architecture against quality attributes, record decisions, analyze impact, track gaps, enforce standards with fitness functions, standardize patterns, and evolve through ADR-backed controlled change.

Invariant Evolutionary architecture requires decision memory and continuous fitness validation.

Flow

Assessment → GapAnalysis → DecisionRecord → FitnessFunction → ChangePlan → Review

Productions

ArchitectureEvolutionGovernance ::= <Assessment> "→" <GapAnalysis> "→" <ImpactAnalysis> "→" <DecisionRecord> "→" <FitnessFunctionSet> "→" <EvolutionPlan> "→" <ReviewGate>
DecisionRecord ::= "ADR" "," "context" "," "decision" "," "consequences" "," "status"

Composes Architecture Assessment

Composed by Architectural Relationship Algebra, Version Provenance, Type-Migration Centralization

Forces correctness_verification, security_governance, architecture_evolution

Grounds none

Before

Architecture drifts; no decision memory, no fitness checks.

After

assessment → gap-analysis → ADR → fitness-functions → change-plan → review gate

How it is checked

Checked by the ontology resolution gate, which validates every relationship record's fields, relations and references

Population Every architecture record in the catalog

Freshness A verdict stands until a record or the relation ranges change

Refusal The gate fails on a dangling edge, an out-of-range relation, an unknown severity or an empty required field

Observation None, because the catalog is data; the checks its records name observe the systems

Evidence Watched to fire and to accept: a suite plants an unchecked principle, a blank required field, a severity outside the closed levels and a definition that opens as another kind, and the bundled records pass

Authoritative side The relation ranges and the closed field vocabularies, which every record conforms to

Depends on Architecture Assessment

Shape it refuses Not answered

Control Plane Coordination

Details

Intent Separate control-plane policy from data-plane execution, centralize configuration, authentication, logging, or orchestration only where shared governance is beneficial, and preserve local autonomy where decentralization is required.

Invariant Control centralization should govern policy without collapsing execution autonomy.

Flow

Policy → ControlPlane → DataPlane → Telemetry → PolicyAdjustment

Productions

ControlPlaneCoordination ::= <PolicySet> "→" <ControlPlane> "→" <DataPlaneSet> "→" <TelemetryFeedback> "→" <GovernanceAdjustment>
ControlConcern ::= "configuration" | "authentication" | "authorization" | "logging" | "orchestration" | "service_registry"

Composes Control Plane

Forces semantic_consistency, security_governance, control_coordination

Grounds none

Distinct from Control Plane: The control plane is the mechanism that coordinates policy; this record composes it and decides which concerns are centralized and which stay local.

Before

Every service does its own config + auth; policy scatters and drifts.

After

policy → control-plane{config, authn, orchestration} → data-planes execute → telemetry → governance adjustment

How it is checked

Checked by the ontology resolution gate, which validates every relationship record's fields, relations and references

Population Every architecture record in the catalog

Freshness A verdict stands until a record or the relation ranges change

Refusal The gate fails on a dangling edge, an out-of-range relation, an unknown severity or an empty required field

Observation None, because the catalog is data; the checks its records name observe the systems

Evidence Watched to fire and to accept: a suite plants an unchecked principle, a blank required field, a severity outside the closed levels and a definition that opens as another kind, and the bundled records pass

Authoritative side The relation ranges and the closed field vocabularies, which every record conforms to

Depends on Control Plane

Shape it refuses Not answered

Metaprogramming Safety

Details

Intent Treat code as data only through schemas, manifests, DSL grammars, reflection contracts, compile-time checks, runtime guards, and generated artifact validation.

Invariant Metaprogramming is safe when generated behavior is bounded by a validated model.

Flow

Model → Schema → Transform → Generate|Interpret → Validate → Execute

Productions

MetaprogrammingSafety ::= <ProgramModel> "→" <ModelSchema> "→" <TransformationEngine> "→" <GeneratedOrInterpretedArtifact> "→" <SafetyValidation> "→" <ExecutionBoundary>
TransformationEngine ::= "reflection" | "introspection" | "compile_time_evaluation" | "runtime_code_generation" | "DSL_interpreter" | "model_driven_generator"

Composes none

Forces contract_compatibility, correctness_verification, model_governance, metaprogramming_modeling

Grounds none

Before

Code-as-string eval'd with no schema or bound.

After

model → schema → transform{reflection | DSL} → generated artifact → safety-validation → bounded execution

How it is checked

Checked by the ontology resolution gate, which validates every relationship record's fields, relations and references

Population Every architecture record in the catalog

Freshness A verdict stands until a record or the relation ranges change

Refusal The gate fails on a dangling edge, an out-of-range relation, an unknown severity or an empty required field

Observation None, because the catalog is data; the checks its records name observe the systems

Evidence Watched to fire and to accept: a suite plants an unchecked principle, a blank required field, a severity outside the closed levels and a definition that opens as another kind, and the bundled records pass

Authoritative side The relation ranges and the closed field vocabularies, which every record conforms to

Depends on Not answered

Shape it refuses Not answered

Model Lifecycle Governance

Details

Intent Register and version models, prompts, datasets, embeddings, retrieval sources and knowledge graphs, evaluate behavior against benchmarks, validate safety constraints, trace inference inputs through an inference contract, and monitor drift after deployment.

Invariant Model-backed architecture requires governance over evidence, model behavior, inference, evaluation, and safety.

Flow

ModelArtifact → Registry → Evaluation → Safety → InferenceTrace → Monitoring

Productions

ModelLifecycleGovernance ::= <ModelArtifactSet> "→" <GovernanceRegistry> "→" <EvaluationSuite> "→" <InferenceContract> "→" <ExplainabilityTrace> "→" <SafetyPolicy> "→" <RuntimeMonitoring>
ModelArtifact ::= "model" | "prompt" | "embedding_index" | "retrieval_source" | "knowledge_graph" | "dataset" | "evaluation"
InferenceContract ::= "input_schema" "," "retrieval_context" "," "model_version" "," "output_schema" "," "explanation_or_trace"

Composes none

Forces contract_compatibility, correctness_verification, observability_traceability, security_governance, model_governance

Grounds none

Before

A model shipped with no registry, eval, trace, or safety gate.

After

artifacts{model, prompt, index} → governance-registry → evaluation → inference-contract → explainability-trace → safety + monitoring

How it is checked

Checked by the ontology resolution gate, which validates every relationship record's fields, relations and references

Population Every architecture record in the catalog

Freshness A verdict stands until a record or the relation ranges change

Refusal The gate fails on a dangling edge, an out-of-range relation, an unknown severity or an empty required field

Observation None, because the catalog is data; the checks its records name observe the systems

Evidence Watched to fire and to accept: a suite plants an unchecked principle, a blank required field, a severity outside the closed levels and a definition that opens as another kind, and the bundled records pass

Authoritative side The relation ranges and the closed field vocabularies, which every record conforms to

Depends on Not answered

Shape it refuses Not answered

Architectural Recommendation

Details

Intent Given a target problem, query the graph for matching violated_by and detected_by signals, collect candidate concepts, compute required dependencies, remove conflicting concepts, rank by severity and reinforcement gain, then recommend an ordered implementation path.

Invariant Recommendations are graph-derived paths from evidence to enforceable architecture change.

Flow

ProblemEvidence → CandidateConcepts → DependencyClosure → ConflictPrune → Rank → Roadmap

Productions

ArchitecturalRecommendation ::= <ProblemEvidenceSet> "→" <ConceptMatchSet> "→" <DependencyClosure> "→" <ConflictTensionResolution> "→" <SeverityRanking> "→" <ImplementationRoadmap>
SeverityRanking ::= "mandatory_before_recommended" "," "contextual_when_scope_matches" "," "discouraged_requires_exception"

Composes Dependency Closure

Forces architecture_evolution

Grounds none

Before

Advice given from intuition, not from the graph or the evidence.

After

problem-evidence → concept-match → dependency-closure → conflict-prune → severity rank → ordered roadmap

How it is checked

Checked by the ontology resolution gate, which validates every relationship record's fields, relations and references

Population Every architecture record in the catalog

Freshness A verdict stands until a record or the relation ranges change

Refusal The gate fails on a dangling edge, an out-of-range relation, an unknown severity or an empty required field

Observation None, because the catalog is data; the checks its records name observe the systems

Evidence Watched to fire and to accept: a suite plants an unchecked principle, a blank required field, a severity outside the closed levels and a definition that opens as another kind, and the bundled records pass

Authoritative side The relation ranges and the closed field vocabularies, which every record conforms to

Depends on Dependency Closure

Shape it refuses Not answered

Architecture Fitness Function Generation

Details

Intent Convert mandatory and high-impact recommended records into executable fitness functions by binding detected_by signals to checks, measured_by fields to thresholds, and enforced_by fields to pipeline gates.

Invariant The catalog becomes self-enforcing when records compile into fitness functions.

Flow

RelationshipRecord → DetectionCheck → MetricThreshold → EnforcementGate → FitnessFunction

Productions

FitnessFunctionGeneration ::= <ArchitecturalRelationshipRecord> "→" <DetectionCheck> "→" <MetricThreshold> "→" <EnforcementGate> "→" <FitnessFunction>
FitnessFunction ::= <Name> "," <Scope> "," <CheckProcedure> "," <Threshold> "," <SeverityPolicy> "," <FailureMessage> "," <RefactorHintSet>

Composes Architectural Relationship Record, Enforcement Gate, Severity Policy

Forces streaming_dataflow, architecture_evolution

Grounds none

Before

Mandatory records sit as prose no check executes.

After

record → detection-check + metric-threshold + enforcement-gate → executable fitness function

How it is checked

Checked by the ontology resolution gate, which validates every relationship record's fields, relations and references

Population Every architecture record in the catalog

Freshness A verdict stands until a record or the relation ranges change

Refusal The gate fails on a dangling edge, an out-of-range relation, an unknown severity or an empty required field

Observation None, because the catalog is data; the checks its records name observe the systems

Evidence Watched to fire and to accept: a suite plants an unchecked principle, a blank required field, a severity outside the closed levels and a definition that opens as another kind, and the bundled records pass

Authoritative side The relation ranges and the closed field vocabularies, which every record conforms to

Depends on Architectural Relationship Record, Enforcement Gate, Severity Policy

Shape it refuses Not answered

Architecture Refactoring Roadmap

Details

Intent Group violations by shared refactor actions, order remediation by prerequisite concepts, apply low-risk structural fixes first, then enforce newly satisfied concepts through gates.

Invariant Architecture repair is more efficient when refactors are grouped by shared conceptual cause.

Flow

Violations → SharedCause → RefactorGroup → DependencyOrder → Apply → Enforce

Productions

RefactoringRoadmap ::= <ViolationRecordSet> "→" <SharedCauseClustering> "→" <RefactorGroupSet> "→" <DependencyOrderedPlan> "→" <ExecutionGateSet>
SharedCause ::= "missing_boundary" | "missing_contract" | "semantic_drift" | "concrete_coupling" | "uncontrolled_state" | "missing_observability" | "manual_governance_only"

Composes none

Forces correctness_verification

Grounds none

Before

Violations fixed one-by-one in random order; shared causes re-fixed repeatedly.

After

violations → cluster by shared-cause{missing-boundary} → refactor-groups → dependency-ordered plan → enforce

How it is checked

Checked by the ontology resolution gate, which validates every relationship record's fields, relations and references

Population Every architecture record in the catalog

Freshness A verdict stands until a record or the relation ranges change

Refusal The gate fails on a dangling edge, an out-of-range relation, an unknown severity or an empty required field

Observation None, because the catalog is data; the checks its records name observe the systems

Evidence Watched to fire and to accept: a suite plants an unchecked principle, a blank required field, a severity outside the closed levels and a definition that opens as another kind, and the bundled records pass

Authoritative side The relation ranges and the closed field vocabularies, which every record conforms to

Depends on Not answered

Shape it refuses Not answered

Concept Cluster Extraction

Details

Intent Group concepts into clusters by mutual requires, reinforces, enables, and shared scope; treat clusters as higher-order architectural concerns.

Invariant Large principle catalogs become usable when concepts are clustered by relationship density.

Flow

Graph → EdgeDensity → Cluster → ConcernFamily

Productions

ConceptClusterExtraction ::= <ArchitectureGraph> "→" <RelationshipDensityAnalysis> "→" <ClusterSet> "→" <ConcernFamilySet>
ConcernFamily ::= <ClusterName> "," <CoreConceptSet> "," <SupportingConceptSet> "," <ConflictConceptSet> "," <EnforcementPolicySet>

Composes none

Composed by Master Architecture Governance Kernel

Forces architecture_evolution

Grounds none

Before

A flat catalog of hundreds of concepts, unusable at scale.

After

graph → relationship-density analysis → clusters → concern-families{core + supporting + conflict concepts}

How it is checked

Checked by the ontology resolution gate, which validates every relationship record's fields, relations and references

Population Every architecture record in the catalog

Freshness A verdict stands until a record or the relation ranges change

Refusal The gate fails on a dangling edge, an out-of-range relation, an unknown severity or an empty required field

Observation None, because the catalog is data; the checks its records name observe the systems

Evidence Watched to fire and to accept: a suite plants an unchecked principle, a blank required field, a severity outside the closed levels and a definition that opens as another kind, and the bundled records pass

Authoritative side The relation ranges and the closed field vocabularies, which every record conforms to

Depends on Not answered

Shape it refuses Not answered

Architecture Decision Support

Details

Intent For each proposed design decision, compute satisfied concepts, violated concepts, tensions introduced, conflicts triggered, enabled capabilities, and enforcement cost; require ADR when trade-offs are nontrivial.

Invariant A design decision should be evaluated as a graph delta.

Flow

Decision → GraphDelta → BenefitSet + RiskSet → ADRRequired?

Productions

ArchitectureDecisionSupport ::= <ProposedDecision> "→" <SatisfiedConceptSet> "→" <ViolatedConceptSet> "→" <TensionSet> "→" <EnabledCapabilitySet> "→" <EnforcementCost> "→" <DecisionGovernance>
DecisionGovernance ::= "approve" | "approve_with_ADR" | "revise" | "reject"

Composes none

Composed by Master Architecture Governance Kernel

Forces architecture_evolution

Grounds none

Before

A design decision judged by gut feel, not by its effect on the graph.

After

decision → graph-delta{satisfied, violated, tensions, enabled} → enforcement-cost → approve / approve-with-ADR / revise / reject

How it is checked

Checked by the ontology resolution gate, which validates every relationship record's fields, relations and references

Population Every architecture record in the catalog

Freshness A verdict stands until a record or the relation ranges change

Refusal The gate fails on a dangling edge, an out-of-range relation, an unknown severity or an empty required field

Observation None, because the catalog is data; the checks its records name observe the systems

Evidence Watched to fire and to accept: a suite plants an unchecked principle, a blank required field, a severity outside the closed levels and a definition that opens as another kind, and the bundled records pass

Authoritative side The relation ranges and the closed field vocabularies, which every record conforms to

Depends on Not answered

Shape it refuses Not answered

Relationship Schema Validation

Details

Intent Validate every concept record for required fields, known relation names, parseable scope, valid severity, nonempty detection and enforcement metadata, and resolvable references where possible.

Invariant The architectural catalog itself must be governed as a schema-bearing artifact.

Flow

Record → SchemaCheck → ReferenceCheck → CompletenessCheck → Valid|Invalid

Productions

RelationshipSchemaValidation ::= <ArchitecturalRelationshipRecordSet> "→" <RequiredFieldValidation> "→" <ReferenceResolution> "→" <SeverityValidation> "→" <CompletenessScore> "→" <CatalogValidity>
RequiredFieldSet ::= "type" "," "scope" "," "requires" "," "reinforces" "," "enables" "," "conflicts_with" "," "tensions_with" "," "violated_by" "," "detected_by" "," "measured_by" "," "refactored_by" "," "enforced_by" "," "severity"

Composes none

Composed by Master Architecture Governance Kernel

Forces correctness_verification

Grounds none

Before

Catalog records with missing fields and dangling references ship unchecked.

After

records → required-field validation → reference-resolution → severity validation → completeness score → catalog validity

How it is checked

Checked by the ontology resolution gate, which validates every relationship record's fields, relations and references

Population Every architecture record in the catalog

Freshness A verdict stands until a record or the relation ranges change

Refusal The gate fails on a dangling edge, an out-of-range relation, an unknown severity or an empty required field

Observation None, because the catalog is data; the checks its records name observe the systems

Evidence Watched to fire and to accept: a suite plants an unchecked principle, a blank required field, a severity outside the closed levels and a definition that opens as another kind, and the bundled records pass

Authoritative side The relation ranges and the closed field vocabularies, which every record conforms to

Depends on Not answered

Shape it refuses Not answered

Architecture Catalog Compiler

Details

Intent Compile the relationship catalog into four executable artifacts: assessment rules, refactor playbooks, decision-support graphs, and governance gates.

Invariant A comprehensive architecture catalog should compile into operational tooling.

Flow

Catalog → Rules + Playbooks + DecisionGraph + Gates

Productions

ArchitectureCatalogCompiler ::= <ArchitectureGraph> "→" <AssessmentRuleSet> "→" <RefactorPlaybookSet> "→" <DecisionSupportModel> "→" <GovernanceGateSet>
AssessmentRule ::= <Concept> "," <DetectedBy> "," <MeasuredBy> "," <EnforcementSeverity>
RefactorPlaybook ::= <ViolationPattern> "," <RefactoredBy> "," <EnforcedBy>

Composes none

Forces security_governance

Grounds none

Before

The catalog read only by the developer — no operational output.

After

graph → {assessment-rules, refactor-playbooks, decision-support-model, governance-gates}

How it is checked

Checked by the ontology resolution gate, which validates every relationship record's fields, relations and references

Population Every architecture record in the catalog

Freshness A verdict stands until a record or the relation ranges change

Refusal The gate fails on a dangling edge, an out-of-range relation, an unknown severity or an empty required field

Observation None, because the catalog is data; the checks its records name observe the systems

Evidence Watched to fire and to accept: a suite plants an unchecked principle, a blank required field, a severity outside the closed levels and a definition that opens as another kind, and the bundled records pass

Authoritative side The relation ranges and the closed field vocabularies, which every record conforms to

Depends on Not answered

Shape it refuses Not answered

Master Architecture Governance Kernel

Details

Intent Parse the catalog, validate records, build the graph, classify target scope, select relevant concept clusters, compute dependency closure, detect violations, measure evidence, resolve conflicts, generate refactor plans, enforce gates, and record decisions.

Invariant The catalog can be executed as a governance kernel for architecture assessment, remediation, and evolution.

Flow

Catalog → Graph → Scope → Concepts → Detection → Metrics → Refactor → Enforcement → ADR

Productions

MasterArchitectureGovernanceKernel ::= <RelationshipSchemaValidation> "→" <ArchitectureGraph> "→" <TargetScopeClassification> "→" <ConceptClusterExtraction> "→" <DependencyClosure> "→" <ViolationDetection> "→" <MeasurementNormalization> "→" <ConflictTensionResolution> "→" <RefactorSelection> "→" <EnforcementGate> "→" <ArchitectureDecisionSupport> "→" <GovernanceReport>
GovernanceReport ::= <SatisfiedConceptSet> "," <ViolationRecordSet> "," <MetricEvidenceSet> "," <ConflictTensionSet> "," <RefactorRoadmap> "," <EnforcementGateSet> "," <ADRRecommendationSet> "," <ResidualRiskSet>

Composes Relationship Schema Validation, Concept Cluster Extraction, Dependency Closure, Violation Detection, Measurement Normalization, Refactor Selection, Enforcement Gate, Architecture Decision Support

Forces correctness_verification, security_governance, architecture_evolution

Grounds none

Before

Assessment, remediation, and evolution done by disconnected manual steps.

After

validate → graph → scope → clusters → closure → detect → measure → resolve → refactor → enforce → ADR → governance report

How it is checked

Checked by the ontology resolution gate, which validates every relationship record's fields, relations and references

Population Every architecture record in the catalog

Freshness A verdict stands until a record or the relation ranges change

Refusal The gate fails on a dangling edge, an out-of-range relation, an unknown severity or an empty required field

Observation None, because the catalog is data; the checks its records name observe the systems

Evidence Watched to fire and to accept: a suite plants an unchecked principle, a blank required field, a severity outside the closed levels and a definition that opens as another kind, and the bundled records pass

Authoritative side The relation ranges and the closed field vocabularies, which every record conforms to

Depends on Relationship Schema Validation, Concept Cluster Extraction, Dependency Closure, Violation Detection, Measurement Normalization, Refactor Selection, Enforcement Gate, Architecture Decision Support

Shape it refuses Not answered

Architectural Relationship Algebra

Details

Intent → → → → → → → → →

Invariant Every architectural principle, pattern, mechanism, metric, and quality attribute can be treated as a relationship contract whose operational lifecycle is detection, measurement, remediation, enforcement, and evolution.

Flow

Record → Graph → Force → Concept → Evidence → Refactor → Gate → Governance

Productions

ArchitecturalRelationshipAlgebra ::= <ArchitecturalRelationshipRecordSet> "→" <ArchitectureGraph> "→" <ForceClassification> "→" <ApplicableConceptSet> "→" <DependencyClosure> "→" <ViolationDetection> "→" <MeasurementNormalization> "→" <RefactorSelection> "→" <EnforcementGate> "→" <ArchitectureEvolutionGovernance>
ArchitecturalRelationshipRecord ::= <ConceptName> ":" <RecordType> "," <ScopeSet> "," <RequiresSet> "," <ReinforcesSet> "," <EnablesSet> "," <ConflictSet> "," <TensionSet> "," <ViolationSet> "," <DetectionSet> "," <MetricSet> "," <RefactorSet> "," <EnforcementSet> "," <EnforcementSeverity>
OperationalLifecycle ::= "define" | "select" | "detect" | "measure" | "refactor" | "enforce" | "observe" | "evolve"
CompletionCondition ::= "all_mandatory_concepts_satisfied" "," "contextual_concepts_justified" "," "recommended_concepts_reported" "," "discouraged_concepts_exception_reviewed" "," "residual_risk_recorded"

Composes Dependency Closure, Violation Detection, Measurement Normalization, Refactor Selection, Enforcement Gate, Architecture Evolution Governance

Forces contract_compatibility, correctness_verification, architecture_evolution

Principle Architectural Consistency

Grounds none

Distinct from Architectural Contract Algebra: The contract algebra designs a system by reducing each force to a contract; the relationship algebra processes the concept records themselves as a graph to detect, measure, refactor and enforce.

How it is checked

Checked by the ontology resolution gate, which validates every relationship record's fields, relations and references

Population Every architecture record in the catalog

Freshness A verdict stands until a record or the relation ranges change

Refusal The gate fails on a dangling edge, an out-of-range relation, an unknown severity or an empty required field

Observation None, because the catalog is data; the checks its records name observe the systems

Evidence Watched to fire and to accept: a suite plants an unchecked principle, a blank required field, a severity outside the closed levels and a definition that opens as another kind, and the bundled records pass

Authoritative side The relation ranges and the closed field vocabularies, which every record conforms to

Depends on Dependency Closure, Violation Detection, Measurement Normalization, Refactor Selection, Enforcement Gate, Architecture Evolution Governance

Shape it refuses Not answered

Architectural Clusters

Every algorithm contract in this domain is listed with its position on the derivation loop, its intent and invariant, the flow it walks and its productions as a grammar. Each record also shows what it composes and is composed by, which forces and principles it answers to, what grounds it and what it grounds, and an exemplar where the record carries one. The diagram shows what composes what inside the domain.

Relations diagram

What composes what inside this domain.

flowchart LR
    n_structural_core["Structural Core"]
    n_correctness_core["Correctness Core"]
    n_evolution_principles["Evolution Principles"]
    n_resource_core["Resource Core"]
    n_execution_core["Execution Core"]
    n_computation_core["Computation Core"]
    n_security_core["Security Core"]
    n_performance_core["Performance Core"]
    n_contracts_core["Contracts Core"]
    n_causality_core["Causality Core"]
    n_declarative_core["Declarative Core"]
    n_extensibility_core["Extensibility Core"]
    n_observability["Observability"]
    n_enforcement_core["Enforcement Core"]
    n_atomic_boundary["Atomic Boundary"]
    n_human_factors["Human Factors"]
    n_domain_modeling["Domain Modeling"]
    n_design_patterns_core["Design Patterns Core"]
    n_state_pattern["State Pattern"]
    n_separation_of_concerns["Separation of Concerns"]
    n_concurrency_correctness["Concurrency Correctness"]
    n_capacity_planning["Capacity Planning"]
Loading

Structural Core

Details

Intent The architectural rules that preserve structural integrity — a single authoritative source, no shortcuts, no fallbacks, no duplication, no orphaned artifacts.

Invariant Structure stays sound only when every element has one authoritative home and no debt-incurring escape hatch exists.

Flow

SingleSource → NoShortcut → NoFallback → NoOrphan

Composes none

Composed by Finite State Machine, Constraints Over Shortcuts, Forward Compatibility Over Backward Compatibility, Fail-Fast Over Fallback, Explicit Removal Over Deprecation, Greenfield Over Legacy, Single-Path Determinism Over Dual-Path, Compression Over Repetition, Semantic Addressing Over Location Addressing, Homoiconicity Over Separation, Bounded Complexity Over Unlimited, Rule As Code Over Convention, Injected Dependency Over Hidden, Convention Discovery Over Hardcoded Wiring

Forces none

Principle Single Source of Truth

Grounds none

How it is checked

Checked by the layer and tension join, which places every principle in a cluster and resolves every tension between clusters

Population Every architecture and lexicon record the membership map places in the cluster

Freshness A verdict stands until the membership map, the topology or a member record changes

Refusal The gate fails on a tension with no resolution, or an override that matches no live edge

Observation None, because a cluster is a grouping of principles

Evidence Watched to fire and to accept: a suite plants a tension between two principles no layer places, and the bundled tensions resolve with no dead override

Authoritative side The membership map and the topology, which a tension's resolution is derived from

Depends on Not answered

Shape it refuses Not answered

Correctness Core

Details

Intent The rules ensuring behavioral correctness and validity — no silent failures, no hidden invalidity, feedback acted on, results observed.

Invariant Correctness holds only when every failure is surfaced and every invalid state is unrepresentable.

Flow

SurfaceFailure → RejectInvalid → ActOnFeedback

Composes none

Composed by Petri Nets, Enforced Feedback Over Ignored, Errors As Language Over Silent Errors, Explicit Invalidity Over Hidden, Computed Health Over Metric Health, Boundary Validation Over Unvalidated Input, Design By Contract Over Implicit Contract, Schema-Validated Boundary Over Untyped, Injected Nondeterminism Over Hidden

Forces none

Principle Fail Fast

Grounds none

How it is checked

Checked by the layer and tension join, which places every principle in a cluster and resolves every tension between clusters

Population Every architecture and lexicon record the membership map places in the cluster

Freshness A verdict stands until the membership map, the topology or a member record changes

Refusal The gate fails on a tension with no resolution, or an override that matches no live edge

Observation None, because a cluster is a grouping of principles

Evidence Watched to fire and to accept: a suite plants a tension between two principles no layer places, and the bundled tensions resolve with no dead override

Authoritative side The membership map and the topology, which a tension's resolution is derived from

Depends on Not answered

Shape it refuses Not answered

Evolution Principles

Details

Intent The rules governing how a system changes over time — no backward-compat cruft, no deprecation debt, no legacy retention, no 'for now'.

Invariant The system evolves cleanly only by deleting the superseded rather than accreting compatibility layers.

Flow

Supersede → Delete → NoLegacy

Composes none

Composed by Forward Compatibility Over Backward Compatibility, Explicit Removal Over Deprecation, Greenfield Over Legacy, Now Over For-Now, Compression Over Repetition, Approved Evolution Over Unapproved, Versioned Evolution Over Breaking Change, Pattern By Fit Over Speculative Pattern

Forces none

Principle Evolutionary Architecture

Grounds none

How it is checked

Checked by the layer and tension join, which places every principle in a cluster and resolves every tension between clusters

Population Every architecture and lexicon record the membership map places in the cluster

Freshness A verdict stands until the membership map, the topology or a member record changes

Refusal The gate fails on a tension with no resolution, or an override that matches no live edge

Observation None, because a cluster is a grouping of principles

Evidence Watched to fire and to accept: a suite plants a tension between two principles no layer places, and the bundled tensions resolve with no dead override

Authoritative side The membership map and the topology, which a tension's resolution is derived from

Depends on Not answered

Shape it refuses Not answered

Resource Core

Details

Intent The rules governing resource lifecycle and ownership — bounded lifetime, single ownership, no leaks, no implicit retention.

Invariant Every resource has one owner and a bounded lifetime; nothing is retained implicitly.

Flow

Acquire → Own → Bound → Release

Composes none

Composed by Fail-Fast Over Fallback, Mandatory Over Optional, Now Over For-Now, Single Owner Over Shared Ownership, Bounded Lifetime Over Unbounded, Enforced Symmetry Over Asymmetric Lifecycle, Explicit Retention Over Implicit, Structural Release Over Discipline, Config Externalization Over Env Fallback, Atomic Boundary Over Partial Commit

Forces none

Principle State Isolation

Grounds none

How it is checked

Checked by the layer and tension join, which places every principle in a cluster and resolves every tension between clusters

Population Every architecture and lexicon record the membership map places in the cluster

Freshness A verdict stands until the membership map, the topology or a member record changes

Refusal The gate fails on a tension with no resolution, or an override that matches no live edge

Observation None, because a cluster is a grouping of principles

Evidence Watched to fire and to accept: a suite plants a tension between two principles no layer places, and the bundled tensions resolve with no dead override

Authoritative side The membership map and the topology, which a tension's resolution is derived from

Depends on Not answered

Shape it refuses Not answered

Execution Core

Details

Intent The rules governing execution flow — a single observable path, no deferring, no dual-path branching, nothing unobserved.

Invariant Execution follows one observable path; nothing runs unobserved or deferred indefinitely.

Flow

SinglePath → Observe → NoDefer

Composes none

Composed by Single-Path Determinism Over Dual-Path, Immediacy Over Deferring, Observed Execution Over Unobserved, Single Owner Over Shared Ownership, Event Emission Over Parent Callbacks, Monotonic Growth Over Retraction, Ordinal Time Over Timestamps, Saga Compensation Over Distributed 2PC, Async Events Over Synchronous Cross-Boundary, Observable Signals Over Opaque Runtime

Forces none

Principle Controlled Side Effects

Grounds none

How it is checked

Checked by the layer and tension join, which places every principle in a cluster and resolves every tension between clusters

Population Every architecture and lexicon record the membership map places in the cluster

Freshness A verdict stands until the membership map, the topology or a member record changes

Refusal The gate fails on a tension with no resolution, or an override that matches no live edge

Observation None, because a cluster is a grouping of principles

Evidence Watched to fire and to accept: a suite plants a tension between two principles no layer places, and the bundled tensions resolve with no dead override

Authoritative side The membership map and the topology, which a tension's resolution is derived from

Depends on Not answered

Shape it refuses Not answered

Computation Core

Details

Intent The rules governing computation determinism and purity — no mutable shared state, no hidden nondeterminism, reproducible results.

Invariant A computation is reproducible only when it has no hidden mutable or nondeterministic input.

Flow

Immutable → Deterministic → Reproducible

Composes none

Composed by Immutable Data Over Mutable State, Errors As Language Over Silent Errors, Explicit Invalidity Over Hidden, Injected Nondeterminism Over Hidden

Forces none

Principle Determinism

Grounds none

How it is checked

Checked by the layer and tension join, which places every principle in a cluster and resolves every tension between clusters

Population Every architecture and lexicon record the membership map places in the cluster

Freshness A verdict stands until the membership map, the topology or a member record changes

Refusal The gate fails on a tension with no resolution, or an override that matches no live edge

Observation None, because a cluster is a grouping of principles

Evidence Watched to fire and to accept: a suite plants a tension between two principles no layer places, and the bundled tensions resolve with no dead override

Authoritative side The membership map and the topology, which a tension's resolution is derived from

Depends on Not answered

Shape it refuses Not answered

Security Core

Details

Intent The rules governing security posture — no hardcoded secrets, validated input, least privilege, no insecure fallbacks.

Invariant The system is secure only when every input is validated and every privilege is least and explicit.

Flow

ValidateInput → LeastPrivilege → NoSecretLeak

Composes none

Composed by Secret Store Over Hardcoded Secrets, Boundary Validation Over Unvalidated Input, Least Privilege Over Broad Privilege, Config Externalization Over Env Fallback

Forces none

Principle Security by Design

Grounds none

How it is checked

Checked by the layer and tension join, which places every principle in a cluster and resolves every tension between clusters

Population Every architecture and lexicon record the membership map places in the cluster

Freshness A verdict stands until the membership map, the topology or a member record changes

Refusal The gate fails on a tension with no resolution, or an override that matches no live edge

Observation None, because a cluster is a grouping of principles

Evidence Watched to fire and to accept: a suite plants a tension between two principles no layer places, and the bundled tensions resolve with no dead override

Authoritative side The membership map and the topology, which a tension's resolution is derived from

Depends on Not answered

Shape it refuses Not answered

Performance Core

Details

Intent The rules governing performance discipline — measured optimization, planned capacity, no guesswork.

Invariant Performance is improved only by measuring first; no optimization is applied unmeasured.

Flow

Measure → Optimize → Verify

Composes none

Composed by Queuing Theory, Profile-First Over Unmeasured Optimization

Forces none

Principle Performance Engineering

Grounds none

How it is checked

Checked by the layer and tension join, which places every principle in a cluster and resolves every tension between clusters

Population Every architecture and lexicon record the membership map places in the cluster

Freshness A verdict stands until the membership map, the topology or a member record changes

Refusal The gate fails on a tension with no resolution, or an override that matches no live edge

Observation None, because a cluster is a grouping of principles

Evidence Watched to fire and to accept: a suite plants a tension between two principles no layer places, and the bundled tensions resolve with no dead override

Authoritative side The membership map and the topology, which a tension's resolution is derived from

Depends on Not answered

Shape it refuses Not answered

Contracts Core

Details

Intent The rules governing interfaces and contracts — explicit typed boundaries, versioned change, no implicit or breaking contracts.

Invariant A boundary is safe only when its contract is explicit, typed, and versioned.

Flow

ExplicitContract → TypedBoundary → VersionChange

Composes none

Composed by Design By Contract Over Implicit Contract, Versioned Evolution Over Breaking Change, Schema-Validated Boundary Over Untyped

Forces none

Principle Explicit Contracts

Grounds none

How it is checked

Checked by the layer and tension join, which places every principle in a cluster and resolves every tension between clusters

Population Every architecture and lexicon record the membership map places in the cluster

Freshness A verdict stands until the membership map, the topology or a member record changes

Refusal The gate fails on a tension with no resolution, or an override that matches no live edge

Observation None, because a cluster is a grouping of principles

Evidence Watched to fire and to accept: a suite plants a tension between two principles no layer places, and the bundled tensions resolve with no dead override

Authoritative side The membership map and the topology, which a tension's resolution is derived from

Depends on Not answered

Shape it refuses Not answered

Causality Core

Details

Intent The rules governing causal ordering and time — logical ordering, retractable state, no wall-clock dependence.

Invariant Order is well-defined only through logical causality, never wall-clock assumptions.

Flow

LogicalOrder → Retract → NoWallClock

Composes none

Composed by Monotonic Growth Over Retraction, Ordinal Time Over Timestamps

Forces none

Principle Causality

Grounds none

How it is checked

Checked by the layer and tension join, which places every principle in a cluster and resolves every tension between clusters

Population Every architecture and lexicon record the membership map places in the cluster

Freshness A verdict stands until the membership map, the topology or a member record changes

Refusal The gate fails on a tension with no resolution, or an override that matches no live edge

Observation None, because a cluster is a grouping of principles

Evidence Watched to fire and to accept: a suite plants a tension between two principles no layer places, and the bundled tensions resolve with no dead override

Authoritative side The membership map and the topology, which a tension's resolution is derived from

Depends on Not answered

Shape it refuses Not answered

Declarative Core

Details

Intent The rules favoring declarative over imperative — declared configuration, separated concerns, no imperative wiring.

Invariant Behavior is declared as data, not encoded imperatively.

Flow

Declare → Separate → NoImperativeConfig

Composes none

Composed by Homoiconicity Over Separation, Declarative Config Over Imperative

Forces none

Principle Declarative Configuration

Grounds none

How it is checked

Checked by the layer and tension join, which places every principle in a cluster and resolves every tension between clusters

Population Every architecture and lexicon record the membership map places in the cluster

Freshness A verdict stands until the membership map, the topology or a member record changes

Refusal The gate fails on a tension with no resolution, or an override that matches no live edge

Observation None, because a cluster is a grouping of principles

Evidence Watched to fire and to accept: a suite plants a tension between two principles no layer places, and the bundled tensions resolve with no dead override

Authoritative side The membership map and the topology, which a tension's resolution is derived from

Depends on Not answered

Shape it refuses Not answered

Extensibility Core

Details

Intent The rules governing extension — declarative discovered wiring over hardcoded, no imperative hardcoded registration.

Invariant The system extends without modification only when wiring is declarative and discovered, not hardcoded.

Flow

DeclareWiring → Discover → Extend

Composes none

Composed by Convention Discovery Over Hardcoded Wiring, Declarative Config Over Imperative

Forces none

Principle Open/Closed Principle (OCP)

Grounds none

How it is checked

Checked by the layer and tension join, which places every principle in a cluster and resolves every tension between clusters

Population Every architecture and lexicon record the membership map places in the cluster

Freshness A verdict stands until the membership map, the topology or a member record changes

Refusal The gate fails on a tension with no resolution, or an override that matches no live edge

Observation None, because a cluster is a grouping of principles

Evidence Watched to fire and to accept: a suite plants a tension between two principles no layer places, and the bundled tensions resolve with no dead override

Authoritative side The membership map and the topology, which a tension's resolution is derived from

Depends on Not answered

Shape it refuses Not answered

Observability

Details

Intent The rules ensuring a system is observable — emitted metrics and signals, no unobserved execution, no opaque runtime.

Invariant A system is operable only when its behavior is observable through emitted signals.

Flow

Emit → Trace → NoOpaque

Composes none

Composed by Observed Execution Over Unobserved, Computed Health Over Metric Health, Observable Signals Over Opaque Runtime

Forces none

Principle Observability

Grounds none

How it is checked

Checked by the layer and tension join, which places every principle in a cluster and resolves every tension between clusters

Population Every architecture and lexicon record the membership map places in the cluster

Freshness A verdict stands until the membership map, the topology or a member record changes

Refusal The gate fails on a tension with no resolution, or an override that matches no live edge

Observation None, because a cluster is a grouping of principles

Evidence Watched to fire and to accept: a suite plants a tension between two principles no layer places, and the bundled tensions resolve with no dead override

Authoritative side The membership map and the topology, which a tension's resolution is derived from

Depends on Not answered

Shape it refuses Not answered

Enforcement Core

Details

Intent The rules ensuring discipline is enforced programmatically — automated gates over convention, no discipline-only reliance.

Invariant A rule holds only when a gate enforces it; a rule kept by convention alone drifts.

Flow

Gate → Automate → NoConventionOnly

Composes none

Composed by Structural Release Over Discipline, Rule As Code Over Convention

Forces none

Principle Fitness Functions

Grounds none

How it is checked

Checked by the layer and tension join, which places every principle in a cluster and resolves every tension between clusters

Population Every architecture and lexicon record the membership map places in the cluster

Freshness A verdict stands until the membership map, the topology or a member record changes

Refusal The gate fails on a tension with no resolution, or an override that matches no live edge

Observation None, because a cluster is a grouping of principles

Evidence Watched to fire and to accept: a suite plants a tension between two principles no layer places, and the bundled tensions resolve with no dead override

Authoritative side The membership map and the topology, which a tension's resolution is derived from

Depends on Not answered

Shape it refuses Not answered

Atomic Boundary

Details

Intent The rules governing atomicity — a transactional boundary that fully commits or fully rolls back, no partial commit, no deferring within.

Invariant A boundary either fully commits or fully rolls back; no partial state escapes.

Flow

Begin → AllOrNothing → Commit

Composes none

Composed by Immediacy Over Deferring, Atomic Boundary Over Partial Commit

Forces none

Principle Atomicity

Grounds none

Refused by rules atomic-boundary

How it is checked

Checked by the layer and tension join, which places every principle in a cluster and resolves every tension between clusters

Population Every architecture and lexicon record the membership map places in the cluster

Freshness A verdict stands until the membership map, the topology or a member record changes

Refusal The gate fails on a tension with no resolution, or an override that matches no live edge

Observation None, because a cluster is a grouping of principles

Evidence Watched to fire and to accept: a suite plants a tension between two principles no layer places, and the bundled tensions resolve with no dead override

Authoritative side The membership map and the topology, which a tension's resolution is derived from

Depends on Not answered

Shape it refuses Not answered

Human Factors

Details

Intent The rules governing human ergonomics — bounded cognitive complexity, acted-on feedback, explicit approval, no unlimited options.

Invariant A system is usable only when its cognitive load is bounded and its decisions are approved and reversible.

Flow

BoundComplexity → Approve → ActOnFeedback

Composes none

Composed by Mandatory Over Optional, Approved Evolution Over Unapproved, Enforced Feedback Over Ignored, Bounded Complexity Over Unlimited

Forces none

Principle Principle of Least Surprise

Grounds none

How it is checked

Checked by the layer and tension join, which places every principle in a cluster and resolves every tension between clusters

Population Every architecture and lexicon record the membership map places in the cluster

Freshness A verdict stands until the membership map, the topology or a member record changes

Refusal The gate fails on a tension with no resolution, or an override that matches no live edge

Observation None, because a cluster is a grouping of principles

Evidence Watched to fire and to accept: a suite plants a tension between two principles no layer places, and the bundled tensions resolve with no dead override

Authoritative side The membership map and the topology, which a tension's resolution is derived from

Depends on Not answered

Shape it refuses Not answered

Domain Modeling

Details

Intent The rules governing domain boundaries — bounded contexts, ubiquitous language, no leaky context.

Invariant A domain model stays coherent only when its context boundaries do not leak.

Flow

BoundContext → NoLeak → UbiquitousLanguage

Composes none

Composed by Anti-Corruption Layer Over Cross-Context Leak

Forces none

Principle Bounded Context

Grounds none

How it is checked

Checked by the layer and tension join, which places every principle in a cluster and resolves every tension between clusters

Population Every architecture and lexicon record the membership map places in the cluster

Freshness A verdict stands until the membership map, the topology or a member record changes

Refusal The gate fails on a tension with no resolution, or an override that matches no live edge

Observation None, because a cluster is a grouping of principles

Evidence Watched to fire and to accept: a suite plants a tension between two principles no layer places, and the bundled tensions resolve with no dead override

Authoritative side The membership map and the topology, which a tension's resolution is derived from

Depends on Not answered

Shape it refuses Not answered

Design Patterns Core

Details

Intent The rules governing design-pattern use — patterns applied only to demonstrated recurrence, no speculative pattern application.

Invariant A pattern is warranted only by demonstrated recurrence, never speculation.

Flow

ObserveRecurrence → ApplyPattern → NoSpeculation

Composes none

Composed by Pattern By Fit Over Speculative Pattern

Forces none

Principle First-Principles Design

Grounds none

How it is checked

Checked by the layer and tension join, which places every principle in a cluster and resolves every tension between clusters

Population Every architecture and lexicon record the membership map places in the cluster

Freshness A verdict stands until the membership map, the topology or a member record changes

Refusal The gate fails on a tension with no resolution, or an override that matches no live edge

Observation None, because a cluster is a grouping of principles

Evidence Watched to fire and to accept: a suite plants a tension between two principles no layer places, and the bundled tensions resolve with no dead override

Authoritative side The membership map and the topology, which a tension's resolution is derived from

Depends on Not answered

Shape it refuses Not answered

State Pattern

Details

Intent The State design pattern — encapsulate state-dependent behavior in distinct state objects so transitions replace conditional branching.

Invariant State-dependent behavior is expressed by delegating to a current-state object, not by scattered conditionals.

Flow

DefineStates → DelegateBehavior → Transition

Composes none

Composed by Finite State Machine

Forces none

Principle State Pattern

Grounds none

Before

State-dependent behavior scattered as if/else conditionals on a status flag.

After

define state objects → delegate behavior to the current-state object → transition replaces the conditional branching

How it is checked

Checked by the layer and tension join, which places every principle in a cluster and resolves every tension between clusters

Population Every architecture and lexicon record the membership map places in the cluster

Freshness A verdict stands until the membership map, the topology or a member record changes

Refusal The gate fails on a tension with no resolution, or an override that matches no live edge

Observation None, because a cluster is a grouping of principles

Evidence Watched to fire and to accept: a suite plants a tension between two principles no layer places, and the bundled tensions resolve with no dead override

Authoritative side The membership map and the topology, which a tension's resolution is derived from

Depends on Not answered

Shape it refuses Not answered

Separation of Concerns

Details

Intent The principle of separating a system into distinct concerns so each is addressed and changed independently.

Invariant Each concern is localized to one place and changes independently of the others.

Flow

IdentifyConcerns → Separate → IsolateChange

Composes none

Composed by Statecharts

Forces none

Grounds none

Refused by rules separation-of-concerns

Before

One module mixes parsing, persistence, and rendering — a change in one ripples through all.

After

identify concerns → separate each into one place → each concern changes independently

How it is checked

Checked by the layer and tension join, which places every principle in a cluster and resolves every tension between clusters

Population Every architecture and lexicon record the membership map places in the cluster

Freshness A verdict stands until the membership map, the topology or a member record changes

Refusal The gate fails on a tension with no resolution, or an override that matches no live edge

Observation None, because a cluster is a grouping of principles

Evidence Watched to fire and to accept: a suite plants a tension between two principles no layer places, and the bundled tensions resolve with no dead override

Authoritative side The membership map and the topology, which a tension's resolution is derived from

Depends on Not answered

Shape it refuses Not answered

Concurrency Correctness

Details

Intent The rules ensuring correct concurrent behavior — no data races, well-defined interleavings, verified with models such as Petri nets.

Invariant Concurrent correctness holds only when every interleaving preserves the invariants.

Flow

ModelInterleavings → PreventRaces → Verify

Composes none

Composed by Petri Nets

Forces none

Grounds none

Before

Concurrent access with a data race; some interleaving violates the invariant.

After

model interleavings → prevent races → verify every interleaving preserves the invariants

How it is checked

Checked by the layer and tension join, which places every principle in a cluster and resolves every tension between clusters

Population Every architecture and lexicon record the membership map places in the cluster

Freshness A verdict stands until the membership map, the topology or a member record changes

Refusal The gate fails on a tension with no resolution, or an override that matches no live edge

Observation None, because a cluster is a grouping of principles

Evidence Watched to fire and to accept: a suite plants a tension between two principles no layer places, and the bundled tensions resolve with no dead override

Authoritative side The membership map and the topology, which a tension's resolution is derived from

Depends on Not answered

Shape it refuses Not answered

Capacity Planning

Details

Intent The activity of forecasting resource demand and provisioning capacity to meet it, informed by queuing theory.

Invariant Capacity meets demand only when provisioning is derived from measured or modeled load, not guessed.

Flow

ModelLoad → Forecast → Provision

Composes none

Composed by Queuing Theory

Forces none

Grounds none

Before

Capacity guessed, then saturates under production load.

After

model load → forecast demand → provision from measured/modeled load, not a guess

How it is checked

Checked by the layer and tension join, which places every principle in a cluster and resolves every tension between clusters

Population Every architecture and lexicon record the membership map places in the cluster

Freshness A verdict stands until the membership map, the topology or a member record changes

Refusal The gate fails on a tension with no resolution, or an override that matches no live edge

Observation None, because a cluster is a grouping of principles

Evidence Watched to fire and to accept: a suite plants a tension between two principles no layer places, and the bundled tensions resolve with no dead override

Authoritative side The membership map and the topology, which a tension's resolution is derived from

Depends on Not answered

Shape it refuses Not answered

Architectural Rules

Every algorithm contract in this domain is listed with its position on the derivation loop, its intent and invariant, the flow it walks and its productions as a grammar. Each record also shows what it composes and is composed by, which forces and principles it answers to, what grounds it and what it grounds, and an exemplar where the record carries one. The diagram shows what composes what inside the domain.

Relations diagram

What composes what inside this domain.

flowchart LR
    n_no_shortcuts["Constraints Over Shortcuts"]
    n_no_backward_compat["Forward Compatibility Over Backward Compatibility"]
    n_no_fallback["Fail-Fast Over Fallback"]
    n_no_deprecation["Explicit Removal Over Deprecation"]
    n_no_legacy["Greenfield Over Legacy"]
    n_no_dual_path["Single-Path Determinism Over Dual-Path"]
    n_no_deferring["Immediacy Over Deferring"]
    n_no_optional["Mandatory Over Optional"]
    n_no_for_now["Now Over For-Now"]
    n_no_unobserved["Observed Execution Over Unobserved"]
    n_no_uncompressed["Compression Over Repetition"]
    n_no_unapproved["Approved Evolution Over Unapproved"]
    n_no_ignored_feedback["Enforced Feedback Over Ignored"]
    n_no_shared_ownership["Single Owner Over Shared Ownership"]
    n_no_unbounded["Bounded Lifetime Over Unbounded"]
    n_no_asymmetric["Enforced Symmetry Over Asymmetric Lifecycle"]
    n_no_implicit_retention["Explicit Retention Over Implicit"]
    n_no_discipline_release["Structural Release Over Discipline"]
    n_no_mutable["Immutable Data Over Mutable State"]
    n_no_silent["Errors As Language Over Silent Errors"]
    n_no_hidden_invalidity["Explicit Invalidity Over Hidden"]
    n_no_callbacks["Event Emission Over Parent Callbacks"]
    n_no_retraction["Monotonic Growth Over Retraction"]
    n_no_location["Semantic Addressing Over Location Addressing"]
    n_no_timestamps["Ordinal Time Over Timestamps"]
    n_no_separation["Homoiconicity Over Separation"]
    n_no_unlimited["Bounded Complexity Over Unlimited"]
    n_no_metrics["Computed Health Over Metric Health"]
    n_no_hardcoded_secrets["Secret Store Over Hardcoded Secrets"]
    n_no_unvalidated_input["Boundary Validation Over Unvalidated Input"]
    n_no_broad_privilege["Least Privilege Over Broad Privilege"]
    n_no_env_fallback["Config Externalization Over Env Fallback"]
    n_no_unmeasured_optimization["Profile-First Over Unmeasured Optimization"]
    n_no_convention_enforcement["Rule As Code Over Convention"]
    n_no_implicit_contract["Design By Contract Over Implicit Contract"]
    n_no_breaking_change["Versioned Evolution Over Breaking Change"]
    n_no_untyped_boundary["Schema-Validated Boundary Over Untyped"]
    n_no_partial_commit["Atomic Boundary Over Partial Commit"]
    n_no_distributed_2pc["Saga Compensation Over Distributed 2PC"]
    n_no_sync_cross_boundary["Async Events Over Synchronous Cross-Boundary"]
    n_no_opaque_runtime["Observable Signals Over Opaque Runtime"]
    n_no_hidden_dependency["Injected Dependency Over Hidden"]
    n_no_hardcoded_wiring["Convention Discovery Over Hardcoded Wiring"]
    n_no_imperative_config["Declarative Config Over Imperative"]
    n_no_leaky_context["Anti-Corruption Layer Over Cross-Context Leak"]
    n_no_hidden_nondeterminism["Injected Nondeterminism Over Hidden"]
    n_no_speculative_pattern["Pattern By Fit Over Speculative Pattern"]
Loading

Constraints Over Shortcuts

Details

Intent Replace a debt-incurring shortcut with an encoded constraint that makes the invalid state unrepresentable, so the rule holds without relying on discipline.

Invariant A value that could be constructed invalidly is instead constructed only through a validating boundary.

Flow

ShortcutTaken → IdentifyInvariant → EncodeConstraint → RouteThroughBoundary → LeverageGained

Productions

NoShortcuts ::= <ShortcutTaken> "→" <IdentifyInvariant> "→" <EncodeConstraint> "→" <RouteThroughBoundary> "→" <LeverageGained>

Composes Structural Core, Coupling Control

Forces shortcuts (debt)

Grounds none

Before

type FooId = string;

function loadFoo(raw: string) {
  return fooStore.get(raw as FooId);
}

After

type FooId = string & { readonly __brand: "FooId" };

function fooId(raw: string): FooId {
  if (!raw.startsWith("foo_") || raw.length <= 4)
    throw new Error(`invalid FooId: ${raw}`);
  return raw as FooId;
}

function loadFoo(id: FooId) {
  return fooStore.get(id);
}

How it is checked

Checked by the quality rules and auto-fixes that refuse the shortcut each architectural rule forbids, the cross-file quality gate

Population Every source file under a governed root

Freshness A verdict stands until the source or the rule changes

Refusal A rule that fires fails the lint stage, and an auto-fix rewrites the shortcut where the fix is deterministic

Observation The telemetry a runtime rule requires, such as observed execution, which locates a path that runs unobserved

Evidence None, because the catalog states this check as a class, so a watched run belongs to each system that adopts it

Authoritative side The architectural rule, which the source conforms to and an auto-fix rewrites toward

Depends on Structural Core, Coupling Control

Shape it refuses Not answered

Forward Compatibility Over Backward Compatibility

Details

Intent Replace accreted legacy input shapes with one forward-compatible envelope that carries extensions, so evolution compounds instead of branching.

Invariant One canonical shape with an open extension slot subsumes every prior variant; no shape-discriminating branch remains.

Flow

ManyVariants → DefineEnvelope → MapToCanonical → OpenExtensionSlot → RemoveVariantBranches

Productions

NoBackwardCompat ::= <ManyVariants> "→" <DefineEnvelope> "→" <MapToCanonical> "→" <OpenExtensionSlot> "→" <RemoveVariantBranches>

Composes Evolution Principles, Structural Core

Forces backward_compatibility (debt)

Grounds none

Before

type FooInput = string | { name: string } | { label: string; flags?: string[] };

function readFoo(input: FooInput) {
  if (typeof input === "string") return { label: input, flags: [] };
  if ("name" in input) return { label: input.name, flags: [] };
  return { label: input.label, flags: input.flags ?? [] };
}

After

type FooEnvelope = {
  kind: "foo";
  label: string;
  extensions: Readonly<Record<string, unknown>>;
};

function readFoo(input: FooEnvelope) {
  return { label: input.label, extensions: input.extensions };
}

How it is checked

Checked by the quality rules and auto-fixes that refuse the shortcut each architectural rule forbids, the cross-file quality gate

Population Every source file under a governed root

Freshness A verdict stands until the source or the rule changes

Refusal A rule that fires fails the lint stage, and an auto-fix rewrites the shortcut where the fix is deterministic

Observation The telemetry a runtime rule requires, such as observed execution, which locates a path that runs unobserved

Evidence None, because the catalog states this check as a class, so a watched run belongs to each system that adopts it

Authoritative side The architectural rule, which the source conforms to and an auto-fix rewrites toward

Depends on Evolution Principles, Structural Core

Shape it refuses Not answered

Fail-Fast Over Fallback

Details

Intent Replace a silent fallback default with a required input that halts loudly when absent, so missing configuration surfaces at the boundary.

Invariant Every required input is present and validated before use; absence throws rather than defaulting.

Flow

OptionalInput → MarkRequired → ValidateAtBoundary → HaltOnAbsence → ClarityGained

Productions

NoFallback ::= <OptionalInput> "→" <MarkRequired> "→" <ValidateAtBoundary> "→" <HaltOnAbsence> "→" <ClarityGained>

Composes Resource Core, Structural Core

Forces fallback (debt)

Grounds none

Before

function makeFoo(config: { mode?: "foo" | "bar" }) {
  const mode = config.mode ?? "foo";
  return mode === "foo" ? new Foo() : new Bar();
}

After

type FooConfig = { mode: "foo" | "bar" };

function makeFoo(config: FooConfig) {
  if (!config.mode) throw new Error("FooConfig.mode is required");
  return config.mode === "foo" ? new Foo() : new Bar();
}

How it is checked

Checked by the quality rules and auto-fixes that refuse the shortcut each architectural rule forbids, the cross-file quality gate

Population Every source file under a governed root

Freshness A verdict stands until the source or the rule changes

Refusal A rule that fires fails the lint stage, and an auto-fix rewrites the shortcut where the fix is deterministic

Observation The telemetry a runtime rule requires, such as observed execution, which locates a path that runs unobserved

Evidence None, because the catalog states this check as a class, so a watched run belongs to each system that adopts it

Authoritative side The architectural rule, which the source conforms to and an auto-fix rewrites toward

Depends on Resource Core, Structural Core

Shape it refuses Not answered

Explicit Removal Over Deprecation

Details

Intent Replace a deprecated alias kept for compatibility with outright removal, so the single current name is the only path.

Invariant No symbol exists solely to forward to another; every callsite targets the canonical name.

Flow

DeprecatedAlias → MigrateCallsites → DeleteAlias → SinglePathRemains

Productions

NoDeprecation ::= <DeprecatedAlias> "→" <MigrateCallsites> "→" <DeleteAlias> "→" <SinglePathRemains>

Composes Evolution Principles, Structural Core

Forces deprecation (debt)

Grounds none

Before

class FooService {
  makeFoo() {
    return this.createFoo();
  }
  createFoo() {
    return new Foo();
  }
}

After

class FooService {
  createFoo() {
    return new Foo();
  }
}

How it is checked

Checked by the quality rules and auto-fixes that refuse the shortcut each architectural rule forbids, the cross-file quality gate

Population Every source file under a governed root

Freshness A verdict stands until the source or the rule changes

Refusal A rule that fires fails the lint stage, and an auto-fix rewrites the shortcut where the fix is deterministic

Observation The telemetry a runtime rule requires, such as observed execution, which locates a path that runs unobserved

Evidence None, because the catalog states this check as a class, so a watched run belongs to each system that adopts it

Authoritative side The architectural rule, which the source conforms to and an auto-fix rewrites toward

Depends on Evolution Principles, Structural Core

Shape it refuses Not answered

Greenfield Over Legacy

Details

Intent Replace a legacy-mode branch with one current algorithm, deleting the old path rather than gating it behind a flag.

Invariant A single implementation serves the concern; no legacy-mode conditional selects behavior.

Flow

LegacyBranch → ExtractCurrentPath → DeleteLegacyPath → RemoveFlag

Productions

NoLegacy ::= <LegacyBranch> "→" <ExtractCurrentPath> "→" <DeleteLegacyPath> "→" <RemoveFlag>

Composes Evolution Principles, Structural Core

Forces legacy (debt)

Grounds none

Before

function calculateFoo(input: FooInput, legacyMode: boolean) {
  if (legacyMode) return oldFooAlgorithm(input);
  return newFooAlgorithm(input);
}

After

function calculateFoo(input: FooInput) {
  return fooAlgorithm(input);
}

How it is checked

Checked by the quality rules and auto-fixes that refuse the shortcut each architectural rule forbids, the cross-file quality gate

Population Every source file under a governed root

Freshness A verdict stands until the source or the rule changes

Refusal A rule that fires fails the lint stage, and an auto-fix rewrites the shortcut where the fix is deterministic

Observation The telemetry a runtime rule requires, such as observed execution, which locates a path that runs unobserved

Evidence None, because the catalog states this check as a class, so a watched run belongs to each system that adopts it

Authoritative side The architectural rule, which the source conforms to and an auto-fix rewrites toward

Depends on Evolution Principles, Structural Core

Shape it refuses Not answered

Single-Path Determinism Over Dual-Path

Details

Intent Collapse a flag-selected dual path into one deterministic path, removing the branch and the flag that caused ambiguity.

Invariant Exactly one code path handles the operation; no runtime flag chooses between equivalent implementations.

Flow

DualPath → ChooseCanonical → MigrateConsumers → DeleteAlternate → DeterminismGained

Productions

NoDualPath ::= <DualPath> "→" <ChooseCanonical> "→" <MigrateConsumers> "→" <DeleteAlternate> "→" <DeterminismGained>

Composes Structural Core, Execution Core

Forces dual-path (confusion)

Grounds none

Before

function saveFoo(foo: Foo, flags: { useNewStore: boolean }) {
  return flags.useNewStore ? newFooStore.save(foo) : oldFooStore.save(foo);
}

After

function saveFoo(foo: Foo) {
  return fooStore.save(foo);
}

How it is checked

Checked by the quality rules and auto-fixes that refuse the shortcut each architectural rule forbids, the cross-file quality gate

Population Every source file under a governed root

Freshness A verdict stands until the source or the rule changes

Refusal A rule that fires fails the lint stage, and an auto-fix rewrites the shortcut where the fix is deterministic

Observation The telemetry a runtime rule requires, such as observed execution, which locates a path that runs unobserved

Evidence None, because the catalog states this check as a class, so a watched run belongs to each system that adopts it

Authoritative side The architectural rule, which the source conforms to and an auto-fix rewrites toward

Depends on Structural Core, Execution Core

Shape it refuses Not answered

Immediacy Over Deferring

Details

Intent Replace a deferred follow-up with an atomic action that completes every coupled effect now, so nothing is forgotten.

Invariant Coupled effects commit together within one boundary; no effect is left as an implicit later step.

Flow

PartialAction → IdentifyCoupledEffects → WrapInTransaction → CommitTogether

Productions

NoDeferring ::= <PartialAction> "→" <IdentifyCoupledEffects> "→" <WrapInTransaction> "→" <CommitTogether>

Composes Execution Core, Atomic Boundary

Forces deferring (forgetting)

Grounds none

Before

async function renameFoo(id: FooId, name: string) {
  await fooStore.rename(id, name);
}

After

async function renameFoo(id: FooId, name: string) {
  await transaction(async (tx) => {
    await tx.foos.rename(id, name);
    await tx.search.reindex(id, name);
  });
}

How it is checked

Checked by the quality rules and auto-fixes that refuse the shortcut each architectural rule forbids, the cross-file quality gate

Population Every source file under a governed root

Freshness A verdict stands until the source or the rule changes

Refusal A rule that fires fails the lint stage, and an auto-fix rewrites the shortcut where the fix is deterministic

Observation The telemetry a runtime rule requires, such as observed execution, which locates a path that runs unobserved

Evidence None, because the catalog states this check as a class, so a watched run belongs to each system that adopts it

Authoritative side The architectural rule, which the source conforms to and an auto-fix rewrites toward

Depends on Execution Core, Atomic Boundary

Shape it refuses Not answered

Mandatory Over Optional

Details

Intent Replace an optional dependency with a mandatory one, removing the null-guarded branch so behavior is system-defined not caller-defined.

Invariant A dependency the behavior relies on is always supplied; no optional-chaining guards its use.

Flow

OptionalDependency → MakeRequired → InjectAlways → RemoveGuards

Productions

NoOptional ::= <OptionalDependency> "→" <MakeRequired> "→" <InjectAlways> "→" <RemoveGuards>

Composes Human Factors, Resource Core

Forces optional (user-orientation)

Grounds none

Before

class FooService {
  constructor(private readonly audit?: AuditSink) {}

  create(foo: Foo) {
    this.audit?.write({ type: "foo.created", foo });
    return fooStore.save(foo);
  }
}

After

class FooService {
  constructor(private readonly audit: AuditSink) {}

  create(foo: Foo) {
    this.audit.write({ type: "foo.created", foo });
    return fooStore.save(foo);
  }
}

How it is checked

Checked by the quality rules and auto-fixes that refuse the shortcut each architectural rule forbids, the cross-file quality gate

Population Every source file under a governed root

Freshness A verdict stands until the source or the rule changes

Refusal A rule that fires fails the lint stage, and an auto-fix rewrites the shortcut where the fix is deterministic

Observation The telemetry a runtime rule requires, such as observed execution, which locates a path that runs unobserved

Evidence None, because the catalog states this check as a class, so a watched run belongs to each system that adopts it

Authoritative side The architectural rule, which the source conforms to and an auto-fix rewrites toward

Depends on Human Factors, Resource Core

Shape it refuses Not answered

Now Over For-Now

Details

Intent Replace a temporary in-memory placeholder with the real durable implementation immediately, so the stopgap never ossifies.

Invariant State that must survive restarts is persisted through the real store, not a transient map.

Flow

TemporaryStub → IdentifyDurabilityNeed → WireRealStore → DeleteStub

Productions

NoForNow ::= <TemporaryStub> "→" <IdentifyDurabilityNeed> "→" <WireRealStore> "→" <DeleteStub>

Composes Resource Core, Evolution Principles

Forces for_now (deferring)

Grounds none

Before

class FooRepository {
  private readonly data = new Map<string, Foo>();
  save(foo: Foo) {
    this.data.set(foo.id, foo);
  }
}

After

class FooRepository {
  constructor(private readonly db: Database) {}

  save(foo: Foo) {
    return this.db.execute(
      "insert into foos(id, value) values (?, ?)",
      foo.id,
      foo,
    );
  }
}

How it is checked

Checked by the quality rules and auto-fixes that refuse the shortcut each architectural rule forbids, the cross-file quality gate

Population Every source file under a governed root

Freshness A verdict stands until the source or the rule changes

Refusal A rule that fires fails the lint stage, and an auto-fix rewrites the shortcut where the fix is deterministic

Observation The telemetry a runtime rule requires, such as observed execution, which locates a path that runs unobserved

Evidence None, because the catalog states this check as a class, so a watched run belongs to each system that adopts it

Authoritative side The architectural rule, which the source conforms to and an auto-fix rewrites toward

Depends on Resource Core, Evolution Principles

Shape it refuses Not answered

Observed Execution Over Unobserved

Details

Intent Wrap an unobserved effect in structured telemetry so every execution emits a learnable signal on success and failure.

Invariant Every significant effect opens and closes a span carrying its outcome; no path executes blind.

Flow

BlindEffect → OpenSpan → ExecuteWithinSpan → RecordOutcome

Productions

NoUnobserved ::= <BlindEffect> "→" <OpenSpan> "→" <ExecuteWithinSpan> "→" <RecordOutcome>

Composes Observability, Execution Core

Forces unobserved-execution (missed-learning)

Grounds none

Before

function publishFoo(foo: Foo) {
  sendFoo(foo);
}

After

async function publishFoo(foo: Foo, telemetry: Telemetry) {
  const span = telemetry.startSpan("foo.publish", { fooId: foo.id });
  try {
    await sendFoo(foo);
    span.end({ status: "ok" });
  } catch (error) {
    span.end({ status: "error", error });
    throw error;
  }
}

How it is checked

Checked by the quality rules and auto-fixes that refuse the shortcut each architectural rule forbids, the cross-file quality gate

Population Every source file under a governed root

Freshness A verdict stands until the source or the rule changes

Refusal A rule that fires fails the lint stage, and an auto-fix rewrites the shortcut where the fix is deterministic

Observation The telemetry a runtime rule requires, such as observed execution, which locates a path that runs unobserved

Evidence None, because the catalog states this check as a class, so a watched run belongs to each system that adopts it

Authoritative side The architectural rule, which the source conforms to and an auto-fix rewrites toward

Depends on Observability, Execution Core

Shape it refuses Not answered

Compression Over Repetition

Details

Intent Extract a repeated pattern into one parameterized form, so the behavior lives once and duplication cannot drift.

Invariant A behavior expressed more than once is factored to a single definition parameterized over its variation.

Flow

DuplicatedPattern → IdentifyVariation → ExtractParameterized → RedirectCallsites

Productions

NoUncompressed ::= <DuplicatedPattern> "→" <IdentifyVariation> "→" <ExtractParameterized> "→" <RedirectCallsites>

Composes Structural Core, Evolution Principles

Forces pattern-without-compression (inefficiency)

Grounds none

Before

function validateFoo(foo: Foo) {
  if (!foo.name) throw new Error("foo.name required");
  if (foo.name.length > 40) throw new Error("foo.name too long");
}
function validateBar(bar: Bar) {
  if (!bar.name) throw new Error("bar.name required");
  if (bar.name.length > 40) throw new Error("bar.name too long");
}

After

function requiredName(value: { name: string }, kind: string) {
  if (!value.name) throw new Error(`${kind}.name required`);
  if (value.name.length > 40) throw new Error(`${kind}.name too long`);
}

const validateFoo = (foo: Foo) => requiredName(foo, "foo");
const validateBar = (bar: Bar) => requiredName(bar, "bar");

How it is checked

Checked by the quality rules and auto-fixes that refuse the shortcut each architectural rule forbids, the cross-file quality gate

Population Every source file under a governed root

Freshness A verdict stands until the source or the rule changes

Refusal A rule that fires fails the lint stage, and an auto-fix rewrites the shortcut where the fix is deterministic

Observation The telemetry a runtime rule requires, such as observed execution, which locates a path that runs unobserved

Evidence None, because the catalog states this check as a class, so a watched run belongs to each system that adopts it

Authoritative side The architectural rule, which the source conforms to and an auto-fix rewrites toward

Depends on Structural Core, Evolution Principles

Shape it refuses Not answered

Approved Evolution Over Unapproved

Details

Intent Gate a structural dependency behind a recorded architecture decision, so evolution proceeds only through approved boundaries.

Invariant Every cross-boundary dependency traces to an approved decision record naming the allowed gateway.

Flow

UnapprovedDependency → RaiseDecision → RecordApproval → WireApprovedGateway

Productions

NoUnapproved ::= <UnapprovedDependency> "→" <RaiseDecision> "→" <RecordApproval> "→" <WireApprovedGateway>

Composes Evolution Principles, Human Factors

Forces evolution-without-approval (architectural-drift)

Grounds none

Before

class FooService {
  private readonly barDb = connectDirectlyToBarDatabase();
}

After

type ArchitectureDecision = {
  id: "ADR-0042";
  status: "approved";
  owner: "foo-platform";
  allowedDependency: "BarGateway";
};

const decision: ArchitectureDecision = approvedDecision("ADR-0042");
class FooService {
  constructor(
    private readonly bars: BarGateway,
    readonly adr = decision.id,
  ) {}
}

How it is checked

Checked by the quality rules and auto-fixes that refuse the shortcut each architectural rule forbids, the cross-file quality gate

Population Every source file under a governed root

Freshness A verdict stands until the source or the rule changes

Refusal A rule that fires fails the lint stage, and an auto-fix rewrites the shortcut where the fix is deterministic

Observation The telemetry a runtime rule requires, such as observed execution, which locates a path that runs unobserved

Evidence None, because the catalog states this check as a class, so a watched run belongs to each system that adopts it

Authoritative side The architectural rule, which the source conforms to and an auto-fix rewrites toward

Depends on Evolution Principles, Human Factors

Shape it refuses Not answered

Enforced Feedback Over Ignored

Details

Intent Turn a logged-and-ignored warning into an enforced result, so negative feedback changes control flow instead of scrolling past.

Invariant A detected invalid condition returns a typed failure; it is never merely logged and continued.

Flow

WarnAndContinue → ModelFailureResult → ReturnTypedError → HaltHappyPath

Productions

NoIgnoredFeedback ::= <WarnAndContinue> "→" <ModelFailureResult> "→" <ReturnTypedError> "→" <HaltHappyPath>

Composes Human Factors, Correctness Core

Forces feedback-ignored (stagnation)

Grounds none

Before

function ingestFoo(foo: Foo) {
  if (foo.score < 0) console.warn("bad foo score", foo.score);
  return fooStore.save(foo);
}

After

function ingestFoo(foo: Foo) {
  if (foo.score < 0) {
    return {
      ok: false,
      error: { code: "INVALID_SCORE", value: foo.score },
    } as const;
  }
  fooStore.save(foo);
  return { ok: true } as const;
}

How it is checked

Checked by the quality rules and auto-fixes that refuse the shortcut each architectural rule forbids, the cross-file quality gate

Population Every source file under a governed root

Freshness A verdict stands until the source or the rule changes

Refusal A rule that fires fails the lint stage, and an auto-fix rewrites the shortcut where the fix is deterministic

Observation The telemetry a runtime rule requires, such as observed execution, which locates a path that runs unobserved

Evidence None, because the catalog states this check as a class, so a watched run belongs to each system that adopts it

Authoritative side The architectural rule, which the source conforms to and an auto-fix rewrites toward

Depends on Human Factors, Correctness Core

Shape it refuses Not answered

Single Owner Over Shared Ownership

Details

Intent Give one service authority over a piece of state and propagate to others by event, removing multi-writer ambiguity.

Invariant Exactly one service mutates a given entity; peers react to its events rather than co-writing it.

Flow

MultiWriter → AssignOwner → EmitEvent → ProjectDownstream

Productions

NoSharedOwnership ::= <MultiWriter> "→" <AssignOwner> "→" <EmitEvent> "→" <ProjectDownstream>

Composes Resource Core, Execution Core

Forces shared-ownership (ambiguity)

Grounds none

Before

async function renameFoo(id: FooId, name: string) {
  await fooService.rename(id, name);
  await barService.patchFooName(id, name);
}

After

async function renameFoo(id: FooId, name: string) {
  await fooService.rename(id, name);
}

fooEvents.on("FooRenamed", (event) => {
  barProjection.apply(event);
});

How it is checked

Checked by the quality rules and auto-fixes that refuse the shortcut each architectural rule forbids, the cross-file quality gate

Population Every source file under a governed root

Freshness A verdict stands until the source or the rule changes

Refusal A rule that fires fails the lint stage, and an auto-fix rewrites the shortcut where the fix is deterministic

Observation The telemetry a runtime rule requires, such as observed execution, which locates a path that runs unobserved

Evidence None, because the catalog states this check as a class, so a watched run belongs to each system that adopts it

Authoritative side The architectural rule, which the source conforms to and an auto-fix rewrites toward

Depends on Resource Core, Execution Core

Shape it refuses Not answered

Bounded Lifetime Over Unbounded

Details

Intent Replace an unbounded cache with a capacity-bounded structure that evicts and clears, so memory release is deterministic.

Invariant Every retained collection has an explicit bound and an eviction policy; growth cannot be unlimited.

Flow

UnboundedStore → SetCapacity → AddEviction → ExposeClear

Productions

NoUnbounded ::= <UnboundedStore> "→" <SetCapacity> "→" <AddEviction> "→" <ExposeClear>

Composes Resource Core

Forces unbounded-lifetime (leaks)

Grounds none

Before

const fooCache = new Map<string, Foo>();

function rememberFoo(foo: Foo) {
  fooCache.set(foo.id, foo);
}

After

class FooCache {
  constructor(private readonly maxEntries: number) {}
  private readonly values = new Map<string, Foo>();

  set(foo: Foo) {
    if (this.values.size >= this.maxEntries) {
      const oldest = this.values.keys().next().value;
      if (oldest !== undefined) this.values.delete(oldest);
    }
    this.values.set(foo.id, foo);
  }

  clear() {
    this.values.clear();
  }
}

How it is checked

Checked by the quality rules and auto-fixes that refuse the shortcut each architectural rule forbids, the cross-file quality gate

Population Every source file under a governed root

Freshness A verdict stands until the source or the rule changes

Refusal A rule that fires fails the lint stage, and an auto-fix rewrites the shortcut where the fix is deterministic

Observation The telemetry a runtime rule requires, such as observed execution, which locates a path that runs unobserved

Evidence None, because the catalog states this check as a class, so a watched run belongs to each system that adopts it

Authoritative side The architectural rule, which the source conforms to and an auto-fix rewrites toward

Depends on Resource Core

Shape it refuses Not answered

Enforced Symmetry Over Asymmetric Lifecycle

Details

Intent Pair every acquire with a guaranteed release via try/finally, so a fault mid-use cannot leak the resource.

Invariant Acquisition and release are structurally symmetric; release runs on every exit path.

Flow

UnbalancedAcquire → WrapTryFinally → ReleaseInFinally → GuaranteedCleanup

Productions

NoAsymmetric ::= <UnbalancedAcquire> "→" <WrapTryFinally> "→" <ReleaseInFinally> "→" <GuaranteedCleanup>

Composes Resource Core

Forces asymmetric-lifecycle (resource-leaks)

Grounds none

Before

async function readFoo() {
  const handle = await openFoo();
  const foo = await handle.read();
  await handle.close();
  return foo;
}

After

async function readFoo() {
  const handle = await openFoo();
  try {
    return await handle.read();
  } finally {
    await handle.close();
  }
}

How it is checked

Checked by the quality rules and auto-fixes that refuse the shortcut each architectural rule forbids, the cross-file quality gate

Population Every source file under a governed root

Freshness A verdict stands until the source or the rule changes

Refusal A rule that fires fails the lint stage, and an auto-fix rewrites the shortcut where the fix is deterministic

Observation The telemetry a runtime rule requires, such as observed execution, which locates a path that runs unobserved

Evidence None, because the catalog states this check as a class, so a watched run belongs to each system that adopts it

Authoritative side The architectural rule, which the source conforms to and an auto-fix rewrites toward

Depends on Resource Core

Shape it refuses Not answered

Explicit Retention Over Implicit

Details

Intent Replace an anonymous listener push with an explicit retention token that names its owner and exposes release.

Invariant Every retained reference is held through an ownership token that can be observed and released.

Flow

AnonymousRetention → MintToken → NameOwner → ExposeRelease

Productions

NoImplicitRetention ::= <AnonymousRetention> "→" <MintToken> "→" <NameOwner> "→" <ExposeRelease>

Composes Resource Core

Forces implicit-retention (hidden-leaks)

Grounds none

Before

const listeners: Array<() => void> = [];

function watchFoo(foo: Foo) {
  listeners.push(() => console.log(foo.id));
}

After

type Retention = { owner: string; release(): void };

function retainFoo(foo: Foo, owner: string): Retention {
  const token = fooRetentions.add({ foo, owner });
  return {
    owner,
    release: () => fooRetentions.delete(token),
  };
}

How it is checked

Checked by the quality rules and auto-fixes that refuse the shortcut each architectural rule forbids, the cross-file quality gate

Population Every source file under a governed root

Freshness A verdict stands until the source or the rule changes

Refusal A rule that fires fails the lint stage, and an auto-fix rewrites the shortcut where the fix is deterministic

Observation The telemetry a runtime rule requires, such as observed execution, which locates a path that runs unobserved

Evidence None, because the catalog states this check as a class, so a watched run belongs to each system that adopts it

Authoritative side The architectural rule, which the source conforms to and an auto-fix rewrites toward

Depends on Resource Core

Shape it refuses Not answered

Structural Release Over Discipline

Details

Intent Replace manual release calls with a language disposal scope, so cleanup is enforced structurally, not by the developer's memory.

Invariant Resource cleanup is bound to scope exit by the language, not to a manually written release call.

Flow

ManualRelease → ImplementDisposable → UseScopedBinding → AutomaticCleanup

Productions

NoDisciplineRelease ::= <ManualRelease> "→" <ImplementDisposable> "→" <UseScopedBinding> "→" <AutomaticCleanup>

Composes Resource Core, Enforcement Core

Forces discipline-release (human-error)

Grounds none

Before

async function useFoo() {
  const foo = await acquireFoo();
  await processFoo(foo);
  await foo.release();
}

After

class FooLease implements Disposable {
  [Symbol.dispose]() {
    releaseFoo(this);
  }
}

function useFoo() {
  using foo = acquireFooLease();
  processFoo(foo);
}

How it is checked

Checked by the quality rules and auto-fixes that refuse the shortcut each architectural rule forbids, the cross-file quality gate

Population Every source file under a governed root

Freshness A verdict stands until the source or the rule changes

Refusal A rule that fires fails the lint stage, and an auto-fix rewrites the shortcut where the fix is deterministic

Observation The telemetry a runtime rule requires, such as observed execution, which locates a path that runs unobserved

Evidence None, because the catalog states this check as a class, so a watched run belongs to each system that adopts it

Authoritative side The architectural rule, which the source conforms to and an auto-fix rewrites toward

Depends on Resource Core, Enforcement Core

Shape it refuses Not answered

Immutable Data Over Mutable State

Details

Intent Replace in-place mutation with a pure transform returning new data, so state transitions are reproducible.

Invariant Data is readonly; a change produces a new value rather than mutating the existing one.

Flow

InPlaceMutation → MarkReadonly → ReturnNewValue → ReproducibilityGained

Productions

NoMutable ::= <InPlaceMutation> "→" <MarkReadonly> "→" <ReturnNewValue> "→" <ReproducibilityGained>

Composes Computation Core

Forces mutable-state (unpredictability)

Grounds none

Before

type Foo = { name: string; tags: string[] };

function addTag(foo: Foo, tag: string) {
  foo.tags.push(tag);
  return foo;
}

After

type Foo = Readonly<{ name: string; tags: readonly string[] }>;

function addTag(foo: Foo, tag: string): Foo {
  return { ...foo, tags: [...foo.tags, tag] };
}

How it is checked

Checked by the quality rules and auto-fixes that refuse the shortcut each architectural rule forbids, the cross-file quality gate

Population Every source file under a governed root

Freshness A verdict stands until the source or the rule changes

Refusal A rule that fires fails the lint stage, and an auto-fix rewrites the shortcut where the fix is deterministic

Observation The telemetry a runtime rule requires, such as observed execution, which locates a path that runs unobserved

Evidence None, because the catalog states this check as a class, so a watched run belongs to each system that adopts it

Authoritative side The architectural rule, which the source conforms to and an auto-fix rewrites toward

Depends on Computation Core

Shape it refuses Not answered

Errors As Language Over Silent Errors

Details

Intent Replace a null-on-failure return with a typed result union, so failure is machine-processable rather than swallowed.

Invariant A fallible operation returns a discriminated ok/error result; failure carries a typed code.

Flow

NullOnFailure → DefineResultUnion → ReturnTypedError → ForceHandling

Productions

NoSilent ::= <NullOnFailure> "→" <DefineResultUnion> "→" <ReturnTypedError> "→" <ForceHandling>

Composes Computation Core, Correctness Core

Forces silent-errors (unknown-failure)

Grounds none

Before

function parseFoo(raw: string): Foo | null {
  try {
    return JSON.parse(raw) as Foo;
  } catch {
    return null;
  }
}

After

type ParseFooResult =
  | { ok: true; value: Foo }
  | {
      ok: false;
      error: { code: "INVALID_JSON" | "INVALID_FOO"; detail: string };
    };

function parseFoo(raw: string): ParseFooResult {
  try {
    const value = JSON.parse(raw);
    return isFoo(value)
      ? { ok: true, value }
      : {
          ok: false,
          error: { code: "INVALID_FOO", detail: "schema mismatch" },
        };
  } catch (error) {
    return {
      ok: false,
      error: { code: "INVALID_JSON", detail: String(error) },
    };
  }
}

How it is checked

Checked by the quality rules and auto-fixes that refuse the shortcut each architectural rule forbids, the cross-file quality gate

Population Every source file under a governed root

Freshness A verdict stands until the source or the rule changes

Refusal A rule that fires fails the lint stage, and an auto-fix rewrites the shortcut where the fix is deterministic

Observation The telemetry a runtime rule requires, such as observed execution, which locates a path that runs unobserved

Evidence None, because the catalog states this check as a class, so a watched run belongs to each system that adopts it

Authoritative side The architectural rule, which the source conforms to and an auto-fix rewrites toward

Depends on Computation Core, Correctness Core

Shape it refuses Not answered

Explicit Invalidity Over Hidden

Details

Intent Model invalid state as an explicit variant rather than coercing to a plausible default that hides uncertainty.

Invariant Validity is a represented state; invalid inputs map to an invalid variant, never a silent valid default.

Flow

CoercedDefault → AddInvalidVariant → MapInvalidInputs → HonestUncertainty

Productions

NoHiddenInvalidity ::= <CoercedDefault> "→" <AddInvalidVariant> "→" <MapInvalidInputs> "→" <HonestUncertainty>

Composes Computation Core, Correctness Core

Forces hidden-invalidity (false-consistency)

Grounds none

Before

type FooState = { count: number };

function readFooCount(raw: unknown): FooState {
  return { count: typeof raw === "number" ? raw : 0 };
}

After

type FooState =
  | { status: "valid"; count: number }
  | { status: "invalid"; reason: "NOT_A_NUMBER" };

function readFooCount(raw: unknown): FooState {
  return typeof raw === "number"
    ? { status: "valid", count: raw }
    : { status: "invalid", reason: "NOT_A_NUMBER" };
}

How it is checked

Checked by the quality rules and auto-fixes that refuse the shortcut each architectural rule forbids, the cross-file quality gate

Population Every source file under a governed root

Freshness A verdict stands until the source or the rule changes

Refusal A rule that fires fails the lint stage, and an auto-fix rewrites the shortcut where the fix is deterministic

Observation The telemetry a runtime rule requires, such as observed execution, which locates a path that runs unobserved

Evidence None, because the catalog states this check as a class, so a watched run belongs to each system that adopts it

Authoritative side The architectural rule, which the source conforms to and an auto-fix rewrites toward

Depends on Computation Core, Correctness Core

Shape it refuses Not answered

Event Emission Over Parent Callbacks

Details

Intent Replace a parent-supplied callback with an emitted event, decoupling the producer from its consumers.

Invariant A component announces facts via events; it holds no reference to who reacts.

Flow

ParentCallback → DefineEvent → EmitFact → SubscribeExternally

Productions

NoCallbacks ::= <ParentCallback> "→" <DefineEvent> "→" <EmitFact> "→" <SubscribeExternally>

Composes Execution Core, Coupling Control

Forces parent-callbacks (tight-coupling)

Grounds none

Before

class FooEditor {
  constructor(private readonly onSaved: (foo: Foo) => void) {}

  save(foo: Foo) {
    fooStore.save(foo);
    this.onSaved(foo);
  }
}

After

class FooEditor {
  constructor(private readonly events: EventSink) {}

  save(foo: Foo) {
    fooStore.save(foo);
    this.events.emit({ type: "FooSaved", fooId: foo.id });
  }
}

fooEvents.on("FooSaved", (event) => refreshFooView(event.fooId));

How it is checked

Checked by the quality rules and auto-fixes that refuse the shortcut each architectural rule forbids, the cross-file quality gate

Population Every source file under a governed root

Freshness A verdict stands until the source or the rule changes

Refusal A rule that fires fails the lint stage, and an auto-fix rewrites the shortcut where the fix is deterministic

Observation The telemetry a runtime rule requires, such as observed execution, which locates a path that runs unobserved

Evidence None, because the catalog states this check as a class, so a watched run belongs to each system that adopts it

Authoritative side The architectural rule, which the source conforms to and an auto-fix rewrites toward

Depends on Execution Core, Coupling Control

Shape it refuses Not answered

Monotonic Growth Over Retraction

Details

Intent Replace destructive deletion with an append-only removal event, so history is monotonic and projectable.

Invariant State changes append events; nothing is deleted in place, and current state is a projection.

Flow

DestructiveDelete → DefineEventLog → AppendRemoval → ProjectCurrent

Productions

NoRetraction ::= <DestructiveDelete> "→" <DefineEventLog> "→" <AppendRemoval> "→" <ProjectCurrent>

Composes Execution Core, Causality Core

Forces retraction (complexity)

Grounds none

Before

type FooIndex = Map<FooId, Foo>;

function deleteFoo(index: FooIndex, id: FooId) {
  index.delete(id);
}

After

type FooEvent =
  | { seq: number; type: "FooAdded"; foo: Foo }
  | { seq: number; type: "FooRemoved"; fooId: FooId };

function removeFoo(log: FooEvent[], id: FooId) {
  log.push({ seq: log.length + 1, type: "FooRemoved", fooId: id });
}

const currentFoos = projectFoos(log);

How it is checked

Checked by the quality rules and auto-fixes that refuse the shortcut each architectural rule forbids, the cross-file quality gate

Population Every source file under a governed root

Freshness A verdict stands until the source or the rule changes

Refusal A rule that fires fails the lint stage, and an auto-fix rewrites the shortcut where the fix is deterministic

Observation The telemetry a runtime rule requires, such as observed execution, which locates a path that runs unobserved

Evidence None, because the catalog states this check as a class, so a watched run belongs to each system that adopts it

Authoritative side The architectural rule, which the source conforms to and an auto-fix rewrites toward

Depends on Execution Core, Causality Core

Shape it refuses Not answered

Semantic Addressing Over Location Addressing

Details

Intent Replace positional path addressing with a semantic identity reference, so references survive structural change.

Invariant An entity is referenced by stable identity, never by its position within a container.

Flow

PositionalRef → AssignIdentity → ReferenceById → ResolveByLookup

Productions

NoLocation ::= <PositionalRef> "→" <AssignIdentity> "→" <ReferenceById> "→" <ResolveByLookup>

Composes Structural Core

Forces location-addressing (brittleness)

Grounds none

Before

const foo = document.sections[2].items[4];
const reference = "sections[2].items[4]";

After

type FooRef = { kind: "foo"; id: FooId };

const reference: FooRef = { kind: "foo", id: fooId("foo_primary") };
const foo = document.foosById.get(reference.id);

How it is checked

Checked by the quality rules and auto-fixes that refuse the shortcut each architectural rule forbids, the cross-file quality gate

Population Every source file under a governed root

Freshness A verdict stands until the source or the rule changes

Refusal A rule that fires fails the lint stage, and an auto-fix rewrites the shortcut where the fix is deterministic

Observation The telemetry a runtime rule requires, such as observed execution, which locates a path that runs unobserved

Evidence None, because the catalog states this check as a class, so a watched run belongs to each system that adopts it

Authoritative side The architectural rule, which the source conforms to and an auto-fix rewrites toward

Depends on Structural Core

Shape it refuses Not answered

Ordinal Time Over Timestamps

Details

Intent Replace wall-clock ordering with an ordinal sequence, so event order is logical and clock-independent.

Invariant Ordering derives from a monotonic ordinal, not a physical timestamp subject to skew.

Flow

WallClockOrder → AssignOrdinal → AppendWithOrdinal → SortByOrdinal

Productions

NoTimestamps ::= <WallClockOrder> "→" <AssignOrdinal> "→" <AppendWithOrdinal> "→" <SortByOrdinal>

Composes Causality Core, Execution Core

Forces timestamp-ordering (wall-clock-dependency)

Grounds none

Before

type FooEvent = { at: number; value: string };

const events = received.map((value) => ({ at: Date.now(), value }));
events.sort((a, b) => a.at - b.at);

After

type FooEvent = { ordinal: bigint; value: string };

function appendFoo(value: string): FooEvent {
  return fooLog.append(nextOrdinal(), value);
}

const events = fooLog.read().sort((a, b) => Number(a.ordinal - b.ordinal));

How it is checked

Checked by the quality rules and auto-fixes that refuse the shortcut each architectural rule forbids, the cross-file quality gate

Population Every source file under a governed root

Freshness A verdict stands until the source or the rule changes

Refusal A rule that fires fails the lint stage, and an auto-fix rewrites the shortcut where the fix is deterministic

Observation The telemetry a runtime rule requires, such as observed execution, which locates a path that runs unobserved

Evidence None, because the catalog states this check as a class, so a watched run belongs to each system that adopts it

Authoritative side The architectural rule, which the source conforms to and an auto-fix rewrites toward

Depends on Causality Core, Execution Core

Shape it refuses Not answered

Homoiconicity Over Separation

Details

Intent Fuse behavior and its separate metadata into one homoiconic data structure that is both the rule and its description.

Invariant A rule is represented as data that is directly evaluated; no parallel metadata can drift from it.

Flow

CodeAndMetadata → DefineExprData → EvaluateData → SingleSource

Productions

NoSeparation ::= <CodeAndMetadata> "→" <DefineExprData> "→" <EvaluateData> "→" <SingleSource>

Composes Structural Core, Declarative Core

Forces separation (duplication)

Grounds none

Before

function calculateFoo(foo: Foo) {
  return foo.value * 2;
}

const fooRuleMetadata = {
  operation: "multiply",
  operand: 2,
};

After

type Expr =
  | { op: "value"; key: keyof Foo }
  | { op: "const"; value: number }
  | { op: "multiply"; left: Expr; right: Expr };

const fooRule: Expr = {
  op: "multiply",
  left: { op: "value", key: "value" },
  right: { op: "const", value: 2 },
};

const result = evaluate(fooRule, foo);

How it is checked

Checked by the quality rules and auto-fixes that refuse the shortcut each architectural rule forbids, the cross-file quality gate

Population Every source file under a governed root

Freshness A verdict stands until the source or the rule changes

Refusal A rule that fires fails the lint stage, and an auto-fix rewrites the shortcut where the fix is deterministic

Observation The telemetry a runtime rule requires, such as observed execution, which locates a path that runs unobserved

Evidence None, because the catalog states this check as a class, so a watched run belongs to each system that adopts it

Authoritative side The architectural rule, which the source conforms to and an auto-fix rewrites toward

Depends on Structural Core, Declarative Core

Shape it refuses Not answered

Bounded Complexity Over Unlimited

Details

Intent Constrain an open-ended rule surface to a bounded grammar with depth and fan-out limits, capping cognitive load.

Invariant A rule structure has enforced maximum depth and breadth; unbounded nesting is rejected.

Flow

OpenEndedRule → DefineBoundedGrammar → ValidateDepth → ValidateFanOut

Productions

NoUnlimited ::= <OpenEndedRule> "→" <DefineBoundedGrammar> "→" <ValidateDepth> "→" <ValidateFanOut>

Composes Human Factors, Structural Core

Forces unlimited-complexity (cognitive-overload)

Grounds none

Before

type FooRule = {
  run(context: unknown): unknown;
};

function execute(rule: FooRule) {
  return rule.run(globalThis);
}

After

type FooRule =
  | { op: "equals"; field: "name" | "kind"; value: string }
  | { op: "all"; rules: readonly FooRule[] };

function validateRule(rule: FooRule, depth = 0): void {
  if (depth > 5) throw new Error("FooRule depth exceeds 5");
  if (rule.op === "all") {
    if (rule.rules.length > 10) throw new Error("FooRule fan-out exceeds 10");
    rule.rules.forEach((child) => validateRule(child, depth + 1));
  }
}

How it is checked

Checked by the quality rules and auto-fixes that refuse the shortcut each architectural rule forbids, the cross-file quality gate

Population Every source file under a governed root

Freshness A verdict stands until the source or the rule changes

Refusal A rule that fires fails the lint stage, and an auto-fix rewrites the shortcut where the fix is deterministic

Observation The telemetry a runtime rule requires, such as observed execution, which locates a path that runs unobserved

Evidence None, because the catalog states this check as a class, so a watched run belongs to each system that adopts it

Authoritative side The architectural rule, which the source conforms to and an auto-fix rewrites toward

Depends on Human Factors, Structural Core

Shape it refuses Not answered

Computed Health Over Metric Health

Details

Intent Replace threshold-on-metrics health with a symbolic diagnosis that names the causes of an unready state.

Invariant Health is a computed state naming concrete blocking causes, not a boolean over numeric thresholds.

Flow

MetricThreshold → EnumerateCauses → ComputeState → NameBlockers

Productions

NoMetrics ::= <MetricThreshold> "→" <EnumerateCauses> "→" <ComputeState> "→" <NameBlockers>

Composes Observability, Correctness Core

Forces metric-health (symptom-tracking)

Grounds none

Before

function fooHealth(metrics: { errorRate: number; latencyMs: number }) {
  return metrics.errorRate < 0.01 && metrics.latencyMs < 200
    ? "healthy"
    : "unhealthy";
}

After

type FooHealth =
  | { state: "ready" }
  | {
      state: "blocked";
      causes: readonly ("STORE_UNREACHABLE" | "SCHEMA_MISMATCH")[];
    };

function fooHealth(status: {
  storeReachable: boolean;
  schemaCompatible: boolean;
}): FooHealth {
  const causes = [
    ...(!status.storeReachable ? ["STORE_UNREACHABLE" as const] : []),
    ...(!status.schemaCompatible ? ["SCHEMA_MISMATCH" as const] : []),
  ];
  return causes.length ? { state: "blocked", causes } : { state: "ready" };
}

How it is checked

Checked by the quality rules and auto-fixes that refuse the shortcut each architectural rule forbids, the cross-file quality gate

Population Every source file under a governed root

Freshness A verdict stands until the source or the rule changes

Refusal A rule that fires fails the lint stage, and an auto-fix rewrites the shortcut where the fix is deterministic

Observation The telemetry a runtime rule requires, such as observed execution, which locates a path that runs unobserved

Evidence None, because the catalog states this check as a class, so a watched run belongs to each system that adopts it

Authoritative side The architectural rule, which the source conforms to and an auto-fix rewrites toward

Depends on Observability, Correctness Core

Shape it refuses Not answered

Secret Store Over Hardcoded Secrets

Details

Intent Replace an inline secret with a resolved read from a secret store that fails fast when the secret is absent.

Invariant No secret literal appears in source; secrets are read at runtime from a store and validated present.

Flow

InlineSecret → MoveToStore → ResolveAtRuntime → FailIfMissing

Productions

NoHardcodedSecrets ::= <InlineSecret> "→" <MoveToStore> "→" <ResolveAtRuntime> "→" <FailIfMissing>

Composes Security Core

Forces hardcoded-secrets (exposure)

Principle Secrets Management

Grounds none

Before

const fooClient = new FooClient({
  apiKey: "foo_live_abc123",
});

After

async function makeFooClient(secrets: SecretStore) {
  const apiKey = await secrets.read("services/foo/api-key");
  if (!apiKey) throw new Error("missing services/foo/api-key");
  return new FooClient({ apiKey });
}

How it is checked

Checked by the quality rules and auto-fixes that refuse the shortcut each architectural rule forbids, the cross-file quality gate

Population Every source file under a governed root

Freshness A verdict stands until the source or the rule changes

Refusal A rule that fires fails the lint stage, and an auto-fix rewrites the shortcut where the fix is deterministic

Observation The telemetry a runtime rule requires, such as observed execution, which locates a path that runs unobserved

Evidence None, because the catalog states this check as a class, so a watched run belongs to each system that adopts it

Authoritative side The architectural rule, which the source conforms to and an auto-fix rewrites toward

Depends on Security Core

Shape it refuses Not answered

Boundary Validation Over Unvalidated Input

Details

Intent Parse and validate untrusted input at the boundary into a typed shape, failing fast on malformed data.

Invariant Input crosses the boundary only after schema validation; no raw external value reaches the core.

Flow

RawInput → ParseAtBoundary → ValidateSchema → PassTypedValue

Productions

NoUnvalidatedInput ::= <RawInput> "→" <ParseAtBoundary> "→" <ValidateSchema> "→" <PassTypedValue>

Composes Security Core, Correctness Core

Forces unvalidated-input (injection)

Principle Input Validation

Grounds none

Before

async function createFoo(request: Request) {
  const body = (await request.json()) as any;
  return fooDb.query(`insert into foo(name) values ('${body.name}')`);
}

After

type CreateFoo = { name: string };

function parseCreateFoo(value: unknown): CreateFoo {
  if (!value || typeof value !== "object")
    throw new Error("body must be an object");
  const name = (value as Record<string, unknown>).name;
  if (typeof name !== "string" || name.length < 1 || name.length > 40) {
    throw new Error("name must be 1..40 characters");
  }
  return { name };
}

async function createFoo(request: Request) {
  const input = parseCreateFoo(await request.json());
  return fooDb.query("insert into foo(name) values (?)", input.name);
}

How it is checked

Checked by the quality rules and auto-fixes that refuse the shortcut each architectural rule forbids, the cross-file quality gate

Population Every source file under a governed root

Freshness A verdict stands until the source or the rule changes

Refusal A rule that fires fails the lint stage, and an auto-fix rewrites the shortcut where the fix is deterministic

Observation The telemetry a runtime rule requires, such as observed execution, which locates a path that runs unobserved

Evidence None, because the catalog states this check as a class, so a watched run belongs to each system that adopts it

Authoritative side The architectural rule, which the source conforms to and an auto-fix rewrites toward

Depends on Security Core, Correctness Core

Shape it refuses Not answered

Least Privilege Over Broad Privilege

Details

Intent Narrow a broad capability to the minimal typed interface a task needs, shrinking the blast radius.

Invariant A component receives only the narrow capability its task requires, never an ambient broad authority.

Flow

BroadCapability → DefineNarrowInterface → InjectMinimal → DenyRest

Productions

NoBroadPrivilege ::= <BroadCapability> "→" <DefineNarrowInterface> "→" <InjectMinimal> "→" <DenyRest>

Composes Security Core, Coupling Control

Forces broad-privilege (blast-radius)

Principle Least Privilege

Grounds none

Before

class FooJob {
  constructor(private readonly admin: AdminDatabase) {}

  run(foo: Foo) {
    return this.admin.execute(
      `delete from bar; insert into foo values (?)`,
      foo,
    );
  }
}

After

interface FooWriter {
  insert(foo: Foo): Promise<void>;
}

class FooJob {
  constructor(private readonly foos: FooWriter) {}

  run(foo: Foo) {
    return this.foos.insert(foo);
  }
}

How it is checked

Checked by the quality rules and auto-fixes that refuse the shortcut each architectural rule forbids, the cross-file quality gate

Population Every source file under a governed root

Freshness A verdict stands until the source or the rule changes

Refusal A rule that fires fails the lint stage, and an auto-fix rewrites the shortcut where the fix is deterministic

Observation The telemetry a runtime rule requires, such as observed execution, which locates a path that runs unobserved

Evidence None, because the catalog states this check as a class, so a watched run belongs to each system that adopts it

Authoritative side The architectural rule, which the source conforms to and an auto-fix rewrites toward

Depends on Security Core, Coupling Control

Shape it refuses Not answered

Config Externalization Over Env Fallback

Details

Intent Replace env-var-or-default reads with a validated config loaded at boot that fails fast on missing values.

Invariant Configuration is parsed and validated once at startup; a missing required var halts boot.

Flow

EnvOrDefault → DefineConfigSchema → LoadAtBoot → FailIfIncomplete

Productions

NoEnvFallback ::= <EnvOrDefault> "→" <DefineConfigSchema> "→" <LoadAtBoot> "→" <FailIfIncomplete>

Composes Security Core, Resource Core

Forces env-fallback-default (silent-misconfig)

Grounds none

Before

const fooUrl = process.env.FOO_URL || "http://localhost:3000";
const retryCount = Number(process.env.FOO_RETRIES || "3");

After

type AppConfig = Readonly<{ fooUrl: URL; retryCount: number }>;

function loadConfig(env: NodeJS.ProcessEnv): AppConfig {
  if (!env.FOO_URL) throw new Error("FOO_URL is required");
  if (!env.FOO_RETRIES) throw new Error("FOO_RETRIES is required");
  const retryCount = Number(env.FOO_RETRIES);
  if (!Number.isInteger(retryCount) || retryCount < 0)
    throw new Error("invalid FOO_RETRIES");
  return Object.freeze({ fooUrl: new URL(env.FOO_URL), retryCount });
}

const config = loadConfig(process.env);

How it is checked

Checked by the quality rules and auto-fixes that refuse the shortcut each architectural rule forbids, the cross-file quality gate

Population Every source file under a governed root

Freshness A verdict stands until the source or the rule changes

Refusal A rule that fires fails the lint stage, and an auto-fix rewrites the shortcut where the fix is deterministic

Observation The telemetry a runtime rule requires, such as observed execution, which locates a path that runs unobserved

Evidence None, because the catalog states this check as a class, so a watched run belongs to each system that adopts it

Authoritative side The architectural rule, which the source conforms to and an auto-fix rewrites toward

Depends on Security Core, Resource Core

Shape it refuses Not answered

Profile-First Over Unmeasured Optimization

Details

Intent Gate any optimization behind a measured profile, so effort is evidence-driven rather than speculative.

Invariant A performance change is justified by a before/after measurement of the actual bottleneck.

Flow

SuspectedHotspot → Profile → IdentifyBottleneck → OptimizeMeasured → Verify

Productions

NoUnmeasuredOptimization ::= <SuspectedHotspot> "→" <Profile> "→" <IdentifyBottleneck> "→" <OptimizeMeasured> "→" <Verify>

Composes Performance Core

Forces unmeasured-optimization (guesswork)

Grounds none

Before

const fooCache = new Map<string, Foo>();

function getFoo(id: string) {
  if (!fooCache.has(id)) fooCache.set(id, expensiveLookup(id));
  return fooCache.get(id)!;
}

After

const profile = profiler.measure("foo.batch", () => {
  for (const id of fooIds) expensiveLookup(id);
});

if (profile.hotspot === "repeated-foo-lookup") {
  const foos = fooStore.getMany(fooIds);
  consume(foos);
}

How it is checked

Checked by the quality rules and auto-fixes that refuse the shortcut each architectural rule forbids, the cross-file quality gate

Population Every source file under a governed root

Freshness A verdict stands until the source or the rule changes

Refusal A rule that fires fails the lint stage, and an auto-fix rewrites the shortcut where the fix is deterministic

Observation The telemetry a runtime rule requires, such as observed execution, which locates a path that runs unobserved

Evidence None, because the catalog states this check as a class, so a watched run belongs to each system that adopts it

Authoritative side The architectural rule, which the source conforms to and an auto-fix rewrites toward

Depends on Performance Core

Shape it refuses Not answered

Rule As Code Over Convention

Details

Intent Replace a written convention with an automated gate, so the invariant is enforced by code not by memory.

Invariant Every stated invariant has an executable check that fails the build on violation.

Flow

WrittenConvention → EncodeCheck → WireGate → FailOnViolation

Productions

NoConventionEnforcement ::= <WrittenConvention> "→" <EncodeCheck> "→" <WireGate> "→" <FailOnViolation>

Composes Enforcement Core, Structural Core

Forces convention-only-enforcement (drift)

Grounds none

Before

import { sql } from "../infrastructure/database";

export function makeFoo() {
  return sql("select * from foo");
}

After

const architectureRule = forbidImports({
  from: "src/domain/**",
  to: "src/infrastructure/**",
});

for (const violation of architectureRule.scan(projectGraph)) {
  throw new Error(`forbidden dependency: ${violation.from} → ${violation.to}`);
}

How it is checked

Checked by the quality rules and auto-fixes that refuse the shortcut each architectural rule forbids, the cross-file quality gate

Population Every source file under a governed root

Freshness A verdict stands until the source or the rule changes

Refusal A rule that fires fails the lint stage, and an auto-fix rewrites the shortcut where the fix is deterministic

Observation The telemetry a runtime rule requires, such as observed execution, which locates a path that runs unobserved

Evidence None, because the catalog states this check as a class, so a watched run belongs to each system that adopts it

Authoritative side The architectural rule, which the source conforms to and an auto-fix rewrites toward

Depends on Enforcement Core, Structural Core

Shape it refuses Not answered

Design By Contract Over Implicit Contract

Details

Intent State pre-conditions, post-conditions, and invariants explicitly, so a boundary's contract is checkable not assumed.

Invariant A boundary declares and enforces its pre/post/invariant conditions; callers are not left to guess.

Flow

ImplicitAssumption → StatePreconditions → StatePostconditions → EnforceInvariants

Productions

NoImplicitContract ::= <ImplicitAssumption> "→" <StatePreconditions> "→" <StatePostconditions> "→" <EnforceInvariants>

Composes Contracts Core, Correctness Core

Forces implicit-contract (silent-breakage)

Grounds none

Before

function divideFoo(total: number, count: number) {
  return total / count;
}

After

function divideFoo(total: number, count: number): number {
  if (!Number.isFinite(total)) throw new Error("pre: total must be finite");
  if (!Number.isInteger(count) || count <= 0)
    throw new Error("pre: count must be positive");

  const result = total / count;

  if (!Number.isFinite(result)) throw new Error("post: result must be finite");
  return result;
}

How it is checked

Checked by the quality rules and auto-fixes that refuse the shortcut each architectural rule forbids, the cross-file quality gate

Population Every source file under a governed root

Freshness A verdict stands until the source or the rule changes

Refusal A rule that fires fails the lint stage, and an auto-fix rewrites the shortcut where the fix is deterministic

Observation The telemetry a runtime rule requires, such as observed execution, which locates a path that runs unobserved

Evidence None, because the catalog states this check as a class, so a watched run belongs to each system that adopts it

Authoritative side The architectural rule, which the source conforms to and an auto-fix rewrites toward

Depends on Contracts Core, Correctness Core

Shape it refuses Not answered

Versioned Evolution Over Breaking Change

Details

Intent Introduce change behind a version so existing consumers keep a stable contract while new ones adopt the new shape.

Invariant A contract change is additive or versioned; no in-place change breaks an existing consumer silently.

Flow

InPlaceChange → IntroduceVersion → RunBothContracts → MigrateConsumers

Productions

NoBreakingChange ::= <InPlaceChange> "→" <IntroduceVersion> "→" <RunBothContracts> "→" <MigrateConsumers>

Composes Contracts Core, Evolution Principles

Forces unversioned-breaking-change (consumer-breakage)

Principle Versioning

Grounds none

Before

app.get("/foo", () => ({ label: "Foo", tag

© 2025 Jay Baleine - Disciplined Methodology · Bane's Lab documentation is covered by CC BY-SA 4.0

Navigation

Home

Reading path PAG

Methodology

Architecture

Ontology

Anatomy

FAQ

Links

Clone this wiki locally