acdl/modules/STANDARDS.md

ACDL Module Engineering Standards

Standards for authoring and reviewing ACDL modules. These standards govern the two module tiers — L1 primitives (single cloud resource or small group of related resources) and L2 modules (compositions that reference L1 primitives to deploy a complete stack) — and the substrate adapter that compiles them to Terraform. They are written for platform engineers and AI agents that author or review new modules against the existing corpus (12 L1 primitives and 2 L2 modules shipped in v1.8).

A module that fails any section below is not ready to publish.

1. Overview

These standards codify the conventions already established by the shipped modules (s3, vpc, ecs-cluster, ecs-service, iam-role, alb, ecr, cloudfront, waf, rds, kms-key, uptime; the L2 modules static-assets and microservice). They exist so that:

• platform engineers can review a new module against a fixed checklist;
• AI agents authoring modules produce code that passes review without iteration; and
• the substrate adapter (adapters/terraform/adapter.py) can compile a module instance with no module-specific code in the adapter beyond the three tables in §8.

When this document and an existing module disagree, the existing module is the authority for v1.x. A change to this document is a MINOR version bump of the standards; a change that breaks shipped modules is a MAJOR bump and requires a migration plan.

2. L1 Primitive Standards

An L1 primitive is a single cloud resource or a small group of related resources (e.g. a VPC with subnets and a route table). It is declared by an interface.json and realized by the substrate adapter; it does not own Terraform code.

2.1 Required files

Every L1 primitive MUST contain, at minimum:

File	Purpose
interface.json	Substrate-agnostic declaration: inputs, outputs, NFRs, optional multi-resource graph.
instance.json	A concrete instance used as the adapter regression baseline.
README.md	Plain-language documentation following README-TEMPLATE.md (see §7).
examples/simple.yaml	A minimal contract that uses the primitive with required inputs only.
examples/complex.yaml	A contract that exercises optional inputs, NFRs, and (if applicable) the multi-resource graph.

Directory layout:

modules/l1/<name>/
  interface.json
  instance.json
  README.md
  examples/
    simple.yaml
    complex.yaml

2.2 interface.json schema

interface.json MUST be a JSON object with the following required fields:

Field	Type	Constraint
name	string	^[a-z][a-z0-9-]*$; MUST match the module folder name.
version	string	Semver (^\d+\d+\.\d+$); MUST match the registry entry semver.
kind	string	Literal "l1".
type	string	Stack type in aws:<service>:<kind> format (see §2.7).
description	string	One or two sentences in plain language; no Terraform jargon.
inputs	object	Keyed by input name; each value is an input declaration (§2.3). MAY be empty.
outputs	object	Keyed by output name; each value is an output declaration (§2.4). MAY be empty.
nfrs	object	Keyed by NFR name; each value is an NFR declaration (§2.5). MUST include deletion_protection and encryption_enabled.

Optional fields for multi-resource primitives:

Field	Type	Constraint
resources	array	One entry per distinct cloud resource; see §2.6.
intra_refs	array	Internal wiring between resources; see §2.6.

A primitive that creates a single resource (e.g. s3, iam-role, rds, kms-key) omits resources and intra_refs; its type field is the single resource's stack type. A primitive that creates a small group of related resources (e.g. vpc, alb, cloudfront) declares resources[] with one entry per resource and intra_refs[] for the internal wiring; its type field is the primary resource's stack type.

2.3 Input declaration

Each entry in inputs is an object:

Field	Type	Required	Notes
type	string	yes	One of: string, number, boolean, array, object.
description	string	yes	Plain language; no Terraform jargon.
required	boolean	yes	true if the consumer MUST supply this input.
default	(any)	no	Present only when required is false. MUST match the declared type.
enum	array	no	Allowed values for string/number inputs (e.g. RDS engine).

region is a required string input on every primitive that creates a regional resource. Global resources (e.g. CloudFront) still declare region because the provider region is used for child resources (the OAC in the cloudfront case).

Every primitive that holds at-rest data MUST declare an optional kms_key_arn input (string, required: false); see §4.

2.4 Output declaration

Each entry in outputs is an object:

Field	Type	Required	Notes
type	string	yes	arn for ARN outputs; string for all others.
description	string	yes	Plain language.

Use arn (not string) for any output that returns an AWS ARN — the adapter and policy engine key off the arn type to apply ARN-scoped rules.

2.5 NFR declaration

Each entry in nfrs is an object:

Field	Type	Required	Notes
type	string	yes	One of: string, number, boolean.
description	string	yes	Plain language.
default	(any)	yes	MUST match the declared type. NFRs always have a default.

Mandatory NFRs on every L1:

NFR	Type	Default	Notes
deletion_protection	boolean	true	See §5.
encryption_enabled	boolean	true	See §4.

A primitive for which an NFR does not conceptually apply (e.g. an IAM role has no at-rest data) still declares it with default: true and a description noting the non-applicability, so the standards check and the adapter emit logic stay uniform. The shipped iam-role primitive is the reference for this case.

Additional NFRs are encouraged where they carry operational meaning (e.g. s3.versioning, rds.backup_retention_period, kms-key.enable_rotation, vpc.flow_logs_encrypted). Name them in lowercase snake_case.

2.6 Multi-resource pattern

A primitive that creates more than one cloud resource (e.g. vpc creates aws_vpc + aws_subnet + aws_route_table; alb creates aws_lb + aws_lb_target_group + aws_lb_listener; cloudfront creates aws_cloudfront_distribution + aws_cloudfront_origin_access_control) declares a resources array.

Each resources[] entry:

Field	Type	Notes
type	string	The resource's stack type (aws:<service>:<kind>).
description	string	Plain language.
inputs	array	Names (strings) of inputs from the top-level inputs object that this resource consumes.
outputs	array	Names (strings) of outputs from the top-level outputs object that this resource produces.

The top-level inputs/outputs objects remain the single source of truth; resources[].inputs and resources[].outputs are arrays of names referencing those objects, not re-declarations.

intra_refs[] wires outputs of one resource to inputs of another within the same primitive. Each entry:

Field	Type	Notes
from	string	<resource-type>.<output-name> — the producing side.
to	string	<resource-type>.<input-name> — the consuming side.

Reference: cloudfront/interface.json declares an intra-ref from aws:cloudfront:distribution.oac_id to aws:cloudfront:originaccesscontrol.oac_id; vpc/interface.json declares intra-refs from the subnet and route table to the VPC's vpc_id.

2.7 Naming and stack types

• Module folder names and interface.json name values MUST match ^[a-z][a-z0-9-]*$ (lowercase, hyphenated, leading letter). Examples: s3, ecs-cluster, kms-key, iam-role, uptime.
• Input and output names are lowercase snake_case.
• Stack types follow aws:<service>:<kind>:
  • aws:s3:bucket
  • aws:ec2:vpc, aws:ec2:subnet, aws:ec2:routetable
  • aws:ecs:cluster, aws:ecs:task_definition, aws:ecs:service, aws:ecs:uptime-service
  • aws:iam:role
  • aws:elbv2:loadbalancer, aws:elbv2:listener, aws:elbv2:targetgroup
  • aws:ecr:repository
  • aws:cloudfront:distribution, aws:cloudfront:originaccesscontrol
  • aws:wafv2:webacl
  • aws:rds:instance
  • aws:kms:key, aws:kms:alias
• The substrate adapter's TYPE_MAP is the registry of stack types the adapter can compile (see §8). A new stack type requires a TYPE_MAP entry before the primitive can be deployed.

3. L2 Module Standards

An L2 module is a composition that references one or more L1 primitives to deploy a complete stack (e.g. an ECS Fargate microservice, a static asset site behind CloudFront + WAF). It is declared by a composition.json; it does not own Terraform code and does not have an instance.json.

3.1 Required files

File	Purpose
composition.json	The composition tree: children, wires, outputs, optional features.
README.md	Plain-language documentation following README-TEMPLATE.md (see §7).
examples/simple.yaml	A minimal contract that uses the module with required inputs only.
examples/complex.yaml	A contract that exercises optional inputs and feature flags.

Directory layout:

modules/l2/<name>/
  composition.json
  README.md
  examples/
    simple.yaml
    complex.yaml

There is no instance.json for an L2 module — the L2 is deployed by resolving the composition tree to L1 instances at compile time, not by loading a pre-baked instance.

3.2 composition.json schema

composition.json MUST be a JSON object with the following fields:

Field	Type	Required	Notes
name	string	yes	^[a-z][a-z0-9-]*$; matches the module folder name.
version	string	yes	Semver; matches the registry entry.
kind	string	yes	Literal "l2".
depth	integer	yes	Literal 1 in v1 (see §3.5).
description	string	yes	Plain language.
children	array	yes	One entry per referenced L1 module (§3.3).
wires	array	yes	Wires from contract inputs / child outputs to child inputs / stack outputs (§3.4).
outputs	array	yes	Wires from child outputs to stack outputs (§3.4).
features	object	no	Feature flags propagated to children by the resolver (§3.6).

3.3 Children

Each children[] entry:

Field	Type	Notes
id	string	The child id, unique within the composition. ^[a-z][a-z0-9-]*$. The id is the local name used in wires (e.g. vpc, cluster, kms).
module	string	<name>@<semver> referencing a registered L1 module.

Children MUST reference L1 modules registered in registry.json (see §6). The referenced semver MUST exist in the registry. An L2 MUST NOT reference another L2 (no L3 in v1; see §3.5).

Reference: microservice/composition.json declares seven children (vpc, cluster, ecr, roles, alb, service, kms), each referencing an L1 at @1.0.0.

3.4 Wire format

A wire is a JSON object {"from": "<source>", "to": "<target>"} with an optional default field for contract-input wires.

Sources (the from side):

Source form	Meaning
contract.inputs.<name>	A value supplied by the consumer's contract YAML.
<childId>.outputs.<name>	An output produced by a child L1 module.

Targets (the to side):

Target form	Meaning
<childId>.inputs.<name>	An input on a child L1 module.
stack.outputs.<name>	A value the L2 exposes as a stack output.

Wires that source from contract.inputs.<name> MAY carry a default value used when the consumer omits the input. Reference: microservice/composition.json wires contract.inputs.bucket_name to vpc.inputs.cidr with default: "10.0.0.0/16" (a historical quirk preserved for regression).

The outputs[] array uses the same wire shape but its to is always stack.outputs.<name> and its from is always <childId>.outputs.<name>.

3.5 Maximum depth

depth is 1 for every L2 in v1. The composition tree is strictly L2 → L1: an L2 may reference only L1 primitives, never another L2. There is no L3 in v1. The stack schema permits depth up to 5 for forward compatibility, but the v1 resolver and adapter only handle depth 1.

3.6 Feature flags

An L2 MAY declare a features object. Two flags are defined in v1:

Flag	Type	Default	Effect
deletion_protection	boolean	true	When true, the resolver propagates deletion_protection: true to every child's NFRs. When false, children are deployed with deletion_protection: false (used by decommission; see §5).
uptime_enabled	boolean	true	When true, the uptime monitoring L1 is deployed after the L2 module in a separate terraform state. When false, the uptime deployment is skipped.

Feature flags are propagated to children by the resolver; the L2 composition.json does not need to wire them explicitly as inputs. The resolver reads features and injects the corresponding NFR/input on each child.

4. Encryption by Default

Encryption is mandatory and on by default across the platform.

1. Every L1 MUST declare an encryption_enabled NFR (boolean, default true) in interface.json. See §2.5.
2. Every L1 that holds at-rest data (S3, RDS, ECR, ECS task definition env, VPC flow logs, CloudWatch log groups) MUST declare an optional kms_key_arn input (string, required: false). When supplied, the adapter wires it to the resource's KMS encryption argument.
3. L2 modules MUST wire a per-stack customer-managed KMS key to all children that accept kms_key_arn. The KMS key is a kms-key child of the L2 — one key per L2 deployment, no shared keys. Reference: both static-assets and microservice declare a kms child (kms-key@1.0.0) and wire kms.outputs.kms_key_arn to every child that accepts a CMK.
4. For a standalone L1 deployment (an L1 used outside an L2), if the consumer does not supply kms_key_arn, the adapter falls back to the AWS-managed default key for that service and emits a warning to stderr. The primitive is still encrypted; only the key manager differs.
5. The kms-key primitive enables key rotation by default (enable_rotation NFR, default true), and the adapter emits enable_key_rotation = true on the aws_kms_key resource.

A primitive that does not hold at-rest data (e.g. iam-role, ecs-cluster, alb) still declares encryption_enabled for standards uniformity (see §2.5) but does not declare kms_key_arn.

5. Deletion Protection by Default

Deletion protection is mandatory and on by default to prevent accidental teardown of production infrastructure.

1. Every L1 MUST declare a deletion_protection NFR (boolean, default true) in interface.json. See §2.5.
2. When deletion_protection is true, the substrate adapter emits a lifecycle { prevent_destroy = true } block on the corresponding Terraform resource. A terraform destroy against a protected resource fails with an error naming the resource.
3. L2 modules expose features.deletion_protection (default true). The resolver propagates the flag to every child's NFRs (see §3.6).
4. Decommission mode. To tear down a stack that was deployed with deletion protection, the consumer sets inputs.deletion_protection: false on the contract (or features.deletion_protection: false on an L2) and re-applies. The decommission transform (decommission_transform) zeroes capacity counts (e.g. ECS desired count to 0, RDS allocated storage to the minimum) so that the subsequent destroy applies against a quiesced stack. The transform is applied by the resolver before the adapter emits resources.

6. Registry

Every module — L1 and L2 — MUST be registered in modules/registry.json at its semver. The registry is the source of truth for what is published; the adapter and resolver refuse to compile a module that is not registered.

Registry entry shape:

{
  "<module-name>": {
    "<semver>": {
      "interface": "modules/<l1|l2>/<module-name>/<interface.json|composition.json>",
      "published_at": "<ISO 8601 timestamp>",
      "deprecated": false
    }
  }
}

• interface is the path (relative to the repo root) to the module's interface file — interface.json for an L1, composition.json for an L2.
• published_at is an ISO 8601 timestamp. Use a full YYYY-MM-DDTHH:MM:SSZ form; do not omit the seconds or the timezone designator.
• deprecated is false for a live module. A MAJOR version bump does not delete the old entry; it flips deprecated to true and starts a 12-month deprecation window (see §7 Versioning).

A new semver of an existing module is a new key under the module's object; old semvers are retained. The registry is append-only for published semvers — a published semver is never edited or deleted.

7. README Standards

Every module README MUST follow the structure of modules/README-TEMPLATE.md. Required sections, in order:

1. # <name> — <plain-language description> — title with the module name and a one-line description.
2. ## Overview — one or two sentences in plain language.
3. ## Resources — a table of the Terraform resources the module creates (L1) or the primitives it references (L2).
4. ## Inputs — a table: | Name | Type | Required | Default | Description |.
5. ## Outputs — a table: | Name | Type | Description |.
6. ## NFRs — a table: | Name | Type | Default | Description |. deletion_protection and encryption_enabled are mandatory NFRs for every L1; they MUST appear in this table.
7. ## Usage — a concrete snippet showing how a consumer references the module in a contract.
8. ## Compliance extension points — resources or behaviors that could be added for the future compliance milestone (GDPR, SOX, SOC2, HIPAA, DORA). Not implemented yet; listed so the redesign can plan for them.
9. ## Examples — links to examples/simple.yaml and examples/complex.yaml with a one-line description of each.
10. ## Versioning — the module's semver policy: interface MAJOR, behavior MINOR, lifecycle PATCH. MAJOR bumps require a new registry.json entry (immutable publication); old entries enter a 12-month deprecation window.

An L2 README's ## Resources section lists the referenced L1 children rather than Terraform resources, and its ## Inputs/## Outputs sections reflect the contract inputs and stack outputs of the composition.

8. Adapter Extension Pattern

The Terraform adapter (adapters/terraform/adapter.py) is a thin translator. It owns no module content; it only maps stack types and names to Terraform types and arguments via three tables and, for complex resources, a specialized emit branch.

8.1 The three tables

Table	Purpose	Keys	Values
TYPE_MAP	Stack type → Terraform resource type.	Stack type string (aws:<service>:<kind>).	Terraform resource type (aws_s3_bucket, aws_db_instance, etc.).
INPUT_MAP	Stack input name → Terraform argument name, per stack type. Only non-identity mappings are listed; an input not present uses the stack name as the Terraform arg (identity).	Stack type.	Object mapping input name → Terraform arg name.
OUTPUT_MAP	Stack output name → Terraform attribute name, per stack type. Only non-identity mappings are listed.	Stack type.	Object mapping output name → Terraform attribute name.

Reference: adapter.py:26 (TYPE_MAP), adapter.py:51 (INPUT_MAP), adapter.py:75 (OUTPUT_MAP).

8.2 Specialized _emit_resource branches

Most resources emit with the generic loop in _emit_resource (adapter.py:156): for each input, look up the Terraform arg in INPUT_MAP, render the value, append arg = value. Resources with nested HCL blocks need a specialized branch. The shipped examples:

• aws:ecs:service emits a load_balancer {} block from the lb_target_group_arn input.
• aws:elbv2:loadbalancer wraps subnets and security_group in list brackets.
• aws:cloudfront:distribution emits nested origin {}, default_cache_behavior {}, and server_side_encryption_configuration {} blocks.
• aws:wafv2:webacl emits nested rules {} blocks.
• aws:ecs:task_definition emits a container_definitions jsonencode block from image/port/env.

A specialized branch lives inside _emit_resource and is keyed on the stack type. It reads the input value, renders the nested block, and appends the lines to body.

8.3 Adding a new L1 to the adapter

When a new L1 primitive is added:

1. Add one entry to TYPE_MAP for each stack type the primitive declares (single resource → one entry; multi-resource → one entry per resource in resources[]).
2. Add one entry to INPUT_MAP for each stack type, listing only the inputs whose Terraform arg name differs from the stack input name (identity mappings are omitted).
3. Add one entry to OUTPUT_MAP for each stack type, listing only the outputs whose Terraform attribute name differs from the stack output name.
4. If any resource requires nested HCL blocks, add a specialized branch in _emit_resource keyed on that stack type.

If steps 1–3 are done and no specialized branch is needed, the primitive deploys with no further adapter changes. The L1 content and the contract YAML do not change when the adapter grows.

9. Code Review Checklist

Use this checklist when reviewing a new module (L1 or L2). Every box must be checked before the module is registered and published.

9.1 Files and structure

• All required files present:
  • L1: interface.json, instance.json, README.md, examples/simple.yaml, examples/complex.yaml.
  • L2: composition.json, README.md, examples/simple.yaml, examples/complex.yaml (no instance.json).
• interface.json (L1) / composition.json (L2) validates against schemas/stack.schema.json.
• examples/simple.yaml and examples/complex.yaml validate against schemas/contract.schema.json.
• Module registered in modules/registry.json at its semver with a full ISO 8601 published_at and deprecated: false.

9.2 Interface (L1)

• name matches the folder name and ^[a-z][a-z0-9-]*$.
• version is semver and matches the registry entry.
• kind is "l1".
• type follows aws:<service>:<kind>.
• Every input has type, description, required; optional inputs carry a default of the correct type; enum present where the value set is constrained.
• Every output has type (arn for ARNs, string otherwise) and description.
• nfrs includes deletion_protection (boolean, default true) and encryption_enabled (boolean, default true).
• kms_key_arn input present if the primitive holds at-rest data.
• Multi-resource primitives declare resources[] (with inputs/ outputs as arrays of names) and intra_refs[] with {from, to}.

9.3 Composition (L2)

• kind is "l2" and depth is 1.
• Every children[] entry is {id, module} with module in <name>@<semver> form referencing a registered L1.
• No child references an L2 (no L3 in v1).
• wires[] use the contract.inputs.<name> / <childId>.outputs.<name> → <childId>.inputs.<name> / stack.outputs.<name> forms.
• outputs[] use <childId>.outputs.<name> → stack.outputs.<name>.
• A kms child (kms-key@<semver>) is present and its kms_key_arn output is wired to every child that accepts a CMK.
• features (if present) only uses defined flags (deletion_protection, uptime_enabled).

9.4 Adapter

• TYPE_MAP has an entry for every stack type the new primitive declares.
• INPUT_MAP and OUTPUT_MAP have entries for every stack type, listing only non-identity mappings.
• A specialized _emit_resource branch is added for any resource that needs nested HCL blocks.
• The new primitive's instance.json round-trips through the adapter without error (regression baseline).

9.5 README and docs

• README follows README-TEMPLATE.md with all required sections in order (§7).
• ## NFRs table lists deletion_protection and encryption_enabled for an L1.
• ## Compliance extension points lists at least one plausible future extension.

9.6 Tests

• A test is added for the new primitive covering adapter emission (the Terraform output for instance.json matches the expected fixture) and interface validation (interface.json validates against stack.schema.json).
• For an L2, a test is added that the composition resolves to the expected set of L1 instances and that the adapter emits a root module calling the L1 modules.