273 lines
7 KiB
Markdown
273 lines
7 KiB
Markdown
# Normative Rules
|
||
|
||
The ABC Pattern is defined by a set of Normative Rules that establish the
|
||
structural, behavioral, and data‑flow guarantees of the architecture. These
|
||
rules are the foundation that makes ABC:
|
||
|
||
* predictable
|
||
* composable
|
||
* verifiable
|
||
* agent‑friendly
|
||
* implementation‑agnostic
|
||
|
||
Normative Rules describe what MUST or SHOULD be true in any ABC‑compliant
|
||
architecture, regardless of the underlying cloud provider, IaC tool, or
|
||
programming language. They are not suggestions or stylistic preferences; they
|
||
are the semantic constraints that ensure ABC constructs behave consistently and
|
||
safely.
|
||
|
||
Each rule is assigned a canonical identifier of the form:
|
||
|
||
```default
|
||
ABC-R#
|
||
```
|
||
|
||
This identifier is stable, unique, and referenced throughout:
|
||
|
||
* the ABC Schema
|
||
* validation rules
|
||
* implementation profiles (e.g., CDKTS, Terraform)
|
||
* agent guidance
|
||
* tooling and linters
|
||
|
||
## Hierarchy Rules
|
||
|
||
These define the allowed structure of an ABC architecture, including the roles
|
||
and relationships of ApplicationStacks, Logical Units, and Resource Groups.
|
||
|
||
### ABC‑R1 (MUST)
|
||
|
||
An Application Stack (ABC‑C1) MUST contain one or more Logical Units (ABC‑C2).
|
||
|
||
### ABC‑R2 (MUST)
|
||
|
||
A Logical Unit (ABC‑C2) MUST contain one or more Resource Groups (ABC‑C3).
|
||
|
||
### ABC‑R3 (MUST)
|
||
|
||
Every Construct (ABC‑C0) MUST have exactly one parent, except the Application
|
||
Stack (ABC‑C1), which has none.
|
||
|
||
### ABC‑R4 (MUST)
|
||
|
||
Constructs MUST form a strict tree hierarchy with no cycles.
|
||
|
||
### ABC‑R5 (SHOULD)
|
||
|
||
Logical Units (ABC‑C2) SHOULD represent coherent functional domains.
|
||
|
||
### ABC‑R6 (MAY)
|
||
|
||
Resource Groups (ABC‑C3) MAY be nested further if the implementation framework
|
||
supports sub‑constructs, provided all other rules remain satisfied.
|
||
|
||
## Relationship Rules
|
||
|
||
Specify how constructs relate to one another, including parent‑child
|
||
constraints, allowed dependencies, and prohibited lateral references.
|
||
|
||
### ABC‑R10 (MUST)
|
||
|
||
A Resource Group (ABC‑C3) MUST NOT reference another Resource Group directly.
|
||
|
||
### ABC‑R11 (MUST)
|
||
|
||
A Logical Unit (ABC‑C2) MUST NOT reference another Logical Unit directly.
|
||
|
||
### ABC‑R12 (MUST)
|
||
|
||
A Construct (ABC‑C0) MUST NOT access parent state except through Capturing Down
|
||
(ABC‑F1).
|
||
|
||
### ABC‑R13 (MUST)
|
||
|
||
A Construct (ABC‑C0) MUST NOT access sibling state under any circumstances.
|
||
|
||
### ABC‑R14 (MUST)
|
||
|
||
All cross‑domain communication MUST be mediated by the parent construct.
|
||
|
||
### ABC‑R15 (SHOULD)
|
||
|
||
Constructs SHOULD minimize the number of outputs they expose to reduce coupling.
|
||
|
||
### ABC‑R16 (MAY)
|
||
|
||
A parent MAY aggregate outputs from multiple children before re‑exposing them.
|
||
|
||
## Interface Rules
|
||
|
||
Define the semantics of Input and Output Contracts, including immutability,
|
||
explicitness, and the boundaries they enforce.
|
||
|
||
### ABC‑R20 (MUST)
|
||
|
||
Every Construct (ABC‑C0) MUST define an Input Contract (ABC‑C4).
|
||
|
||
### ABC‑R21 (MUST)
|
||
|
||
Every Construct (ABC‑C0) MUST define an Output Contract (ABC‑C5), even if empty.
|
||
|
||
### ABC‑R22 (MUST)
|
||
|
||
A Construct MUST NOT depend on any value not present in its Input Contract.
|
||
|
||
### ABC‑R23 (MUST)
|
||
|
||
A Construct MUST NOT expose any value not present in its Output Contract.
|
||
|
||
### ABC‑R24 (MUST)
|
||
|
||
Input Contracts MUST be immutable after instantiation.
|
||
|
||
### ABC‑R25 (SHOULD)
|
||
|
||
Output Contracts SHOULD be minimal and stable across versions.
|
||
|
||
### ABC‑R26 (MAY)
|
||
|
||
A Construct MAY expose composite outputs if they simplify parent‑level wiring.
|
||
|
||
## Instantiation Rules
|
||
|
||
Specify how constructs are created, how inputs are provided, and how
|
||
instantiation must avoid side effects or hidden dependencies.
|
||
|
||
### ABC‑R30 (MUST)
|
||
|
||
A Construct (ABC‑C0) MUST be instantiated exclusively through its Instantiation
|
||
Interface (ABC‑C6).
|
||
|
||
### ABC‑R31 (MUST)
|
||
|
||
Instantiation MUST be top‑down: parents instantiate children; children MUST NOT
|
||
instantiate parents or siblings.
|
||
|
||
### ABC‑R32 (MUST)
|
||
|
||
The Instantiation Interface MUST accept only the Input Contract (ABC‑C4) and no
|
||
additional parameters.
|
||
|
||
### ABC‑R33 (MUST)
|
||
|
||
Instantiation MUST NOT produce side effects beyond constructing the child.
|
||
|
||
### ABC‑R34 (SHOULD)
|
||
|
||
Instantiation Interfaces SHOULD remain stable across minor revisions.
|
||
|
||
### ABC‑R35 (MAY)
|
||
|
||
Constructs MAY provide optional parameters in the Input Contract if defaults are
|
||
well‑defined.
|
||
|
||
## Data Flow Rules
|
||
|
||
Formalize the two fundamental ABC data‑flow mechanisms:
|
||
|
||
* Capturing Down (parent → child)
|
||
* Bubbling Up (child → parent)
|
||
|
||
These rules ensure that all communication flows through the parent construct,
|
||
eliminating ambiguity and hidden coupling.
|
||
|
||
### ABC‑R40 (MUST)
|
||
|
||
All downward data flow MUST occur through Capturing Down (ABC‑F1).
|
||
|
||
### ABC‑R41 (MUST)
|
||
|
||
All upward data flow MUST occur through Bubbling Up (ABC‑F2).
|
||
|
||
### ABC‑R42 (MUST)
|
||
|
||
A Construct MUST NOT read values from its parent except those explicitly passed
|
||
via Capturing Down.
|
||
|
||
### ABC‑R43 (MUST)
|
||
|
||
A Construct MUST NOT write values to its parent except through Bubbling Up.
|
||
|
||
### ABC‑R44 (MUST)
|
||
|
||
Parents MUST mediate all routing of outputs between children.
|
||
|
||
### ABC‑R45 (SHOULD)
|
||
|
||
Parents SHOULD avoid passing unnecessary outputs downward to reduce coupling.
|
||
|
||
### ABC‑R46 (MAY)
|
||
|
||
Parents MAY transform outputs before passing them down.
|
||
|
||
## Encapsulation & Testability Rules
|
||
|
||
Ensure that constructs remain isolated, testable, and free from cross‑cutting
|
||
concerns. These rules prevent leakage of internal details and enforce strict
|
||
boundaries.
|
||
|
||
### ABC‑R50 (MUST)
|
||
|
||
Constructs MUST encapsulate all internal implementation details.
|
||
|
||
### ABC‑R51 (MUST)
|
||
|
||
Constructs MUST be instantiable in isolation using mock Input Contracts.
|
||
|
||
### ABC‑R52 (SHOULD)
|
||
|
||
Constructs SHOULD avoid exposing internal resource identifiers unless required.
|
||
|
||
### ABC‑R53 (SHOULD)
|
||
|
||
Constructs SHOULD minimize internal state to simplify testing.
|
||
|
||
### ABC‑R54 (MAY)
|
||
|
||
Constructs MAY provide diagnostic outputs if they do not violate encapsulation.
|
||
|
||
## Evolution & Change Management Rules
|
||
|
||
Define how ABC architectures evolve safely over time, including versioning,
|
||
contract stability, and backward‑compatible changes.
|
||
|
||
### ABC‑R60 (MUST)
|
||
|
||
If a child’s Output Contract changes, the parent MUST adapt explicitly.
|
||
|
||
### ABC‑R61 (MUST)
|
||
|
||
Breaking changes to Input Contracts MUST be versioned or documented.
|
||
|
||
### ABC‑R62 (SHOULD)
|
||
|
||
Constructs SHOULD maintain backward compatibility where feasible.
|
||
|
||
### ABC‑R63 (SHOULD)
|
||
|
||
Parents SHOULD validate child outputs before routing them.
|
||
|
||
### ABC‑R64 (MAY)
|
||
|
||
Constructs MAY deprecate fields gradually before removal.
|
||
|
||
## Optional Flexibility Rules
|
||
|
||
Provide non‑mandatory guidance that enhances clarity, maintainability, or
|
||
ergonomics without affecting correctness. These rules are advisory and may be
|
||
adopted at the discretion of the implementation or team.
|
||
|
||
### ABC‑R70 (MAY)
|
||
|
||
Logical Units MAY be composed dynamically if the framework supports it, provided
|
||
all other rules remain satisfied.
|
||
|
||
### ABC‑R71 (MAY)
|
||
|
||
Resource Groups MAY be reused across Logical Units if instantiated
|
||
independently.
|
||
|
||
### ABC‑R72 (MAY)
|
||
|
||
The Application Stack MAY expose a composite Output Contract aggregating all
|
||
Logical Unit outputs.
|