docs(P20): specify phase 20 — consumer happy path + reusable deploy workflow (v1.5)

---ci--- project: acdl phase: 20 milestone: v1.5 status: specify ---/ci--- Add v1.5 milestone to ROADMAP.md + REQUIREMENTS.md. Phase 20 covers REQ-46 (README consumer model + mermaid + L3B/spike scrub), REQ-47 (generic CONSUMER_GUIDE.md + versioned uses: + consumer-scoped prereqs + run-time platform fetch), REQ-48 (zero-trust OIDC/ABAC credentials + static-key override + daily rotation), REQ-49 (reusable byte-identical deploy.yml Gitea+GitHub implementing pipelines/deploy.yaml), REQ-50 (contracts/static-asset.yaml @v1.4), REQ-51 (deploy-workflow conformance tests). Update config.json milestone to v1.5.
2026-07-22 17:09:23 +00:00
parent e050e65158
commit 895a2f3806
78 changed files with 55 additions and 4297 deletions
@@ -0,0 +1,71 @@
+# l1-alb — Application Load Balancer (load balancer + target group + listener)
+
+> **Module kind:** L1 primitive  |  **Version:** 1.0.0
+
+An Application Load Balancer with a target group and a listener. This is
+a multi-resource module: it creates a load balancer, a target group, and
+a listener that forwards traffic to the target group. The target group
+is what `l1-ecs-service` registers its tasks with.
+
+## Resources
+
+| Resource | Type | Purpose |
+|----------|------|---------|
+| load_balancer | `aws_lb` | Application load balancer in the VPC subnets |
+| target_group | `aws_lb_target_group` | Target group for the ECS service tasks |
+| listener | `aws_lb_listener` | Listener forwarding the LB port to the target group |
+
+## Inputs
+
+| Name | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `name` | string | yes | — | Name tag for the load balancer and child resources |
+| `subnets` | string | yes | — | Comma-separated subnet ids (from `l1-vpc`) |
+| `security_group` | string | yes | — | Security group id for the load balancer |
+| `port` | number | no | 80 | Listener port |
+| `protocol` | string | no | `HTTP` | Listener protocol |
+| `region` | string | yes | — | AWS region the load balancer is created in |
+
+## Outputs
+
+| Name | Type | Description |
+|------|------|-------------|
+| `lb_arn` | arn | The load balancer ARN |
+| `listener_arn` | arn | The listener ARN |
+| `target_group_arn` | arn | The target group ARN |
+
+## Usage
+
+```json
+{
+  "id": "alb",
+  "type": "aws:elbv2:loadbalancer",
+  "module": "l1-alb@1.0.0",
+  "inputs": {
+    "name": "acdl-microservice",
+    "subnets": "ref:vpc.subnet_ids",
+    "security_group": "ref:roles.role_arn",
+    "port": 8080,
+    "protocol": "HTTP",
+    "region": "us-east-1"
+  }
+}
+```
+
+The `target_group_arn` output is referenced by `l1-ecs-service` as its
+`lb_target_group_arn` input to wire the service to the ALB.
+
+## Compliance extension points
+
+- **TLS / HTTPS listener** — add `aws_acm_certificate` + `ssl_policy` + `certificate_arn` for encryption in transit (SOC2 CC6.1, PCI-DSS 4.1, HIPAA §164.312(e)(1), GDPR Art.32).
+- **Access logs** — add `access_logs { bucket = ..., prefix = ... }` to the load balancer (SOX, SOC2 CC7.2, DORA ICT audit trail).
+- **Security group rules** — add ingress/egress rules restricting traffic to known sources (SOC2 CC6.6, PCI-DSS 1.2).
+- **Health check** — add a `health_check` block to the target group (SOC2 CC7.3 monitoring, DORA operational resilience).
+- **WAF** — add `aws_wafv2_web_acl_association` for application-layer protection (SOC2 CC7.6, PCI-DSS 6.5, DORA ICT risk).
+- **Deregistration delay** — add `deregistration_delay` for graceful draining (SOC2 CC9.1 resilience).
+
+## Versioning
+
+`1.0.0` — interface MAJOR, behavior MINOR, lifecycle PATCH. MAJOR bumps
+require a new registry entry (immutable publication); old entries enter
+a 12-month deprecation window.
@@ -0,0 +1,76 @@
+{
+  "name": "l1-alb",
+  "version": "1.0.0",
+  "kind": "l1",
+  "type": "aws:elbv2:loadbalancer",
+  "description": "Application Load Balancer primitive (substrate-agnostic IR types aws:elbv2:loadbalancer + aws:elbv2:listener + aws:elbv2:targetgroup; the Terraform adapter translates to aws_lb/aws_lb_listener/aws_lb_target_group).",
+  "inputs": {
+    "name": {
+      "type": "string",
+      "description": "Name tag for the load balancer and child resources.",
+      "required": true
+    },
+    "subnets": {
+      "type": "string",
+      "description": "Comma-separated subnet ids (ref to l1-vpc).",
+      "required": true
+    },
+    "security_group": {
+      "type": "string",
+      "description": "Security group id for the load balancer.",
+      "required": true
+    },
+    "port": {
+      "type": "number",
+      "description": "Listener port (default 80).",
+      "required": false,
+      "default": 80
+    },
+    "protocol": {
+      "type": "string",
+      "description": "Listener protocol (default HTTP).",
+      "required": false,
+      "default": "HTTP"
+    },
+    "region": {
+      "type": "string",
+      "description": "AWS region the load balancer is created in.",
+      "required": true
+    }
+  },
+  "outputs": {
+    "lb_arn": {
+      "type": "arn",
+      "description": "The load balancer ARN."
+    },
+    "listener_arn": {
+      "type": "arn",
+      "description": "The listener ARN."
+    },
+    "target_group_arn": {
+      "type": "arn",
+      "description": "The target group ARN."
+    }
+  },
+  "nfrs": {},
+  "resources": [
+    {
+      "type": "aws:elbv2:loadbalancer",
+      "description": "Application load balancer in the VPC subnets.",
+      "inputs": ["name", "subnets", "security_group"],
+      "outputs": ["lb_arn"]
+    },
+    {
+      "type": "aws:elbv2:targetgroup",
+      "description": "Target group for the ECS service tasks.",
+      "inputs": ["name", "port", "protocol", "vpc_id"],
+      "outputs": ["target_group_arn"]
+    },
+    {
+      "type": "aws:elbv2:listener",
+      "description": "Listener forwarding the LB port to the target group.",
+      "inputs": ["lb_arn", "port", "protocol", "target_group_arn"],
+      "outputs": ["listener_arn"]
+    }
+  ]
+}
@@ -0,0 +1,58 @@
+# l1-ecr — ECR repository
+
+> **Module kind:** L1 primitive  |  **Version:** 1.0.0
+
+A single ECR repository that hosts the container image for the ECS
+task. The simplest container-registry module — one resource, two
+inputs, two outputs.
+
+## Resources
+
+| Resource | Type | Purpose |
+|----------|------|---------|
+| repository | `aws_ecr_repository` | The ECR repository |
+
+## Inputs
+
+| Name | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `name` | string | yes | — | The ECR repository name |
+| `region` | string | yes | — | AWS region the repository is created in |
+
+## Outputs
+
+| Name | Type | Description |
+|------|------|-------------|
+| `repository_url` | string | The ECR repository URL |
+| `repository_arn` | arn | The ECR repository ARN |
+
+## Usage
+
+```json
+{
+  "id": "ecr",
+  "type": "aws:ecr:repository",
+  "module": "l1-ecr@1.0.0",
+  "inputs": {
+    "name": "acdl-microservice",
+    "region": "us-east-1"
+  }
+}
+```
+
+The `repository_url` output is used to build the `image` input for
+`l1-ecs-service` (e.g. `<repository_url>:latest`).
+
+## Compliance extension points
+
+- **Image scanning** — add `image_scanning_configuration { scan_on_push = true }` for vulnerability scanning (SOC2 CC7.6, DORA ICT risk testing, HIPAA security monitoring).
+- **Encryption** — add `encryption_configuration { encryption_type = "KMS", kms_key = ... }` with a customer-managed key (SOC2 CC6.1, HIPAA §164.312(a)(2)(iv), GDPR Art.32).
+- **Image tag immutability** — add `image_tag_mutability = "IMMUTABLE"` to prevent tag overwriting (SOX §802, SOC2 CC6.1 integrity, DORA audit integrity).
+- **Lifecycle policy** — add `aws_ecr_lifecycle_policy` to enforce image retention / cleanup (GDPR Art.5(2) data minimization, SOC2 CC5.2).
+- **Access policy** — add a repository policy restricting pull/push to known roles (SOC2 CC6.1, HIPAA §164.308(a)(4)).
+
+## Versioning
+
+`1.0.0` — interface MAJOR, behavior MINOR, lifecycle PATCH. MAJOR bumps
+require a new registry entry (immutable publication); old entries enter
+a 12-month deprecation window.
@@ -0,0 +1,30 @@
+{
+  "name": "l1-ecr",
+  "version": "1.0.0",
+  "kind": "l1",
+  "type": "aws:ecr:repository",
+  "description": "ECR repository primitive (substrate-agnostic IR type aws:ecr:repository; the Terraform adapter translates to aws_ecr_repository).",
+  "inputs": {
+    "name": {
+      "type": "string",
+      "description": "The ECR repository name.",
+      "required": true
+    },
+    "region": {
+      "type": "string",
+      "description": "AWS region the repository is created in.",
+      "required": true
+    }
+  },
+  "outputs": {
+    "repository_url": {
+      "type": "string",
+      "description": "The ECR repository URL."
+    },
+    "repository_arn": {
+      "type": "arn",
+      "description": "The ECR repository ARN."
+    }
+  },
+  "nfrs": {}
+}
@@ -0,0 +1,56 @@
+# l1-ecs-cluster — ECS Fargate cluster
+
+> **Module kind:** L1 primitive  |  **Version:** 1.0.0
+
+An ECS Fargate cluster. The simplest ECS module — one resource, two
+inputs, two outputs. The cluster is the container orchestration
+boundary that `l1-ecs-service` references for task placement.
+
+## Resources
+
+| Resource | Type | Purpose |
+|----------|------|---------|
+| cluster | `aws_ecs_cluster` | The ECS Fargate cluster |
+
+## Inputs
+
+| Name | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `name` | string | yes | — | The ECS cluster name |
+| `region` | string | yes | — | AWS region the cluster is created in |
+
+## Outputs
+
+| Name | Type | Description |
+|------|------|-------------|
+| `cluster_arn` | arn | The ECS cluster ARN |
+| `cluster_id` | string | The ECS cluster id (name) |
+
+## Usage
+
+```json
+{
+  "id": "cluster",
+  "type": "aws:ecs:cluster",
+  "module": "l1-ecs-cluster@1.0.0",
+  "inputs": {
+    "name": "acdl-microservice",
+    "region": "us-east-1"
+  }
+}
+```
+
+The `cluster_arn` output is referenced by `l1-ecs-service` as its
+`cluster_arn` input.
+
+## Compliance extension points
+
+- **Container Insights** — add `configuration { container_insights = "enabled" }` for observability (SOC2 CC7.3, DORA ICT risk monitoring).
+- **CloudWatch Logs** — add a log group with retention policy for cluster-level audit logs (SOX, SOC2 CC7.2, HIPAA §164.312(b)).
+- **Encryption** — add `settings { name = "containerInsights", value = "enabled" }` and KMS-based encryption for container data (HIPAA §164.312(a)(2)(iv), GDPR Art.32).
+
+## Versioning
+
+`1.0.0` — interface MAJOR, behavior MINOR, lifecycle PATCH. MAJOR bumps
+require a new registry entry (immutable publication); old entries enter
+a 12-month deprecation window.
@@ -0,0 +1,30 @@
+{
+  "name": "l1-ecs-cluster",
+  "version": "1.0.0",
+  "kind": "l1",
+  "type": "aws:ecs:cluster",
+  "description": "ECS Fargate cluster primitive (substrate-agnostic IR type aws:ecs:cluster; the Terraform adapter translates to aws_ecs_cluster).",
+  "inputs": {
+    "name": {
+      "type": "string",
+      "description": "The ECS cluster name.",
+      "required": true
+    },
+    "region": {
+      "type": "string",
+      "description": "AWS region the cluster is created in.",
+      "required": true
+    }
+  },
+  "outputs": {
+    "cluster_arn": {
+      "type": "arn",
+      "description": "The ECS cluster ARN."
+    },
+    "cluster_id": {
+      "type": "string",
+      "description": "The ECS cluster id (name)."
+    }
+  },
+  "nfrs": {}
+}
@@ -0,0 +1,78 @@
+# l1-ecs-service — ECS Fargate service (task definition + service)
+
+> **Module kind:** L1 primitive  |  **Version:** 1.0.0
+
+An ECS Fargate service with its task definition. Runs a container image
+on Fargate, optionally behind an ALB target group. This is a
+multi-resource module: it creates a task definition and a service that
+runs it.
+
+## Resources
+
+| Resource | Type | Purpose |
+|----------|------|---------|
+| task_definition | `aws_ecs_task_definition` | Fargate task definition with container image, CPU, memory, port, env |
+| service | `aws_ecs_service` | Fargate service running the task definition in a cluster + subnets |
+
+## Inputs
+
+| Name | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `image` | string | yes | — | ECR image URL for the task container |
+| `port` | number | yes | — | Container port the service listens on |
+| `cpu` | number | no | 256 | Task CPU units (Fargate) |
+| `memory` | number | no | 512 | Task memory in MiB (Fargate) |
+| `env` | string | no | — | Environment variables as a JSON map string |
+| `cluster_arn` | arn | yes | — | ECS cluster ARN (from `l1-ecs-cluster`) |
+| `subnets` | string | yes | — | Comma-separated subnet ids (from `l1-vpc`) |
+| `security_group` | string | yes | — | Security group id for the service ENIs |
+| `lb_target_group_arn` | arn | no | — | Optional ALB target group ARN (from `l1-alb`) |
+| `region` | string | yes | — | AWS region the service is created in |
+
+## Outputs
+
+| Name | Type | Description |
+|------|------|-------------|
+| `service_arn` | arn | The ECS service ARN |
+| `task_def_arn` | arn | The ECS task definition ARN |
+
+## Usage
+
+```json
+{
+  "id": "service",
+  "type": "aws:ecs:task_definition",
+  "module": "l1-ecs-service@1.0.0",
+  "inputs": {
+    "image": "581513795199.dkr.ecr.us-east-1.amazonaws.com/acdl-microservice:latest",
+    "port": 8080,
+    "cpu": 256,
+    "memory": 512,
+    "cluster_arn": "ref:cluster.cluster_arn",
+    "subnets": "ref:vpc.subnet_ids",
+    "security_group": "ref:roles.role_arn",
+    "region": "us-east-1"
+  }
+}
+```
+
+The `image`, `port`, and `env` inputs are compiled into a
+`container_definitions` JSON block by the adapter. The service is
+placed in the cluster with the given subnets and security group, and
+optionally wired to the ALB target group if `lb_target_group_arn` is
+provided.
+
+## Compliance extension points
+
+- **CloudWatch Logs** — add `logConfiguration` to the container definition with a log group + retention policy (SOX, SOC2 CC7.2, HIPAA §164.312(b), DORA ICT incident logging).
+- **Task execution role separation** — add a separate `aws_iam_role` for execution vs. the task role (SOC2 CC6.3 segregation of duties at runtime).
+- **Secrets injection** — add `secrets` block referencing AWS Secrets Manager / SSM Parameter Store with KMS encryption (SOC2 CC6.1, HIPAA §164.312(a)(2)(iv)).
+- **Execute command** — add `enable_execute_command` with KMS encryption for session audit (SOC2 CC7.2).
+- **Deployment circuit breaker** — add `deployment_circuit_breaker` block for resilience (SOC2 CC9.1, DORA operational resilience).
+- **Health check** — add a `health_check` block to the target group (currently missing despite the contract schema having a healthcheck field).
+
+## Versioning
+
+`1.0.0` — interface MAJOR, behavior MINOR, lifecycle PATCH. MAJOR bumps
+require a new registry entry (immutable publication); old entries enter
+a 12-month deprecation window.
@@ -0,0 +1,86 @@
+{
+  "name": "l1-ecs-service",
+  "version": "1.0.0",
+  "kind": "l1",
+  "type": "aws:ecs:task_definition",
+  "description": "ECS Fargate service primitive (substrate-agnostic IR types aws:ecs:task_definition + aws:ecs:service; the Terraform adapter translates to aws_ecs_task_definition/aws_ecs_service).",
+  "inputs": {
+    "image": {
+      "type": "string",
+      "description": "ECR image URL for the task container.",
+      "required": true
+    },
+    "port": {
+      "type": "number",
+      "description": "Container port the service listens on.",
+      "required": true
+    },
+    "cpu": {
+      "type": "number",
+      "description": "Task CPU units (Fargate).",
+      "required": false,
+      "default": 256
+    },
+    "memory": {
+      "type": "number",
+      "description": "Task memory (MiB, Fargate).",
+      "required": false,
+      "default": 512
+    },
+    "env": {
+      "type": "string",
+      "description": "Environment variables as a JSON map string (optional).",
+      "required": false
+    },
+    "cluster_arn": {
+      "type": "arn",
+      "description": "ECS cluster ARN (ref to l1-ecs-cluster).",
+      "required": true
+    },
+    "subnets": {
+      "type": "string",
+      "description": "Comma-separated subnet ids (ref to l1-vpc).",
+      "required": true
+    },
+    "security_group": {
+      "type": "string",
+      "description": "Security group id for the service ENIs.",
+      "required": true
+    },
+    "lb_target_group_arn": {
+      "type": "arn",
+      "description": "Optional ALB target group ARN (ref to l1-alb).",
+      "required": false
+    },
+    "region": {
+      "type": "string",
+      "description": "AWS region the service is created in.",
+      "required": true
+    }
+  },
+  "outputs": {
+    "service_arn": {
+      "type": "arn",
+      "description": "The ECS service ARN."
+    },
+    "task_def_arn": {
+      "type": "arn",
+      "description": "The ECS task definition ARN."
+    }
+  },
+  "nfrs": {},
+  "resources": [
+    {
+      "type": "aws:ecs:task_definition",
+      "description": "Fargate task definition; the adapter jsonencodes image/port/env into container_definitions.",
+      "inputs": ["image", "port", "cpu", "memory", "env"],
+      "outputs": ["task_def_arn"]
+    },
+    {
+      "type": "aws:ecs:service",
+      "description": "Fargate service running the task definition in the cluster + subnets.",
+      "inputs": ["cluster_arn", "subnets", "security_group", "lb_target_group_arn"],
+      "outputs": ["service_arn"]
+    }
+  ]
+}
@@ -0,0 +1,64 @@
+# l1-iam-role — IAM role
+
+> **Module kind:** L1 primitive  |  **Version:** 1.0.0
+
+A single IAM role with an assume-role policy and optional managed
+policy attachments. Used as the ECS task execution role.
+
+## Resources
+
+| Resource | Type | Purpose |
+|----------|------|---------|
+| role | `aws_iam_role` | The IAM role with assume-role policy |
+
+## Inputs
+
+| Name | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `role_name` | string | yes | — | The IAM role name |
+| `assume_role_policy` | string | yes | — | Assume-role policy document (JSON string) |
+| `managed_policies` | string | no | — | Comma-separated list of managed policy ARNs to attach |
+| `region` | string | yes | — | AWS region the role is created in |
+
+## Outputs
+
+| Name | Type | Description |
+|------|------|-------------|
+| `role_arn` | arn | The IAM role ARN |
+| `role_id` | string | The IAM role id |
+
+## Usage
+
+```json
+{
+  "id": "roles",
+  "type": "aws:iam:role",
+  "module": "l1-iam-role@1.0.0",
+  "inputs": {
+    "role_name": "acdl-microservice-exec",
+    "assume_role_policy": "{\"Version\":\"2012-10-17\",\"Statement\":[{\"Effect\":\"Allow\",\"Principal\":{\"Service\":\"ecs-tasks.amazonaws.com\"},\"Action\":\"sts:AssumeRole\"}]}",
+    "managed_policies": "arn:aws:iam::aws:policy/service-role/AmazonECSTaskExecutionRolePolicy",
+    "region": "us-east-1"
+  }
+}
+```
+
+The `assume_role_policy` is a JSON string — the adapter jsonencodes it
+into the Terraform `assume_role_policy` argument. The
+`managed_policies` input is a comma-separated list of ARNs, emitted as
+`managed_policy_arns = [...]`.
+
+## Compliance extension points
+
+- **Permissions boundary** — add `permissions_boundary` to enforce least-privilege guardrails (SOC2 CC6.1, SOX ITGC, DORA ICT access control).
+- **Inline policy** — add `aws_iam_role_policy` for fine-grained least-privilege instead of broad managed policies (SOC2 CC6.1, HIPAA §164.308(a)(4)).
+- **MFA conditions** — add `condition` blocks requiring MFA for assume-role (SOC2 CC6.1, HIPAA §164.312(d)).
+- **Source IP / region conditions** — add `aws:SourceIp` / `aws:RequestedRegion` conditions for data residency enforcement (GDPR Art.44-49, DORA ICT third-party risk).
+- **Access Analyzer** — add `aws_accessanalyzer_analyzer` to verify least-privilege (SOC2 CC6.1, GDPR Art.32).
+- **Role separation** — add a separate task role vs. execution role (SOC2 CC6.3 segregation of duties).
+
+## Versioning
+
+`1.0.0` — interface MAJOR, behavior MINOR, lifecycle PATCH. MAJOR bumps
+require a new registry entry (immutable publication); old entries enter
+a 12-month deprecation window.
@@ -0,0 +1,40 @@
+{
+  "name": "l1-iam-role",
+  "version": "1.0.0",
+  "kind": "l1",
+  "type": "aws:iam:role",
+  "description": "IAM role primitive (substrate-agnostic IR type aws:iam:role; the Terraform adapter translates to aws_iam_role).",
+  "inputs": {
+    "role_name": {
+      "type": "string",
+      "description": "The IAM role name.",
+      "required": true
+    },
+    "assume_role_policy": {
+      "type": "string",
+      "description": "Assume-role policy document (JSON string).",
+      "required": true
+    },
+    "managed_policies": {
+      "type": "string",
+      "description": "Comma-separated list of managed policy ARNs to attach.",
+      "required": false
+    },
+    "region": {
+      "type": "string",
+      "description": "AWS region the role is created in.",
+      "required": true
+    }
+  },
+  "outputs": {
+    "role_arn": {
+      "type": "arn",
+      "description": "The IAM role ARN."
+    },
+    "role_id": {
+      "type": "string",
+      "description": "The IAM role id."
+    }
+  },
+  "nfrs": {}
+}
@@ -0,0 +1,63 @@
+# l1-s3 — S3 bucket
+
+> **Module kind:** L1 primitive  |  **Version:** 1.0.0
+
+A single S3 bucket for object storage. The simplest module — one
+resource, two inputs, two outputs. Versioning is enabled by default.
+
+## Resources
+
+| Resource | Type | Purpose |
+|----------|------|---------|
+| bucket | `aws_s3_bucket` | The S3 bucket itself |
+
+## Inputs
+
+| Name | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `bucket_name` | string | yes | — | Globally-unique S3 bucket name |
+| `region` | string | yes | — | AWS region the bucket is created in |
+
+## Outputs
+
+| Name | Type | Description |
+|------|------|-------------|
+| `bucket_arn` | arn | The S3 bucket ARN |
+| `bucket_name` | string | The bucket name (echoes the input) |
+
+## NFRs
+
+| Name | Type | Default | Description |
+|------|------|---------|-------------|
+| `versioning` | boolean | true | Enable S3 versioning |
+
+## Usage
+
+```json
+{
+  "id": "s3",
+  "type": "aws:s3:bucket",
+  "module": "l1-s3@1.0.0",
+  "inputs": {
+    "bucket_name": "acdl-spike-bucket",
+    "region": "us-east-1"
+  }
+}
+```
+
+A concrete instance is at `spike_instance.json` (used by the platform
+pipeline as the regression baseline).
+
+## Compliance extension points
+
+- **Encryption at rest** — add `aws_s3_bucket_server_side_encryption_configuration` with a customer-managed KMS key (SOC2 CC6.1, HIPAA §164.312(a)(2)(iv), GDPR Art.32).
+- **Object Lock** — add `aws_s3_bucket_object_lock_configuration` in compliance mode with 7-year retention for immutable evidence (SOX §802, DORA audit trail).
+- **Access logging** — add `aws_s3_bucket_logging` to a target logging bucket (SOC2 CC7.2).
+- **Public access block** — add `aws_s3_bucket_public_access_block` to prevent data exfiltration (SOC2 CC6.1, GDPR Art.32).
+- **Lifecycle policy** — add `aws_s3_bucket_lifecycle_configuration` for retention enforcement (GDPR Art.5(2), HIPAA §164.530(j)).
+
+## Versioning
+
+`1.0.0` — interface MAJOR, behavior MINOR, lifecycle PATCH. MAJOR bumps
+require a new registry entry (immutable publication); old entries enter
+a 12-month deprecation window.
@@ -0,0 +1,23 @@
+{
+  "version": "1.0.0",
+  "stack": {
+    "name": "l1-s3",
+    "kind": "l1",
+    "depth": 1
+  },
+  "resources": [
+    {
+      "id": "s3",
+      "type": "aws:s3:bucket",
+      "module": "l1-s3@1.0.0",
+      "inputs": {
+        "bucket_name": "acdl-spike-bucket",
+        "region": "us-east-1"
+      },
+      "outputs": {
+        "bucket_arn": {"type": "arn", "description": "The S3 bucket ARN."},
+        "bucket_name": {"type": "string", "description": "The bucket name."}
+      }
+    }
+  ]
+}
@@ -0,0 +1,36 @@
+{
+  "name": "l1-s3",
+  "version": "1.0.0",
+  "kind": "l1",
+  "type": "aws:s3:bucket",
+  "description": "S3 bucket primitive (substrate-agnostic IR type aws:s3:bucket; the Terraform adapter translates to aws_s3_bucket).",
+  "inputs": {
+    "bucket_name": {
+      "type": "string",
+      "description": "Globally-unique S3 bucket name.",
+      "required": true
+    },
+    "region": {
+      "type": "string",
+      "description": "AWS region the bucket is created in.",
+      "required": true
+    }
+  },
+  "outputs": {
+    "bucket_arn": {
+      "type": "arn",
+      "description": "The S3 bucket ARN."
+    },
+    "bucket_name": {
+      "type": "string",
+      "description": "The bucket name (echoes the input)."
+    }
+  },
+  "nfrs": {
+    "versioning": {
+      "type": "boolean",
+      "description": "Enable S3 versioning (default true).",
+      "default": true
+    }
+  }
+}
@@ -0,0 +1,67 @@
+# l1-vpc — VPC with subnets and routing
+
+> **Module kind:** L1 primitive  |  **Version:** 1.0.0
+
+A VPC with one subnet per availability zone and a route table with a
+default route through an internet gateway. The networking foundation
+that other modules (ALB, ECS service) reference for subnet ids.
+
+## Resources
+
+| Resource | Type | Purpose |
+|----------|------|---------|
+| vpc | `aws_vpc` | The VPC itself |
+| subnet | `aws_subnet` | One subnet per availability zone |
+| route_table | `aws_route_table` | Route table with default route 0.0.0.0/0 |
+| internet_gateway | `aws_internet_gateway` | IGW for public internet access |
+| route_table_association | `aws_route_table_association` | Binds subnet to route table |
+
+## Inputs
+
+| Name | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `cidr` | string | yes | — | VPC CIDR block, e.g. `10.0.0.0/16` |
+| `azs` | string | yes | — | Comma-separated availability zones, e.g. `us-east-1a,us-east-1b` |
+| `name` | string | yes | — | Name tag for the VPC and child resources |
+| `region` | string | yes | — | AWS region the VPC is created in |
+
+## Outputs
+
+| Name | Type | Description |
+|------|------|-------------|
+| `vpc_id` | string | The VPC id |
+| `subnet_ids` | string | Comma-separated subnet ids |
+
+## Usage
+
+```json
+{
+  "id": "vpc",
+  "type": "aws:ec2:vpc",
+  "module": "l1-vpc@1.0.0",
+  "inputs": {
+    "cidr": "10.0.0.0/16",
+    "azs": "us-east-1a,us-east-1b",
+    "name": "acdl-microservice",
+    "region": "us-east-1"
+  }
+}
+```
+
+The `azs` input is split on comma; one subnet is created per zone. The
+route table gets a default route `0.0.0.0/0` → internet gateway. Other
+modules reference `subnet_ids` for their network placement.
+
+## Compliance extension points
+
+- **VPC Flow Logs** — add `aws_flow_log` + CloudWatch Logs group / S3 destination (SOX ITGC, SOC2 CC7.2, HIPAA §164.312(b), DORA ICT risk logging).
+- **Private subnets + NAT gateway** — add private subnets with a NAT gateway so ECS tasks don't need public IPs (SOC2 CC6.6, PCI-DSS 1.3, HIPAA network isolation).
+- **VPC endpoints** — add S3, ECR, KMS, DynamoDB, CloudWatch interface/gateway endpoints to keep traffic off the public internet (SOC2 CC6.7, GDPR Art.32(1)(a), DORA ICT third-party risk).
+- **Security groups** — add `aws_security_group` as a first-class sub-resource (currently missing; needed for all regulated deployments) (SOC2 CC6.6, PCI-DSS 1.2).
+- **Network ACLs** — add `aws_network_acl` for subnet-level segmentation (PCI-DSS 1.3).
+
+## Versioning
+
+`1.0.0` — interface MAJOR, behavior MINOR, lifecycle PATCH. MAJOR bumps
+require a new registry entry (immutable publication); old entries enter
+a 12-month deprecation window.
@@ -0,0 +1,64 @@
+{
+  "name": "l1-vpc",
+  "version": "1.0.0",
+  "kind": "l1",
+  "type": "aws:ec2:vpc",
+  "description": "VPC primitive (substrate-agnostic IR types aws:ec2:vpc + aws:ec2:subnet + aws:ec2:routetable; the Terraform adapter translates to aws_vpc/aws_subnet/aws_route_table).",
+  "inputs": {
+    "cidr": {
+      "type": "string",
+      "description": "VPC CIDR block, e.g. 10.0.0.0/16.",
+      "required": true
+    },
+    "azs": {
+      "type": "string",
+      "description": "Comma-separated availability zones, e.g. us-east-1a,us-east-1b.",
+      "required": true
+    },
+    "name": {
+      "type": "string",
+      "description": "Name tag for the VPC and child resources.",
+      "required": true
+    },
+    "region": {
+      "type": "string",
+      "description": "AWS region the VPC is created in.",
+      "required": true
+    }
+  },
+  "outputs": {
+    "vpc_id": {
+      "type": "string",
+      "description": "The VPC id."
+    },
+    "subnet_ids": {
+      "type": "string",
+      "description": "Comma-separated subnet ids."
+    }
+  },
+  "nfrs": {},
+  "resources": [
+    {
+      "type": "aws:ec2:vpc",
+      "description": "The VPC itself.",
+      "inputs": ["cidr", "name"],
+      "outputs": ["vpc_id"]
+    },
+    {
+      "type": "aws:ec2:subnet",
+      "description": "One subnet per availability zone (azs split on comma).",
+      "inputs": ["cidr", "az", "vpc_id", "name"],
+      "outputs": ["subnet_id"]
+    },
+    {
+      "type": "aws:ec2:routetable",
+      "description": "Route table bound to the VPC with an internet gateway + default route.",
+      "inputs": ["vpc_id"],
+      "outputs": []
+    }
+  ],
+  "intra_refs": [
+    {"from": "aws:ec2:subnet.vpc_id", "to": "aws:ec2:vpc.vpc_id"},
+    {"from": "aws:ec2:routetable.vpc_id", "to": "aws:ec2:vpc.vpc_id"}
+  ]
+}