tiararodney/abc-spec
2
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

init

Browse source
This commit is contained in:
Tiara Rodney 2026-02-05 01:54:17 +01:00
parent 0d674783f6
commit 3cffcc9ee4
No known key found for this signature in database
GPG key ID: 5CD8EC1D46106723
18 changed files with 2938 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

1
src/.gitignore vendored Normal file
View file

@ -0,0 +1 @@
/.doctrees/

198
src/AGENTS.rst Normal file
View file

@ -0,0 +1,198 @@
######
AGENTS
######
Operational Guidance for Autonomous Agents Using specification (ABC Specification)
==================================================================================
MUST USE ``index.md`` as entrypoint for specification and subsequent referenced
documents within.
Purpose of this document
------------------------
This document defines how an autonomous agent must operate when using the
Abstract Base Cloud (ABC) Specification (specification) as the authoritative
source of truth. It does not redefine, summarize, or restate the ABC Pattern.
Its purpose is to establish procedures, behaviors, and decision rules that
ensure all agent actions remain compliant with the specification.
How to Read and Interpret spec.txt
----------------------------------
#. Treat specification as canonical; all definitions, rules, and schemas
originate there.
#. When encountering ambiguity, defer to specification rather than internal
heuristics.
#. When interpreting any rule:
- Use the identifiers in specification as binding references.
- Do not reinterpret or rephrase the rule; apply it operationally.
#. When a task requires clarification, locate the relevant section in
specification and apply its constraints directly.
How to Apply the ABC Normative Rules
------------------------------------
#. Use normative rules as constraints on generation and transformation.
#. For any action:
- Identify which normative rules apply.
- Enforce them mechanically.
#. When generating constructs:
- Ensure hierarchy, relationships, interfaces, and data flow conform to
normative rules.
#. When routing data:
- Apply downward and upward flow rules exactly as defined.
#. When evaluating a user request:
- Reject or correct requests that would violate normative rules.
How to Apply the ABC Validation Rules
-------------------------------------
#. Treat validation rules as mechanical checks.
#. For any ABC architecture:
- Validate structure.
- Validate contracts.
- Validate data flow.
- Validate instantiation semantics.
#. When a violation is detected:
- Identify the violated rule by its identifier.
- Provide a corrective action path.
#. Never modify validation rules; only apply them.
SECTION 5 — How to Use the ABC Schema
-------------------------------------
#. Use the schema as the machine-readable representation of an ABC architecture.
#. When generating or transforming architectures:
- Produce JSON that conforms exactly to the schema.
#. When validating:
- Apply schema constraints before normative or validation rules.
#. When consuming the schema:
- Use ``$defs`` to resolve construct types, contracts, and rule bindings.
#. Never alter the schema; only instantiate or validate against it.
How to Use the Code Generation Profiles
---------------------------------------
#. Profiles define how to map ABC constructs into specific IaC tools.
#. When generating code:
- Select the appropriate profile.
- Apply profile rules exactly as written in specification.
#. When a profile conflicts with user instructions:
- The profile takes precedence.
#. When generating code:
- Use the ABC hierarchy as the structural backbone.
- Use Input/Output Contracts as the only wiring mechanism.
#. Never invent new profile rules; only apply those defined in specification.
Operational Procedures for Construct Creation
---------------------------------------------
#. Determine the construct type.
#. Create the construct with:
- A unique ID.
- A valid parent (except ApplicationStack).
- A complete Input Contract.
- A complete Output Contract.
#. Instantiate children strictly top-down.
#. Ensure no lateral references are introduced.
#. Enforce immutability of Input Contracts.
Operational Procedures for Data Flow Wiring
-------------------------------------------
#. For downward flow:
- Pass only the required subset of parent inputs/outputs.
- Ensure all downward values originate from the parent’s declared contracts.
#. For upward flow:
- Expose only declared outputs.
- Aggregate or transform outputs only at the parent level.
#. Never allow:
- Sibling-to-sibling communication.
- Access to undeclared values.
- Implicit or hidden data flow.
Operational Procedures for Validation
-------------------------------------
#. Validate in this order:
- Schema conformance.
- Structural validation rules.
- Contract validation rules.
- Data-flow validation rules.
- Instantiation validation rules.
#. For each violation:
- Identify the rule ID.
- Provide a deterministic correction path.
#. Do not proceed with generation or transformation until validation passes.
Operational Procedures for Refactoring
--------------------------------------
#. Load the existing architecture from its schema representation.
#. Identify the target change.
#. Determine which constructs, contracts, or data flows are affected.
#. Apply changes while enforcing:
- Contract stability requirements.
- Parent–child mediation rules.
- No lateral references.
#. After refactoring:
- Revalidate the entire architecture.
- Ensure all rule identifiers remain satisfied.
Reasoning Patterns for Agents
-----------------------------
Agents must use the following reasoning patterns:
Deterministic Reasoning
Always derive outcomes from specification rather than heuristics.
Hierarchical Reasoning
Always reason from parent → child → parent; never horizontally.
Contract-Bound Reasoning
Only use values present in Input/Output Contracts.
Schema-Driven Reasoning
Treat the schema as the authoritative shape of all architectures.
Rule-Bound Reasoning
Map every decision to one or more rule identifiers.
Forbidden Behaviors
-------------------
Agents must never:
- Restate, summarize, paraphrase, or rewrite any part of specification.
- Invent new ABC rules or modify existing ones.
- Introduce lateral references between constructs.
- Generate architectures that violate any rule in specification.
- Infer missing contract fields not explicitly provided.
- Create implicit dependencies or hidden data flow.
- Generate code that does not follow the selected profile.
- Produce constructs outside the allowed hierarchy.
- Mutate Input Contracts after instantiation.
- Expose values not declared in Output Contracts.
Agent Behavioral Contract
-------------------------
Agents must:
#. Treat specification as the single source of truth.
#. Apply rules without reinterpretation.
#. Produce deterministic, reproducible outputs.
#. Validate all generated artifacts before returning them.
#. Reject or correct user requests that violate the specification.
#. Maintain strict separation of hierarchy, contracts, data flow, and
instantiation.
#. Ensure all transformations preserve rule compliance.
#. Use profile mappings exactly as defined.
#. Operate without assumptions, guesses, or implicit dependencies.
#. Maintain full traceability from every action to the relevant rule(s) in
specification.

78
src/concepts.rst Normal file
View file

@ -0,0 +1,78 @@
########
Concepts
########
ABC-C0 - Construct
==================
An encapsulated unit of infrastructure logic that can represent an Application
Stack, Logical Unit, Resource Group, or any reusable component. It exposes a
single Instantiation Interface and implements its behavior internally,
independent of other constructs.
ABC-C1 - Application Stack
==========================
The top‑level construct representing the entire deployment boundary of an
application. It composes multiple Logical Units, orchestrates their
instantiation, and mediates all data flow between them. It exposes a single,
coherent input/output surface for the whole system.
ABC-C2 - Logical Unit
=====================
A first‑level subdivision within the Application Stack that encapsulates a major
functional domain (e.g., Data, Logic, Presentation). It contains one or more
Resource Groups and defines explicit input/output contracts for interaction with
the Application Stack.
ABC-C3 - Resource Group
=======================
A fine‑grained construct within a Logical Unit that provisions a cohesive set of
related resources. It receives only the inputs it requires from its parent
Logical Unit and returns outputs upward; it never communicates directly with
sibling Resource Groups.
ABC-C4 - Input Contract
=======================
A formally defined set of parameters that a Construct (ABC‑C0) MUST receive from
its parent. It specifies all required configuration, contextual values, and
dependencies needed for correct instantiation. It prohibits implicit or global
state; every dependency must appear explicitly in this contract.
ABC-C5 - Output Contract
========================
A formally defined set of values that a Construct (ABC‑C0) MUST expose upward to
its parent. It represents the complete set of externally consumable identifiers,
endpoints, or computed values produced by the construct. It ensures that all
upward dependencies are explicit and traceable.
ABC-C6 - Instantiation Interface
================================
The single, explicit mechanism through which a Construct (ABC‑C0) is created and
provided with its Input Contract (ABC‑C4). It defines how callers supply inputs
and how the construct exposes its Output Contract (ABC‑C5). The interface is
stable, minimal, and framework‑agnostic, ensuring that internal implementation
details never leak into parent constructs.
ABC-C7 - Capturing Down
=======================
A parent‑to‑child data‑flow mechanism in which a Construct (ABC‑C0) provides its
children with the exact subset of inputs they require. It ensures that all
downward dependencies are explicit, scoped, and passed only through the child’s
Input Contract (ABC‑C4). No child may access parent state except through this
mechanism.
ABC-C8 - Bubbling Up
====================
A child‑to‑parent data‑flow mechanism in which a Construct (ABC‑C0) exposes its
outputs exclusively through its Output Contract (ABC‑C5). Parents receive these
outputs, may aggregate or transform them, and may optionally pass them further
down to other children via Capturing Down. No lateral or implicit communication
is permitted.

41
src/conf.py Normal file
View file

@ -0,0 +1,41 @@
import datetime
extensions = [
'sphinx.ext.intersphinx',
'sphinx.ext.todo',
'sphinx_last_updated_by_git',
'sphinx_markdown_builder'
]
templates_path = ["_templates"]
project = "Abstract Base Cloud Specification"
copyright = "2026, Tiara Rodney"
html_title = project
html_theme = 'pydata_sphinx_theme'
html_sidebars = {}
html_show_sphinx = False
html_show_sourcelink = False
html_context = {
"bitbucket_url": "https://bitbucket.org",
"bitbucket_user": "byteb4rb1e",
"bitbucket_repo": "blog.tiararodney.com",
"bitbucket_version": "master",
"doc_path": "src/"
}
language = 'en'
todo_include_todos = True
rst_prolog = f"""
.. |build-time| replace:: {datetime.datetime.now().strftime("%d %B %Y, %H:%M")}
"""
html_last_updated_fmt = "%d %B %Y, %H:%M"

386
src/example.rst Normal file
View file

@ -0,0 +1,386 @@
#################
Canonical Example
#################
This example demonstrates how the ABC Pattern structures a real application
using only:
* Constructs (ABC‑C0)
* Application Stack (ABC‑C1)
* Logical Units (ABC‑C2)
* Resource Groups (ABC‑C3)
* Input/Output Contracts (ABC‑C4, ABC‑C5)
* Instantiation Interface (ABC‑C6)
* Capturing Down (ABC‑C7)
* Bubbling Up (ABC‑C8)
Every interaction is explicit. Every dependency is visible. Nothing leaks
sideways.
Overview
========
We model a classic 3‑tier architecture:
* Data Tier - database + storage
* Logic Tier - compute + messaging
* Presentation Tier - CDN + web frontend
Each tier is a Logical Unit (ABC‑C2).
Each component inside a tier is a Resource Group (ABC‑C3).
The Application Stack (ABC‑C1) composes them, wires them, and exposes the final
outputs.
Conceptual Diagram
==================
.. code-block::
┌──────────────────────────────┐
│ Application Stack │
│ (ABC‑C1) │
└─────────────┬────────────────┘
│
┌──────────────────────┼────────────────────────┐
│ │ │
┌───────▼────────┐ ┌───────▼────────┐ ┌─────────▼────────┐
│ DataUnit │ │ LogicUnit │ │ PresentationUnit │
│ (C2) │ │ (C2) │ │ (C2) │
└───────┬────────┘ └───────┬────────┘ └────────┬─────────┘
│ │ │
│ │ ┌────────│──────┐
┌────▼─────┐ ┌────▼─────┐ ┌────▼──────┐ ┌──────▼─────┐
│StorageGrp│ │ComputeGrp│ │WebAppGrp │ │ CDNGrp │
│ (C3) │ │ (C3) │ │ (C3) │ │ (C3) │
└──────────┘ └──────────┘ └───────────┘ └────────────┘
Application Stack (ABC‑C1)
==========================
The Application Stack is the root construct.
It has no parent and defines the deployment boundary.
Responsibilities
----------------
* Instantiate each Logical Unit (ABC‑R1).
* Provide downward inputs (ABC‑F1).
* Receive upward outputs (ABC‑F2).
* Route outputs between Logical Units (ABC‑R44).
* Expose a final Output Contract representing the whole system.
Input Contract (ABC‑C4)
-----------------------
The Application Stack receives only global configuration:
.. code-block::
AppStackInputs:
environment: string
region: string
global_tags: map<string,string>
Output Contract (ABC‑C5)
------------------------
The Application Stack exposes:
.. code-block::
AppStackOutputs:
frontend_url: string
api_endpoint: string
These values originate from the Presentation and Logic tiers, respectively.
Logical Units (ABC‑C2)
======================
Each Logical Unit encapsulates a functional domain.
They do not know about each other.
They communicate only through the Application Stack.
We define three:
* DataUnit
* LogicUnit
* PresentationUnit
Each has its own Input/Output Contracts and internal Resource Groups.
Data Logical Unit (ABC‑C2)
--------------------------
Purpose
^^^^^^^
Provide persistent storage and database capabilities.
Resource Groups (ABC‑C3)
^^^^^^^^^^^^^^^^^^^^^^^^
* StorageGroup - object storage
* DatabaseGroup - relational database
Input Contract
^^^^^^^^^^^^^^
.. code-block::
DataUnitInputs:
environment: string
region: string
storage_class: string
db_engine: string
db_instance_size: string
Output Contract
^^^^^^^^^^^^^^^
.. code-block::
DataUnitOutputs:
storage_bucket_name: string
database_endpoint: string
Internal Wiring
^^^^^^^^^^^^^^^
* StorageGroup produces ``storage_bucket_name``.
* DatabaseGroup produces ``database_endpoint``.
* DataUnit aggregates both and bubbles them up (ABC‑F2).
.. note::
* StorageGroup and DatabaseGroup do not know about each other (ABC‑R10).
* All configuration flows downward from DataUnit (ABC‑F1).
Logic Logical Unit (ABC‑C2)
---------------------------
Purpose
^^^^^^^
Provide compute and messaging capabilities for the application backend.
Resource Groups
^^^^^^^^^^^^^^^
* ComputeGroup - application compute (e.g., functions, containers)
* MessagingGroup - queue or pub/sub system
Input Contract
^^^^^^^^^^^^^^
.. code-block::
LogicUnitInputs:
environment: string
region: string
compute_size: string
message_retention: number
database_endpoint: string # Provided by DataUnit via AppStack
Output Contract
^^^^^^^^^^^^^^^
.. code-block::
LogicUnitOutputs:
api_endpoint: string
message_queue_url: string
Internal Wiring
^^^^^^^^^^^^^^^
* ComputeGroup receives ``database_endpoint`` via Capturing Down (ABC‑F1).
* MessagingGroup is independent.
* LogicUnit aggregates outputs and bubbles them up.
.. note::
* LogicUnit does not know where the database came from.
* It only knows it received a database_endpoint in its Input Contract
(ABC‑R22).
Presentation Logical Unit (ABC‑C2)
----------------------------------
Purpose
^^^^^^^
Serve the frontend and expose the public entry point.
Resource Groups
^^^^^^^^^^^^^^^
* CDNGroup - global content distribution
* WebAppGroup - static or dynamic frontend
Input Contract
^^^^^^^^^^^^^^
.. code-block::
PresentationUnitInputs:
environment: string
region: string
frontend_assets_bucket: string
api_endpoint: string # Provided by LogicUnit via AppStack
Output Contract
^^^^^^^^^^^^^^^
.. code-block::
PresentationUnitOutputs:
frontend_url: string
Internal Wiring
^^^^^^^^^^^^^^^
* WebAppGroup receives ``api_endpoint`` via Capturing Down.
* CDNGroup receives the output of WebAppGroup.
* PresentationUnit bubbles up the final ``frontend_url``.
Resource Groups (ABC‑C3)
========================
Each Resource Group is a small, focused construct with:
* A minimal Input Contract
* A minimal Output Contract
* No knowledge of siblings
* No access to parent state except via inputs
* No side effects during instantiation (ABC‑R33)
Example: Database Group
-----------------------
Input Contract
^^^^^^^^^^^^^^
.. code-block::
DatabaseGroupInputs:
db_engine: string
db_instance_size: string
environment: string
Output Contract
^^^^^^^^^^^^^^^
.. code-block::
DatabaseGroupOutputs:
database_endpoint: string
Instantiation Interface
^^^^^^^^^^^^^^^^^^^^^^^
.. code-block::
new DatabaseGroup(DatabaseGroupInputs) -> DatabaseGroupOutputs
This pattern repeats for all Resource Groups.
Full Data Flow (ABC‑F1 and ABC‑F2)
==================================
The complete data flow includes:
* AppStack → Logical Units
* Logical Units → Resource Groups
* Resource Groups → Logical Units
* Logical Units → AppStack
This is the full vertical chain required by the ABC Pattern.
Downward Flow (Capturing Down — ABC‑F1)
---------------------------------------
#. AppStack → DataUnit
* ``environment``
* ``region``
* ``storage_class``
* ``db_engine``
* ``db_instance_size``
#. DataUnit → StorageGroup
* ``environment``
* ``region``
* ``storage_class``
#. DataUnit → DatabaseGroup
* ``environment``
* ``db_engine``
* ``db_instance_size``
#. AppStack → LogicUnit
* ``environment``
* ``region``
* ``compute_size``
* ``message_retention``
* ``database_endpoint`` (bubbled up from DataUnit)
#. LogicUnit → ComputeGroup
* ``environment``
* ``compute_size``
* ``database_endpoint``
#. LogicUnit → MessagingGroup
* ``environment``
* ``message_retention``
#. AppStack → PresentationUnit
* ``environment``
* ``region``
* ``frontend_assets_bucket``
* ``api_endpoint`` (bubbled up from LogicUnit)
#. PresentationUnit → WebAppGroup
* ``environment``
* ``frontend_assets_bucket``
* ``api_endpoint``
#. PresentationUnit → CDNGroup
* ``environment``
* ``webapp_origin_url`` (bubbled up from WebAppGroup)
Upward Flow (Bubbling Up — ABC‑F2)
----------------------------------
#. StorageGroup → DataUnit
* ``storage_bucket_name``
#. DatabaseGroup → DataUnit
* ``database_endpoint``
#. DataUnit → AppStack
* ``storage_bucket_name``
* ``database_endpoint``
#. ComputeGroup → LogicUnit
* ``api_endpoint``
#. MessagingGroup → LogicUnit
* ``message_queue_url``
#. LogicUnit → AppStack
* ``api_endpoint``
* ``message_queue_url``
#. WebAppGroup → PresentationUnit
* ``webapp_origin_url``
#. CDNGroup → PresentationUnit
* ``frontend_url``
#. PresentationUnit → AppStack
* ``frontend_url``
Rationale
=========
This example demonstrates:
* Strict encapsulation
* Explicit dependencies
* No lateral references
* Deterministic wiring
* Testability at every level
* Predictable evolution
* Agent‑friendly structure
It is the canonical reference for all profiles (CDK, Terraform, etc.).

98
src/index.rst Normal file
View file

@ -0,0 +1,98 @@
###################
Abstract Base Cloud
###################
The ABC Pattern is a universal architectural model for structuring cloud
infrastructure in a way that is predictable, explicit, and safe for automated
reasoning. It defines a small set of composable building blocks and a strict set
of rules governing how those blocks relate, communicate, and evolve. The result
is an architecture that is easy to understand, easy to validate, and easy to
generate or transform using both human and machine agents.
ABC is intentionally tool‑agnostic and cloud‑agnostic. It does not prescribe
specific services, resource types, or implementation languages. Instead, it
defines a semantic architecture model that can be mapped onto any
infrastructure-as-code system, including imperative tools (such as CDK) and
declarative tools (such as Terraform).
At its core, ABC is built on three foundational ideas:
**1. A strict hierarchical structure**
Every ABC architecture is composed of three construct types:
* ApplicationStack — the root of the system
* Logical Units — functional domains
* Resource Groups — cohesive clusters of cloud resources
This hierarchy forms a strict tree with no lateral references, ensuring clarity
and isolation.
**2. Explicit contracts and deterministic data flow**
Every construct defines:
* an Input Contract (what it needs)
* an Output Contract (what it produces)
Data flows only in two directions:
* Capturing Down — parents pass data to children
* Bubbling Up — children return data to parents
This eliminates hidden dependencies and makes the architecture fully analyzable.
**3. A stable foundation for automation**
Because ABC is explicit, typed, and deterministic, it is uniquely suited for:
* automated code generation
* architecture validation
* refactoring and transformation
* multi‑cloud portability
* agent‑driven reasoning
ABC is designed to be the intermediate representation (IR) for infrastructure,
something like the "AST of cloud architecture".
Purpose and Philosophy
======================
The ABC Pattern exists to solve a fundamental problem in cloud architecture:
infrastructure is too implicit.
* Dependencies are hidden.
* Data flow is unclear.
* Modules are entangled.
* Refactoring is risky.
* Automation is fragile.
ABC replaces this with a model that is:
* explicit,
* typed,
* hierarchical,
* deterministic,
* verifiable, and
* portable
It is designed to be understood by humans, validated by tools, and generated by
agents.
Content
=======
.. toctree::
:maxdepth: 1
concepts
model
rules/index
schema
example
profiles/index
.. toctree::
:hidden:
AGENTS

207
src/model.rst Normal file
View file

@ -0,0 +1,207 @@
##############
Abstract Model
##############
Hierarchy Model
===============
The ABC Pattern defines a strict three‑layer hierarchy of constructs (ABC‑C0):
* Application Stack (ABC‑C1) — the root deployment boundary.
* Logical Units (ABC‑C2) — first‑level domains within the application.
* Resource Groups (ABC‑C3) — fine‑grained functional clusters inside each
Logical Unit.
This hierarchy is **strictly vertical**.
Every construct belongs to exactly one parent, and no construct may exist
outside this tree.
The hierarchy expresses **encapsulation**:
* ABC‑C1 encapsulates the entire application.
* ABC‑C2 encapsulates domain‑level concerns.
* ABC‑C3 encapsulates resource‑level concerns.
Each layer exposes its behavior exclusively through its Instantiation Interface
(ABC‑C6) and its Input/Output Contracts (ABC‑C4, ABC‑C5).
Relationship Semantics
======================
The ABC Pattern enforces a parent–child‑only relationship model.
Allowed relationships
---------------------
A parent construct MAY instantiate children using the child’s Instantiation
Interface (ABC‑C6).
A child MAY expose outputs upward via its Output Contract (ABC‑C5).
A parent MAY route outputs from one child to another via Capturing Down
(ABC‑C7).
Forbidden relationships
-----------------------
* **No lateral references:**
- Resource Groups (ABC‑C3) may not reference each other directly.
- Logical Units (ABC‑C2) may not reference each other directly.
* **No implicit dependencies:**
- A construct may not read global state, shared variables, or parent
internals.
* **No hidden communication channels:**
- All data must flow through Input/Output Contracts.
These constraints ensure loose coupling, testability, and predictable
composition.
Interface Semantics
===================
Every construct (ABC‑C0) defines two explicit interfaces:
Input Contract (ABC‑C4)
-----------------------
The complete set of parameters required for instantiation.
A construct MUST NOT depend on any value not present in its Input Contract.
Output Contract (ABC‑C5)
------------------------
The complete set of values the construct exposes upward.
A construct MUST NOT leak internal state except through this contract.
Interface Binding
-----------------
When a parent instantiates a child:
#. The parent supplies the child’s Input Contract.
#. The child returns its Output Contract.
#. The parent may:
* consume the outputs,
* aggregate them,
* or pass them down to other children.
This creates a **closed, explicit dependency graph** with no hidden edges.
Instantiation Semantics
=======================
The Instantiation Interface (ABC‑C6) is the single mechanism through which a
construct is created.
It has three properties:
* **Stability** - The interface remains stable even if internal implementation
changes.
* **Minimality** - Only the Input Contract is accepted; no additional
parameters.
* **Purity** - Instantiation has no side effects beyond constructing the child.
Instantiation is always **top‑down**:
* ABC‑C1 instantiates ABC‑C2 constructs.
* ABC‑C2 instantiates ABC‑C3 constructs.
* No construct may instantiate its parent or siblings.
This ensures deterministic composition and predictable dependency flow.
Data Flow Semantics
===================
Data flows vertically through two complementary mechanisms:
ABC‑F1 — Capturing Down (maps to ABC‑C7)
----------------------------------------
A parent passes scoped inputs to its children.
This mechanism ensures:
* Children receive only what they need.
* No child can access parent state implicitly.
* Parents mediate all cross‑domain dependencies.
.. admonition:: Example
The Application Stack (ABC‑C1) passes a VPC ID to a Logical Unit (ABC‑C2),
which passes a subnet ID to a Resource Group (ABC‑C3).
ABC‑F2 — Bubbling Up (maps to ABC‑C8)
-------------------------------------
A child exposes outputs upward to its parent.
This mechanism ensures:
* All produced values are explicit.
* Parents can aggregate or route outputs.
* No child communicates directly with siblings.
.. admonition:: Example
A Database Resource Group returns a database endpoint to its Logical Unit,
which returns it to the Application Stack.
Routing Semantics
-----------------
Parents MAY:
* **Consume** outputs (e.g., store them).
* **Transform** outputs (e.g., wrap them in a composite object).
* **Re‑expose** outputs upward.
* **Pass** outputs downward to other children.
Children MAY not route data themselves.
Conceptual Diagram
==================
.. code-block::
Application Stack (ABC‑C1)
│
├── Logical Unit: Data (ABC‑C2)
│ ├── Resource Group: Storage (ABC‑C3)
│ └── Resource Group: Database (ABC‑C3)
│
├── Logical Unit: Logic (ABC‑C2)
│ ├── Resource Group: Compute (ABC‑C3)
│ └── Resource Group: Messaging (ABC‑C3)
│
└── Logical Unit: Presentation (ABC‑C2)
├── Resource Group: CDN (ABC‑C3)
└── Resource Group: WebApp (ABC‑C3)
**Downward arrows** represent Capturing Down (ABC‑F1).
**Upward arrows** represent Bubbling Up (ABC‑F2).
No horizontal arrows exist.
Rationale & Design Intent
=========================
The ABC Pattern enforces a strict, explicit, and testable structure for cloud
infrastructure code.
* **Encapsulation** ensures each construct hides its internal details.
* **Explicit interfaces** eliminate hidden dependencies.
* **Loose coupling** prevents cross‑domain entanglement.
* **Reusability** emerges from stable Instantiation Interfaces.
* **Testability** is guaranteed because each construct can be instantiated with
mock inputs.
* **Scalability** follows naturally from the ability to evolve constructs
independently.
This model is intentionally tool‑agnostic so it can be mapped cleanly to CDK,
Terraform, Pulumi, or any imperative, as well as declarative IaC framework.

442
src/profiles/cdk-ts.rst Normal file
View file

@ -0,0 +1,442 @@
######################
CDK TypeScript Profile
######################
Concept → CDK Mapping
=====================
.. list-table::
:header-rows: 1
* - ABC Concept
- Meaning
- CDK Mapping
* - ABC‑C0
- Construct
- ``Construct`` subclass
* - ABC‑C1
- Application Stack
- ``Stack`` subclass
* - ABC‑C2
- Logical Unit (LU)
- ``Construct`` subclass with LU semantics
* - ABC‑C3
- Resource Group (RG)
- ``Construct`` subclass with RG semantics
* - ABC‑C4
- Input Contract
- TypeScript interface (``InputContract``)
* - ABC‑C5
- Output Contract
- TypeScript interface (``OutputContract``)
* - ABC‑C6
- Instantiation Interface
- Constructor (``scope``, ``id``, ``inputs``)
* - ABC‑C7
- Capturing Down
- Passing inputs to children
* - ABC‑C8
- Bubbling Up
- Exposing outputs upward
*ABC* itself remains naming‑agnostic; this profile defines CDK‑idiomatic
conventions.
Rules
=====
These are profile‑specific rules for CDK-Typescript users.
ABC-PROFILE-CDKTS‑R1 (SHOULD)
-----------------------------
The directory structure SHOULD reflect the ABC hierarchy:
Application Stack → Logical Units → Resource Groups.
ABC-PROFILE-CDKTS‑R2 (SHOULD)
-----------------------------
Each Logical Unit SHOULD reside in its own top‑level directory:
.. code-block::
src/
app-stack.ts
data/
logic/
presentation/
ABC-PROFILE-CDKTS‑R3 (SHOULD)
-----------------------------
Each Resource Group SHOULD reside inside its parent Logical Unit:
.. code-block::
src/data/storage/
src/data/database/
ABC-PROFILE-CDKTS‑R4 (SHOULD)
-----------------------------
Each construct directory SHOULD contain an index.ts exporting the construct.
ABC-PROFILE-CDKTS‑R5 (SHOULD)
-----------------------------
File and directory names SHOULD follow CDK naming conventions.
ABC-PROFILE-CDKTS‑R6 (MAY)
--------------------------
Modules MAY split into multiple files if needed, as long as they remain in the
same directory.
ABC-PROFILE-CDKTS‑R7 (SHOULD)
-----------------------------
Each construct module SHOULD define its own ``InputContract`` and
``OutputContract``.
ABC-PROFILE-CDKTS‑R8 (SHOULD)
-----------------------------
Within a module, contracts SHOULD be named simply ``InputContract`` and
``OutputContract``.
ABC-PROFILE-CDKTS‑R9 (SHOULD)
-----------------------------
When importing contracts from another module, they SHOULD be aliased:
ABC-PROFILE-CDKTS‑R10 (MUST)
----------------------------
Constructs MUST be instantiated using a single InputContract object.
Also see ABC‑R30/32.
ABC-PROFILE-CDKTS‑R11 (MUST)
----------------------------
All cross‑construct wiring MUST occur in the parent construct.
Also see ABC‑R44.
ABC-PROFILE-CDKTS‑R12 (SHOULD)
------------------------------
Imported contracts SHOULD be aliased to descriptive names.
ABC-PROFILE-CDKTS‑R13 (SHOULD)
------------------------------
Contracts SHOULD be co‑located with their construct modules.
ABC-PROFILE-CDKTS‑R14 (SHOULD)
------------------------------
Generated code SHOULD mirror the ABC hierarchy in structure and composition.
ABC-PROFILE-CDKTS‑R15 (SHOULD)
------------------------------
Construct internals SHOULD NOT be accessed except through outputs.
ABC-PROFILE-CDKTS‑R16 (SHOULD)
------------------------------
Constructs SHOULD be generated in ABC order: Resource Groups → Logical Units →
Application Stack.
Base ABC Classes for Typescript-CDK
===================================
Core Types
----------
.. code-block:: javascript
:caption: src/abc/core-types.ts
export interface InputContract {}
export interface OutputContract {}
export interface HasOutputs<TOutputs extends OutputContract> {
readonly outputs: TOutputs;
}
Application Stack Base
----------------------
.. code-block:: javascript
:caption: src/abc/application-stack.ts
import { Stack, StackProps } from 'aws-cdk-lib';
import { Construct } from 'constructs';
import { OutputContract } from './core-types';
export abstract class ABCApplicationStack<
TOutputs extends OutputContract = OutputContract
> extends Stack {
public abstract readonly outputs: TOutputs;
protected constructor(scope: Construct, id: string, props?: StackProps) {
super(scope, id, props);
}
}
Logical Unit Base
-----------------
.. code-block:: javascript
:caption: src/abc/logical-unit.ts
import { Construct } from 'constructs';
import { InputContract, OutputContract, HasOutputs } from './core-types';
export abstract class ABCLogicalUnit<
TInputs extends InputContract,
TOutputs extends OutputContract
> extends Construct implements HasOutputs<TOutputs> {
public abstract readonly outputs: TOutputs;
protected readonly inputs: TInputs;
protected constructor(scope: Construct, id: string, inputs: TInputs) {
super(scope, id);
this.inputs = Object.freeze({ ...inputs }) as TInputs;
}
}
Resource Group Base
-------------------
.. code-block:: javascript
:caption: src/abc/resource-group.ts
import { Construct } from 'constructs';
import { InputContract, OutputContract, HasOutputs } from './core-types';
export abstract class ABCResourceGroup<
TInputs extends InputContract,
TOutputs extends OutputContract
> extends Construct implements HasOutputs<TOutputs> {
public abstract readonly outputs: TOutputs;
protected readonly inputs: TInputs;
protected constructor(scope: Construct, id: string, inputs: TInputs) {
super(scope, id);
this.inputs = Object.freeze({ ...inputs }) as TInputs;
}
}
Logical Units & Resource Groups (Canonical Example)
===================================================
Below is the full 3‑tier example implemented in CDK.
Data Logical Unit
-----------------
.. code-block::
src/data/index.ts
src/data/storage/index.ts
src/data/database/index.ts
.. code-block:: javascript
:caption: src/data/index.ts
import { Construct } from 'constructs';
import { ABCLogicalUnit } from '../abc/logical-unit';
import { StorageGroup } from './storage';
import { DatabaseGroup } from './database';
export interface InputContract {
environment: string;
region: string;
storageClass: string;
dbEngine: string;
dbInstanceSize: string;
}
export interface OutputContract {
storageBucketName: string;
databaseEndpoint: string;
}
export class DataUnit extends ABCLogicalUnit<InputContract, OutputContract> {
public readonly outputs: OutputContract;
constructor(scope: Construct, id: string, inputs: InputContract) {
super(scope, id, inputs);
const storage = new StorageGroup(this, 'Storage', {
environment: inputs.environment,
region: inputs.region,
storageClass: inputs.storageClass,
});
const database = new DatabaseGroup(this, 'Database', {
environment: inputs.environment,
dbEngine: inputs.dbEngine,
dbInstanceSize: inputs.dbInstanceSize,
});
this.outputs = {
storageBucketName: storage.outputs.storageBucketName,
databaseEndpoint: database.outputs.databaseEndpoint,
};
}
}
Storage Resource Group
^^^^^^^^^^^^^^^^^^^^^^
.. code-block::
:caption: src/data/storage/index.ts
import { Construct } from 'constructs';
import { ABCResourceGroup } from '../../abc/resource-group';
export interface InputContract {
environment: string;
region: string;
storageClass: string;
}
export interface OutputContract {
storageBucketName: string;
}
export class StorageGroup extends ABCResourceGroup<InputContract, OutputContract> {
public readonly outputs: OutputContract;
constructor(scope: Construct, id: string, inputs: InputContract) {
super(scope, id, inputs);
this.outputs = {
storageBucketName: 'bucket-name-placeholder',
};
}
}
Database Resource Group
^^^^^^^^^^^^^^^^^^^^^^^
.. code-block::
:caption: src/data/database/index.ts
import { Construct } from 'constructs';
import { ABCResourceGroup } from '../../abc/resource-group';
export interface InputContract {
environment: string;
dbEngine: string;
dbInstanceSize: string;
}
export interface OutputContract {
databaseEndpoint: string;
}
export class DatabaseGroup extends ABCResourceGroup<InputContract, OutputContract> {
public readonly outputs: OutputContract;
constructor(scope: Construct, id: string, inputs: InputContract) {
super(scope, id, inputs);
this.outputs = {
databaseEndpoint: 'db-endpoint-placeholder',
};
}
}
Logic Logical Unit
------------------
.. code-block::
src/logic/index.ts
src/logic/compute/index.ts
src/logic/messaging/index.ts
Compute Resource Group and Messaging Resource Group follow the same pattern.
Presentation Logical Unit
-------------------------
.. code-block::
src/presentation/index.ts
src/presentation/webapp/index.ts
src/presentation/cdn/index.ts
WebApp Resource Group and CDN Resource Group follow the same pattern.
Application Stack
=================
.. code-block:: javascript
:caption: src/app-stack.ts
import { Construct } from 'constructs';
import { ABCApplicationStack } from './abc/application-stack';
import { DataUnit } from './data';
import type { InputContract as DataUnitInput } from './data';
import { LogicUnit } from './logic';
import type { InputContract as LogicUnitInput } from './logic';
import { PresentationUnit } from './presentation';
import type { InputContract as PresentationUnitInput } from './presentation';
export interface InputContract {
environment: string;
region: string;
globalTags?: Record<string, string>;
}
export interface OutputContract {
frontendUrl: string;
apiEndpoint: string;
}
export class AppStack extends ABCApplicationStack<OutputContract> {
public readonly outputs: OutputContract;
constructor(scope: Construct, id: string, inputs: InputContract) {
super(scope, id);
const dataInputs: DataUnitInput = {
environment: inputs.environment,
region: inputs.region,
storageClass: 'STANDARD',
dbEngine: 'postgres',
dbInstanceSize: 'db.t3.micro',
};
const dataUnit = new DataUnit(this, 'DataUnit', dataInputs);
const logicInputs: LogicUnitInput = {
environment: inputs.environment,
region: inputs.region,
computeSize: 'small',
messageRetention: 1209600,
databaseEndpoint: dataUnit.outputs.databaseEndpoint,
};
const logicUnit = new LogicUnit(this, 'LogicUnit', logicInputs);
const presentationInputs: PresentationUnitInput = {
environment: inputs.environment,
region: inputs.region,
frontendAssetsBucket: dataUnit.outputs.storageBucketName,
apiEndpoint: logicUnit.outputs.apiEndpoint,
};
const presentationUnit = new PresentationUnit(this, 'PresentationUnit', presentationInputs);
this.outputs = {
frontendUrl: presentationUnit.outputs.frontendUrl,
apiEndpoint: logicUnit.outputs.apiEndpoint,
};
}
}

26
src/profiles/index.rst Normal file
View file

@ -0,0 +1,26 @@
########
Profiles
########
Profiles define how the ABC Pattern maps onto specific IaC tools. Each profile
introduces additional rules, conventions, and examples tailored to the target
system.
Profiles use identifiers of the form:
.. code-block::
ABC-PROFILE-<PROFILE>-R#
Current profiles include:
* imperative, object‑oriented implementations
* declarative module‑based implementation
Profiles demonstrate that ABC is not tied to any particular paradigm.
.. toctree::
:glob:
:maxdepth: 1
*

249
src/profiles/tf.rst Normal file
View file

@ -0,0 +1,249 @@
#################
Terraform Profile
#################
Concept → Terraform Mapping
===========================
.. list-table::
:header-rows: 1
* - ABC Concept
- Meaning
- Terraform Mapping
* - ABC‑C0
- Construct
- Terraform module
* - ABC‑C1
- Application Stack
- Root Terraform module
* - ABC‑C2
- Logical Unit
- Child module representing a domain
* - ABC‑C3
- Resource Group
- Submodule representing a cohesive resource cluster
* - ABC‑C4
- Input Contract
- variables.tf in a module
* - ABC‑C5
- Output Contract
- outputs.tf in a module
* - ABC‑C6
- Instantiation Interface
- ``module "" { ... }`` block
* - ABC‑C7
- Capturing Down
- Passing variables from parent to child module
* - ABC‑C8
- Bubbling Up
- Exposing outputs from child modules to parent
Proile Rules
============
Terraform profile rules follow the canonical identifier format:
.. code-block::
ABC-PROFILE-TF-R#
These rules are profile‑specific, not core ABC rules.
ABC-PROFILE-TF-R1 (SHOULD)
--------------------------
Each ABC construct SHOULD be implemented as a Terraform module.
ABC-PROFILE-TF-R2 (SHOULD)
--------------------------
The directory structure SHOULD reflect the ABC hierarchy:
.. code-block::
root/
main.tf
data/
main.tf
storage/
main.tf
database/
main.tf
logic/
main.tf
presentation/
main.tf
ABC-PROFILE-TF-R3 (SHOULD)
--------------------------
Each module SHOULD contain:
* main.tf
* variables.tf (InputContract)
* outputs.tf (OutputContract)
ABC-PROFILE-TF-R4 (MUST)
------------------------
Module inputs MUST be declared exclusively in variables.tf.
ABC-PROFILE-TF-R5 (MUST)
------------------------
Module outputs MUST be declared exclusively in outputs.tf.
ABC-PROFILE-TF-R6 (MUST)
------------------------
Modules MUST NOT reference parent or sibling modules directly; all data MUST
flow through variables and outputs.
(This enforces ABC‑R22, ABC‑R40, ABC‑R42.)
ABC-PROFILE-TF-R7 (MUST)
------------------------
Modules MUST be instantiated using a module "<name>" { ... } block with explicit
variable assignments.
ABC-PROFILE-TF-R8 (MUST)
------------------------
Modules MUST NOT read Terraform state from other modules except via outputs.
ABC-PROFILE-TF-R9 (MUST)
------------------------
Capturing Down MUST be implemented by passing parent variables or outputs into
child module inputs.
ABC-PROFILE-TF-R10 (MUST)
-------------------------
Bubbling Up MUST be implemented by exposing child module outputs and re‑exposing
them in the parent module if needed.
ABC-PROFILE-TF-R11 (MUST)
-------------------------
Resource definitions MUST reside only in Resource Group modules (ABC‑C3).
ABC-PROFILE-TF-R12 (MUST)
-------------------------
Logical Units MUST NOT contain Terraform resources directly.
ABC-PROFILE-TF-R13 (SHOULD)
---------------------------
Logical Units SHOULD only orchestrate child modules and expose aggregated
outputs.
Canonical Example
=================
A minimal 3‑tier ABC architecture in Terraform.
Application Stack
-----------------
.. code-block:: hcl
:caption: main.tf
module "data" {
source = "./data"
environment = var.environment
region = var.region
}
module "logic" {
source = "./logic"
environment = var.environment
region = var.region
database_endpoint = module.data.database_endpoint
}
module "presentation" {
source = "./presentation"
environment = var.environment
region = var.region
frontend_assets_bucket = module.data.storage_bucket_name
api_endpoint = module.logic.api_endpoint
}
output "frontend_url" {
value = module.presentation.frontend_url
}
output "api_endpoint" {
value = module.logic.api_endpoint
}
.. code-block:: hcl
:caption: variables.tf
variable "environment" { type = string }
variable "region" { type = string }
Data Logical Unit
-----------------
.. code-block::
:caption: data/main.tf
module "storage" {
source = "./storage"
environment = var.environment
region = var.region
storage_class = var.storage_class
}
module "database" {
source = "./database"
environment = var.environment
db_engine = var.db_engine
db_instance_size = var.db_instance_size
}
output "storage_bucket_name" {
value = module.storage.bucket_name
}
output "database_endpoint" {
value = module.database.endpoint
}
.. code-block::
:caption: data/variables.tf
variable "environment" { type = string }
variable "region" { type = string }
variable "storage_class" { type = string }
variable "db_engine" { type = string }
variable "db_instance_size" { type = string }
Storage Resource Group
^^^^^^^^^^^^^^^^^^^^^^
.. code-block:: hcl
:caption: data/storage/main.tf
resource "aws_s3_bucket" "bucket" {
bucket = "${var.environment}-storage"
}
.. code-block:: hcl
:caption: data/storage/variables.tf
variable "environment" { type = string }
variable "region" { type = string }
variable "storage_class" { type = string }
.. code-block:: hcl
:caption: data/storage/outputs.tf
output "bucket_name" {
value = aws_s3_bucket.bucket.bucket
}

26
src/rules/index.rst Normal file
View file

@ -0,0 +1,26 @@
#####
Rules
#####
The ABC Pattern is defined and enforced through two complementary rule families:
.. toctree::
:glob:
:maxdepth: 1
*
Together, these rule sets establish the semantic, structural, and mechanical
guarantees that make ABC architectures predictable, verifiable, and safe for
automated reasoning and transformation.
Although closely related, the two rule families serve distinct purposes:
**Normative Rules** define the semantic contract of the ABC Pattern. They
specify what MUST, SHOULD, or MAY be true in any ABC‑compliant architecture,
independent of implementation language, cloud provider, or IaC tool.
**Validation Rules** define the mechanical checks required to verify that an ABC
architecture conforms to the Normative Rules and the ABC Schema. Where Normative
Rules describe what must be true, Validation Rules describe how to detect
violations.

328
src/rules/normative.rst Normal file
View file

@ -0,0 +1,328 @@
###############
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:
.. code-block::
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.

186
src/rules/validation.rst Normal file
View file

@ -0,0 +1,186 @@
################
Validation Rules
################
The ABC Validation Rules define the mechanical checks required to verify that an
ABC architecture conforms to the ABC Schema and the normative rules of the
specification. These rules are intended for:
* automated validators
* linters
* compilers
* agent‑driven code generation
* CI/CD enforcement
Validation Rules are **not** conceptual rules; they are operational constraints
that ensure an ABC description is structurally correct and unambiguous.
Validation Rules follow the canonical identifier format:
.. code-block::
ABC-VALID-R#
They are grouped into:
* Structural Validation
* Contract Validation
* Data‑Flow Validation
* Hierarchy Validation
* Profile‑Specific Validation (optional)
Structural Validation Rules
===========================
These rules ensure the ABC hierarchy is well‑formed.
ABC-VALID-R1 (MUST)
-------------------
Every construct MUST have exactly one parent, except the ApplicationStack which
MUST have none.
ABC-VALID-R2 (MUST)
-------------------
The hierarchy MUST follow the pattern:
``ApplicationStack → LogicalUnit → ResourceGroup``.
ABC-VALID-R3 (MUST)
-------------------
Construct trees MUST NOT contain cycles.
ABC-VALID-R4 (MUST)
-------------------
Construct IDs MUST be unique within the architecture.
ABC-VALID-R5 (MUST)
-------------------
Construct types MUST be one of:
ApplicationStack, LogicalUnit, ResourceGroup.
ABC-VALID-R6 (MUST)
-------------------
ResourceGroups MUST NOT have children.
ABC-VALID-R7 (MUST)
-------------------
LogicalUnits MUST NOT have parents that are not ApplicationStacks.
ABC-VALID-R8 (MUST)
-------------------
ResourceGroups MUST NOT have parents that are not LogicalUnits.
Contract Validation Rules
=========================
These rules ensure Input/Output Contracts are well‑defined and consistent.
ABC-VALID-R10 (MUST)
--------------------
Every construct MUST define both an InputContract and an OutputContract.
ABC-VALID-R11 (MUST)
--------------------
InputContracts MUST be immutable after instantiation.
ABC-VALID-R12 (MUST)
--------------------
Constructs MUST NOT reference values not present in their InputContract.
ABC-VALID-R13 (MUST)
--------------------
Constructs MUST NOT expose outputs not declared in their OutputContract.
ABC-VALID-R14 (SHOULD)
----------------------
OutputContracts SHOULD be minimal and stable across versions.
ABC-VALID-R15 (MUST)
--------------------
InputContracts MUST NOT reference parent or sibling constructs directly.
ABC-VALID-R16 (MUST)
--------------------
OutputContracts MUST NOT expose internal implementation details (e.g., resource
objects).
Data‑Flow Validation Rules
==========================
These rules enforce Capturing Down and Bubbling Up.
ABC-VALID-R20 (MUST)
--------------------
All downward references MUST originate from:
* parent.InputContract
* parent.OutputContract
ABC-VALID-R21 (MUST)
--------------------
All upward references MUST originate from:
* child.OutputContract
ABC-VALID-R22 (MUST)
--------------------
No lateral data flow is permitted between siblings.
ABC-VALID-R23 (MUST)
--------------------
Constructs MUST NOT read values from grandparents or ancestors except through
parent‑mediated Capturing Down.
ABC-VALID-R24 (MUST)
--------------------
Constructs MUST NOT write values to ancestors except through Bubbling Up.
ABC-VALID-R25 (MUST)
--------------------
Constructs MUST NOT read or write values from siblings or cousins.
Instantiation Validation Rules
==============================
These rules ensure constructs are instantiated correctly.
ABC-VALID-R30 (MUST)
--------------------
Constructs MUST be instantiated using the Instantiation Interface:
(scope, id, inputs).
ABC-VALID-R31 (MUST)
--------------------
Instantiation MUST NOT accept parameters outside the InputContract.
ABC-VALID-R32 (MUST)
--------------------
Instantiation MUST NOT produce side effects beyond constructing children.
ABC-VALID-R33 (MUST)
--------------------
Constructs MUST NOT mutate their InputContract after instantiation.

229
src/schema.rst Normal file
View file

@ -0,0 +1,229 @@
######
Schema
######
The ABC Schema is the authoritative, machine‑readable definition of the ABC
Pattern. It formalizes:
* Construct types
* Hierarchy rules
* Contract requirements
* Data‑flow semantics
* Instantiation constraints
* Validation rules
* Profile extension hooks
The schema is expressed as a single JSON Schema document, making it suitable
for:
* Linting
* Static analysis
* Code generation
* Agent reasoning
* Architecture validation
* Profile extension (CDKTS, Terraform, Pulumi, etc.)
This schema is intentionally strict. It defines the shape of an ABC
architecture, not the cloud resources themselves. Profiles map this schema to
concrete IaC implementations.
.. code-block:: json
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://schema.tiararodney.com/abc/abc.schema.json",
"title": "ABC Schema",
"description": "The canonical machine-readable schema for the ABC Pattern.",
"type": "object",
"properties": {
"version": {
"type": "string",
"description": "Schema version identifier."
},
"constructs": {
"type": "array",
"description": "List of constructs in the ABC architecture.",
"items": { "$ref": "#/$defs/Construct" }
}
},
"required": ["version", "constructs"],
"$defs": {
"Construct": {
"type": "object",
"description": "A construct in the ABC hierarchy.",
"properties": {
"id": {
"type": "string",
"description": "Unique identifier for the construct."
},
"type": {
"type": "string",
"enum": ["ApplicationStack", "LogicalUnit", "ResourceGroup"],
"description": "Construct type (ABC-C1, C2, or C3)."
},
"parent": {
"type": ["string", "null"],
"description": "Parent construct ID. Null only for ApplicationStack."
},
"inputs": {
"$ref": "#/$defs/InputContract"
},
"outputs": {
"$ref": "#/$defs/OutputContract"
},
"children": {
"type": "array",
"items": { "type": "string" },
"description": "IDs of child constructs."
}
},
"required": ["id", "type", "inputs", "outputs", "children"],
"allOf": [
{ "$ref": "#/$defs/HierarchyRules" },
{ "$ref": "#/$defs/ContractRules" },
{ "$ref": "#/$defs/DataFlowRules" }
]
},
"InputContract": {
"type": "object",
"description": "ABC-C4 Input Contract.",
"additionalProperties": {
"type": ["string", "number", "boolean", "object", "array", "null"]
}
},
"OutputContract": {
"type": "object",
"description": "ABC-C5 Output Contract.",
"additionalProperties": {
"type": ["string", "number", "boolean", "object", "array", "null"]
}
},
"HierarchyRules": {
"type": "object",
"description": "Hierarchy validation rules.",
"properties": {},
"allOf": [
{
"if": { "properties": { "type": { "const": "ApplicationStack" } } },
"then": {
"properties": {
"parent": { "type": "null" }
},
"errorMessage": {
"parent": "ABC-R3: ApplicationStack MUST have no parent."
}
}
},
{
"if": { "properties": { "type": { "const": "LogicalUnit" } } },
"then": {
"properties": {
"children": {
"minItems": 1,
"errorMessage": "ABC-R2: Logical Units MUST contain one or more Resource Groups."
}
}
}
},
{
"if": { "properties": { "type": { "const": "ResourceGroup" } } },
"then": {
"properties": {
"children": {
"maxItems": 0,
"errorMessage": "ABC-R10: Resource Groups MUST NOT contain child constructs."
}
}
}
}
]
},
"ContractRules": {
"type": "object",
"description": "Contract validation rules.",
"properties": {},
"allOf": [
{
"properties": {
"inputs": {
"type": "object",
"errorMessage": "ABC-R24: Input Contracts MUST be immutable objects."
}
}
},
{
"properties": {
"outputs": {
"type": "object",
"errorMessage": "ABC-R23: Output Contracts MUST be declared explicitly."
}
}
}
]
},
"DataFlowRules": {
"type": "object",
"description": "Data flow validation rules.",
"properties": {},
"allOf": [
{
"if": { "properties": { "type": { "const": "LogicalUnit" } } },
"then": {
"properties": {
"inputs": {
"type": "object"
}
}
}
}
]
}
}
}
How Profiles Extend This Schema
===============================
Profiles (e.g., Typescript CDK, Terraform) extend the monolithic schema using
JSON Schema’s allOf mechanism.
.. code-block:: json
:caption: https://schema.tiararodney.com/abc/profile/cdkts.json
{
"$id": "https://schema.tiararodney.com/abc/profile/cdkts.schema.json",
"title": "ABC CDK TypeScript Profile",
"allOf": [
{ "$ref": "https://abc-spec.org/schema/abc-schema.json" }
],
"properties": {
"cdkts": {
"type": "object",
"description": "CDKTS-specific rules and metadata."
}
}
}
How The Schema is Consumed
==========================
#. **Generate ABC structures from natural language**
The schema defines the allowed constructs and relationships.
#. **Validate the architecture**
The schema + validation rules ensure correctness.
#. **Compile into IaC**
Profiles map the schema to CDK, Terraform, Pulumi, etc.
#. **Refactor architectures**
Agents can safely transform the schema because the rules are explicit.
#. **Generate documentation**
The schema is a perfect source for diagrams and docs.