Compare commits
17 Commits
| Author | SHA1 | Date | |
|---|---|---|---|
 Jon Chery
|
f68f85c9fd | ||
|
Jon Chery
|
75c227429a | ||
|
Jon Chery
|
04bf6bc31a | ||
|
Jon Chery
|
9a1ea04f93 | ||
|
Jon Chery
|
2a84c0047b | ||
|
Jon Chery
|
895a2f3806 | ||
|
Jon Chery
|
e050e65158 | ||
|
Jon Chery
|
6e23c168f1 | ||
|
Jon Chery
|
c816493e7e | ||
|
Jon Chery
|
1598c54a8b | ||
|
Jon Chery
|
2c6464afd4 | ||
|
Jon Chery
|
431341a0ab | ||
|
Jon Chery
|
ae86a29a5e | ||
|
Jon Chery
|
3508671377 | ||
|
Jon Chery
|
f874879973 | ||
|
Jon Chery
|
0fc69b4d0c | ||
|
Jon Chery
|
2ec2a87a4e |
+30
-212
@@ -1,225 +1,43 @@
|
||||
# ACDL v1.1 Milestone — Audit
|
||||
# Phase 18 — Audit (v1.3.2)
|
||||
|
||||
**Auditor:** ci-audit-verifier (model: glm-5.2)
|
||||
**Scope:** v1.1 milestone — Phases 06–10 (tags v1.1.1..v1.1.5), milestone ship tag `v1.2.0`, diff `v1.1.0..HEAD` (48 commits)
|
||||
**Date:** 2026-07-21
|
||||
**Verdict:** **CLEAN** — 0 P0 (no critical issues, no feedback loop), 2 P1 post-hoc hygiene items, 0 P2.
|
||||
**Date:** 2026-07-22
|
||||
**Phase:** 18 — testing-and-cicd-pipelines
|
||||
**Milestone:** v1.3 (active, NFR)
|
||||
**Tag:** v1.3.2
|
||||
|
||||
---
|
||||
## 1. Reconstruction Test
|
||||
|
||||
## 1. Reconstruction test
|
||||
Git log (2 commits for phase 18) matches `.ciagent/` files:
|
||||
|
||||
**PASS.** The project state can be reconstructed from the git log `---ci---` blocks alone, and it matches the `.ciagent/` file contents.
|
||||
| Commit | Status | .ciagent match |
|
||||
|--------|--------|----------------|
|
||||
| 1598c54 | verify | VERIFY.md updated, ROADMAP/REQUIREMENTS marked complete |
|
||||
| (specify was done in prior commit ae86a29 for phase 17) | | |
|
||||
|
||||
### HEAD ci block (d6b1923)
|
||||
ROADMAP.md has Phase 18 with `Status: complete (v1.3.2)`.
|
||||
REQUIREMENTS.md has REQ-39, REQ-40, REQ-41, REQ-42 marked `complete (v1.3.2)`.
|
||||
VERIFY.md has `VERIFY PASS` verdict.
|
||||
Tag `v1.3.2` exists. **PASS.**
|
||||
|
||||
The latest `---ci---` block on `main` HEAD (== `v1.2.0` tag target) reads:
|
||||
## 2. File Discipline
|
||||
|
||||
```
|
||||
project: acdl
|
||||
phase: 0
|
||||
milestone: v1.1
|
||||
status: complete
|
||||
requirements:
|
||||
covered: [REQ-16..REQ-28]
|
||||
```
|
||||
Working tree clean. All new files present (pyproject.toml,
|
||||
requirements-test.txt, 7 test files, 2 workflow YAMLs). Modified files
|
||||
(run_platform.sh, README.md, terraform/spike/terraform.tf) are expected.
|
||||
**PASS.**
|
||||
|
||||
This matches the prompt's expected block exactly: `status: complete`, `milestone: v1.1`, `requirements covered: [REQ-16..28]`. ✅
|
||||
## 3. Branch Hygiene
|
||||
|
||||
### Phase progression (walk-back through ci blocks)
|
||||
On `main`, no stale phase branches. `milestone/v1.0-initial` is
|
||||
historical. **PASS.**
|
||||
|
||||
Each phase (06–10) shows the documented plan → plan-as-execute → shipped → verify progression with the correct phase number. The complete sequence reconstructed from `git log`:
|
||||
## 4. Commit Discipline
|
||||
|
||||
| Phase | plan commit | plan-as-execute commits | ship commit (release.tag) | verify commit (verdict) |
|
||||
|-------|--------------|--------------------------|----------------------------|--------------------------|
|
||||
| 06 | b927f90 (`status: plan`) | e044a2d | ecb2c78 (`release.tag: v1.1.1`) + 4ab15cb (docs) | 0779a92 (`verdict: VERIFIED`) |
|
||||
| 07 | b40aadd | 92d4535, f8e99ed, 6ed93f0, 68d90c0, 412e1ef | 8723206 (`release.tag: v1.1.2`) | 167a92f (`verdict: VERIFIED`) |
|
||||
| 08 | a003168 | f8ddd8b, 1d5c4d2, d28630d, 727c873 (prep) | 067fef1 (`release.tag: v1.1.3`) + 96ab42f (docs) | 6d27dad (`verdict: VERIFIED`) |
|
||||
| 09 | 327ba1d | e054a95, 3070a68, 3936bf46 | 5555796 (`release.tag: v1.1.4`) + 4c93147 (docs) | e71539d (`verdict: VERIFIED`) |
|
||||
| 10 | cc4c27c (prep 798f430) | 8437a51, 622abe0, 7afaa34, e29319a | 35a336a (`release.tag: v1.1.5`) + d3aa960 (docs) | 4b87584 (`verdict: VERIFIED`) |
|
||||
All phase-18 commits have `---ci---` blocks with correct closing
|
||||
`---/ci---` tag. Tag `v1.3.2` follows NFR patch versioning (v1.3.1 →
|
||||
v1.3.2). **PASS.**
|
||||
|
||||
Then the milestone tail: 2ed2ca6 (`status: review`, `verdict: READY TO SHIP`) → d6b1923 (`status: complete`, `v1.2.0` tag). ✅
|
||||
## Verdict
|
||||
|
||||
### Tags
|
||||
|
||||
`git tag --list` returns the expected set:
|
||||
|
||||
- `v1.0.1..v1.0.5` (v1.0 demo phase tags, preserved per D-rule)
|
||||
- `v1.1.0` (pre-v1.1 demo — points at 58adf9e, the v1.0 Phase 05 traceability commit)
|
||||
- `v1.1.1..v1.1.5` (phase patches 06–10)
|
||||
- `v1.2.0` (milestone ship tag — points at HEAD d6b1923, the complete commit)
|
||||
|
||||
All 12 tags present; no missing tags; no extra tags. ✅
|
||||
|
||||
### ROADMAP.md ↔ tags
|
||||
|
||||
The ROADMAP.md phase statuses match the tags exactly:
|
||||
|
||||
- Phase 06 → `complete (v1.1.1)` ✅
|
||||
- Phase 07 → `complete (v1.1.2)` ✅
|
||||
- Phase 08 → `complete (v1.1.3)` ✅
|
||||
- Phase 09 → `complete (v1.1.4)` ✅
|
||||
- Phase 10 → `complete (v1.1.5)` ✅
|
||||
|
||||
The v1.1 milestone header (line 74) reads `## v1.1 (Complete — architecture finalization + v1 spike, 2026-07-21)` and line 80 says `Status: COMPLETE — all 5 phases shipped (v1.1.1..v1.1.5) + verified; review READY TO SHIP (0 P0); audit pending`. The "audit pending" clause is now stale (this audit closes it) — see P1-A below.
|
||||
|
||||
### REQUIREMENTS.md ↔ tags
|
||||
|
||||
The v1.1 traceability table (lines 117–129) matches the phase tags:
|
||||
|
||||
| REQ | Phase | Status (file) | Tag (git) | Match |
|
||||
|-----|-------|---------------|-----------|-------|
|
||||
| REQ-16..22 | 07 | complete (v1.1.2) | v1.1.2 | ✅ |
|
||||
| REQ-23 | 08 | complete (v1.1.3) | v1.1.3 | ✅ |
|
||||
| REQ-24, 26 | 09 | complete (v1.1.4) | v1.1.4 | ✅ |
|
||||
| REQ-25, 27, 28 | 10 | complete (v1.1.5) | v1.1.5 | ✅ |
|
||||
|
||||
The HEAD complete-commit ci block's `requirements.covered: [REQ-16..REQ-28]` matches REQUIREMENTS.md's 13 complete entries. ✅
|
||||
|
||||
### Reconstruction conclusion
|
||||
|
||||
Reconstructing the project state from git log `---ci---` blocks alone reproduces the `.ciagent/` file contents (PROJECT.md phase table, ROADMAP.md statuses, REQUIREMENTS.md traceability, REVIEW.md verdict). **No drift detected.** ✅
|
||||
|
||||
---
|
||||
|
||||
## 2. .ciagent/ file discipline
|
||||
|
||||
**PASS with one P1 hygiene item.** All required files exist; the latest phase's PLAN/VERIFY are in place; no orphans; no stale v1.0 framing. One stale-path issue in PERSONAS.md.
|
||||
|
||||
### Required files (all present)
|
||||
|
||||
| File | Exists | Notes |
|
||||
|------|--------|-------|
|
||||
| `config.json` | ✅ | mode=single, active_project=acdl, milestone=v1.1 |
|
||||
| `PROJECT.md` | ✅ | v1.1 objective (architecture finalization + v1 spike); D-034..D-046 + D-P08/P09/P10 present |
|
||||
| `ARCHITECTURE.md` | ✅ | v1.1 target architecture; v1.1 spike scope; Gitea API surface with D-039 OIDC waiver |
|
||||
| `REQUIREMENTS.md` | ✅ | REQ-16..28 complete; traceability table matches tags |
|
||||
| `ROADMAP.md` | ✅ | v1.1 header marked Complete; phases 06–10 statuses match tags |
|
||||
| `PERSONAS.md` | ✅ | v1.1 roster; deactivated v1.0 stub-engineer; phase-specific overrides |
|
||||
| `PLAN.md` | ✅ | Phase 10 (the last phase) — `phase: 10, name: v1-spike-l2-and-contract-e2e` |
|
||||
| `RESEARCH.md` | ✅ | 8 research targets (OIDC blocker, runner tooling, IR prior art, Checkov adapter, outbox, confidence signal, audit ledger, HITL matrix) |
|
||||
| `VERIFY.md` | ✅ | Phase 10 verification (the last one) — `Verdict: Phase 10: VERIFIED`, tag v1.1.5 |
|
||||
| `REVIEW.md` | ✅ | new for the milestone review — `Verdict: READY TO SHIP`, 0 P0, 1 P1 carried-forward |
|
||||
|
||||
### No stale v1.0 framing in v1.1 files
|
||||
|
||||
- `PROJECT.md` correctly states the v1.1 objective (line 53: "Finalize the architecture to v1.0 ... and prove the locked commitments with one end-to-end v1 implementation spike"). **No** occurrence of "30-min stub demo" / "30 min" / "stub demo" as the current objective. The v1.0 demo is correctly archived under `demo/` (line 89). ✅
|
||||
- The v1.0 demo is referenced as the *prior* milestone (status complete, tag v1.1.0) with a pointer to its archived location. ✅
|
||||
|
||||
### PLAN.md = Phase 10 (the last phase)
|
||||
|
||||
PLAN.md frontmatter: `phase: 10`, `name: v1-spike-l2-and-contract-e2e`, `requirements: [REQ-25, REQ-27, REQ-28]`. Not a stale Phase 06–09 plan. ✅
|
||||
|
||||
### VERIFY.md = Phase 10 (the last verification)
|
||||
|
||||
VERIFY.md header: `# Phase 10 — v1-spike-l2-and-contract-e2e (v1.1) VERIFY`, `Verdict: Phase 10: VERIFIED`, `Tag: v1.1.5`. Not a stale Phase 06–09 verification. ✅
|
||||
|
||||
### No orphan .ciagent/ files
|
||||
|
||||
`ls .ciagent/` shows exactly the 10 standard files (config.json + the 9 markdown files). No leftover/extra files. ✅
|
||||
|
||||
### P1-A (post-hoc hygiene, non-blocking)
|
||||
|
||||
**Two stale-path drift items inside `.ciagent/`:**
|
||||
|
||||
1. **`config.json` line 8:** `"status": "specify"` — the milestone is `complete` (shipped v1.2.0), but the project-status field still reads `specify`. Should be `"complete"` (or `shipped`). Cosmetic — the milestone field reads `v1.1` correctly, and ROADMAP.md carries the authoritative status.
|
||||
|
||||
2. **`PERSONAS.md` territory paths:** 6 references use the stale `platform/...` path prefix (lines 7, 38, 47, 56, 80, 109) instead of the renamed `acdl_platform/...`. The rename happened in Phase 08 prep commit 727c873 (`fix(P08 prep): rename platform/ -> acdl_platform/ (stdlib shadow fix)`). All executable code + the other `.ciagent/` files use `acdl_platform/`; PERSONAS.md was not updated. The territories listed (`platform/confidence_signal.py`, `platform/contract_resolver.py`, `platform/outbox/**`, `platform/registry/**`, `platform/hitl_matrix_design.md`, `platform/audit_ledger_design.md`, `platform/separation_of_duties.py`) should all read `acdl_platform/...`. Non-blocking — the verification toolchain (`PERSONAS.md` `verification_toolchain.typecheck` line 7 also has the stale `platform/**/*.py`) is overridden per-phase by each PLAN.md's explicit `verification.typecheck`, so the stale path does not break any verify script. **Recommended redaction for v1.2 cleanup.**
|
||||
|
||||
---
|
||||
|
||||
## 3. Branch hygiene
|
||||
|
||||
**PASS.** Clean branch topology, clean working tree.
|
||||
|
||||
### Branch list
|
||||
|
||||
`git branch -a` returns:
|
||||
- `main`
|
||||
- `milestone/v1.0-initial` (the v1.0 milestone branch, intentionally retained)
|
||||
- `remotes/origin/main`
|
||||
- `remotes/origin/milestone/v1.0-initial`
|
||||
|
||||
**No leftover `phase/NN-*` branches** (all 5 phase branches — `phase/06-archive-demo-and-reorient`, `phase/07-architecture-v1-finalization`, `phase/08-aws-bootstrap`, `phase/09-v1-spike-ir-and-l1-and-adapter`, `phase/10-v1-spike-l2-and-contract-e2e` — were deleted post-merge, confirmed by the ship commit messages referencing the squash-merge of the phase branch). ✅
|
||||
|
||||
### Working tree
|
||||
|
||||
`git status` on `main`: "nothing to commit, working tree clean". The branch is ahead of `origin/main` by 43 commits (the v1.1 milestone work has not been pushed to the remote yet — this is expected for an audit pass before the milestone is declared shipped; the push is the final ship step). No uncommitted changes; no stray artifacts (`.env.secrets`, `terraform/spike/.terraform/`, `terraform/spike/.terraform.lock.hcl`, `terraform/spike/tfplan`, `terraform/spike/*.tfstate*` are all gitignored per REVIEW.md Lens 3). ✅
|
||||
|
||||
### Branch hygiene conclusion
|
||||
|
||||
Clean. ✅
|
||||
|
||||
---
|
||||
|
||||
## 4. Commit discipline
|
||||
|
||||
**PASS with one P1 hygiene item.** Every v1.1-stage commit carries a `---ci---` block with the documented fields; the field-usage rules hold; the merges are the documented `--no-ff` squash-merge pattern.
|
||||
|
||||
### `---ci---` block presence
|
||||
|
||||
48 commits in `v1.1.0..HEAD`. Audit of ci-block presence:
|
||||
|
||||
- **3 commits with no `---ci---` block:** `52665b8 Add docs/architecture.md`, `7614c41 Add docs/vision.md`, `b84a8a2 Update docs/architecture.md`. All three are **pre-specify upstream-doc ingestion** commits: each is an ancestor of the specify commit `288607b` (`docs(specify): ingest docs/vision+architecture`). They are the raw upstream `docs/` files being added to the repo *before* the v1.1 CIAgent protocol was applied (the specify commit 288607b is the first v1.1-stage commit and the first to carry a v1.1 `---ci---` block). These three commits belong to the v1.0→v1.1 transition, not the v1.1 milestone proper. They are inside the `v1.1.0..HEAD` audit range only because `v1.1.0` is tagged at the v1.0 Phase 05 traceability commit (58adf9e) — a tag-placement choice that puts the v1.0-complete + audit-v1.0 + docs-ingestion commits inside the v1.1 range. **P1-B (post-hoc, non-blocking):** if the audit protocol requires every commit in the `v1.1.0..HEAD` range to carry a v1.1 ci block, these three pre-specify ingestion commits technically fail it. However: (a) they predate the v1.1 specify stage, (b) the v1.0 milestone-complete commit `80ac975` and the v1.0 audit `d700148` carry v1.0 ci blocks (correct for their milestone), and (c) the v1.0 contracts commit `30e63d6` carries a v1.0 ci block. Only the 3 raw `docs/` ingestion commits lack any ci block at all. Recommended for a future note in the run.md about tag placement (a v1.1.0 tag on the v1.0 *complete* commit rather than the v1.0 Phase 05 traceability commit would have excluded these from the v1.1 range). Non-blocking.
|
||||
|
||||
- **45 commits with `---ci---` blocks:** all carry `project: acdl`, `phase:` (0 for milestone-stage, 6–10 for phase-stage), `milestone: v1.1`, and `status:` from the documented set {specify, clarify, research, plan, plan-as-execute, shipped, verify, review, complete}. ✅
|
||||
|
||||
### Field usage rules
|
||||
|
||||
- **`release.tag`** appears only on the 5 ship commits (ecb2c78 v1.1.1, 8723206 v1.1.2, 067fef1 v1.1.3, 5555796 v1.1.4, 35a336a v1.1.5) — never on plan/plan-as-execute/verify/review/complete commits. ✅
|
||||
- **`verdict`** appears only on the 5 verify commits (0779a92, 167a92f, 6d27dad, e71539d, 4b87584) and the 1 review commit (2ed2ca6) — never elsewhere. ✅
|
||||
- **`requirements.covered`** appears on plan-as-execute commits (where a task covers a specific REQ) and on the complete commit (REQ-16..28). The complete commit uses the documented nested form (`requirements:\n covered: [...]`). ✅
|
||||
- **No ad-hoc fields.** All fields used (`project`, `phase`, `milestone`, `status`, `release.tag`, `verdict`, `requirements.covered`, `persona`, `tasks`) are from the documented set. ✅
|
||||
|
||||
### Merge commits
|
||||
|
||||
`git log --merges v1.1.0..HEAD` returns exactly the 5 ship commits:
|
||||
|
||||
```
|
||||
35a336a ship: phase-10 ... (v1.1.5) [parents: e71539d d3aa960]
|
||||
5555796 ship: phase-09 ... (v1.1.4) [parents: 327ba1d 4c93147]
|
||||
067fef1 ship: phase-08 ... (v1.1.3) [parents: 167a92f 96ab42f]
|
||||
8723206 ship: phase-07 ... (v1.1.2) [parents: b40aadd 412e1ef]
|
||||
ecb2c78 ship: phase-06 ... (v1.1.1) [parents: b927f90 4ab15cb]
|
||||
```
|
||||
|
||||
Each ship commit has two parents: (1) the prior `verify` commit on `main`, and (2) the phase branch's final `docs(PNN): post-ship traceability` commit. This is the documented `--no-ff` squash-merge pattern (the phase branch is merged into main as a merge commit, not a fast-forward). **No** other merge commits exist in the range — no surprise merges, no `--ff-only` regressions. ✅
|
||||
|
||||
### Closing-tag note
|
||||
|
||||
All 45 ci-block commits close the block with `---/ci---` (the documented closing tag). **No** commit uses the malformed `---ci---` close. ✅
|
||||
|
||||
---
|
||||
|
||||
## Critical issues
|
||||
|
||||
**No critical issues (0 P0).** The audit found no blocking problems:
|
||||
|
||||
- Reconstruction test passes — git log reproduces the `.ciagent/` state with no drift.
|
||||
- File discipline passes — all 10 files present, latest-phase PLAN/VERIFY in place, no orphans, no stale v1.0 framing.
|
||||
- Branch hygiene passes — clean topology, no leftover phase branches, clean working tree.
|
||||
- Commit discipline passes — every v1.1-stage commit carries a well-formed `---ci---` block; field rules hold; merges are the documented pattern.
|
||||
|
||||
**No feedback loop is triggered.** The milestone does not need to return to EXECUTE.
|
||||
|
||||
---
|
||||
|
||||
## Post-hoc hygiene (P1s for v1.2 cleanup)
|
||||
|
||||
| ID | Item | Severity | File / location | Fix |
|
||||
|----|------|----------|-----------------|-----|
|
||||
| **P1-1** (carried-forward from REVIEW.md) | Two AWS access key IDs (`AKIA…SPIKE` rotated spike key, `AKIA…ROOT-DEACTIVATED` deactivated root key) appeared in `.ciagent/VERIFY.md` Phase 09 narrative. **Public identifiers, not secret pairs.** They lived in the `.ciagent/` audit narrative, not in any executable code path. | P1 (non-blocking) | `.ciagent/VERIFY.md` Phase 09 narrative (v1.1) | **Redacted in v1.2 Phase 12** to placeholders `AKIA…SPIKE` / `AKIA…ROOT-DEACTIVATED` across `.ciagent/RESEARCH.md`, `PROJECT.md`, `REVIEW.md`, `AUDIT.md`. The original VERIFY.md instances were overwritten by Phase 11's VERIFY.md. |
|
||||
| **P1-A** (audit-new) | `config.json` line 8 `"status": "specify"` is stale — the milestone is `complete` (v1.2.0 shipped). | P1 (non-blocking) | `.ciagent/config.json:8` | Update to `"status": "complete"` (or `"shipped"`) in v1.2 cleanup. |
|
||||
| **P1-B** (audit-new) | `PERSONAS.md` territory paths (lines 7, 38, 47, 56, 80, 109) reference the stale `platform/...` prefix instead of the renamed `acdl_platform/...`. The rename happened in Phase 08 prep (commit 727c873). The verification toolchain line 7 also has the stale `platform/**/*.py` glob. Non-blocking: each PLAN.md overrides the toolchain per-phase, and territories are descriptive (enforcement mode = `warn`). | P1 (non-blocking) | `.ciagent/PERSONAS.md` lines 7, 38, 47, 56, 80, 109 | Replace `platform/` with `acdl_platform/` in v1.2 cleanup. |
|
||||
| **P1-C** (audit-new, observation) | 3 pre-specify upstream-doc ingestion commits (`52665b8 Add docs/architecture.md`, `7614c41 Add docs/vision.md`, `b84a8a2 Update docs/architecture.md`) carry no `---ci---` block. They predate the v1.1 specify stage (each is an ancestor of the specify commit 288607b). They fall inside the `v1.1.0..HEAD` audit range only because the `v1.1.0` tag is placed at the v1.0 Phase 05 traceability commit (58adf9e) rather than the v1.0 complete commit (80ac975). | P1 (non-blocking, process note) | tag placement + run.md | Document in run.md that the milestone-complete tag should be placed on the milestone-complete commit to exclude the transition-window commits from the next milestone's audit range. No file change needed for v1.1; v1.2 should pick the tag placement deliberately. |
|
||||
| **P1-D** (audit-new, cosmetic) | `ROADMAP.md` line 81 says `audit pending` — now stale (this audit closes it). | P1 (non-blocking, cosmetic) | `.ciagent/ROADMAP.md:81` | Update to `audit CLEAN` (or remove the clause) in v1.2 cleanup. |
|
||||
|
||||
---
|
||||
|
||||
## Final verdict
|
||||
|
||||
**v1.1 milestone audit: CLEAN**
|
||||
|
||||
- 0 P0 (no critical issues, no feedback loop).
|
||||
- 5 P1 post-hoc hygiene items (1 carried-forward from REVIEW.md + 4 audit-new), all non-blocking, all flagged for v1.2 cleanup.
|
||||
- The milestone is shippable as-is. The `v1.2.0` tag on `main` HEAD is valid.
|
||||
**AUDIT CLEAN** — reconstruction, file discipline, branch hygiene, and
|
||||
commit discipline all pass. No critical issues.
|
||||
+48
-2
@@ -84,7 +84,7 @@ id 202 published. D-034 closed (root key deactivated by user).**
|
||||
Milestone COMPLETE gate: review → ship `v1.2.0` (feature milestone, next
|
||||
minor per ship.md) → audit. **DONE.**
|
||||
|
||||
## Objective for Milestone v1.2 (active)
|
||||
## Objective for Milestone v1.2 (prior — complete)
|
||||
|
||||
Platform hardening + first real consumer deployment. The v1.1 spike proved
|
||||
the IR commitments hold on a single dev-only `terraform plan` for one S3
|
||||
@@ -133,6 +133,40 @@ microservice), not just a plan.
|
||||
Milestone COMPLETE gate: review → ship `v1.3.0` (feature milestone, next
|
||||
minor per ship.md — v1.1 shipped `v1.2.0`) → audit.
|
||||
|
||||
## Objective for Milestone v1.4 (active)
|
||||
|
||||
Central pipeline contract + shell reproducibility + output streaming. The
|
||||
v1.3 milestone (Phases 17–18) created identical CI/CD pipelines for Gitea
|
||||
and GitHub but they were duplicated copies with no single source of truth.
|
||||
v1.4 makes the pipeline a declarative contract, enables full shell
|
||||
reproducibility, and streams terraform/checkov output so users can see
|
||||
what the platform is doing.
|
||||
|
||||
Three scope axes:
|
||||
|
||||
1. **Central pipeline contract.** A JSON Schema
|
||||
(`schemas/pipeline.schema.json`) + YAML instance (`pipelines/ci.yaml`)
|
||||
declares the pipeline stages, commands, triggers, and runner. Both
|
||||
`.gitea/workflows/ci.yml` (Gitea Actions, dev) and
|
||||
`.github/workflows/ci.yml` (GitHub Actions, production) implement the
|
||||
contract. A test validates conformance.
|
||||
2. **Shell reproducibility.** `scripts/run_ci.sh` mirrors the CI pipeline
|
||||
locally — runs the same 3 stages (lint, test, check-only) in sequence.
|
||||
The pipeline is fully reproducible from the shell, not just in CI.
|
||||
3. **Output streaming.** `scripts/run_platform.sh` streams terraform
|
||||
init/validate/plan output, Checkov compliance results, and
|
||||
PolicyCheckResult records to stdout by default, so the user sees what
|
||||
is happening. A `--quiet` flag suppresses streaming for log-only mode.
|
||||
|
||||
## Milestone v1.4 Phases
|
||||
|
||||
| Phase | Name | Goal |
|
||||
|-------|------|------|
|
||||
| 19 | central-pipeline-contract-and-shell-reproducibility | Create the central pipeline contract (JSON Schema + YAML instance). Create `scripts/run_ci.sh` for shell reproducibility. Update `run_platform.sh` to stream terraform/checkov output. Update both workflow YAMLs with contract references (staying byte-identical). Add tests for contract validation, workflow conformance, and streaming. |
|
||||
|
||||
Milestone COMPLETE gate: review → ship `v1.4.1` (feature milestone, next
|
||||
minor per ship.md — v1.3 shipped `v1.3.2`) → audit.
|
||||
|
||||
## Requirements
|
||||
|
||||
### v1.0 (Prior milestone — the demo)
|
||||
@@ -168,7 +202,7 @@ New requirements REQ-16..REQ-28 — see `REQUIREMENTS.md` §v1.1. Summary:
|
||||
- **REQ-28:** Spike verification proves the IR-shaped commitments hold (no
|
||||
polyglot mess; the adapter is the only substrate-specific code).
|
||||
|
||||
### v1.2 (Active milestone — platform hardening + first real consumer deployment)
|
||||
### v1.2 (Prior milestone — platform hardening + first real consumer deployment, complete)
|
||||
|
||||
New requirements REQ-29..REQ-35 — see `REQUIREMENTS.md` §v1.2. Summary:
|
||||
|
||||
@@ -189,6 +223,18 @@ New requirements REQ-29..REQ-35 — see `REQUIREMENTS.md` §v1.2. Summary:
|
||||
- **REQ-35:** End-to-end verification — consumer commit → live ECS service
|
||||
(HTTP 200) → evidence event → timeline.
|
||||
|
||||
### v1.4 (Active milestone — central pipeline contract + shell reproducibility + streaming)
|
||||
|
||||
New requirements REQ-43..REQ-45 — see `REQUIREMENTS.md` §v1.4. Summary:
|
||||
|
||||
- **REQ-43:** Central pipeline contract — `schemas/pipeline.schema.json` +
|
||||
`pipelines/ci.yaml`. Both Gitea and GitHub workflows implement the
|
||||
contract; a test validates conformance.
|
||||
- **REQ-44:** `scripts/run_ci.sh` mirrors the CI pipeline locally (lint →
|
||||
test → check-only), exiting 0 with "CI PIPELINE OK".
|
||||
- **REQ-45:** `scripts/run_platform.sh` streams terraform/checkov output by
|
||||
default (with `--quiet` for log-only mode). Both workflows byte-identical.
|
||||
|
||||
## Constraints
|
||||
|
||||
- **Forge:** Gitea at `https://git.cloudinit.dev`, org `continuous-intelligence`.
|
||||
|
||||
+75
-16
@@ -70,7 +70,7 @@
|
||||
| Prod/dr environments | v1.2. |
|
||||
| Terraform `apply` (real provisioning) | Spike runs `plan` only; `apply` is gated by HITL in v1.2. |
|
||||
|
||||
## v1.2 (Active milestone — platform hardening + first real consumer deployment)
|
||||
## v1.2 (Prior milestone — platform hardening + first real consumer deployment, complete, tag `v1.3.0`)
|
||||
|
||||
### Category: Documentation & Simplification
|
||||
- **REQ-29:** `README.md` is fully rewritten to reflect the v1.1-complete platform: the actual spike flow (contract → IR → `terraform plan` → Checkov → confidence signal → outbox), how to run it (`scripts/run_platform.sh`), the real repo layout (`acdl_platform/`, `schemas/`, `adapters/`, `terraform/`, `modules-ir/`, `contracts/`, `demo/`), and the v1.2 objective. No stale "v1.1 (active)" framing.
|
||||
@@ -91,21 +91,49 @@
|
||||
### Category: End-to-End Verification
|
||||
- **REQ-35:** One end-to-end flow: consumer commit to `acdl-consumer-microservice` → pipeline triggered → contract→IR resolution → `terraform plan` → `terraform apply` (dev) → a live ECS Fargate service serving HTTP 200 on its ALB → evidence event written to the DynamoDB outbox → the event renders on the `acdl-evidence` timeline. `scripts/verify_phase16.sh` proves the full flow green.
|
||||
|
||||
## v1.3 (Prior — module documentation + thin-composition removal, complete)
|
||||
|
||||
### Category: Thin-Composition Removal
|
||||
- **REQ-36:** The L2 thin-composition layer is removed completely: `composition.json` files, `acdl_platform/contract_resolver.py`, `schemas/contract.schema.json`, `contracts/spike.yaml`, `contracts/microservice.yaml`, and L2 entries in `modules-ir/registry.json` are deleted. The L2 directories are kept as placeholders with READMEs. The downstream pipeline (adapter → checkov → confidence → outbox) is patched to load a pre-existing IR instance instead of resolving a contract.
|
||||
- **REQ-37:** A `modules-ir/README-TEMPLATE.md` exists that works for both L1 and L2 modules, written in plain language (no jargon), with sections for Overview, Resources, Inputs, Outputs, Usage, Compliance extension points, and Versioning.
|
||||
- **REQ-38:** Every module has a `README.md`: the 7 L1 modules have full READMEs with Resources/Inputs/Outputs/Usage/Compliance-extension-points/Versioning sections derived from their `interface.json`; the 2 L2 modules have placeholder READMEs noting the composition is under redesign. A `modules-ir/README.md` catalog index lists all modules with one-line descriptions and links.
|
||||
|
||||
### Category: Testing
|
||||
- **REQ-39:** A pytest test suite exists under `tests/` covering the platform components offline (no AWS, no Checkov, no DynamoDB): the Terraform adapter (`adapters/terraform/adapter.py`), the confidence signal (`acdl_platform/confidence_signal.py`), the Checkov adapter (`adapters/terraform/policy/checkov_adapter.py`), and the outbox writer (`acdl_platform/outbox_writer.py`). The suite validates the IR schema, registry, spike_instance, and adapter output structure. `pyproject.toml` + `requirements-test.txt` pin test dependencies (pytest, jsonschema, pyyaml, boto3-stubs or moto for outbox mocking).
|
||||
|
||||
### Category: Shell Reproducibility
|
||||
- **REQ-40:** `scripts/run_platform.sh` has a `--check-only` mode that runs offline: loads the pre-existing IR instance, runs the adapter to emit Terraform, validates the JSON structure — without AWS credentials, Checkov, or DynamoDB. The existing `--plan-only` and full modes continue to require AWS. The `--check-only` mode is what CI pipelines run.
|
||||
|
||||
### Category: CI/CD Pipelines
|
||||
- **REQ-41:** Identical CI/CD pipelines exist for both Gitea Actions (`.gitea/workflows/ci.yml`, dev environment) and GitHub Actions (`.github/workflows/ci.yml`, production). Both run the same three stages: (1) lint — `py_compile` all Python files, (2) test — `pytest`, (3) check-only — `bash scripts/run_platform.sh --check-only`. Both trigger on push to main + pull request. Both use `ubuntu-latest`. Identical outcomes — the only difference is the runner environment.
|
||||
|
||||
- **REQ-42:** `pyproject.toml` exists at the repo root with pytest configuration (testpaths, markers) and the project metadata. `requirements-test.txt` pins test-only dependencies separate from runtime dependencies.
|
||||
|
||||
## v1.4 (Active — central pipeline contract + shell reproducibility + streaming)
|
||||
|
||||
### Category: Central Pipeline Contract
|
||||
- **REQ-43:** A central pipeline contract exists as `schemas/pipeline.schema.json` (JSON Schema draft 2020-12) + `pipelines/ci.yaml` (YAML instance). The contract declares the pipeline name, triggers (push/PR branches), runner, Python version, and stages (name + command + required + install + description). Both `.gitea/workflows/ci.yml` (Gitea Actions, dev) and `.github/workflows/ci.yml` (GitHub Actions, production) implement the same stages, commands, triggers, and runner as declared in the contract. A test (`tests/test_pipeline_contract.py`) validates the contract against the schema and asserts both workflows conform (same jobs, same commands, same triggers, same runner, byte-identical).
|
||||
|
||||
### Category: Shell Reproducibility
|
||||
- **REQ-44:** `scripts/run_ci.sh` reproduces the CI pipeline locally — runs the same 3 stages (lint, test, check-only) in sequence with proper exit codes, failing on first error. The script exits 0 with "CI PIPELINE OK" on success. A `--quiet` flag suppresses per-stage banners. The script mirrors the central pipeline contract (`pipelines/ci.yaml`) so the shell and CI environments produce identical outcomes.
|
||||
|
||||
### Category: Pipeline Streaming
|
||||
- **REQ-45:** `scripts/run_platform.sh` streams output by default: terraform init/validate/plan output is piped to stdout via `tee` (visible to the user and logged), Checkov results are printed in human-readable form, and PolicyCheckResult records are displayed with severity, rule ID, and pass/fail status per record. The `--check-only` mode streams the emitted Terraform file content. A `--quiet` flag suppresses streaming (output to log files only) for backwards compatibility. Both gitea and github workflows are byte-identical (identical outcomes — the only difference is the forge runtime).
|
||||
|
||||
## v1.5 (Prior — consumer happy path + zero-trust docs + reusable deploy workflow, complete)
|
||||
|
||||
### Category: Consumer Happy Path Documentation
|
||||
- **REQ-46:** `README.md` is rewritten so the consumer model is unambiguous: this repo is the platform source; a consumer never clones it. A consumer repo contains only app code + `contract.yaml` referencing the central pipeline + contract. The platform-flow diagram is a mermaid `flowchart TD` (replacing the ASCII art). "L3A"/"L3B" nomenclature is removed from README (single-surface model). "spike" nomenclature is removed from prose (code paths in bash blocks are kept verbatim).
|
||||
- **REQ-47:** `docs/CONSUMER_GUIDE.md` (all-caps) replaces `docs/consumer-guide-static-asset.md`. It is generic across all L2 modules (`static-asset` as the worked example), uses mermaid diagrams (model + pipeline flow), documents versioned `uses:` references (floating MAJOR+MINOR tags — bare/`@main` discouraged), scopes prerequisites to consumer-repo bootstrap only (no Terraform/Checkov/boto3/runner-key — those are platform-repo concerns), and documents that the pipeline fetches the ACDL repo at run time via a reusable workflow (consumers never invoke `scripts/run_platform.sh` locally for the happy path).
|
||||
- **REQ-48:** `README.md` Credentials section is rewritten to express the zero-trust target model: consumer repos use OIDC federation (no long-lived keys) with attribute-based authorization (ABAC) — IAM roles + session policies scoped by repository identity and resource-creation tags so a consumer can only view/update resources it created (blast-radius containment). A documented override allows a static key in GitHub Secrets (consumer repo) or `.env.secrets` (local testing), rotated by a platform-managed scheduled pipeline on a daily cadence; when `.env.secrets` is used locally, rotating out of band is the consumer's responsibility.
|
||||
|
||||
### Category: Reusable Deploy Workflow
|
||||
- **REQ-49:** A reusable deploy workflow exists as byte-identical `.gitea/workflows/deploy.yml` (Gitea, dev) and `.github/workflows/deploy.yml` (GitHub, production), implementing the central deployment pipeline contract (`pipelines/deploy.yaml` validated against `schemas/deploy-pipeline.schema.json`). It is invoked by consumer repos via `uses: acdl/.gitea/workflows/deploy.yml@vMAJOR.MINOR` (versioned tag). The workflow checks out the consumer repo, checks out the ACDL platform repo into the runner workspace, installs runtime deps (Python, Terraform, Checkov), and invokes `scripts/run_platform.sh` against the consumer's contract path (passed as a workflow input). OIDC is the default auth (`permissions: id-token: write`); a static-key override reads from repository secrets.
|
||||
- **REQ-50:** `contracts/static-asset.yaml` uses a versioned `uses:` reference (`@v1.4`, MAJOR+MINOR) — not bare `@v1` or `@main` — as the canonical example the consumer guide points at.
|
||||
- **REQ-51:** `tests/test_pipeline_contract.py` is extended to validate the new deploy workflows: both files exist, are byte-identical, and conform to `schemas/deploy-pipeline.schema.json` (stages present, names match `pipelines/deploy.yaml` stage names). The existing CI-workflow conformance tests continue to pass unchanged.
|
||||
|
||||
## Out of Scope (v1.2)
|
||||
|
||||
| Feature | Reason |
|
||||
|---------|--------|
|
||||
| Real OIDC federation | go-gitea/gitea#36988 still open (re-checked 2026-07-21). v1.2 extends D-039 waiver (D-047); real OIDC is v1.3+. |
|
||||
| Full HITL matrix wiring (qa/prod/dr) | v1.2 is dev-only autonomous `apply`; HITL wiring is v1.3. |
|
||||
| Kyverno + OPA policy engines | v1.2 keeps Checkov only; Kyverno/OPA are v1.3. |
|
||||
| MCP skill catalog + real L3B agent | v1.2 keeps the L3B stub; the 5-skill catalog is v1.3. |
|
||||
| Audit ledger build-out (S3 Object Lock + JWS + async worker + DLQ + daily checkpoints) | v1.2 keeps the v1.1 outbox; the regulatory ledger is v1.3. |
|
||||
| Multi-region state / outbox | Single-region in v1 (§9, §12.3); multi-region is v1.3+. |
|
||||
| Prod/dr environments | v1.2 is dev-only; prod/dr are v1.3. |
|
||||
| GitOps reconciler (ArgoCD/Flux) | v1.3+. |
|
||||
|
||||
## Clarifications (Phase 01, v1.0 — retained for history)
|
||||
|
||||
| REQ | Original criterion | Clarified criterion (effective) | Decision |
|
||||
|-----|--------------------|----------------------------------|----------|
|
||||
| REQ-09 | Three repos exist | Three repos exist (`acdl`, `acdl-contracts`, `acdl-evidence`) under `continuous-intelligence`; new repos use `default_branch: "main"`, `auto_init: true` | D-015 |
|
||||
@@ -162,7 +190,7 @@
|
||||
| REQ-27 | 10 | complete (v1.1.5) |
|
||||
| REQ-28 | 10 | complete (v1.1.5) |
|
||||
|
||||
### v1.2 (active — platform hardening + first real consumer deployment)
|
||||
### v1.2 (prior — platform hardening + first real consumer deployment, complete)
|
||||
|
||||
| Requirement | Phase | Status |
|
||||
|-------------|-------|--------|
|
||||
@@ -172,4 +200,35 @@
|
||||
| REQ-32 | 14 | complete (v1.2.4) |
|
||||
| REQ-33 | 15 | partial (v1.2.5, IAM-blocked) |
|
||||
| REQ-34 | 15 | complete (v1.2.5) |
|
||||
| REQ-35 | 16 | partial (v1.2.6, IAM-blocked) |
|
||||
| REQ-35 | 16 | partial (v1.2.6, IAM-blocked) |
|
||||
|
||||
### v1.3 (prior — module documentation + thin-composition removal, complete)
|
||||
|
||||
| Requirement | Phase | Status |
|
||||
|-------------|-------|--------|
|
||||
| REQ-36 | 17 | complete (v1.3.1) |
|
||||
| REQ-37 | 17 | complete (v1.3.1) |
|
||||
| REQ-38 | 17 | complete (v1.3.1) |
|
||||
| REQ-39 | 18 | complete (v1.3.2) |
|
||||
| REQ-40 | 18 | complete (v1.3.2) |
|
||||
| REQ-41 | 18 | complete (v1.3.2) |
|
||||
| REQ-42 | 18 | complete (v1.3.2) |
|
||||
|
||||
### v1.4 (prior — central pipeline contract + shell reproducibility + streaming)
|
||||
|
||||
| Requirement | Phase | Status |
|
||||
|-------------|-------|--------|
|
||||
| REQ-43 | 19 | complete (v1.4.1) |
|
||||
| REQ-44 | 19 | complete (v1.4.1) |
|
||||
| REQ-45 | 19 | complete (v1.4.1) |
|
||||
|
||||
### v1.5 (active — consumer happy path + zero-trust docs + reusable deploy workflow)
|
||||
|
||||
| Requirement | Phase | Status |
|
||||
|-------------|-------|--------|
|
||||
| REQ-46 | 20 | complete (v1.5.0) |
|
||||
| REQ-47 | 20 | complete (v1.5.0) |
|
||||
| REQ-48 | 20 | complete (v1.5.0) |
|
||||
| REQ-49 | 20 | complete (v1.5.0) |
|
||||
| REQ-50 | 20 | complete (v1.5.0) |
|
||||
| REQ-51 | 20 | complete (v1.5.0) |
|
||||
+94
-4
@@ -4,7 +4,10 @@
|
||||
|
||||
- **v1.0 (demo):** complete — tag `v1.1.0`, 2026-07-21. All 5 phases shipped + audited PASS.
|
||||
- **v1.1 (complete):** architecture finalization + v1 spike. 5 phases (06–10). Tag `v1.2.0`, 2026-07-21. All 5 phases shipped + verified; review READY TO SHIP (0 P0); audit CLEAN. Gitea release id 202.
|
||||
- **v1.2 (active):** platform hardening + first real consumer deployment. 6 phases (11–16). Ship tag `v1.3.0`.
|
||||
- **v1.2 (complete):** platform hardening + first real consumer deployment. 6 phases (11–16). Tag `v1.3.0`, 2026-07-21. All 6 phases shipped + verified; review READY TO SHIP (1 P0 operator action, 1 P1 deferred); audit CLEAN.
|
||||
- **v1.3 (complete):** module documentation + thin-composition removal. The L2 composition layer is removed; module READMEs are built out. Tag `v1.3.2`.
|
||||
- **v1.4 (complete):** central pipeline contract + shell reproducibility + output streaming. A declarative pipeline contract (`schemas/pipeline.schema.json` + `pipelines/ci.yaml`) binds the Gitea and GitHub workflows to a single source of truth. `scripts/run_ci.sh` mirrors the CI pipeline locally. `scripts/run_platform.sh` streams terraform/checkov output by default.
|
||||
- **v1.5 (complete, tag `v1.5.0`):** consumer happy path + zero-trust docs + reusable deploy workflow. README rewritten so the consumer model is unambiguous (consumer owns only contract + app code; the rest is the platform source). Platform-flow + consumer-guide diagrams converted to mermaid. Legacy surface + implementation nomenclature removed from docs. Credentials section rewritten for zero-trust OIDC + ABAC (with a static-key override + daily rotation). A generic `docs/CONSUMER_GUIDE.md` (all L2 modules, versioned `uses:`, consumer-scoped prereqs, run-time platform fetch) replaces the module-specific guide. A byte-identical reusable `deploy.yml` workflow (Gitea + GitHub) implements `pipelines/deploy.yaml` and is invoked by consumer repos via a versioned tag.
|
||||
- **v1.0 demo URL:** https://git.cloudinit.dev/continuous-intelligence/acdl-evidence/raw/branch/main/index.html
|
||||
|
||||
---
|
||||
@@ -139,13 +142,17 @@ After Phase 10: COMPLETE gate — review → ship `v1.2.0` → audit. **DONE.**
|
||||
|
||||
---
|
||||
|
||||
## v1.2 (Active — platform hardening + first real consumer deployment)
|
||||
## v1.2 (Complete — platform hardening + first real consumer deployment, 2026-07-21, tag `v1.3.0`)
|
||||
|
||||
Six-phase breakdown to harden the v1.1 spike, simplify the setup, update
|
||||
the docs, and prove the platform delivers real value by deploying a basic
|
||||
microservice to AWS ECS Fargate end-to-end. Ship tag at milestone COMPLETE:
|
||||
**`v1.3.0`** (feature milestone, next minor per ship.md — v1.1 shipped
|
||||
`v1.2.0`). Phase patches `v1.2.1`..`v1.2.6`.
|
||||
`v1.2.0`). Phase patches `v1.2.1`..`v1.2.6`. **Status: COMPLETE — all 6
|
||||
phases shipped (v1.2.1..v1.2.6) + verified; review READY TO SHIP (1 P0
|
||||
operator action, 1 P1 deferred to v1.3); audit CLEAN. The terraform apply
|
||||
is blocked by the live IAM policy (P0-IAM, operator action); the platform
|
||||
flow is verified end-to-end up to terraform plan (13 to add).**
|
||||
|
||||
### Phase 11 — v1.2-research-and-readme
|
||||
- **Description:** Re-evaluate go-gitea/gitea#36988 (OIDC for Gitea Actions) — confirm still open (re-checked 2026-07-21: open, last updated 2026-05-27, not merged) and record the decision to extend D-039 as D-047. Audit the v1.1 spike for NFR gaps (least-privilege IAM, idempotency, error handling, rotation hygiene) and simplification opportunities (script consolidation, dead code, stale paths). Rewrite `README.md` to reflect v1.1 complete + the actual spike flow + how to run + the real repo layout + the v1.2 objective.
|
||||
@@ -212,4 +219,87 @@ microservice to AWS ECS Fargate end-to-end. Ship tag at milestone COMPLETE:
|
||||
- `scripts/verify_phase16.sh` exits 0.
|
||||
- README accurately documents the v1.2 platform flow.
|
||||
|
||||
After Phase 16: COMPLETE gate — review → ship `v1.3.0` → audit.
|
||||
After Phase 16: COMPLETE gate — review → ship `v1.3.0` → audit.
|
||||
|
||||
---
|
||||
|
||||
## v1.3 (Complete — module documentation + thin-composition removal)
|
||||
|
||||
The v1.3 milestone starts with simplification: removing the unsatisfactory
|
||||
thin-composition layer and building out proper module documentation. The
|
||||
L2 composition mechanism will be redesigned in a later phase.
|
||||
|
||||
### Phase 17 — remove-thin-composition-and-module-readmes
|
||||
- **Description:** Remove the L2 thin-composition layer completely (composition.json files, contract_resolver.py, contract schema, sample contracts) and build out proper module READMEs. Create a README template for both L1 and L2 modules, rewrite all 7 L1 module READMEs in plain language (no jargon, with Resources/Inputs/Outputs/Usage/Compliance-extension-points/Versioning sections), write 2 L2 placeholder READMEs noting the composition is under redesign, create a catalog index, and patch run_platform.sh to load a pre-existing IR instance instead of resolving a contract. Prune L2 entries from the registry.
|
||||
- **Status:** complete (v1.3.1)
|
||||
- **Depends on:** —
|
||||
- **Requirements:** REQ-36, REQ-37, REQ-38
|
||||
- **Success Criteria:**
|
||||
- The thin-composition layer is fully removed (composition.json, contract_resolver.py, contract schema, contracts/).
|
||||
- run_platform.sh loads a pre-existing IR instance; the downstream adapter/checkov/confidence/outbox pipeline still works.
|
||||
- A README-TEMPLATE.md exists for both L1 and L2 modules.
|
||||
- Every L1 module has a README.md with Resources/Inputs/Outputs/Usage/Compliance-extension-points/Versioning.
|
||||
- Every L2 module has a placeholder README.md noting the composition is under redesign.
|
||||
- A modules-ir/README.md catalog index exists.
|
||||
|
||||
### Phase 18 — testing-and-cicd-pipelines
|
||||
- **Description:** Create a pytest test suite that reproduces the platform pipeline offline (adapter, confidence_signal, checkov_adapter, outbox_writer). Add an offline `--check-only` mode to `run_platform.sh` that runs the pipeline up to adapter emission without AWS/Checkov/outbox. Create identical CI/CD pipelines for both Gitea Actions (`.gitea/workflows/ci.yml`, dev environment) and GitHub Actions (`.github/workflows/ci.yml`, production) that run: lint, pytest, `run_platform.sh --check-only`. Add `pyproject.toml` + `requirements-test.txt` for dependency pinning.
|
||||
- **Status:** complete (v1.3.2)
|
||||
- **Depends on:** [17]
|
||||
- **Requirements:** REQ-39, REQ-40, REQ-41, REQ-42
|
||||
- **Success Criteria:**
|
||||
- `pytest` runs and passes offline (no AWS, no Checkov, no DynamoDB).
|
||||
- `run_platform.sh --check-only` runs offline and exits 0.
|
||||
- `.gitea/workflows/ci.yml` and `.github/workflows/ci.yml` exist with identical job stages (lint, test, check-only).
|
||||
- `pyproject.toml` + `requirements-test.txt` pin test dependencies.
|
||||
|
||||
After Phase 18: COMPLETE gate — review → ship `v1.3.2` → audit.
|
||||
|
||||
---
|
||||
|
||||
## v1.4 (Active — central pipeline contract + shell reproducibility + streaming)
|
||||
|
||||
The v1.4 milestone makes the CI/CD pipeline a declarative contract rather
|
||||
than duplicated workflow copies, enables full shell reproducibility of the
|
||||
CI pipeline, and streams terraform/checkov output so users can see what
|
||||
the platform is doing.
|
||||
|
||||
### Phase 19 — central-pipeline-contract-and-shell-reproducibility
|
||||
- **Description:** Create a central pipeline contract (`schemas/pipeline.schema.json` JSON Schema + `pipelines/ci.yaml` YAML instance) that both `.gitea/workflows/ci.yml` (Gitea Actions, dev) and `.github/workflows/ci.yml` (GitHub Actions, production) implement. Create `scripts/run_ci.sh` that mirrors the CI pipeline locally (lint → test → check-only). Update `scripts/run_platform.sh` to stream terraform init/validate/plan output, Checkov compliance results, and PolicyCheckResult records to stdout by default (with `--quiet` for log-only mode). Add `tests/test_pipeline_contract.py` validating the contract schema, workflow conformance, and run_ci.sh. Update both workflow YAMLs with contract reference headers (staying byte-identical).
|
||||
- **Status:** complete (v1.4.1)
|
||||
- **Depends on:** [18]
|
||||
- **Requirements:** REQ-43, REQ-44, REQ-45
|
||||
- **Success Criteria:**
|
||||
- `pipelines/ci.yaml` validates against `schemas/pipeline.schema.json`.
|
||||
- Both `.gitea/workflows/ci.yml` and `.github/workflows/ci.yml` are byte-identical.
|
||||
- A test parses both workflows and asserts their stages/commands match the contract.
|
||||
- `scripts/run_ci.sh` exits 0 and outputs "CI PIPELINE OK".
|
||||
- `scripts/run_platform.sh --check-only` streams the emitted Terraform to stdout.
|
||||
- `scripts/run_platform.sh --check-only --quiet` suppresses the Terraform stream.
|
||||
- `pytest` total count increases from 90 to 122 (32 new contract/streaming tests).
|
||||
|
||||
After Phase 19: COMPLETE gate — review → ship `v1.4.1` → audit.
|
||||
|
||||
---
|
||||
|
||||
## v1.5 (Active — consumer happy path + zero-trust docs + reusable deploy workflow)
|
||||
|
||||
The v1.5 milestone makes the consumer happy path self-evident, documents the
|
||||
zero-trust credential model, and provides a reusable deploy workflow so
|
||||
consumer repos never need to clone the platform repo or invoke its scripts
|
||||
locally.
|
||||
|
||||
### Phase 20 — consumer-happy-path-and-reusable-deploy-workflow
|
||||
- **Description:** Rewrite `README.md` so the consumer model is unambiguous (this repo is the platform source; a consumer owns only `contract.yaml` + app code). Convert the platform-flow diagram to a mermaid `flowchart TD`. Remove "L3A"/"L3B" + "spike" nomenclature from README prose. Rewrite the Credentials section for zero-trust OIDC + ABAC (with a static-key override + daily rotation; consumer rotates out of band when using `.env.secrets` locally). Replace `docs/consumer-guide-static-asset.md` with a generic `docs/CONSUMER_GUIDE.md` (all L2 modules, mermaid diagrams, versioned `uses:` floating MAJOR+MINOR, consumer-scoped prerequisites, run-time platform fetch via a reusable workflow). Create byte-identical `.gitea/workflows/deploy.yml` + `.github/workflows/deploy.yml` implementing `pipelines/deploy.yaml` — a reusable workflow invoked by consumer repos via `uses: acdl/.gitea/workflows/deploy.yml@v1.4` that checks out the consumer repo + the ACDL platform repo and runs `scripts/run_platform.sh`. Update `contracts/static-asset.yaml` to `uses: acdl/pipelines/deploy.yaml@v1.4`. Extend `tests/test_pipeline_contract.py` to validate the new deploy workflows (byte-identical, schema-conformant).
|
||||
- **Status:** complete (v1.5.0)
|
||||
- **Depends on:** [19]
|
||||
- **Requirements:** REQ-46, REQ-47, REQ-48, REQ-49, REQ-50, REQ-51
|
||||
- **Success Criteria:**
|
||||
- `README.md` states the platform-source vs consumer-repo distinction up front; platform flow is a mermaid `flowchart TD`; `grep L3B README.md` returns 0 hits; `grep -i spike README.md` returns 0 prose hits (code paths in bash blocks allowed).
|
||||
- `docs/CONSUMER_GUIDE.md` exists; `docs/consumer-guide-static-asset.md` is deleted; `grep -R consumer-guide-static-asset` returns 0 dangling references; guide is generic (static-asset is the worked example, not the scope); diagrams are mermaid; `uses:` references use `@v1.4`.
|
||||
- `README.md` Credentials section describes OIDC + ABAC zero-trust as the default and the static-key override + daily rotation + consumer out-of-band rotation duty for local `.env.secrets`.
|
||||
- `.gitea/workflows/deploy.yml` and `.github/workflows/deploy.yml` exist, are byte-identical, conform to `schemas/deploy-pipeline.schema.json`, and are reusable (`on: workflow_call` with a `contract` input).
|
||||
- `contracts/static-asset.yaml` uses `uses: acdl/pipelines/deploy.yaml@v1.4`.
|
||||
- `tests/test_pipeline_contract.py` validates the deploy workflows (exist, byte-identical, schema-conformant); the extended test suite passes; `bash scripts/run_ci.sh` exits 0.
|
||||
|
||||
After Phase 20: COMPLETE gate — review → ship `v1.5.0` → audit.
|
||||
+35
-61
@@ -1,71 +1,45 @@
|
||||
# Phase 16 — v1.2-capstone-e2e (v1.2) VERIFY
|
||||
# Phase 18 — Verify (v1.3.2)
|
||||
|
||||
**Verdict: Phase 16: VERIFIED** (capstone, up to IAM-blocked apply)
|
||||
**Tag: v1.2.6**
|
||||
**Date: 2026-07-21**
|
||||
## Structural
|
||||
|
||||
---
|
||||
All 11 new files confirmed present: pyproject.toml, requirements-test.txt,
|
||||
tests/__init__.py, tests/conftest.py, tests/test_adapter.py,
|
||||
tests/test_confidence_signal.py, tests/test_checkov_adapter.py,
|
||||
tests/test_outbox_writer.py, tests/test_pipeline.py,
|
||||
.gitea/workflows/ci.yml, .github/workflows/ci.yml. **PASS.**
|
||||
|
||||
## Scope
|
||||
## Behavioral
|
||||
|
||||
Phase 16 is the v1.2 capstone: end-to-end verification of the full platform
|
||||
flow (consumer content → contract → IR → adapter → terraform validate + plan)
|
||||
+ the NFR improvements + the documentation + the v1.1 regression. The
|
||||
`terraform apply` (the final step) is blocked by the IAM P0 (Phase 15);
|
||||
this verify confirms everything *up to* the apply. Requirement: **REQ-35**.
|
||||
- `py_compile` passes on all Python files. **PASS.**
|
||||
- `pytest` — 90 tests, all passing, all offline (moto for DynamoDB
|
||||
mocking). **PASS.**
|
||||
- `run_platform.sh --check-only` — exits 0, outputs
|
||||
"PLATFORM CHECK OK", requires no AWS credentials. **PASS.**
|
||||
- `run_platform.sh --plan-only` — syntax valid (unchanged from phase 17).
|
||||
**PASS.**
|
||||
- Both workflow YAMLs are valid YAML, parseable. **PASS.**
|
||||
- Workflows are byte-identical (diff confirms). **PASS.**
|
||||
|
||||
## Verification layers
|
||||
## Security
|
||||
|
||||
### 1. Structural
|
||||
- `scripts/verify_phase16.sh` exists (+x, 11 assertions).
|
||||
- `.ciagent/PLAN.md` updated to Phase 16.
|
||||
- **PASS.**
|
||||
- No secrets in any new file (tests, workflows, pyproject, requirements).
|
||||
**PASS.**
|
||||
- CI pipelines do not use any AWS credentials — `--check-only` is fully
|
||||
offline. **PASS.**
|
||||
|
||||
### 2. Behavioral (`scripts/verify_phase16.sh`)
|
||||
```
|
||||
=== Phase 16 — v1.2 capstone e2e verification ===
|
||||
Consumer microservice: OK
|
||||
v1.2 contract -> IR -> adapter: OK (11 resources)
|
||||
terraform validate + plan: OK (Plan: 13 to add, 0 to change, 0 to destroy.)
|
||||
NFR improvements (Phase 12): OK (run_platform.sh + IAM expanded)
|
||||
P1-1 redaction: OK (no live AWS key IDs)
|
||||
README accuracy: OK
|
||||
v1.1 S3 regression: OK
|
||||
L1 catalog: OK (7 L1s)
|
||||
l2-microservice: OK
|
||||
.ciagent/ consistency: OK
|
||||
outbox: OK (3 event(s))
|
||||
Evidence events: OK
|
||||
## Quality
|
||||
|
||||
=== Phase 16: VERIFIED (capstone, up to IAM-blocked apply) ===
|
||||
```
|
||||
- pyproject.toml has pytest config (testpaths, markers, addopts).
|
||||
**PASS.**
|
||||
- requirements-test.txt pins all test deps. **PASS.**
|
||||
- Test suite covers all 4 platform components (adapter, confidence
|
||||
signal, checkov adapter, outbox writer) + pipeline integration.
|
||||
**PASS.**
|
||||
- Both workflows run 3 stages: lint, test, check-only. **PASS.**
|
||||
- README updated with "Test the platform" section + CI/CD documentation.
|
||||
**PASS.**
|
||||
|
||||
All 11 assertions pass. The full v1.2 platform is verified end-to-end up
|
||||
to the `terraform apply`. The `MILESTONE_CAPSTONE_VERIFIED` evidence event
|
||||
is written to the DynamoDB outbox.
|
||||
- **PASS.**
|
||||
## Verdict
|
||||
|
||||
### 3. Security
|
||||
- No credentials introduced. The IAM P0 blocker is a security positive (least-privilege enforced; policy push requires a deliberate privileged action).
|
||||
- **PASS.**
|
||||
|
||||
### 4. Quality
|
||||
- The capstone verify exercises every v1.2 deliverable: consumer microservice (Phase 15), contract→IR→adapter pipeline (Phase 14), L1 catalog (Phase 13), NFR improvements (Phase 12), README (Phase 11), v1.1 S3 regression.
|
||||
- The `terraform plan` (13 to add) confirms the adapter fixes from Phase 15 produce valid HCL for the full ECS microservice stack.
|
||||
- **PASS.**
|
||||
|
||||
## P0 / P1
|
||||
- **P0: 1 (carried from Phase 15 — operator action).** `terraform apply` blocked by IAM. Unblock: operator runs `create_iam_user.py` with root/admin creds, then `terraform apply` (13 to add) → live ECS service → HTTP 200. This completes REQ-33 + REQ-35.
|
||||
- **P1: none new.**
|
||||
|
||||
## Requirements covered
|
||||
- **REQ-35:** End-to-end verification — consumer commit → pipeline → ECS service → evidence event → timeline. **PARTIAL** (verified up to `terraform plan`; the `apply` + HTTP 200 check are the operator's post-unblock step). The `MILESTONE_CAPSTONE_VERIFIED` evidence event is in the outbox.
|
||||
|
||||
## Conclusion
|
||||
|
||||
Phase 16 is VERIFIED (capstone, up to the IAM-blocked apply). The v1.2
|
||||
milestone is complete in code: all 6 phases shipped (v1.2.1–v1.2.6), the
|
||||
platform flow is verified end-to-end up to `terraform plan` (13 to add),
|
||||
and the one remaining step (`terraform apply` → live ECS service) is the
|
||||
operator's IAM policy push (P0, documented). The milestone is ready for
|
||||
the COMPLETE gate (review → ship v1.3.0 → audit).
|
||||
**VERIFY PASS** — all four layers pass. 90 offline tests, no AWS
|
||||
required for CI.
|
||||
@@ -4,8 +4,8 @@
|
||||
{
|
||||
"slug": "acdl",
|
||||
"name": "Agentic Cloud Delivery Platform",
|
||||
"milestone": "v1.2",
|
||||
"status": "specify"
|
||||
"milestone": "v1.5",
|
||||
"status": "active"
|
||||
}
|
||||
],
|
||||
"active_project": "acdl",
|
||||
|
||||
@@ -0,0 +1,75 @@
|
||||
# ACDL CI Pipeline — Gitea Actions (dev environment)
|
||||
#
|
||||
# This workflow implements the central pipeline contract:
|
||||
# pipelines/ci.yaml (validated against schemas/pipeline.schema.json)
|
||||
#
|
||||
# The same contract is implemented by .github/workflows/ci.yml (GitHub
|
||||
# Actions, production). Both files must be byte-identical — the only
|
||||
# declared difference is the forge/runtime, not the stages or commands.
|
||||
#
|
||||
# Shell reproducibility: scripts/run_ci.sh runs the same 3 stages locally.
|
||||
#
|
||||
# Stages (from the contract):
|
||||
# 1. lint — py_compile all Python files
|
||||
# 2. test — pytest test suite (offline, no AWS)
|
||||
# 3. check-only — run_platform.sh --check-only (offline, no AWS)
|
||||
name: acdl-ci
|
||||
|
||||
on:
|
||||
push:
|
||||
branches: [main]
|
||||
pull_request:
|
||||
branches: [main]
|
||||
|
||||
jobs:
|
||||
lint:
|
||||
name: Lint
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
|
||||
- uses: actions/setup-python@v5
|
||||
with:
|
||||
python-version: "3.12"
|
||||
|
||||
- name: Compile all Python files
|
||||
run: |
|
||||
python3 -m py_compile \
|
||||
acdl_platform/confidence_signal.py \
|
||||
acdl_platform/outbox_writer.py \
|
||||
acdl_platform/contract_resolver.py \
|
||||
adapters/terraform/adapter.py \
|
||||
adapters/terraform/policy/checkov_adapter.py \
|
||||
scripts/push_consumer_image.py
|
||||
|
||||
test:
|
||||
name: Test
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
|
||||
- uses: actions/setup-python@v5
|
||||
with:
|
||||
python-version: "3.12"
|
||||
|
||||
- name: Install test dependencies
|
||||
run: pip install -r requirements-test.txt
|
||||
|
||||
- name: Run pytest
|
||||
run: python3 -m pytest tests/ -v --tb=short
|
||||
|
||||
check-only:
|
||||
name: Platform check-only (offline)
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
|
||||
- uses: actions/setup-python@v5
|
||||
with:
|
||||
python-version: "3.12"
|
||||
|
||||
- name: Install runtime dependencies
|
||||
run: pip install jsonschema pyyaml boto3
|
||||
|
||||
- name: Run platform check-only
|
||||
run: bash scripts/run_platform.sh --check-only
|
||||
@@ -0,0 +1,127 @@
|
||||
# ACDL Reusable Deploy Workflow — Gitea Actions (dev environment)
|
||||
#
|
||||
# This reusable workflow implements the central deployment pipeline contract:
|
||||
# pipelines/deploy.yaml (validated against schemas/deploy-pipeline.schema.json)
|
||||
#
|
||||
# The same contract is implemented by .github/workflows/deploy.yml (GitHub
|
||||
# Actions, production). Both files must be byte-identical — the only
|
||||
# declared difference is the forge/runtime, not the stages or commands.
|
||||
#
|
||||
# Consumer repos invoke this workflow via a versioned tag (floating MAJOR + MINOR):
|
||||
# uses: acdl/.gitea/workflows/deploy.yml@v1.4 (Gitea)
|
||||
# uses: acdl/.github/workflows/deploy.yml@v1.4 (GitHub)
|
||||
#
|
||||
# Unversioned references (@main, bare) are discouraged — the consumer's setup
|
||||
# must be immutable + resilient. The versioned tag is the only immutability
|
||||
# lever (version constraints cannot be expressed inside the contract).
|
||||
#
|
||||
# What this workflow does:
|
||||
# 1. Checks out the consumer repo (the repo that invoked the workflow).
|
||||
# 2. Checks out the ACDL platform repo into the workspace (acdl-platform/).
|
||||
# This is the run-time fetch — consumers never clone the platform repo.
|
||||
# 3. Installs runtime deps: Python 3.12, Terraform 1.9.*, Checkov.
|
||||
# 4. Configures AWS auth (OIDC default; static-key override via secrets).
|
||||
# 5. Runs scripts/run_platform.sh against the consumer's contract path.
|
||||
# 6. Uploads artifacts (emitted Terraform, Checkov JSON, confidence JSON,
|
||||
# platform log) for auditability.
|
||||
#
|
||||
# Inputs:
|
||||
# contract — path to the consumer's contract YAML (default .acdl/contract.yaml)
|
||||
# mode — full | plan-only | check-only (default full; dev = full apply,
|
||||
# higher environments hold for HITL — the calling repo or the
|
||||
# forge environment gate enforces that)
|
||||
#
|
||||
# Auth (zero-trust default — see README.md#credentials--zero-trust):
|
||||
# OIDC federation is the default. permissions: id-token: write lets the
|
||||
# forge mint a short-lived STS token. The role-to-assume is scoped by the
|
||||
# consumer's repository identity (ABAC) — the workflow assumes the role
|
||||
# that matches repo:org/consumer-repo:ref:refs/heads/main, and the session
|
||||
# policy restricts view/update to resources tagged acdl:owner=<consumer-repo>.
|
||||
#
|
||||
# Override (where OIDC is unavailable, e.g. Gitea pending
|
||||
# go-gitea/gitea#36988): set ACDL_AWS_ACCESS_KEY_ID + ACDL_AWS_SECRET_ACCESS_KEY
|
||||
# as repository secrets. The platform-managed scheduled pipeline rotates
|
||||
# the key on a daily cadence. When .env.secrets is used locally instead,
|
||||
# rotating the key out of band is the consumer's responsibility.
|
||||
name: acdl-deploy
|
||||
|
||||
on:
|
||||
workflow_call:
|
||||
inputs:
|
||||
contract:
|
||||
description: Path to the consumer contract YAML (in the consumer repo)
|
||||
type: string
|
||||
default: .acdl/contract.yaml
|
||||
mode:
|
||||
description: Pipeline mode — full (apply), plan-only, or check-only
|
||||
type: string
|
||||
default: full
|
||||
|
||||
permissions:
|
||||
id-token: write
|
||||
contents: read
|
||||
|
||||
jobs:
|
||||
deploy:
|
||||
name: Deploy
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- name: Check out consumer repo
|
||||
uses: actions/checkout@v4
|
||||
|
||||
- name: Check out ACDL platform repo
|
||||
uses: actions/checkout@v4
|
||||
with:
|
||||
repository: acdl/acdl
|
||||
path: acdl-platform
|
||||
ref: v1.4
|
||||
|
||||
- uses: actions/setup-python@v5
|
||||
with:
|
||||
python-version: "3.12"
|
||||
|
||||
- name: Install runtime dependencies
|
||||
run: |
|
||||
pip install --break-system-packages jsonschema pyyaml boto3
|
||||
pip install --break-system-packages "checkov>=3.2,<4"
|
||||
|
||||
- name: Install Terraform 1.9.*
|
||||
run: |
|
||||
wget -qO- https://apt.releases.hashicorp.com/gpg | sudo gpg --dearmor -o /usr/share/keyrings/hashicorp.gpg
|
||||
echo "deb [signed-by=/usr/share/keyrings/hashicorp.gpg] https://apt.releases.hashicorp.com $(lsb_release -cs) main" | sudo tee /etc/apt/sources.list.d/hashicorp.list
|
||||
sudo apt-get update && sudo apt-get install -y terraform=1.9.*
|
||||
|
||||
- name: Configure AWS credentials (OIDC default)
|
||||
uses: aws-actions/configure-aws-credentials@v4
|
||||
with:
|
||||
role-to-assume: arn:aws:iam::${{ secrets.ACDL_AWS_ACCOUNT_ID }}:role/acdl-deploy-${{ github.repository_id }}
|
||||
aws-region: us-east-1
|
||||
env:
|
||||
ACDL_AWS_ACCESS_KEY_ID: ${{ secrets.ACDL_AWS_ACCESS_KEY_ID }}
|
||||
ACDL_AWS_SECRET_ACCESS_KEY: ${{ secrets.ACDL_AWS_SECRET_ACCESS_KEY }}
|
||||
|
||||
- name: Run the platform pipeline
|
||||
working-directory: ${{ github.workspace }}
|
||||
run: |
|
||||
MODE_FLAG=""
|
||||
case "${{ inputs.mode }}" in
|
||||
full) MODE_FLAG="" ;;
|
||||
plan-only) MODE_FLAG="--plan-only" ;;
|
||||
check-only) MODE_FLAG="--check-only" ;;
|
||||
*) echo "Unknown mode: ${{ inputs.mode }}"; exit 1 ;;
|
||||
esac
|
||||
bash acdl-platform/scripts/run_platform.sh $MODE_FLAG "${{ inputs.contract }}"
|
||||
|
||||
- name: Upload emitted Terraform
|
||||
uses: actions/upload-artifact@v4
|
||||
with:
|
||||
name: acdl-terraform
|
||||
path: acdl-platform/terraform/spike/*.tf
|
||||
if-no-files-found: warn
|
||||
|
||||
- name: Upload platform log
|
||||
uses: actions/upload-artifact@v4
|
||||
with:
|
||||
name: acdl-platform-log
|
||||
path: acdl-platform/logs/
|
||||
if-no-files-found: warn
|
||||
@@ -0,0 +1,75 @@
|
||||
# ACDL CI Pipeline — Gitea Actions (dev environment)
|
||||
#
|
||||
# This workflow implements the central pipeline contract:
|
||||
# pipelines/ci.yaml (validated against schemas/pipeline.schema.json)
|
||||
#
|
||||
# The same contract is implemented by .github/workflows/ci.yml (GitHub
|
||||
# Actions, production). Both files must be byte-identical — the only
|
||||
# declared difference is the forge/runtime, not the stages or commands.
|
||||
#
|
||||
# Shell reproducibility: scripts/run_ci.sh runs the same 3 stages locally.
|
||||
#
|
||||
# Stages (from the contract):
|
||||
# 1. lint — py_compile all Python files
|
||||
# 2. test — pytest test suite (offline, no AWS)
|
||||
# 3. check-only — run_platform.sh --check-only (offline, no AWS)
|
||||
name: acdl-ci
|
||||
|
||||
on:
|
||||
push:
|
||||
branches: [main]
|
||||
pull_request:
|
||||
branches: [main]
|
||||
|
||||
jobs:
|
||||
lint:
|
||||
name: Lint
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
|
||||
- uses: actions/setup-python@v5
|
||||
with:
|
||||
python-version: "3.12"
|
||||
|
||||
- name: Compile all Python files
|
||||
run: |
|
||||
python3 -m py_compile \
|
||||
acdl_platform/confidence_signal.py \
|
||||
acdl_platform/outbox_writer.py \
|
||||
acdl_platform/contract_resolver.py \
|
||||
adapters/terraform/adapter.py \
|
||||
adapters/terraform/policy/checkov_adapter.py \
|
||||
scripts/push_consumer_image.py
|
||||
|
||||
test:
|
||||
name: Test
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
|
||||
- uses: actions/setup-python@v5
|
||||
with:
|
||||
python-version: "3.12"
|
||||
|
||||
- name: Install test dependencies
|
||||
run: pip install -r requirements-test.txt
|
||||
|
||||
- name: Run pytest
|
||||
run: python3 -m pytest tests/ -v --tb=short
|
||||
|
||||
check-only:
|
||||
name: Platform check-only (offline)
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
|
||||
- uses: actions/setup-python@v5
|
||||
with:
|
||||
python-version: "3.12"
|
||||
|
||||
- name: Install runtime dependencies
|
||||
run: pip install jsonschema pyyaml boto3
|
||||
|
||||
- name: Run platform check-only
|
||||
run: bash scripts/run_platform.sh --check-only
|
||||
@@ -0,0 +1,127 @@
|
||||
# ACDL Reusable Deploy Workflow — Gitea Actions (dev environment)
|
||||
#
|
||||
# This reusable workflow implements the central deployment pipeline contract:
|
||||
# pipelines/deploy.yaml (validated against schemas/deploy-pipeline.schema.json)
|
||||
#
|
||||
# The same contract is implemented by .github/workflows/deploy.yml (GitHub
|
||||
# Actions, production). Both files must be byte-identical — the only
|
||||
# declared difference is the forge/runtime, not the stages or commands.
|
||||
#
|
||||
# Consumer repos invoke this workflow via a versioned tag (floating MAJOR + MINOR):
|
||||
# uses: acdl/.gitea/workflows/deploy.yml@v1.4 (Gitea)
|
||||
# uses: acdl/.github/workflows/deploy.yml@v1.4 (GitHub)
|
||||
#
|
||||
# Unversioned references (@main, bare) are discouraged — the consumer's setup
|
||||
# must be immutable + resilient. The versioned tag is the only immutability
|
||||
# lever (version constraints cannot be expressed inside the contract).
|
||||
#
|
||||
# What this workflow does:
|
||||
# 1. Checks out the consumer repo (the repo that invoked the workflow).
|
||||
# 2. Checks out the ACDL platform repo into the workspace (acdl-platform/).
|
||||
# This is the run-time fetch — consumers never clone the platform repo.
|
||||
# 3. Installs runtime deps: Python 3.12, Terraform 1.9.*, Checkov.
|
||||
# 4. Configures AWS auth (OIDC default; static-key override via secrets).
|
||||
# 5. Runs scripts/run_platform.sh against the consumer's contract path.
|
||||
# 6. Uploads artifacts (emitted Terraform, Checkov JSON, confidence JSON,
|
||||
# platform log) for auditability.
|
||||
#
|
||||
# Inputs:
|
||||
# contract — path to the consumer's contract YAML (default .acdl/contract.yaml)
|
||||
# mode — full | plan-only | check-only (default full; dev = full apply,
|
||||
# higher environments hold for HITL — the calling repo or the
|
||||
# forge environment gate enforces that)
|
||||
#
|
||||
# Auth (zero-trust default — see README.md#credentials--zero-trust):
|
||||
# OIDC federation is the default. permissions: id-token: write lets the
|
||||
# forge mint a short-lived STS token. The role-to-assume is scoped by the
|
||||
# consumer's repository identity (ABAC) — the workflow assumes the role
|
||||
# that matches repo:org/consumer-repo:ref:refs/heads/main, and the session
|
||||
# policy restricts view/update to resources tagged acdl:owner=<consumer-repo>.
|
||||
#
|
||||
# Override (where OIDC is unavailable, e.g. Gitea pending
|
||||
# go-gitea/gitea#36988): set ACDL_AWS_ACCESS_KEY_ID + ACDL_AWS_SECRET_ACCESS_KEY
|
||||
# as repository secrets. The platform-managed scheduled pipeline rotates
|
||||
# the key on a daily cadence. When .env.secrets is used locally instead,
|
||||
# rotating the key out of band is the consumer's responsibility.
|
||||
name: acdl-deploy
|
||||
|
||||
on:
|
||||
workflow_call:
|
||||
inputs:
|
||||
contract:
|
||||
description: Path to the consumer contract YAML (in the consumer repo)
|
||||
type: string
|
||||
default: .acdl/contract.yaml
|
||||
mode:
|
||||
description: Pipeline mode — full (apply), plan-only, or check-only
|
||||
type: string
|
||||
default: full
|
||||
|
||||
permissions:
|
||||
id-token: write
|
||||
contents: read
|
||||
|
||||
jobs:
|
||||
deploy:
|
||||
name: Deploy
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- name: Check out consumer repo
|
||||
uses: actions/checkout@v4
|
||||
|
||||
- name: Check out ACDL platform repo
|
||||
uses: actions/checkout@v4
|
||||
with:
|
||||
repository: acdl/acdl
|
||||
path: acdl-platform
|
||||
ref: v1.4
|
||||
|
||||
- uses: actions/setup-python@v5
|
||||
with:
|
||||
python-version: "3.12"
|
||||
|
||||
- name: Install runtime dependencies
|
||||
run: |
|
||||
pip install --break-system-packages jsonschema pyyaml boto3
|
||||
pip install --break-system-packages "checkov>=3.2,<4"
|
||||
|
||||
- name: Install Terraform 1.9.*
|
||||
run: |
|
||||
wget -qO- https://apt.releases.hashicorp.com/gpg | sudo gpg --dearmor -o /usr/share/keyrings/hashicorp.gpg
|
||||
echo "deb [signed-by=/usr/share/keyrings/hashicorp.gpg] https://apt.releases.hashicorp.com $(lsb_release -cs) main" | sudo tee /etc/apt/sources.list.d/hashicorp.list
|
||||
sudo apt-get update && sudo apt-get install -y terraform=1.9.*
|
||||
|
||||
- name: Configure AWS credentials (OIDC default)
|
||||
uses: aws-actions/configure-aws-credentials@v4
|
||||
with:
|
||||
role-to-assume: arn:aws:iam::${{ secrets.ACDL_AWS_ACCOUNT_ID }}:role/acdl-deploy-${{ github.repository_id }}
|
||||
aws-region: us-east-1
|
||||
env:
|
||||
ACDL_AWS_ACCESS_KEY_ID: ${{ secrets.ACDL_AWS_ACCESS_KEY_ID }}
|
||||
ACDL_AWS_SECRET_ACCESS_KEY: ${{ secrets.ACDL_AWS_SECRET_ACCESS_KEY }}
|
||||
|
||||
- name: Run the platform pipeline
|
||||
working-directory: ${{ github.workspace }}
|
||||
run: |
|
||||
MODE_FLAG=""
|
||||
case "${{ inputs.mode }}" in
|
||||
full) MODE_FLAG="" ;;
|
||||
plan-only) MODE_FLAG="--plan-only" ;;
|
||||
check-only) MODE_FLAG="--check-only" ;;
|
||||
*) echo "Unknown mode: ${{ inputs.mode }}"; exit 1 ;;
|
||||
esac
|
||||
bash acdl-platform/scripts/run_platform.sh $MODE_FLAG "${{ inputs.contract }}"
|
||||
|
||||
- name: Upload emitted Terraform
|
||||
uses: actions/upload-artifact@v4
|
||||
with:
|
||||
name: acdl-terraform
|
||||
path: acdl-platform/terraform/spike/*.tf
|
||||
if-no-files-found: warn
|
||||
|
||||
- name: Upload platform log
|
||||
uses: actions/upload-artifact@v4
|
||||
with:
|
||||
name: acdl-platform-log
|
||||
path: acdl-platform/logs/
|
||||
if-no-files-found: warn
|
||||
@@ -11,85 +11,102 @@ a configuration file, or a Terraform module.
|
||||
- **Architecture** (the how): [`docs/architecture.md`](docs/architecture.md) + [`.ciagent/ARCHITECTURE.md`](.ciagent/ARCHITECTURE.md)
|
||||
- **Decisions**: [`.ciagent/PROJECT.md`](.ciagent/PROJECT.md)
|
||||
- **Phase plan**: [`.ciagent/ROADMAP.md`](.ciagent/ROADMAP.md)
|
||||
- **Consumer guide**: [`docs/CONSUMER_GUIDE.md`](docs/CONSUMER_GUIDE.md)
|
||||
|
||||
## Repository roles
|
||||
|
||||
There are two kinds of repository in the ACDL model:
|
||||
|
||||
- **Platform repo (this one).** This is the **source code of the platform**.
|
||||
It owns `modules/`, `adapters/`, `acdl_platform/`, `schemas/`, `pipelines/`,
|
||||
`scripts/`, and the reusable workflow files. Platform engineers work here.
|
||||
A **consumer never clones it.**
|
||||
- **Consumer repo (yours).** A consumer repo contains only its application
|
||||
code and a single `contract.yaml` that references the central pipeline +
|
||||
contract. The consumer does not write Terraform, workflow YAML, or adapter
|
||||
code — they write a contract YAML file and the platform does the rest.
|
||||
|
||||
The rest of this README describes the **platform repo** (how the platform
|
||||
works, how to run it locally, how it's laid out). If you are a consumer,
|
||||
jump to the [Consumer guide](docs/CONSUMER_GUIDE.md).
|
||||
|
||||
## Status
|
||||
|
||||
- **v1.2 (active):** platform hardening + first real consumer deployment.
|
||||
Harden the v1.1 spike's NFRs, simplify the setup, rewrite the docs, and
|
||||
prove the platform delivers real value by deploying a basic microservice
|
||||
to AWS ECS Fargate end-to-end (`terraform apply`, dev autonomous). Ship
|
||||
tag `v1.3.0`.
|
||||
- **v1.1 (complete, tag `v1.2.0`):** architecture finalization + v1 spike.
|
||||
Finalized the architecture to v1.0 (resolved all 11 open design
|
||||
decisions) and proved the IR commitments hold with one end-to-end spike
|
||||
(`l1-s3` + `l2-static-asset` + Terraform adapter → real `terraform plan`
|
||||
against AWS). Gitea release id 202.
|
||||
- **v1.0 demo (complete, archived under `demo/`, tag `v1.1.0`):** the
|
||||
30-minute stub-driven executive demo. Preserved as the intent reference;
|
||||
it is not the platform.
|
||||
- **v1.5 (active):** consumer happy path + zero-trust docs + reusable deploy
|
||||
workflow. README rewritten so the consumer model is unambiguous. Platform
|
||||
flow + consumer guide converted to mermaid. Legacy surface + implementation
|
||||
nomenclature removed from docs. Credentials section rewritten for
|
||||
zero-trust OIDC + ABAC. A generic `docs/CONSUMER_GUIDE.md` (all L2 modules,
|
||||
versioned `uses:`, consumer-scoped prerequisites, run-time platform fetch)
|
||||
replaces the module-specific guide. A byte-identical reusable `deploy.yml`
|
||||
workflow (Gitea + GitHub) implements `pipelines/deploy.yaml` and is invoked
|
||||
by consumer repos via a versioned tag.
|
||||
- **v1.4 (complete, tag `v1.4.1`):** central pipeline contract + shell
|
||||
reproducibility + output streaming. A declarative pipeline contract
|
||||
(`schemas/pipeline.schema.json` + `pipelines/ci.yaml`) binds the Gitea
|
||||
and GitHub workflows to a single source of truth. `scripts/run_ci.sh`
|
||||
mirrors the CI pipeline locally. `scripts/run_platform.sh` streams
|
||||
terraform/checkov output by default. L2 compositions re-introduced with
|
||||
a `uses:`-based contract resolution mechanism.
|
||||
- **v1.3 (complete, tag `v1.3.2`):** module documentation. Testing + CI/CD
|
||||
pipelines (pytest, `--check-only`, Gitea + GitHub workflows).
|
||||
- **v1.2 (complete, tag `v1.3.0`):** platform hardening + first real
|
||||
consumer deployment. Harden the v1.1 implementation's NFRs, simplify the
|
||||
setup, rewrite the docs, and prove the platform delivers real value by
|
||||
deploying a basic microservice to AWS ECS Fargate end-to-end (`terraform
|
||||
apply`, dev autonomous).
|
||||
- **v1.1 (complete, tag `v1.2.0`):** architecture finalization + v1
|
||||
implementation. Finalized the architecture to v1.0 (resolved all 11 open
|
||||
design decisions) and proved the stack commitments hold with one
|
||||
end-to-end run (`s3` + `static-asset` + Terraform adapter → real
|
||||
`terraform plan` against AWS). Gitea release id 202.
|
||||
|
||||
## How the platform works
|
||||
|
||||
The platform is **four layers + six cross-cutting concerns**, bound by the
|
||||
vision's "Two Consumer Surfaces, One Platform" tenet: technical developers
|
||||
(L3A) and non-technical consumers (L3B) converge on the same contract
|
||||
schema, the same policy envelope, and the same evidence stream.
|
||||
vision's "Two Consumer Surfaces, One Platform" tenet: consumers declare
|
||||
intent via a contract; the platform delivers the deployment through the
|
||||
same contract schema, the same policy envelope, and the same evidence
|
||||
stream.
|
||||
|
||||
### The v1.1 spike flow (end-to-end)
|
||||
Consumers have their own repos and consume ACDL by referencing `uses:` the
|
||||
central pipeline definitions. A consumer declares a contract (module +
|
||||
environment + inputs); the platform resolves it to a stack instance,
|
||||
compiles it to Terraform, runs policy checks, computes a confidence signal,
|
||||
and writes an evidence event to the audit outbox.
|
||||
|
||||
```
|
||||
contracts/spike.yaml
|
||||
│ (contract schema validation)
|
||||
▼
|
||||
acdl_platform/contract_resolver.py ──▶ Target Stack IR (JSON)
|
||||
│ (IR schema validation)
|
||||
▼
|
||||
adapters/terraform/adapter.py ──▶ terraform/spike/{main,terraform,providers}.tf
|
||||
│ (the only substrate-specific code)
|
||||
▼
|
||||
terraform plan (real AWS, via the rotated spike key — D-039/D-047)
|
||||
│
|
||||
▼
|
||||
adapters/terraform/policy/checkov_adapter.py ──▶ PolicyCheckResult (JSON list)
|
||||
│ (normalized, engine-agnostic)
|
||||
▼
|
||||
acdl_platform/confidence_signal.py ──▶ { score, band, perInput, reasonCodes }
|
||||
│ (6 inputs: policy, validation, freshness, source, history, nfrs)
|
||||
▼
|
||||
acdl_platform/outbox_writer.py ──▶ DynamoDB outbox (acdl-outbox)
|
||||
│ (hash-chained evidence event)
|
||||
▼
|
||||
acdl-evidence timeline (acdl-evidence repo, raw-file served)
|
||||
### The platform flow (end-to-end)
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
A["contracts/static-asset.yaml<br/>(consumer contract: uses + module + inputs)"] --> B
|
||||
B["schema validation<br/>(schemas/contract.schema.json)"] --> C
|
||||
C["acdl_platform/contract_resolver.py<br/>→ Target Stack (JSON)"] --> D
|
||||
D["stack schema validation<br/>(schemas/stack.schema.json)"] --> E
|
||||
E["adapters/terraform/adapter.py<br/>→ terraform/spike/{main,terraform,providers}.tf<br/>(the only substrate-specific code)"] --> F
|
||||
F["terraform plan<br/>(real AWS, via the rotated runner key — D-039/D-047)"] --> G
|
||||
G["adapters/terraform/policy/checkov_adapter.py<br/>→ PolicyCheckResult (JSON list)<br/>(normalized, engine-agnostic)"] --> H
|
||||
H["acdl_platform/confidence_signal.py<br/>→ { score, band, perInput, reasonCodes }<br/>(6 inputs: policy, validation, freshness, source, history, nfrs)"] --> I
|
||||
I["acdl_platform/outbox_writer.py<br/>→ DynamoDB outbox (acdl-outbox)<br/>(hash-chained evidence event)"] --> J
|
||||
J["acdl-evidence timeline<br/>(acdl-evidence repo, raw-file served)"]
|
||||
```
|
||||
|
||||
The spike validates the architecture's claim that the **IR-shaped
|
||||
The platform validates the architecture's claim that the **stack
|
||||
commitments do not require a polyglot mess**: the adapter is the only
|
||||
substrate-specific code. `modules-ir/`, `schemas/`, `contracts/`,
|
||||
substrate-specific code. `modules/`, `schemas/`, `contracts/`,
|
||||
`acdl_platform/confidence_signal.py`, `acdl_platform/contract_resolver.py`,
|
||||
and `acdl_platform/outbox_writer.py` are all substrate-agnostic (no
|
||||
`aws_s3_bucket` / `aws_` Terraform terms).
|
||||
|
||||
### What's different in v1.2
|
||||
|
||||
v1.2 extends the spike to a real, simpler, better-documented platform that
|
||||
**deploys a microservice to ECS Fargate**:
|
||||
|
||||
- Six new IR-typed L1s: `l1-vpc`, `l1-ecs-cluster`, `l1-ecs-service`,
|
||||
`l1-iam-role`, `l1-alb`, `l1-ecr`.
|
||||
- One new L2 thin-composition: `l2-microservice` (references the six L1s).
|
||||
- `terraform apply` (dev, autonomous per §10, confidence ≥ 0.50) — real
|
||||
provisioning, not just `plan`.
|
||||
- A new consumer repo `acdl-consumer-microservice` with a basic HTTP
|
||||
container + Dockerfile + ECR push + contract submission.
|
||||
- One `scripts/run_platform.sh` (consolidated from the v1.1 spike scripts).
|
||||
- NFR hardening: least-privilege IAM (expanded for ECS), idempotent
|
||||
bootstrap, proper error handling, P1-1 redaction.
|
||||
|
||||
## How to run
|
||||
|
||||
### Prerequisites
|
||||
|
||||
- AWS account + the rotated spike key in `.env.secrets` (see
|
||||
> These prerequisites are for running the **platform repo** locally. A
|
||||
> consumer does not need any of these — see the
|
||||
> [Consumer guide](docs/CONSUMER_GUIDE.md) for the consumer happy path.
|
||||
|
||||
- AWS account + the rotated runner key in `.env.secrets` (see
|
||||
`scripts/rotate_spike_key.sh`; the bootstrap root key was deactivated
|
||||
per D-034 closure).
|
||||
- `terraform` (pin `1.9.*`), `checkov` (pin `>=3.2,<4`), `python3` + `boto3`
|
||||
@@ -98,7 +115,7 @@ v1.2 extends the spike to a real, simpler, better-documented platform that
|
||||
### Run the platform pipeline end-to-end
|
||||
|
||||
```bash
|
||||
# 1. Bootstrap the AWS state backend + spike IAM user (one-time, idempotent)
|
||||
# 1. Bootstrap the AWS state backend + runner IAM user (one-time, idempotent)
|
||||
# (requires the bootstrap root key in env — now deactivated; skip if
|
||||
# the state bucket + acdl-spike-runner already exist)
|
||||
ACDL_BOOTSTRAP_AWS_ACCESS_KEY_ID=... ACDL_BOOTSTRAP_AWS_SECRET_ACCESS_KEY=... \
|
||||
@@ -106,61 +123,185 @@ ACDL_BOOTSTRAP_AWS_ACCESS_KEY_ID=... ACDL_BOOTSTRAP_AWS_SECRET_ACCESS_KEY=... \
|
||||
ACDL_BOOTSTRAP_AWS_ACCESS_KEY_ID=... ACDL_BOOTSTRAP_AWS_SECRET_ACCESS_KEY=... \
|
||||
python3 terraform/bootstrap/create_iam_user.py # prints the initial key
|
||||
|
||||
# 2. Rotate the spike key (writes .env.secrets, gitignored)
|
||||
# 2. Rotate the runner key (writes .env.secrets, gitignored)
|
||||
ACDL_BOOTSTRAP_AWS_ACCESS_KEY_ID=... ACDL_BOOTSTRAP_AWS_SECRET_ACCESS_KEY=... \
|
||||
bash scripts/rotate_spike_key.sh
|
||||
|
||||
# 3. Run the full platform pipeline (contract -> IR -> plan -> Checkov ->
|
||||
# confidence -> outbox)
|
||||
bash scripts/run_platform.sh
|
||||
# 3. Run the full platform pipeline (contract -> stack -> adapter -> plan ->
|
||||
# Checkov -> confidence -> outbox). Output is streamed to stdout by default.
|
||||
bash scripts/run_platform.sh contracts/static-asset.yaml
|
||||
# Expected: "=== PLATFORM E2E OK ==="
|
||||
|
||||
# Or plan-only (contract -> IR -> terraform plan; no Checkov/outbox):
|
||||
bash scripts/run_platform.sh --plan-only
|
||||
# Or plan-only (contract -> stack -> adapter -> terraform plan; no Checkov/outbox):
|
||||
bash scripts/run_platform.sh --plan-only contracts/static-asset.yaml
|
||||
|
||||
# Add --quiet to suppress streaming (output to log files only):
|
||||
bash scripts/run_platform.sh --quiet contracts/static-asset.yaml
|
||||
```
|
||||
|
||||
### Re-run the archived v1.0 demo (stubs only, no AWS)
|
||||
### Test the platform (offline, no AWS required)
|
||||
|
||||
```bash
|
||||
bash demo/scripts/run_demo.sh --no-upload
|
||||
# Install test dependencies
|
||||
pip install -r requirements-test.txt
|
||||
|
||||
# Run the test suite (all offline — uses moto for DynamoDB mocking)
|
||||
python3 -m pytest tests/ -v
|
||||
|
||||
# Run the platform in check-only mode (offline — no AWS, no Checkov, no outbox)
|
||||
# Uses the default sample contract (contracts/static-asset.yaml)
|
||||
bash scripts/run_platform.sh --check-only
|
||||
# Expected: "=== PLATFORM CHECK OK ==="
|
||||
|
||||
# Reproduce the full CI pipeline locally (lint → test → check-only)
|
||||
bash scripts/run_ci.sh
|
||||
# Expected: "=== CI PIPELINE OK ==="
|
||||
```
|
||||
|
||||
The demo deck is at [`demo/ACDL_DEMO.md`](demo/ACDL_DEMO.md). It runs
|
||||
entirely on local stubs — no AWS, no AI — and shows intent and safety
|
||||
behavior rather than provisioning real cloud resources.
|
||||
### CI/CD pipelines
|
||||
|
||||
The CI/CD pipeline is defined by a **central pipeline contract** — a
|
||||
declarative YAML instance (`pipelines/ci.yaml`) validated against a JSON
|
||||
Schema (`schemas/pipeline.schema.json`). Both forge workflows implement
|
||||
the same contract:
|
||||
|
||||
- `.gitea/workflows/ci.yml` — Gitea Actions (dev environment)
|
||||
- `.github/workflows/ci.yml` — GitHub Actions (production)
|
||||
|
||||
Both workflow files are **byte-identical** — the only difference is the
|
||||
forge runtime. Both run three stages: **lint** (py_compile), **test**
|
||||
(pytest), and **check-only** (`run_platform.sh --check-only`). Both
|
||||
trigger on push to `main` and on pull requests. A test
|
||||
(`tests/test_pipeline_contract.py`) validates that both workflows conform
|
||||
to the contract.
|
||||
|
||||
`scripts/run_ci.sh` mirrors the CI pipeline locally — running the same
|
||||
three stages in sequence. This makes the pipeline fully reproducible from
|
||||
the shell, not just in CI:
|
||||
|
||||
```bash
|
||||
bash scripts/run_ci.sh # run all 3 stages (lint, test, check-only)
|
||||
bash scripts/run_ci.sh --quiet # suppress per-stage banners
|
||||
```
|
||||
|
||||
### Reusable deploy workflow
|
||||
|
||||
The deployment pipeline is defined by a **central deployment pipeline
|
||||
contract** (`pipelines/deploy.yaml`, validated against
|
||||
`schemas/deploy-pipeline.schema.json`) and exposed to consumer repos as a
|
||||
**reusable workflow**:
|
||||
|
||||
- `.gitea/workflows/deploy.yml` — Gitea Actions (dev environment)
|
||||
- `.github/workflows/deploy.yml` — GitHub Actions (production)
|
||||
|
||||
Both files are **byte-identical** and implement the same stages as
|
||||
`pipelines/deploy.yaml` (validate-contract → resolve-stack →
|
||||
terraform-plan → checkov → confidence → apply). A consumer repo invokes
|
||||
the reusable workflow via a **versioned tag** (floating MAJOR + MINOR, e.g.
|
||||
`acdl/.gitea/workflows/deploy.yml@v1.4`). The workflow checks out the
|
||||
consumer repo, then checks out the ACDL platform repo into the runner
|
||||
workspace, and runs `scripts/run_platform.sh` against the consumer's
|
||||
contract — the consumer never clones the platform repo or invokes its
|
||||
scripts locally. See the [Consumer guide](docs/CONSUMER_GUIDE.md) for the
|
||||
end-to-end happy path.
|
||||
|
||||
### Output streaming (run_platform.sh)
|
||||
|
||||
`scripts/run_platform.sh` streams output by default so the user can see
|
||||
what the platform is doing:
|
||||
|
||||
- **`--check-only`**: streams the emitted Terraform file content to stdout
|
||||
- **`--plan-only`** and **full mode**: streams `terraform init`, `terraform
|
||||
validate`, and `terraform plan` output via `tee` (visible and logged)
|
||||
- **Full mode**: prints Checkov compliance results and each
|
||||
PolicyCheckResult record with severity, rule ID, and pass/fail status
|
||||
|
||||
A `--quiet` flag suppresses streaming (output to log files only) for
|
||||
backwards-compatible log-only mode.
|
||||
|
||||
## Consumer guide
|
||||
|
||||
A step-by-step guide for a consumer to create their pipeline and define a
|
||||
contract that deploys any ACDL module to AWS is at
|
||||
[`docs/CONSUMER_GUIDE.md`](docs/CONSUMER_GUIDE.md). The guide is generic
|
||||
across all L2 modules; `static-asset` is the worked example.
|
||||
|
||||
## Repository layout
|
||||
|
||||
| Path | Purpose | Status |
|
||||
|------|---------|--------|
|
||||
| `acdl_platform/` | Platform code: confidence signal, contract resolver, outbox writer, HITL/ledger/SoD designs (renamed from `platform/` in Phase 08 to avoid shadowing the stdlib `platform` module) | v1.1 complete; v1.2 extends |
|
||||
| `schemas/` | JSON Schemas: IR, PolicyCheckResult, contract (draft 2020-12) | v1.1 complete; v1.2 extends contract schema |
|
||||
| `adapters/` | Substrate adapters — Terraform adapter (the only substrate-specific code per §12) + Checkov policy adapter | v1.1 complete; v1.2 expands `TYPE_MAP` |
|
||||
| `terraform/` | State backend (S3 + DynamoDB) + spike TF (`terraform/spike/`) + bootstrap scripts (`terraform/bootstrap/`) | v1.1 complete; v1.2 adds ECS apply |
|
||||
| `modules-ir/` | IR-typed L1/L2 modules + `registry.json`. v1.1: `l1-s3`, `l2-static-asset`. v1.2: + 6 ECS L1s, `l2-microservice` | v1.1 complete; v1.2 expands |
|
||||
| `contracts/` | Sample contracts (`spike.yaml` for `l2-static-asset`) | v1.1 complete; v1.2 adds `microservice.yaml` |
|
||||
| `scripts/` | Verify scripts (`verify_phaseNN.sh`), platform run script (`run_platform.sh`; `--plan-only` for plan subset), key rotation | v1.1 complete; v1.2 consolidates |
|
||||
| `demo/` | Archived v1.0 executive demo (tag `v1.1.0`); runs locally via `demo/scripts/run_demo.sh --no-upload` | complete (archived) |
|
||||
| `acdl_platform/` | Platform code: contract resolver, confidence signal, outbox writer, separation of duties, HITL/ledger designs | active |
|
||||
| `schemas/` | JSON Schemas: stack, contract, PolicyCheckResult, pipeline contract, deploy pipeline contract (draft 2020-12) | active |
|
||||
| `pipelines/` | Central pipeline contracts: `ci.yaml` (CI), `deploy.yaml` (deployment) | active |
|
||||
| `adapters/` | Substrate adapters — Terraform adapter (the only substrate-specific code per §12) + Checkov policy adapter | active |
|
||||
| `terraform/` | State backend (S3 + DynamoDB) + platform TF (`terraform/spike/`) + bootstrap scripts (`terraform/bootstrap/`) | active |
|
||||
| `modules/` | L1/L2 modules + `registry.json`. L1: s3, vpc, ecs-cluster, ecs-service, iam-role, alb, ecr. L2: microservice, static-asset | active |
|
||||
| `contracts/` | Sample consumer contracts (e.g. `static-asset.yaml`) | active |
|
||||
| `scripts/` | Platform run script (`run_platform.sh` with `--check-only`/`--plan-only`/`--quiet`), CI pipeline script (`run_ci.sh`), key rotation | active |
|
||||
| `tests/` | Pytest suite (all offline — adapter, confidence signal, checkov adapter, outbox writer, pipeline contract, contract resolver, streaming) | active |
|
||||
| `.gitea/workflows/` | Gitea Actions workflows: `ci.yml` (CI), `deploy.yml` (reusable deploy, invoked by consumer repos) | active |
|
||||
| `.github/workflows/` | GitHub Actions workflows: `ci.yml` (CI), `deploy.yml` (reusable deploy, invoked by consumer repos) | active |
|
||||
| `.ciagent/` | CIAgent metadata (config, project, architecture, requirements, roadmap, personas, plans, research, verify, review, audit) | active |
|
||||
| `docs/` | Upstream vision + architecture sources (`vision.md`, `architecture.md`) | active |
|
||||
| `docs/` | Upstream vision + architecture sources (`vision.md`, `architecture.md`) + consumer guide | active |
|
||||
|
||||
## Environments
|
||||
|
||||
| Environment | Autonomy | Gate | Status |
|
||||
|---|---|---|---|
|
||||
| dev | Full autonomy (no HITL) | Confidence ≥ 0.50 | v1.1 spike (`plan`); v1.2 (`apply`) |
|
||||
| dev | Full autonomy (no HITL) | Confidence ≥ 0.50 | v1.1 (`plan`); v1.2 (`apply`) |
|
||||
| qa | Held for attestation | QA HITL + confidence ≥ 0.75 | v1.3+ |
|
||||
| prod | Held for attestation | SRE HITL + confidence ≥ 0.90 | v1.3+ |
|
||||
| dr | Held for attestation | SRE HITL + confidence ≥ 0.95 + dr-drill | v1.3+ |
|
||||
|
||||
**Staging does not exist** (Path A locked).
|
||||
|
||||
## Credentials
|
||||
## Credentials & zero-trust
|
||||
|
||||
**Long-lived AWS credentials are forbidden** (§12.5). The v1.1 spike uses a
|
||||
temporary long-lived key **once** to bootstrap (waiver D-034, now closed —
|
||||
the root key was deactivated by the user), then rotates the spike key
|
||||
per-run via `scripts/rotate_spike_key.sh` (waiver D-039, extended for v1.2
|
||||
as D-047). Real OIDC federation is deferred to v1.3+, blocked on
|
||||
[go-gitea/gitea#36988](https://github.com/go-gitea/gitea/pull/36988) (still
|
||||
open as of 2026-07-21).
|
||||
### Default — zero-trust OIDC + attribute-based authorization (the locked target)
|
||||
|
||||
Consumer GitHub/Gitea repos are **zero-trust**: they hold **no long-lived
|
||||
AWS keys** and no static credentials in repo secrets.
|
||||
|
||||
- **Authentication** is **OIDC federation** between the forge (GitHub or
|
||||
Gitea Actions) and AWS. Each job mints a short-lived STS token; no
|
||||
credential is ever stored in the consumer repo or in a forge secret.
|
||||
- **Authorization** is **attribute-based (ABAC)**, not role-based (RBAC).
|
||||
AWS IAM roles and session policies are scoped by two attribute classes:
|
||||
- **Repository identity** — the forge claim (e.g.
|
||||
`repo:org/consumer-repo:ref:refs/heads/main`) binds the role's trust
|
||||
policy to the exact consumer repo + branch that invoked the workflow.
|
||||
- **Resource-creation attributes** — every resource the pipeline creates
|
||||
is tagged with `acdl:owner=<consumer-repo>` and
|
||||
`acdl:contract=<contract-id>`. The session policy grants
|
||||
view/update/delete **only on resources whose tags match the calling
|
||||
repo**.
|
||||
|
||||
The effect: a consumer's pipeline can only view and update the resources
|
||||
it created. Blast radius is contained to that consumer's own stack
|
||||
instances — one consumer can never touch another consumer's resources,
|
||||
and the consumer cannot escape its own scope.
|
||||
|
||||
### Override — static key + managed daily rotation
|
||||
|
||||
Where OIDC is not yet available (Gitea Actions OIDC is blocked on
|
||||
[go-gitea/gitea#36988](https://github.com/go-gitea/gitea/pull/36988), still
|
||||
open as of 2026-07-21), a static AWS key **may** be used as a documented
|
||||
override:
|
||||
|
||||
- The key is stored in **GitHub Secrets** (consumer repo) for forge runs,
|
||||
or in **`.env.secrets`** (gitignored, chmod 600) for local testing.
|
||||
- The key is rotated by a **platform-managed scheduled pipeline on a daily
|
||||
cadence** — rotation is not the consumer's burden in the forge path.
|
||||
- **When `.env.secrets` is used locally**, rotating the key **out of band is
|
||||
the consumer's responsibility**. The platform guarantees daily rotation
|
||||
for forge runs; it does not guarantee rotation for locally-held copies.
|
||||
The consumer must rotate a local key via `scripts/rotate_spike_key.sh`
|
||||
(or equivalent) on their own cadence.
|
||||
|
||||
The current per-run-rotated-key flow (waivers D-039 / D-047) is the
|
||||
present-day instance of this override. The zero-trust OIDC + ABAC model
|
||||
above is the locked target; the override is time-boxed until the Gitea
|
||||
OIDC provider merges. `§12.5` forbids long-lived credentials; both the
|
||||
target and the override satisfy its *intent* (no *persistently* long-lived
|
||||
key — the forge key's useful lifetime is one workflow run, and the
|
||||
override is rotated at least daily).
|
||||
@@ -7,7 +7,7 @@ instinct is not a substitute.
|
||||
|
||||
Inputs (weights sum to 1.0, D-040):
|
||||
1. policy_results (0.30) — list[PolicyCheckResult] (schemas/policy_check_result.schema.json)
|
||||
2. validation (0.25) — {schema: bool, ir_resolved: bool, tf_validated: bool, tf_planned: bool}
|
||||
2. validation (0.25) — {schema: bool, stack_resolved: bool, tf_validated: bool, tf_planned: bool}
|
||||
3. freshness (0.10) — {age_days: float, max_age_days: float}
|
||||
4. source (0.15) — {submitter: str, commit_sha: str, signed: bool}
|
||||
5. history (0.10) — {prior_rollbacks: int, prior_policy_fails: int}
|
||||
@@ -83,7 +83,7 @@ def _per_input_score(name: str, raw: Any) -> tuple:
|
||||
scores.append(0.0)
|
||||
return sum(scores) / len(scores), []
|
||||
if name == "validation":
|
||||
keys = ("schema", "ir_resolved", "tf_validated", "tf_planned")
|
||||
keys = ("schema", "stack_resolved", "tf_validated", "tf_planned")
|
||||
if not isinstance(raw, dict):
|
||||
return 0.5, []
|
||||
trues = sum(1 for k in keys if raw.get(k))
|
||||
|
||||
+221
-215
@@ -1,34 +1,21 @@
|
||||
"""ACDL Contract Resolver — resolve a contract to a Target Stack IR instance.
|
||||
"""ACDL Contract Resolver — resolve a consumer contract to a Target Stack instance.
|
||||
|
||||
ARCHITECTURE.md §12.8: the contract declares intent in IR-typed terms;
|
||||
the resolver resolves the contract to a target stack (list of L1
|
||||
instances + inputs + relationships); the adapter compiles the target
|
||||
stack to a plan.
|
||||
The contract resolver is the bridge between the consumer's declared intent
|
||||
(a contract YAML) and the platform's executable representation (a Target
|
||||
Stack JSON instance). It:
|
||||
|
||||
Steps:
|
||||
1. Load the contract (YAML -> dict).
|
||||
2. Validate the contract against schemas/contract.schema.json.
|
||||
3. Look up the L2 in modules-ir/registry.json.
|
||||
4. Load the L2's composition.json (the thin-composition tree).
|
||||
5. Map the contract's inputs through the composition's wires to the
|
||||
child L1s' inputs. Two wire kinds:
|
||||
- passthrough: {target, input} (or an array of the same) -> the
|
||||
concrete contract value.
|
||||
- child->child: {target, input, source:"child:<id>.<output>"} ->
|
||||
a "ref:<ir_resource_id>.<output>" string (value known at apply
|
||||
time only).
|
||||
A wire value may be a single object or an array of objects (for
|
||||
contract inputs that fan out to multiple children); both forms are
|
||||
iterated.
|
||||
6. Emit an IR instance {version, stack:{name, kind:l2, depth},
|
||||
resources:[<L1 instances with concrete inputs>], relationships:[...]}.
|
||||
Multi-resource L1s (interface.json has a `resources` array) expand
|
||||
into one IR resource per entry, id `<child_id>-<type_suffix>` where
|
||||
type_suffix is the last IR-type segment with underscores stripped;
|
||||
single-resource L1s keep the child id verbatim.
|
||||
7. Validate the IR instance against schemas/ir.schema.json.
|
||||
1. Loads and validates the contract against schemas/contract.schema.json.
|
||||
2. Looks up the module name in modules/registry.json.
|
||||
3. If the module is an L1 primitive: builds a stack instance directly from
|
||||
the interface.json + contract inputs.
|
||||
4. If the module is an L2 composition: loads the composition.json, expands
|
||||
children to stack resources, resolves wires to ref: expressions, and
|
||||
emits the full stack instance.
|
||||
|
||||
CLI: contract_resolver.py <contract.yaml> <out_ir.json>
|
||||
The output is a JSON instance valid against schemas/stack.schema.json,
|
||||
ready for the Terraform adapter to compile.
|
||||
|
||||
CLI: contract_resolver.py <contract.yaml> <out.json>
|
||||
"""
|
||||
|
||||
import json
|
||||
@@ -39,218 +26,237 @@ import yaml
|
||||
import jsonschema
|
||||
|
||||
|
||||
REPO_ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
|
||||
|
||||
|
||||
def _load_json(path):
|
||||
with open(path, "r") as fh:
|
||||
return json.load(fh)
|
||||
|
||||
|
||||
def _iter_wire_targets(wire_value):
|
||||
"""Yield each target-spec from a wire value (single object or array)."""
|
||||
if isinstance(wire_value, list):
|
||||
for spec in wire_value:
|
||||
yield spec
|
||||
elif isinstance(wire_value, dict):
|
||||
yield wire_value
|
||||
def _load_yaml(path):
|
||||
with open(path, "r") as fh:
|
||||
return yaml.safe_load(fh)
|
||||
|
||||
|
||||
def _type_suffix(ir_type):
|
||||
"""Last segment of an IR type, underscores stripped (e.g. aws:ec2:vpc -> vpc,
|
||||
aws:elbv2:targetgroup -> targetgroup, aws:ecs:task_definition -> taskdefinition)."""
|
||||
return ir_type.rsplit(":", 1)[-1].replace("_", "")
|
||||
def _resolve_wire_value(wire, contract_inputs, child_outputs):
|
||||
"""Resolve a wire 'from' reference to a concrete value.
|
||||
|
||||
Wire 'from' can be:
|
||||
- "contract.inputs.<name>" — a contract input value
|
||||
- "<childId>.outputs.<name>" — a reference to another child's output
|
||||
|
||||
def _resolve_child_ref(source, child_id, l1_iface, child_ir_ids):
|
||||
"""Resolve a "child:<id>.<output>" source to "ref:<ir_resource_id>.<output>".
|
||||
|
||||
The ir_resource_id is the producing child's sub-resource that
|
||||
declares the output. For single-resource L1s that is the child id;
|
||||
for multi-resource L1s the L1's `resources` array is scanned for
|
||||
which sub-resource declares the output (exact match, then a
|
||||
singular->plural fallback so e.g. `subnet_ids` matches a per-resource
|
||||
`subnet_id`). The ref's output name is the per-resource output name
|
||||
when matched that way, else the source output name verbatim.
|
||||
Returns either a concrete value (string/number/boolean) or a
|
||||
"ref:<childId>.<outputName>" string for cross-child references.
|
||||
"""
|
||||
prefix = "child:"
|
||||
if not source.startswith(prefix):
|
||||
raise ValueError(f"unsupported wire source {source!r}")
|
||||
body = source[len(prefix):]
|
||||
src_child_id, src_output = body.split(".", 1)
|
||||
if src_child_id != child_id:
|
||||
# Cross-child reference: look up the producing child's first IR
|
||||
# resource id (the child->child wiring table is keyed by child id
|
||||
# by the caller; this branch is unused for v1.2's wires but kept
|
||||
# for completeness).
|
||||
ir_resource_id = child_ir_ids.get(src_child_id, src_child_id)
|
||||
return f"ref:{ir_resource_id}.{src_output}"
|
||||
# Same-child reference: find the producing sub-resource.
|
||||
resources = l1_iface.get("resources")
|
||||
if not resources:
|
||||
return f"ref:{child_id}.{src_output}"
|
||||
for idx, sub in enumerate(resources):
|
||||
sub_outputs = sub.get("outputs", [])
|
||||
if src_output in sub_outputs:
|
||||
ir_id = child_ir_ids[child_id][idx]
|
||||
return f"ref:{ir_id}.{src_output}"
|
||||
# Singular->plural fallback (subnet_ids -> subnet_id).
|
||||
singular = src_output[:-1] if src_output.endswith("s") else src_output
|
||||
for idx, sub in enumerate(resources):
|
||||
sub_outputs = sub.get("outputs", [])
|
||||
if singular in sub_outputs:
|
||||
ir_id = child_ir_ids[child_id][idx]
|
||||
return f"ref:{ir_id}.{singular}"
|
||||
# No per-resource match: point at the first sub-resource, keep the
|
||||
# source output name verbatim.
|
||||
ir_id = child_ir_ids[child_id][0]
|
||||
return f"ref:{ir_id}.{src_output}"
|
||||
from_expr = wire["from"]
|
||||
to_expr = wire["to"]
|
||||
|
||||
# If the 'from' is a contract input, use the concrete value
|
||||
if from_expr.startswith("contract.inputs."):
|
||||
input_name = from_expr[len("contract.inputs."):]
|
||||
if input_name in contract_inputs:
|
||||
return contract_inputs[input_name]
|
||||
# Check for default
|
||||
default = wire.get("default")
|
||||
if default is not None:
|
||||
return default
|
||||
return None
|
||||
|
||||
# If the 'from' is a child output, emit a ref: expression
|
||||
if "." in from_expr:
|
||||
parts = from_expr.split(".", 2)
|
||||
if len(parts) >= 3 and parts[1] == "outputs":
|
||||
child_id = parts[0]
|
||||
output_name = parts[2]
|
||||
return f"ref:{child_id}.{output_name}"
|
||||
|
||||
return None
|
||||
|
||||
|
||||
def resolve_l1(contract, registry, repo_root):
|
||||
"""Resolve a contract referencing an L1 primitive to a stack instance."""
|
||||
module_name = contract["module"]
|
||||
module_ref = f"{module_name}@1.0.0"
|
||||
inputs = contract.get("inputs", {})
|
||||
environment = contract.get("environment", "dev")
|
||||
|
||||
# Load the interface
|
||||
entry = registry[module_name]["1.0.0"]
|
||||
iface_path = os.path.join(repo_root, entry["interface"])
|
||||
iface = _load_json(iface_path)
|
||||
|
||||
# Build the stack instance
|
||||
stack_instance = {
|
||||
"version": "1.0.0",
|
||||
"stack": {
|
||||
"name": module_name,
|
||||
"kind": "l1",
|
||||
"depth": 1,
|
||||
},
|
||||
"resources": [
|
||||
{
|
||||
"id": iface.get("type", module_name).split(":")[-1]
|
||||
if ":" in iface.get("type", "") else module_name,
|
||||
"type": iface["type"],
|
||||
"module": module_ref,
|
||||
"inputs": dict(inputs),
|
||||
"outputs": {
|
||||
out_name: {"type": out_spec.get("type", "string")}
|
||||
for out_name, out_spec in iface.get("outputs", {}).items()
|
||||
},
|
||||
}
|
||||
],
|
||||
}
|
||||
|
||||
# Add NFRs if present in the interface
|
||||
nfrs = iface.get("nfrs", {})
|
||||
if nfrs:
|
||||
stack_instance["resources"][0]["nfrs"] = nfrs
|
||||
|
||||
return stack_instance
|
||||
|
||||
|
||||
def resolve_l2(contract, registry, repo_root):
|
||||
"""Resolve a contract referencing an L2 composition to a stack instance."""
|
||||
module_name = contract["module"]
|
||||
inputs = contract.get("inputs", {})
|
||||
|
||||
# Load the composition
|
||||
entry = registry[module_name]["1.0.0"]
|
||||
comp_path = os.path.join(repo_root, entry["interface"])
|
||||
composition = _load_json(comp_path)
|
||||
|
||||
# Track child outputs for wire resolution
|
||||
child_outputs = {}
|
||||
resources = []
|
||||
|
||||
# Expand children to resources
|
||||
for child in composition["children"]:
|
||||
child_id = child["id"]
|
||||
child_module = child["module"]
|
||||
child_name = child_module.split("@")[0]
|
||||
|
||||
# Load the child's interface to get type and outputs
|
||||
child_entry = registry[child_name]["1.0.0"]
|
||||
child_iface_path = os.path.join(repo_root, child_entry["interface"])
|
||||
child_iface = _load_json(child_iface_path)
|
||||
|
||||
# For multi-resource L1s (like vpc), the first resource type is the
|
||||
# primary; the adapter handles expansion. Use the interface's type
|
||||
# or the first resource in the interface's resources array.
|
||||
if "resources" in child_iface and child_iface["resources"]:
|
||||
# Multi-resource L1: create one resource per sub-resource
|
||||
for sub_res in child_iface["resources"]:
|
||||
resource = {
|
||||
"id": f"{child_id}-{sub_res['type'].split(':')[-1].replace('_', '-')}"
|
||||
if len(child_iface["resources"]) > 1 else child_id,
|
||||
"type": sub_res["type"],
|
||||
"module": child_module,
|
||||
"inputs": {},
|
||||
"outputs": {
|
||||
out: {"type": "string"}
|
||||
for out in sub_res.get("outputs", [])
|
||||
},
|
||||
}
|
||||
resources.append(resource)
|
||||
else:
|
||||
# Single-resource L1
|
||||
resource = {
|
||||
"id": child_id,
|
||||
"type": child_iface["type"],
|
||||
"module": child_module,
|
||||
"inputs": {},
|
||||
"outputs": {
|
||||
out_name: {"type": out_spec.get("type", "string")}
|
||||
for out_name, out_spec in child_iface.get("outputs", {}).items()
|
||||
},
|
||||
}
|
||||
resources.append(resource)
|
||||
|
||||
# Track outputs for this child
|
||||
child_outputs[child_id] = child_iface.get("outputs", {})
|
||||
|
||||
# Resolve wires to populate inputs
|
||||
for wire in composition.get("wires", []):
|
||||
to_expr = wire["to"]
|
||||
# Parse "to": "<childId>.inputs.<inputName>"
|
||||
to_parts = to_expr.split(".")
|
||||
if len(to_parts) != 3 or to_parts[1] != "inputs":
|
||||
continue
|
||||
target_child = to_parts[0]
|
||||
input_name = to_parts[2]
|
||||
|
||||
value = _resolve_wire_value(wire, inputs, child_outputs)
|
||||
if value is not None:
|
||||
# Find the target resource and set the input
|
||||
for res in resources:
|
||||
if res["id"] == target_child or res["id"].startswith(f"{target_child}-"):
|
||||
res["inputs"][input_name] = value
|
||||
break
|
||||
|
||||
# Build the stack instance
|
||||
stack_instance = {
|
||||
"version": "1.0.0",
|
||||
"stack": {
|
||||
"name": module_name,
|
||||
"kind": "l2",
|
||||
"depth": composition.get("depth", 1),
|
||||
},
|
||||
"resources": resources,
|
||||
}
|
||||
|
||||
return stack_instance
|
||||
|
||||
|
||||
def resolve(contract_path, repo_root=None):
|
||||
"""Resolve a contract YAML to an IR instance dict."""
|
||||
rr = repo_root or REPO_ROOT
|
||||
"""Resolve a consumer contract to a Target Stack instance.
|
||||
|
||||
# 1. Load the contract YAML.
|
||||
with open(contract_path, "r") as fh:
|
||||
contract = yaml.safe_load(fh)
|
||||
Args:
|
||||
contract_path: Path to the contract YAML file.
|
||||
repo_root: Root of the ACDL repo (defaults to two levels up from this file).
|
||||
|
||||
# 2. Validate the contract against the contract schema.
|
||||
contract_schema = _load_json(os.path.join(rr, "schemas/contract.schema.json"))
|
||||
Returns:
|
||||
A dict representing the Target Stack instance.
|
||||
"""
|
||||
if repo_root is None:
|
||||
repo_root = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
|
||||
|
||||
# Load contract
|
||||
contract = _load_yaml(contract_path)
|
||||
|
||||
# Load schemas
|
||||
contract_schema = _load_json(os.path.join(repo_root, "schemas", "contract.schema.json"))
|
||||
|
||||
# Validate contract against schema
|
||||
jsonschema.validate(contract, contract_schema)
|
||||
|
||||
# 3. Look up the L2 in the registry.
|
||||
stack_name = contract["stack"]
|
||||
registry = _load_json(os.path.join(rr, "modules-ir/registry.json"))
|
||||
if stack_name not in registry:
|
||||
raise ValueError(f"stack {stack_name!r} not in registry")
|
||||
versions = registry[stack_name]
|
||||
# Pick the highest 1.x.x (spike: just take the first non-deprecated).
|
||||
entry = next(v for v in versions.values() if not v.get("deprecated", False))
|
||||
# Load registry
|
||||
registry = _load_json(os.path.join(repo_root, "modules", "registry.json"))
|
||||
|
||||
# 4. Load the L2's composition.json.
|
||||
composition_key = entry.get("composition") or entry.get("interface")
|
||||
composition = _load_json(os.path.join(rr, composition_key))
|
||||
module_name = contract["module"]
|
||||
if module_name not in registry:
|
||||
raise ValueError(f"module '{module_name}' not found in registry")
|
||||
|
||||
# 5. Map the contract's inputs through the wires to the child L1s' inputs.
|
||||
wires = composition.get("wires", {})
|
||||
contract_inputs = contract.get("inputs", {})
|
||||
children = composition.get("children", [])
|
||||
# Determine if L1 or L2
|
||||
entry = registry[module_name]["1.0.0"]
|
||||
interface_path = entry["interface"]
|
||||
is_l2 = "l2" in interface_path or "composition" in interface_path
|
||||
|
||||
# Pre-load every child's L1 interface + compute IR resource ids.
|
||||
child_ifaces = {}
|
||||
child_ir_ids = {}
|
||||
for child in children:
|
||||
child_id = child["id"]
|
||||
child_module = child["module"]
|
||||
l1_name, l1_version = child_module.split("@", 1)
|
||||
l1_entry = registry.get(l1_name, {}).get(l1_version)
|
||||
if not l1_entry:
|
||||
raise ValueError(f"L1 {child_module!r} not in registry")
|
||||
l1_iface = _load_json(os.path.join(rr, l1_entry["interface"]))
|
||||
child_ifaces[child_id] = l1_iface
|
||||
sub_resources = l1_iface.get("resources")
|
||||
if sub_resources:
|
||||
child_ir_ids[child_id] = [
|
||||
f"{child_id}-{_type_suffix(sub['type'])}" for sub in sub_resources
|
||||
]
|
||||
else:
|
||||
child_ir_ids[child_id] = [child_id]
|
||||
if is_l2:
|
||||
stack_instance = resolve_l2(contract, registry, repo_root)
|
||||
else:
|
||||
stack_instance = resolve_l1(contract, registry, repo_root)
|
||||
|
||||
# Build each child's mapped inputs (concrete values + ref strings).
|
||||
child_inputs_map = {child["id"]: {} for child in children}
|
||||
for wire_name, wire_value in wires.items():
|
||||
for spec in _iter_wire_targets(wire_value):
|
||||
target = spec.get("target")
|
||||
if target not in child_inputs_map:
|
||||
continue
|
||||
input_name = spec["input"]
|
||||
source = spec.get("source")
|
||||
if source:
|
||||
# Child->child reference: emit a ref string.
|
||||
src_child_id = source[len("child:"):].split(".", 1)[0]
|
||||
child_inputs_map[target][input_name] = _resolve_child_ref(
|
||||
source, src_child_id, child_ifaces[src_child_id], child_ir_ids
|
||||
)
|
||||
else:
|
||||
# Contract->child passthrough.
|
||||
if wire_name in contract_inputs:
|
||||
child_inputs_map[target][input_name] = contract_inputs[wire_name]
|
||||
# Validate against stack schema
|
||||
stack_schema = _load_json(os.path.join(repo_root, "schemas", "stack.schema.json"))
|
||||
jsonschema.validate(stack_instance, stack_schema)
|
||||
|
||||
# 6. Emit the IR instance.
|
||||
resources = []
|
||||
relationships = []
|
||||
for child in children:
|
||||
child_id = child["id"]
|
||||
child_module = child["module"]
|
||||
l1_iface = child_ifaces[child_id]
|
||||
l1_outputs = l1_iface.get("outputs", {})
|
||||
child_inputs = child_inputs_map[child_id]
|
||||
sub_resources = l1_iface.get("resources")
|
||||
ir_ids = child_ir_ids[child_id]
|
||||
if sub_resources:
|
||||
for idx, sub in enumerate(sub_resources):
|
||||
ir_id = ir_ids[idx]
|
||||
sub_in_names = sub.get("inputs", [])
|
||||
sub_out_names = sub.get("outputs", [])
|
||||
sub_inputs = {
|
||||
n: child_inputs[n] for n in sub_in_names if n in child_inputs
|
||||
}
|
||||
sub_outputs = {
|
||||
n: l1_outputs[n] for n in sub_out_names if n in l1_outputs
|
||||
}
|
||||
resources.append({
|
||||
"id": ir_id,
|
||||
"type": sub["type"],
|
||||
"module": child_module,
|
||||
"inputs": sub_inputs,
|
||||
"outputs": sub_outputs,
|
||||
})
|
||||
relationships.append({"from": "root", "to": ir_id, "kind": "parent"})
|
||||
# Resolve intra-L1 refs (refs between sub-resources of the same L1).
|
||||
intra_refs = l1_iface.get("intra_refs", [])
|
||||
for iref in intra_refs:
|
||||
from_type, from_input = iref["from"].split(".", 1)
|
||||
to_type, to_output = iref["to"].split(".", 1)
|
||||
from_ir_id = next((ir_ids[i] for i, s in enumerate(sub_resources) if s["type"] == from_type), None)
|
||||
to_ir_id = next((ir_ids[i] for i, s in enumerate(sub_resources) if s["type"] == to_type), None)
|
||||
if from_ir_id and to_ir_id:
|
||||
for r in resources:
|
||||
if r["id"] == from_ir_id:
|
||||
r["inputs"][from_input] = f"ref:{to_ir_id}.{to_output}"
|
||||
else:
|
||||
resources.append({
|
||||
"id": child_id,
|
||||
"type": l1_iface["type"],
|
||||
"module": child_module,
|
||||
"inputs": child_inputs,
|
||||
"outputs": l1_outputs,
|
||||
})
|
||||
relationships.append({"from": "root", "to": child_id, "kind": "parent"})
|
||||
|
||||
ir_instance = {
|
||||
"version": "1.0.0",
|
||||
"stack": {
|
||||
"name": composition["name"],
|
||||
"kind": composition["kind"],
|
||||
"depth": composition["depth"],
|
||||
},
|
||||
"resources": resources,
|
||||
"relationships": relationships,
|
||||
}
|
||||
|
||||
# 7. Validate the IR instance against the IR schema.
|
||||
ir_schema = _load_json(os.path.join(rr, "schemas/ir.schema.json"))
|
||||
jsonschema.validate(ir_instance, ir_schema)
|
||||
|
||||
return ir_instance
|
||||
return stack_instance
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
if len(sys.argv) != 3:
|
||||
print("usage: contract_resolver.py <contract.yaml> <out_ir.json>", file=sys.stderr)
|
||||
print("usage: contract_resolver.py <contract.yaml> <out.json>", file=sys.stderr)
|
||||
sys.exit(2)
|
||||
ir = resolve(sys.argv[1])
|
||||
result = resolve(sys.argv[1])
|
||||
with open(sys.argv[2], "w") as fh:
|
||||
json.dump(ir, fh, indent=2)
|
||||
print(f"resolver: emitted IR to {sys.argv[2]}", file=sys.stderr)
|
||||
json.dump(result, fh, indent=2)
|
||||
print(f"resolver: resolved {sys.argv[1]} -> {sys.argv[2]}", file=sys.stderr)
|
||||
@@ -1,19 +1,19 @@
|
||||
"""ACDL Terraform adapter — compile a Target Stack IR instance to Terraform.
|
||||
"""ACDL Terraform adapter — compile a Target Stack instance to Terraform.
|
||||
|
||||
ARCHITECTURE.md §12.2: the adapter translates the IR-typed L1 interface
|
||||
to a Terraform variable/output block, the L2 thin-composition tree to a
|
||||
root module that calls the L1 modules, the IR-typed relationships to
|
||||
Terraform module references, and emits a Terraform plan from the IR.
|
||||
ARCHITECTURE.md §12.2: the adapter translates the stack-typed L1 interface
|
||||
to a Terraform variable/output block, the L2 composition tree to a
|
||||
root module that calls the L1 modules, the stack-typed relationships to
|
||||
Terraform module references, and emits a Terraform plan from the stack.
|
||||
|
||||
The adapter is a THIN LAYER; it does not own L1/L2 content — it only
|
||||
translates. Substrate-agnostic in, Terraform out.
|
||||
|
||||
Phase 09 spike: handled one L1 (l1-s3, IR type aws:s3:bucket).
|
||||
Phase 09 spike: handled one L1 (s3, stack type aws:s3:bucket).
|
||||
Phase 13: generalized the resource/output emission via TYPE_MAP +
|
||||
INPUT_MAP + OUTPUT_MAP tables; added ECS Fargate IR types. S3 behavior
|
||||
is preserved (regression baseline: modules-ir/l1/l1-s3/spike_instance.json).
|
||||
INPUT_MAP + OUTPUT_MAP tables; added ECS Fargate stack types. S3 behavior
|
||||
is preserved (regression baseline: modules/l1/s3/instance.json).
|
||||
|
||||
CLI: adapter.py <ir_instance.json> <out_dir>
|
||||
CLI: adapter.py <instance.json> <out_dir>
|
||||
"""
|
||||
|
||||
import json
|
||||
@@ -21,8 +21,8 @@ import os
|
||||
import sys
|
||||
|
||||
|
||||
# IR type -> Terraform resource type. The only substrate-specific table.
|
||||
# As more L1s land, this grows; the L1 content + IR do not change.
|
||||
# Stack type -> Terraform resource type. The only substrate-specific table.
|
||||
# As more L1s land, this grows; the L1 content + stack do not change.
|
||||
TYPE_MAP = {
|
||||
"aws:s3:bucket": "aws_s3_bucket",
|
||||
"aws:ec2:vpc": "aws_vpc",
|
||||
@@ -38,8 +38,8 @@ TYPE_MAP = {
|
||||
"aws:ecr:repository": "aws_ecr_repository",
|
||||
}
|
||||
|
||||
# IR input name -> Terraform arg name, per IR type. Only non-identity
|
||||
# mappings are listed; any input not present here uses the IR name as
|
||||
# Stack input name -> Terraform arg name, per stack type. Only non-identity
|
||||
# mappings are listed; any input not present here uses the stack name as
|
||||
# the Terraform arg name (identity).
|
||||
INPUT_MAP = {
|
||||
"aws:s3:bucket": {"bucket_name": "bucket"},
|
||||
@@ -56,9 +56,9 @@ INPUT_MAP = {
|
||||
"aws:ecr:repository": {},
|
||||
}
|
||||
|
||||
# IR output name -> Terraform attribute name, per IR type. Only
|
||||
# Stack output name -> Terraform attribute name, per stack type. Only
|
||||
# non-identity mappings are listed; any output not present here uses the
|
||||
# IR name as the Terraform attribute name (identity).
|
||||
# stack name as the Terraform attribute name (identity).
|
||||
OUTPUT_MAP = {
|
||||
"aws:s3:bucket": {"bucket_arn": "arn", "bucket_name": "id"},
|
||||
"aws:ec2:vpc": {"vpc_id": "id"},
|
||||
@@ -101,24 +101,24 @@ def _tf_value(value):
|
||||
|
||||
|
||||
def _ref_expr(ref_value, type_by_id):
|
||||
"""Translate a "ref:<ir_resource_id>.<output>" string to a Terraform
|
||||
"""Translate a "ref:<stack_resource_id>.<output>" string to a Terraform
|
||||
interpolation "${<tf_type>.<id>.<attr>}".
|
||||
|
||||
<ir_resource_id> is the IR resource id of the producing resource;
|
||||
<stack_resource_id> is the stack resource id of the producing resource;
|
||||
<output> is the per-resource output name (e.g. `subnet_id`,
|
||||
`cluster_arn`); the attribute is mapped through OUTPUT_MAP for the
|
||||
referenced resource's IR type. The resolver emits the ref using the
|
||||
IR resource id directly (not the child id), so no child->resource
|
||||
referenced resource's stack type. The resolver emits the ref using the
|
||||
stack resource id directly (not the child id), so no child->resource
|
||||
lookup table is needed here.
|
||||
"""
|
||||
body = ref_value[len("ref:"):]
|
||||
rid, out_name = body.split(".", 1)
|
||||
rtype = type_by_id.get(rid)
|
||||
if not rtype:
|
||||
raise ValueError(f"ref to unknown IR resource id {rid!r}")
|
||||
raise ValueError(f"ref to unknown stack resource id {rid!r}")
|
||||
tf_type = TYPE_MAP.get(rtype)
|
||||
if not tf_type:
|
||||
raise ValueError(f"ref target {rid!r} has unknown IR type {rtype!r}")
|
||||
raise ValueError(f"ref target {rid!r} has unknown stack type {rtype!r}")
|
||||
out_map = OUTPUT_MAP.get(rtype, {})
|
||||
tf_attr = out_map.get(out_name, out_name)
|
||||
return f"{tf_type}.{rid}.{tf_attr}"
|
||||
@@ -139,7 +139,7 @@ def _emit_resource(resource, type_by_id=None):
|
||||
rid = resource["id"]
|
||||
tf_type = TYPE_MAP.get(rtype)
|
||||
if not tf_type:
|
||||
raise ValueError(f"unknown IR type {rtype!r} (adapter TYPE_MAP has no entry)")
|
||||
raise ValueError(f"unknown stack type {rtype!r} (adapter TYPE_MAP has no entry)")
|
||||
in_map = INPUT_MAP.get(rtype, {})
|
||||
body = []
|
||||
inputs = resource.get("inputs", {})
|
||||
@@ -306,11 +306,11 @@ def _emit_output(output_name, value_expr):
|
||||
return f'output "{output_name}" {{\n value = {value_expr}\n}}\n'
|
||||
|
||||
|
||||
def adapt(ir_instance, out_dir):
|
||||
"""Emit main.tf + terraform.tf + providers.tf to out_dir for the IR instance."""
|
||||
def adapt(stack_instance, out_dir):
|
||||
"""Emit main.tf + terraform.tf + providers.tf to out_dir for the stack instance."""
|
||||
os.makedirs(out_dir, exist_ok=True)
|
||||
stack = ir_instance["stack"]
|
||||
resources = ir_instance["resources"]
|
||||
stack = stack_instance["stack"]
|
||||
resources = stack_instance["resources"]
|
||||
|
||||
# --- providers.tf: aws provider, region from the first resource's inputs.region ---
|
||||
region = "us-east-1"
|
||||
@@ -345,9 +345,9 @@ def adapt(ir_instance, out_dir):
|
||||
)
|
||||
|
||||
# --- main.tf: resources + outputs ---
|
||||
# Build an IR-resource-id -> IR-type table so `ref:` input values can
|
||||
# Build a stack-resource-id -> stack-type table so `ref:` input values can
|
||||
# be resolved to Terraform interpolations without a child->resource
|
||||
# lookup (the resolver emits refs with the IR resource id directly).
|
||||
# lookup (the resolver emits refs with the stack resource id directly).
|
||||
type_by_id = {r["id"]: r["type"] for r in resources}
|
||||
main_tf_parts = []
|
||||
has_vpc = any(r["type"] == "aws:ec2:vpc" for r in resources)
|
||||
@@ -376,9 +376,9 @@ def adapt(ir_instance, out_dir):
|
||||
|
||||
if __name__ == "__main__":
|
||||
if len(sys.argv) != 3:
|
||||
print("usage: adapter.py <ir_instance.json> <out_dir>", file=sys.stderr)
|
||||
print("usage: adapter.py <instance.json> <out_dir>", file=sys.stderr)
|
||||
sys.exit(2)
|
||||
with open(sys.argv[1], "r") as fh:
|
||||
ir = json.load(fh)
|
||||
adapt(ir, sys.argv[2])
|
||||
stack = json.load(fh)
|
||||
adapt(stack, sys.argv[2])
|
||||
print(f"adapter: emitted terraform to {sys.argv[2]}", file=sys.stderr)
|
||||
@@ -2,7 +2,7 @@
|
||||
|
||||
A basic HTTP microservice for the ACDL v1.2 milestone. Returns 200 on `/`
|
||||
and `/health` with a JSON status body. Deployed to AWS ECS Fargate via the
|
||||
ACDL platform's `l2-microservice` contract.
|
||||
ACDL platform's `microservice` contract.
|
||||
|
||||
## Build + push to ECR
|
||||
|
||||
|
||||
@@ -2,7 +2,7 @@
|
||||
|
||||
This is the reference consumer microservice for the v1.2 milestone. It's
|
||||
intentionally minimal: stdlib only, no framework, no dependencies. The
|
||||
platform deploys it to ECS Fargate via the l2-microservice contract.
|
||||
platform deploys it to ECS Fargate via the microservice contract.
|
||||
"""
|
||||
import json
|
||||
import os
|
||||
|
||||
@@ -1,13 +0,0 @@
|
||||
stack: l2-microservice
|
||||
environment: dev
|
||||
inputs:
|
||||
name: acdl-microservice
|
||||
cidr: "10.0.0.0/16"
|
||||
azs: "us-east-1a,us-east-1b"
|
||||
image: "581513795199.dkr.ecr.us-east-1.amazonaws.com/acdl-microservice:latest"
|
||||
port: 8080
|
||||
cpu: 256
|
||||
memory: 512
|
||||
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"
|
||||
@@ -1,5 +0,0 @@
|
||||
stack: l2-static-asset
|
||||
environment: dev
|
||||
inputs:
|
||||
bucket_name: acdl-spike-bucket
|
||||
region: us-east-1
|
||||
@@ -0,0 +1,17 @@
|
||||
# ACDL sample consumer contract — static-asset module (dev)
|
||||
#
|
||||
# This is the reference example for a consumer contract. It declares:
|
||||
# uses: the central ACDL deployment pipeline to reference
|
||||
# module: which module to deploy (must match a registry key)
|
||||
# environment: which environment to deploy to (dev = autonomous)
|
||||
# inputs: module-specific inputs
|
||||
#
|
||||
# Validated against schemas/contract.schema.json.
|
||||
# Resolved by acdl_platform/contract_resolver.py to a Target Stack instance.
|
||||
|
||||
uses: acdl/pipelines/deploy.yaml@v1.4
|
||||
module: static-asset
|
||||
environment: dev
|
||||
inputs:
|
||||
bucket_name: acdl-spike-bucket
|
||||
region: us-east-1
|
||||
@@ -1,153 +0,0 @@
|
||||
# ACDL pipeline workflow (Phase 04 implementation).
|
||||
#
|
||||
# 3-dispatch approval-gate topology (D-027 / D-028; ARCHITECTURE.md
|
||||
# "Phase 04 pipeline topology"):
|
||||
#
|
||||
# Dispatch 1 (initial): approve_qa=false, approve_prod=false
|
||||
# -> runs the `dev` job (policy check, confidence
|
||||
# gate, mock_executor, evidence + finalize).
|
||||
# Dispatch 2 (QA approve): approve_qa=true, approve_prod=false
|
||||
# -> runs the `qa-gate` job (records QA approval
|
||||
# in the audit chain via evidence_writer +
|
||||
# finalize_evidence).
|
||||
# Dispatch 3 (Prod approve): approve_prod=true
|
||||
# -> runs the `prod-gate` job, then the `finalize`
|
||||
# job (needs: prod-gate) which writes the final
|
||||
# evidence event and commits audit.json to
|
||||
# acdl-evidence.
|
||||
#
|
||||
# Gitea Actions limitations driving this design:
|
||||
# - No `repository_dispatch` trigger (D-014).
|
||||
# - No environments API / `environment:` blocks are ignored (D-013).
|
||||
# - Re-dispatch starts a NEW run; artifacts do NOT survive between runs,
|
||||
# so state is persisted to acdl-evidence via the file-contents API
|
||||
# (D-028 / finalize_evidence.py) instead of via artifacts.
|
||||
#
|
||||
# Branch-pin rule (ARCHITECTURE.md "Branch pinning rule"):
|
||||
# This workflow lives on `acdl`'s default branch `milestone/v1.0-initial`.
|
||||
# Cross-repo `uses:` references (e.g. the issue-trigger's checkout of
|
||||
# l3b_agent_stub.py) MUST pin to `@milestone/v1.0-initial`, NOT `@main`
|
||||
# (the `acdl` repo has no `main` branch). This workflow is invoked via
|
||||
# the workflow_dispatch API (D-014), NOT via `workflow_call`, so the
|
||||
# `uses:` rule applies to the issue-trigger's checkout of the acdl repo,
|
||||
# not to this file itself.
|
||||
name: acdl-pipeline
|
||||
|
||||
"on":
|
||||
workflow_dispatch:
|
||||
inputs:
|
||||
contract-ref:
|
||||
description: "Ref on acdl-contracts that carries the contract"
|
||||
required: false
|
||||
type: string
|
||||
default: main
|
||||
approve_qa:
|
||||
description: "Human approval to advance past QA"
|
||||
required: false
|
||||
type: boolean
|
||||
default: false
|
||||
approve_prod:
|
||||
description: "Human approval to advance past Prod"
|
||||
required: false
|
||||
type: boolean
|
||||
default: false
|
||||
|
||||
jobs:
|
||||
dev:
|
||||
name: "Dev (autonomous)"
|
||||
if: inputs.approve_qa != true && inputs.approve_prod != true
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- name: "Checkout acdl (this repo, pinned to milestone/v1.0-initial)"
|
||||
uses: actions/checkout@v4
|
||||
with:
|
||||
ref: milestone/v1.0-initial
|
||||
|
||||
- name: "Checkout acdl-contracts at contract-ref"
|
||||
uses: actions/checkout@v4
|
||||
with:
|
||||
repository: continuous-intelligence/acdl-contracts
|
||||
ref: ${{ inputs.contract-ref }}
|
||||
token: ${{ secrets.GITEA_TOKEN }}
|
||||
path: acdl-contracts
|
||||
|
||||
- name: "Policy check"
|
||||
run: |
|
||||
python3 scripts/policy_checker.py acdl-contracts/contract.yaml
|
||||
|
||||
- name: "Confidence signal"
|
||||
id: confidence
|
||||
run: |
|
||||
set +e
|
||||
SCORE_JSON=$(python3 scripts/confidence_signal.py acdl-contracts/contract.yaml)
|
||||
echo "$SCORE_JSON"
|
||||
echo "score_json=$SCORE_JSON" >> "$GITHUB_OUTPUT"
|
||||
|
||||
- name: "Apply or reject based on confidence (gate < 0.50)"
|
||||
run: |
|
||||
set +e
|
||||
SCORE=$(python3 -c "import json,sys; print(json.load(sys.stdin)['score'])" <<< '${{ steps.confidence.outputs.score_json }}')
|
||||
python3 -c "import sys; sys.exit(0 if float('${SCORE}') >= 0.50 else 1)"
|
||||
THRESHOLD_RC=$?
|
||||
if [ "$THRESHOLD_RC" -ne 0 ]; then
|
||||
python3 scripts/evidence_writer.py --stage dev --event "dev rejected: confidence < 0.50" --audit audit.json
|
||||
python3 scripts/finalize_evidence.py --audit audit.json
|
||||
exit 1
|
||||
fi
|
||||
STACK=$(python3 -c 'import yaml; print(yaml.safe_load(open("acdl-contracts/contract.yaml"))["stack"])')
|
||||
bash scripts/mock_executor.sh acdl-contracts/contract.yaml
|
||||
python3 scripts/evidence_writer.py --stage dev --event "dev applied: ${STACK}" --audit audit.json
|
||||
python3 scripts/finalize_evidence.py --audit audit.json
|
||||
|
||||
- name: "Upload dev state artifacts (best-effort)"
|
||||
uses: actions/upload-artifact@v3
|
||||
with:
|
||||
name: dev-state
|
||||
path: |
|
||||
audit.json
|
||||
state.json
|
||||
|
||||
qa-gate:
|
||||
name: "QA (manual approval)"
|
||||
if: inputs.approve_qa == true && inputs.approve_prod != true
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- name: "Checkout acdl (this repo, pinned to milestone/v1.0-initial)"
|
||||
uses: actions/checkout@v4
|
||||
with:
|
||||
ref: milestone/v1.0-initial
|
||||
|
||||
- name: "Record QA approval in evidence"
|
||||
run: |
|
||||
python3 scripts/evidence_writer.py --stage qa --event "qa approved" --audit audit.json
|
||||
python3 scripts/finalize_evidence.py --audit audit.json
|
||||
|
||||
prod-gate:
|
||||
name: "Prod (manual approval)"
|
||||
if: inputs.approve_prod == true
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- name: "Checkout acdl (this repo, pinned to milestone/v1.0-initial)"
|
||||
uses: actions/checkout@v4
|
||||
with:
|
||||
ref: milestone/v1.0-initial
|
||||
|
||||
- name: "Record Prod approval in evidence"
|
||||
run: |
|
||||
python3 scripts/evidence_writer.py --stage prod --event "prod approved" --audit audit.json
|
||||
python3 scripts/finalize_evidence.py --audit audit.json
|
||||
|
||||
finalize:
|
||||
name: "Finalize (publish evidence)"
|
||||
needs: [prod-gate]
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- name: "Checkout acdl (this repo, pinned to milestone/v1.0-initial)"
|
||||
uses: actions/checkout@v4
|
||||
with:
|
||||
ref: milestone/v1.0-initial
|
||||
|
||||
- name: "Write finalize event + commit audit.json to acdl-evidence"
|
||||
run: |
|
||||
python3 scripts/evidence_writer.py --stage finalize --event "pipeline complete: audit.json committed to acdl-evidence" --audit audit.json
|
||||
python3 scripts/finalize_evidence.py --audit audit.json
|
||||
@@ -1,368 +0,0 @@
|
||||
---
|
||||
marp: true
|
||||
theme: default
|
||||
paginate: true
|
||||
size: 16:9
|
||||
header: 'ACDL · Agentic Cloud Delivery Platform'
|
||||
footer: 'Executive Demo · v1.0'
|
||||
style: |
|
||||
/* S&P Global-inspired palette */
|
||||
:root {
|
||||
--sp-red: #C8102E;
|
||||
--sp-red-dark: #8E0B20;
|
||||
--sp-ink: #1A1A1A;
|
||||
--sp-slate: #4A4A4A;
|
||||
--sp-gray: #6E6E6E;
|
||||
--sp-line: #D6D6D6;
|
||||
--sp-bg: #FFFFFF;
|
||||
--sp-tint: #F4F4F4;
|
||||
}
|
||||
section {
|
||||
font-size: 24px;
|
||||
color: var(--sp-ink);
|
||||
background: var(--sp-bg);
|
||||
font-family: 'Helvetica Neue', Helvetica, Arial, sans-serif;
|
||||
padding: 50px 60px;
|
||||
}
|
||||
section.title {
|
||||
text-align: center;
|
||||
background: var(--sp-red);
|
||||
color: #FFFFFF;
|
||||
display: flex;
|
||||
flex-direction: column;
|
||||
justify-content: center;
|
||||
}
|
||||
section.title h1 {
|
||||
color: #FFFFFF;
|
||||
font-size: 64px;
|
||||
margin-bottom: 0;
|
||||
border: none;
|
||||
}
|
||||
section.title h2 {
|
||||
color: #FFFFFF;
|
||||
border: none;
|
||||
font-weight: 400;
|
||||
}
|
||||
section.title strong { color: #FFFFFF; }
|
||||
h1 {
|
||||
color: var(--sp-red);
|
||||
font-size: 40px;
|
||||
font-weight: 700;
|
||||
margin-bottom: 12px;
|
||||
}
|
||||
h2 {
|
||||
color: var(--sp-red);
|
||||
border-bottom: 3px solid var(--sp-red);
|
||||
padding-bottom: 6px;
|
||||
font-weight: 700;
|
||||
}
|
||||
h3 {
|
||||
color: var(--sp-red-dark);
|
||||
font-weight: 600;
|
||||
margin-top: 24px;
|
||||
}
|
||||
ul, ol { color: var(--sp-slate); }
|
||||
li { margin-bottom: 6px; }
|
||||
strong { color: var(--sp-ink); }
|
||||
table {
|
||||
font-size: 18px;
|
||||
width: 100%;
|
||||
border-collapse: collapse;
|
||||
margin: 12px 0;
|
||||
}
|
||||
th {
|
||||
background: var(--sp-red);
|
||||
color: #FFFFFF;
|
||||
text-align: left;
|
||||
padding: 10px 12px;
|
||||
font-weight: 600;
|
||||
border: 1px solid var(--sp-red-dark);
|
||||
}
|
||||
td {
|
||||
padding: 8px 12px;
|
||||
border: 1px solid var(--sp-line);
|
||||
color: var(--sp-slate);
|
||||
}
|
||||
tr:nth-child(even) td { background: var(--sp-tint); }
|
||||
pre {
|
||||
font-size: 13px;
|
||||
background: var(--sp-tint);
|
||||
border-left: 4px solid var(--sp-red);
|
||||
padding: 14px 16px;
|
||||
border-radius: 0;
|
||||
color: var(--sp-ink);
|
||||
}
|
||||
code {
|
||||
background: var(--sp-tint);
|
||||
color: var(--sp-red-dark);
|
||||
padding: 1px 5px;
|
||||
border-radius: 2px;
|
||||
font-family: 'Menlo', 'Consolas', monospace;
|
||||
}
|
||||
pre code {
|
||||
background: none;
|
||||
color: var(--sp-ink);
|
||||
padding: 0;
|
||||
}
|
||||
blockquote {
|
||||
border-left: 5px solid var(--sp-red);
|
||||
background: var(--sp-tint);
|
||||
padding: 10px 16px;
|
||||
color: var(--sp-slate);
|
||||
font-style: italic;
|
||||
border-radius: 0;
|
||||
}
|
||||
header {
|
||||
color: var(--sp-red);
|
||||
font-weight: 700;
|
||||
font-size: 14px;
|
||||
}
|
||||
footer {
|
||||
color: var(--sp-gray);
|
||||
font-size: 12px;
|
||||
}
|
||||
section::after {
|
||||
color: var(--sp-red);
|
||||
font-weight: 700;
|
||||
}
|
||||
---
|
||||
|
||||
<!-- _class: title -->
|
||||
|
||||
# ACDL
|
||||
## Agentic Cloud Delivery Platform
|
||||
|
||||
Automatic. Safe. Audited. — in 30 minutes, on stubs.
|
||||
|
||||
v1.0 · GitHub Actions · stub-driven
|
||||
|
||||
<!--
|
||||
30-min exec demo. Emphasize: we prove INTENT and SAFETY, not provision real infra.
|
||||
Everything runs as local stubs on Linux via GitHub Actions. No AWS.
|
||||
-->
|
||||
|
||||
---
|
||||
|
||||
# The Problem
|
||||
|
||||
### Today, deploying infrastructure takes **weeks**
|
||||
|
||||
- Ticket → triage queue → copy-paste config → peer review → security review → waiting for central IT to release
|
||||
|
||||
> Two weeks of human latency for a service that should take minutes.
|
||||
|
||||
### What we want instead
|
||||
|
||||
- Developer commits a **contract** → pipeline runs
|
||||
- Safety **computed** automatically (confidence signal)
|
||||
- Manual gates only where they matter (QA, Prod)
|
||||
- Every step written to a tamper-evident **evidence stream**
|
||||
|
||||
<!--
|
||||
Set the pain. Ask: who has lived this? Then pivot to the vision.
|
||||
-->
|
||||
|
||||
---
|
||||
|
||||
# How It Works
|
||||
|
||||
```
|
||||
┌────────────── acdl-contracts ──────────────┐
|
||||
Developer ──▶│ commit contract.yaml │
|
||||
└───────┬───────────────────────────────────┘
|
||||
│ (push)
|
||||
Citizen ┌─────────┴──────────┐
|
||||
│ "ingest gas pricing into data lake"
|
||||
▼
|
||||
Claude agent ──▶ contract.yaml ─┘
|
||||
│ (push)
|
||||
▼
|
||||
┌─────────────────┐
|
||||
│ reusable │
|
||||
│ GitHub Actions │
|
||||
│ pipeline │
|
||||
└────────┬────────┘
|
||||
│
|
||||
┌─────────────┼─────────────┐
|
||||
▼ ▼ ▼
|
||||
Dev (auto) QA (approval) Prod (approval)
|
||||
│
|
||||
▼
|
||||
evidence_writer ─▶ audit.json (hash-chained) ─▶ Pages timeline
|
||||
```
|
||||
|
||||
Two entry paths, **one** pipeline, **one** audit trail — developer via GitHub, citizen developer via their own Claude agent.
|
||||
|
||||
<!--
|
||||
Two surfaces: developers push contracts directly to GitHub; citizen developers prompt a Claude agent they own, which writes and pushes the contract for them.
|
||||
Both converge on one GitHub Actions pipeline with three stages.
|
||||
-->
|
||||
|
||||
---
|
||||
|
||||
# The Safety Story
|
||||
|
||||
### Computed, not requested
|
||||
|
||||
| Signal | Behavior |
|
||||
|--------|----------|
|
||||
| **Base confidence** | 0.90 |
|
||||
| **On policy violation** | drop to 0.40 + reason code |
|
||||
| **Gate threshold** | ≥ 0.50 to proceed past Dev |
|
||||
|
||||
### Policy (v1)
|
||||
- `public-ingress: true` → `POLICY_VIOLATION:PUBLIC_INGRESS`
|
||||
|
||||
### Evidence
|
||||
- Each event appended to `audit.json` with SHA-256 link to previous (`prev_hash` + `hash`)
|
||||
- Published to Pages → vanilla-JS timeline
|
||||
|
||||
<!--
|
||||
Safety is computed by the platform, not asked of the developer.
|
||||
Threshold 0.50 is exact → 0.90 passes, 0.40 halts. That's what makes the three scenarios deterministic.
|
||||
-->
|
||||
|
||||
---
|
||||
|
||||
# Scenario 1 — Developer Self-Service
|
||||
|
||||
### Trigger
|
||||
Developer commits a valid `contract.yaml` requesting **`l2-commodity-price-feed`** via **GitHub**.
|
||||
|
||||
### What you'll see
|
||||
- **Dev:** policy ✅ → apply api-gateway, lambda, s3 → confidence **0.90** → proceed
|
||||
- **QA:** pipeline pauses → click **Approve**
|
||||
- **Prod:** pipeline pauses → click **Approve**
|
||||
- **Finalize:** `audit.json` committed → Pages timeline updates
|
||||
|
||||
### Evidence outcome
|
||||
Timeline shows: contract received → policy pass → apply × 3 → confidence 0.90 → QA → Prod → published.
|
||||
|
||||
<!--
|
||||
Normal developer flow: human writes the contract, pushes to GitHub, the GitHub Action pipeline runs.
|
||||
Narrate: developer commits and walks away; platform does the rest.
|
||||
Pause visibly at each gate so the audience sees human-in-the-loop.
|
||||
End by refreshing the Pages timeline.
|
||||
-->
|
||||
|
||||
---
|
||||
|
||||
# Scenario 1 — Journey
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
classDef gh fill:#F4F4F4,stroke:#1A1A1A,stroke-width:2px,color:#1A1A1A
|
||||
classDef stage fill:#C8102E,stroke:#8E0B20,stroke-width:1px,color:#FFFFFF
|
||||
classDef gate fill:#FFFFFF,stroke:#1A1A1A,stroke-width:2px,color:#1A1A1A
|
||||
classDef evidence fill:#F4F4F4,stroke:#C8102E,stroke-width:1px,color:#1A1A1A
|
||||
|
||||
D["Developer"]:::gh -->|"writes contract.yaml"| GH["GitHub<br/>acdl-contracts"]:::gh
|
||||
GH -->|"push triggers<br/>GitHub Action"| DEV["Dev<br/>(autonomous)"]:::stage
|
||||
DEV -->|"policy ✅ · confidence 0.90"| QA["QA<br/>approval gate"]:::gate
|
||||
QA -->|"approve"| PROD["Prod<br/>approval gate"]:::gate
|
||||
PROD -->|"approve"| FIN["Finalize<br/>commit audit.json"]:::stage
|
||||
FIN --> TL["GitHub Pages<br/>timeline"]:::evidence
|
||||
```
|
||||
|
||||
<!--
|
||||
Point to the two approval gates — QA and Prod — both human clicks.
|
||||
The whole chain from commit to timeline is one GitHub Actions workflow.
|
||||
-->
|
||||
|
||||
---
|
||||
|
||||
# Scenario 2 — Citizen Developer
|
||||
|
||||
### Trigger
|
||||
Non-technical user prompts their **own Claude agent** in natural language:
|
||||
|
||||
> "I need a new service to ingest real-time natural gas pricing data into our data lake."
|
||||
|
||||
### What you'll see
|
||||
- Claude agent parses intent, writes `contract.yaml` for **`l2-commodity-price-feed`**, pushes a branch
|
||||
- Issue **closed**; branch push triggers the **identical** pipeline from Scenario 1
|
||||
- Citizen developer follows the run all the way to **Prod**
|
||||
|
||||
### Evidence outcome
|
||||
Timeline is **indistinguishable** from Scenario 1 — the agentic surface is first-class, not a bolt-on.
|
||||
|
||||
<!--
|
||||
Punchline: same timeline, same safety, same audit — different entry.
|
||||
The citizen developer owns and drives their own Claude agent; they are the actor, not the platform.
|
||||
Normal developers (Scenario 1) keep using GitHub directly — two surfaces, one pipeline, one audit.
|
||||
-->
|
||||
|
||||
---
|
||||
|
||||
# Scenario 2 — Journey
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
classDef cit fill:#F4F4F4,stroke:#C8102E,stroke-width:2px,color:#1A1A1A
|
||||
classDef agent fill:#C8102E,stroke:#8E0B20,stroke-width:1px,color:#FFFFFF
|
||||
classDef stage fill:#1A1A1A,stroke:#1A1A1A,stroke-width:1px,color:#FFFFFF
|
||||
classDef gate fill:#FFFFFF,stroke:#1A1A1A,stroke-width:2px,color:#1A1A1A
|
||||
classDef evidence fill:#F4F4F4,stroke:#C8102E,stroke-width:1px,color:#1A1A1A
|
||||
|
||||
CD["Citizen developer"]:::cit -->|"natural-language<br/>prompt"| CL["Claude agent<br/>(citizen-owned)"]:::agent
|
||||
CL -->|"generates<br/>contract.yaml"| GH["GitHub<br/>acdl-contracts"]:::cit
|
||||
GH -->|"push triggers<br/>GitHub Action"| DEV["Dev<br/>(autonomous)"]:::stage
|
||||
DEV -->|"policy ✅ · confidence 0.90"| QA["QA<br/>approval gate"]:::gate
|
||||
QA -->|"approve"| PROD["Prod<br/>approval gate"]:::gate
|
||||
PROD -->|"approve"| FIN["Finalize<br/>commit audit.json"]:::stage
|
||||
FIN --> TL["GitHub Pages<br/>timeline"]:::evidence
|
||||
```
|
||||
|
||||
<!--
|
||||
Highlight the red Claude-agent node — owned by the citizen, not by the platform.
|
||||
From GitHub onward the journey is identical to Scenario 1.
|
||||
-->
|
||||
|
||||
---
|
||||
|
||||
# Scenario 3 — The Safety Net
|
||||
|
||||
### Trigger
|
||||
Developer commits a **malicious** `contract.yaml` for `l2-regulatory-reporting` via **GitHub**:
|
||||
|
||||
```yaml
|
||||
stack: l2-regulatory-reporting
|
||||
public-ingress: true
|
||||
```
|
||||
|
||||
### What you'll see
|
||||
- **Dev:** `policy_checker` → `POLICY_VIOLATION:PUBLIC_INGRESS`
|
||||
- `confidence_signal` drops 0.90 → **0.40**
|
||||
- `0.40 < 0.50` → pipeline **halts in Dev**
|
||||
- Rejection reason written to the evidence stream
|
||||
|
||||
### Evidence outcome
|
||||
Timeline shows the attempted deploy, the violation, the confidence drop, and the **halt** — visible and explained.
|
||||
|
||||
<!--
|
||||
The safety money shot. The platform said NO, and said WHY, on the record.
|
||||
No human had to catch it — the confidence signal computed the risk.
|
||||
Contrast with The Problem's old-world review queue.
|
||||
-->
|
||||
|
||||
---
|
||||
|
||||
# Scenario 3 — Journey
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
classDef gh fill:#F4F4F4,stroke:#1A1A1A,stroke-width:2px,color:#1A1A1A
|
||||
classDef stage fill:#C8102E,stroke:#8E0B20,stroke-width:1px,color:#FFFFFF
|
||||
classDef halt fill:#1A1A1A,stroke:#1A1A1A,stroke-width:1px,color:#FFFFFF
|
||||
classDef evidence fill:#F4F4F4,stroke:#C8102E,stroke-width:1px,color:#1A1A1A
|
||||
|
||||
D["Developer"]:::gh -->|"writes malicious<br/>contract.yaml"| GH["GitHub<br/>acdl-contracts"]:::gh
|
||||
GH -->|"push triggers<br/>GitHub Action"| DEV["Dev<br/>(autonomous)"]:::stage
|
||||
DEV -->|"POLICY_VIOLATION:PUBLIC_INGRESS<br/>confidence 0.90 → 0.40"| HALT["Halt in Dev<br/>+ rejection reason"]:::halt
|
||||
HALT --> TL["GitHub Pages<br/>timeline"]:::evidence
|
||||
```
|
||||
|
||||
<!--
|
||||
The black halt node is the whole point — pipeline stops, evidence records why.
|
||||
Notice there are no QA/Prod gates on this path; the journey ends at Dev.
|
||||
-->
|
||||
@@ -1,145 +0,0 @@
|
||||
# ACDL issue-to-contract workflow (Phase 04 implementation).
|
||||
#
|
||||
# Trigger: a new Issue is opened in acdl-contracts. The workflow runs
|
||||
# l3b_agent_stub.py (checked out from the `acdl` repo, pinned to
|
||||
# @milestone/v1.0-initial) to map the Issue body to a contract.yaml, commits
|
||||
# the contract to a new branch `contract/<issue-number>` on acdl-contracts
|
||||
# via the Gitea file-contents API, closes the Issue with a comment, and
|
||||
# dispatches the main pipeline in the `acdl` repo via the workflow_dispatch
|
||||
# API (D-014; Gitea Actions does not support repository_dispatch).
|
||||
#
|
||||
# Cross-repo trigger (D-014):
|
||||
# The final step POSTs to
|
||||
# /api/v1/repos/continuous-intelligence/acdl/actions/workflows/pipeline.yml/dispatches
|
||||
# with body {"ref": "milestone/v1.0-initial",
|
||||
# "inputs": {"contract-ref": "contract/<issue-number>"}}.
|
||||
#
|
||||
# Branch-pin rule (ARCHITECTURE.md):
|
||||
# The `acdl` repo's default branch is `milestone/v1.0-initial`, so the
|
||||
# checkout step pins `ref: milestone/v1.0-initial`. The pipeline dispatch
|
||||
# also pins `ref: milestone/v1.0-initial` (the workflow file lives on
|
||||
# that branch). The new `contract/<n>` branch is created on acdl-contracts
|
||||
# (whose default branch is `main`, per D-015).
|
||||
#
|
||||
# File-contents POST with `new_branch` (D-030):
|
||||
# The POST to /repos/.../contents/contract.yaml includes
|
||||
# `new_branch: contract/<n>`, which tells Gitea to create the file on a
|
||||
# NEW branch off the current head of `branch: main` instead of committing
|
||||
# directly to main. This avoids a separate branch-create + commit round
|
||||
# trip.
|
||||
name: issue-to-contract
|
||||
|
||||
"on":
|
||||
issues:
|
||||
types: [opened]
|
||||
|
||||
jobs:
|
||||
parse-and-trigger:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- name: "Checkout acdl (pinned to milestone/v1.0-initial for l3b_agent_stub.py)"
|
||||
uses: actions/checkout@v4
|
||||
with:
|
||||
repository: continuous-intelligence/acdl
|
||||
ref: milestone/v1.0-initial
|
||||
token: ${{ secrets.GITEA_TOKEN }}
|
||||
|
||||
- name: "Parse Issue body into contract.yaml"
|
||||
env:
|
||||
ISSUE_BODY: ${{ gitea.event.issue.body }}
|
||||
run: |
|
||||
# Pass the Issue body via an env var to avoid shell injection from
|
||||
# arbitrary Issue text. l3b_agent_stub.py reads argv[1]; we pass
|
||||
# the env var quoted so no metacharacter interpretation happens.
|
||||
python3 scripts/l3b_agent_stub.py "$ISSUE_BODY" -o contract.yaml
|
||||
echo "--- generated contract.yaml ---"
|
||||
cat contract.yaml
|
||||
|
||||
- name: "Commit contract.yaml to new branch contract/${{ gitea.event.issue.number }} on acdl-contracts"
|
||||
env:
|
||||
GITEA_TOKEN: ${{ secrets.GITEA_TOKEN }}
|
||||
run: |
|
||||
set -euo pipefail
|
||||
STACK=$(python3 -c 'import yaml; print(yaml.safe_load(open("contract.yaml"))["stack"])')
|
||||
ISSUE_NUMBER="${{ gitea.event.issue.number }}"
|
||||
BRANCH="contract/${ISSUE_NUMBER}"
|
||||
HOST="https://git.cloudinit.dev"
|
||||
API="${HOST}/api/v1/repos/continuous-intelligence/acdl-contracts/contents/contract.yaml"
|
||||
B64=$(base64 -w 0 contract.yaml)
|
||||
BODY=$(python3 -c "
|
||||
import json
|
||||
print(json.dumps({
|
||||
'content': '${B64}',
|
||||
'message': 'l3b: contract for issue #${ISSUE_NUMBER}',
|
||||
'branch': 'main',
|
||||
'new_branch': '${BRANCH}'
|
||||
}))
|
||||
")
|
||||
STATUS=$(curl -sS -o /tmp/contract_post.json -w "%{http_code}" \
|
||||
-X POST \
|
||||
-H "Authorization: token ${GITEA_TOKEN}" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d "$BODY" \
|
||||
"$API")
|
||||
echo "POST contract.yaml -> HTTP ${STATUS}"
|
||||
cat /tmp/contract_post.json || true
|
||||
case "$STATUS" in
|
||||
201) echo "contract.yaml committed on branch ${BRANCH}" ;;
|
||||
*) echo "ERROR: file-contents POST failed (HTTP ${STATUS})" >&2; exit 1 ;;
|
||||
esac
|
||||
echo "STACK=${STACK}" >> "$GITHUB_ENV"
|
||||
echo "BRANCH=${BRANCH}" >> "$GITHUB_ENV"
|
||||
|
||||
- name: "Comment on Issue + close it"
|
||||
env:
|
||||
GITEA_TOKEN: ${{ secrets.GITEA_TOKEN }}
|
||||
run: |
|
||||
set -euo pipefail
|
||||
ISSUE_NUMBER="${{ gitea.event.issue.number }}"
|
||||
HOST="https://git.cloudinit.dev"
|
||||
ISSUES_API="${HOST}/api/v1/repos/continuous-intelligence/acdl-contracts/issues/${ISSUE_NUMBER}"
|
||||
COMMENT_BODY=$(python3 -c "
|
||||
import json
|
||||
print(json.dumps({'body': 'Generated contract.yaml for stack \`' + '${STACK}' + '\` on branch \`' + '${BRANCH}' + '\`. Pipeline dispatched.'}))
|
||||
")
|
||||
curl -sS -o /tmp/comment.json -w "comment HTTP %{http_code}\n" \
|
||||
-X POST \
|
||||
-H "Authorization: token ${GITEA_TOKEN}" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d "$COMMENT_BODY" \
|
||||
"${ISSUES_API}/comments"
|
||||
CLOSE_BODY='{"state":"closed"}'
|
||||
curl -sS -o /tmp/close.json -w "close HTTP %{http_code}\n" \
|
||||
-X PATCH \
|
||||
-H "Authorization: token ${GITEA_TOKEN}" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d "$CLOSE_BODY" \
|
||||
"${ISSUES_API}"
|
||||
|
||||
- name: "Dispatch the pipeline on acdl (contract-ref = contract/${{ gitea.event.issue.number }})"
|
||||
env:
|
||||
GITEA_TOKEN: ${{ secrets.GITEA_TOKEN }}
|
||||
run: |
|
||||
set -euo pipefail
|
||||
ISSUE_NUMBER="${{ gitea.event.issue.number }}"
|
||||
HOST="https://git.cloudinit.dev"
|
||||
DISPATCH_URL="${HOST}/api/v1/repos/continuous-intelligence/acdl/actions/workflows/pipeline.yml/dispatches"
|
||||
BODY=$(python3 -c "
|
||||
import json
|
||||
print(json.dumps({
|
||||
'ref': 'milestone/v1.0-initial',
|
||||
'inputs': {'contract-ref': 'contract/${ISSUE_NUMBER}'}
|
||||
}))
|
||||
")
|
||||
STATUS=$(curl -sS -o /tmp/dispatch.json -w "%{http_code}" \
|
||||
-X POST \
|
||||
-H "Authorization: token ${GITEA_TOKEN}" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d "$BODY" \
|
||||
"$DISPATCH_URL")
|
||||
echo "pipeline dispatch -> HTTP ${STATUS}"
|
||||
cat /tmp/dispatch.json || true
|
||||
case "$STATUS" in
|
||||
201|202|204) echo "pipeline dispatched (contract-ref=contract/${ISSUE_NUMBER})" ;;
|
||||
*) echo "ERROR: pipeline dispatch failed (HTTP ${STATUS})" >&2; exit 1 ;;
|
||||
esac
|
||||
@@ -1,55 +0,0 @@
|
||||
# Elaborate developer contract — energy trading price feed.
|
||||
#
|
||||
# Schema (D-021): stack + inputs (open-ended string map) + public-ingress.
|
||||
# The `stack` field MUST match an L2 folder name under modules/l2/.
|
||||
# The `inputs` map is free-form string values; these are L2-level params
|
||||
# that travel with the deployment into state.json and the audit trail.
|
||||
# The L1 input values are declared by the L2's manifest.yaml, not here.
|
||||
#
|
||||
# Commit this to acdl-contracts as contract.yaml to trigger the pipeline:
|
||||
# git add contract.yaml && git commit -m "feat: deploy price feed (prod)" && git push
|
||||
|
||||
stack: l2-commodity-price-feed
|
||||
|
||||
inputs:
|
||||
# --- Environment + ownership ---
|
||||
environment: prod
|
||||
owner: commodity-trading-platform-team
|
||||
team: power-and-gas-desk
|
||||
cost_center: CC-TRD-4471
|
||||
change_ticket: CHG-2026-07-21-093
|
||||
|
||||
# --- Business context (rides into the audit timeline) ---
|
||||
business_owner: kchen@jccapital.xyz
|
||||
oncall_email: sre-commodity@example.com
|
||||
sla_tier: T1
|
||||
business_hours: "Mon-Fri 07:00-19:00 ET"
|
||||
data_classification: internal
|
||||
|
||||
# --- Source feed contract (business-facing) ---
|
||||
feed_vendor: Platts
|
||||
feed_name: natural-gas-daily-settlement
|
||||
feed_cadence: daily
|
||||
feed_timezone: US/Eastern
|
||||
symbols: "NG-WTI-HH,NG-HH-M,NG-PJM"
|
||||
retry_policy: backoff-3x-15min
|
||||
dead_letter_queue: commodity-price-dlq
|
||||
|
||||
# --- Deployment knobs (consumed by the pipeline; passed to L1s via L2 manifest) ---
|
||||
replicas: "3"
|
||||
cpu_request: "500m"
|
||||
memory_request: "1Gi"
|
||||
autoscale_min: "2"
|
||||
autoscale_max: "8"
|
||||
log_retention_days: "90"
|
||||
archive_retention_days: "2555"
|
||||
|
||||
# --- Operational flags ---
|
||||
enable_canary: "true"
|
||||
canary_percentage: "10"
|
||||
enable_pagerduty: "true"
|
||||
enable_cost_alerts: "true"
|
||||
cost_alert_threshold_usd: "500"
|
||||
|
||||
# Policy-gated field. true -> POLICY_VIOLATION:PUBLIC_INGRESS -> confidence 0.40 < 0.50 -> Dev rejects (Act 4).
|
||||
public-ingress: false
|
||||
@@ -1,55 +0,0 @@
|
||||
# Elaborate developer contract — regulatory reporting (with policy violation).
|
||||
#
|
||||
# Same schema as the price-feed example, but with public-ingress: true,
|
||||
# which triggers Act 4: the policy_checker fails, the confidence_signal
|
||||
# drops to 0.40, the 0.50 gate halts the pipeline in Dev, and the
|
||||
# rejection appears on the evidence timeline.
|
||||
#
|
||||
# Commit this to acdl-contracts as contract.yaml to reproduce Act 4:
|
||||
# git add contract.yaml && git commit -m "feat: deploy regulatory reporting" && git push
|
||||
|
||||
stack: l2-regulatory-reporting
|
||||
|
||||
inputs:
|
||||
# --- Environment + ownership ---
|
||||
environment: prod
|
||||
owner: compliance-and-controls-team
|
||||
team: regulatory-reporting-desk
|
||||
cost_center: CC-CMP-9902
|
||||
change_ticket: CHG-2026-07-21-118
|
||||
business_owner: compliance@jccapital.xyz
|
||||
oncall_email: sre-regulatory@example.com
|
||||
sla_tier: T0
|
||||
business_hours: "24x7"
|
||||
data_classification: confidential
|
||||
|
||||
# --- Regulatory context ---
|
||||
regulator: FERC
|
||||
filing_frequency: monthly
|
||||
filing_deadline_day_of_month: "15"
|
||||
reporting_period: 2026-Q3
|
||||
jurisdiction: US-Federal
|
||||
legal_hold: "false"
|
||||
|
||||
# --- Deployment knobs ---
|
||||
replicas: "2"
|
||||
cpu_request: "1000m"
|
||||
memory_request: "2Gi"
|
||||
autoscale_min: "2"
|
||||
autoscale_max: "4"
|
||||
log_retention_days: "365"
|
||||
archive_retention_days: "2555"
|
||||
enable_encryption_at_rest: "true"
|
||||
enable_kms_rotation: "true"
|
||||
|
||||
# --- Operational flags ---
|
||||
enable_canary: "false"
|
||||
enable_pagerduty: "true"
|
||||
enable_cost_alerts: "true"
|
||||
cost_alert_threshold_usd: "1000"
|
||||
|
||||
# POLICY VIOLATION — this is the Act 4 trigger.
|
||||
# The policy_checker.py will emit: POLICY_VIOLATION:PUBLIC_INGRESS
|
||||
# The confidence_signal.py will return: {"score": 0.40, "reason": "POLICY_VIOLATION:PUBLIC_INGRESS"}
|
||||
# The 0.50 gate halts the pipeline in Dev; mock_executor never runs.
|
||||
public-ingress: true
|
||||
@@ -1,334 +0,0 @@
|
||||
<!DOCTYPE html>
|
||||
<html lang="en">
|
||||
<head>
|
||||
<meta charset="utf-8">
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1">
|
||||
<title>ACDL Evidence Timeline</title>
|
||||
<style>
|
||||
:root {
|
||||
--stage-dev: #2563eb;
|
||||
--stage-qa: #ca8a04;
|
||||
--stage-prod: #ea580c;
|
||||
--stage-finalize: #16a34a;
|
||||
--stage-genesis: #6b7280;
|
||||
--stage-rejected: #dc2626;
|
||||
--bg: #f8fafc;
|
||||
--card-bg: #ffffff;
|
||||
--text: #0f172a;
|
||||
--muted: #64748b;
|
||||
--border: #e2e8f0;
|
||||
}
|
||||
* { box-sizing: border-box; }
|
||||
html, body {
|
||||
margin: 0;
|
||||
padding: 0;
|
||||
background: var(--bg);
|
||||
color: var(--text);
|
||||
font-family: system-ui, -apple-system, sans-serif;
|
||||
line-height: 1.5;
|
||||
}
|
||||
header {
|
||||
padding: 24px 32px 16px;
|
||||
border-bottom: 1px solid var(--border);
|
||||
background: var(--card-bg);
|
||||
}
|
||||
header h1 {
|
||||
margin: 0 0 6px;
|
||||
font-size: 1.5rem;
|
||||
font-weight: 600;
|
||||
}
|
||||
header p {
|
||||
margin: 0;
|
||||
color: var(--muted);
|
||||
font-size: 0.95rem;
|
||||
}
|
||||
.toolbar {
|
||||
display: flex;
|
||||
align-items: center;
|
||||
gap: 12px;
|
||||
padding: 16px 32px;
|
||||
background: var(--card-bg);
|
||||
border-bottom: 1px solid var(--border);
|
||||
}
|
||||
button#refresh {
|
||||
appearance: none;
|
||||
border: 1px solid var(--border);
|
||||
background: var(--text);
|
||||
color: #fff;
|
||||
padding: 8px 16px;
|
||||
border-radius: 6px;
|
||||
font-size: 0.9rem;
|
||||
font-family: inherit;
|
||||
cursor: pointer;
|
||||
}
|
||||
button#refresh:hover { opacity: 0.9; }
|
||||
button#refresh:active { transform: translateY(1px); }
|
||||
.toolbar .status {
|
||||
color: var(--muted);
|
||||
font-size: 0.85rem;
|
||||
}
|
||||
main {
|
||||
padding: 24px 32px 48px;
|
||||
max-width: 900px;
|
||||
margin: 0 auto;
|
||||
}
|
||||
.empty {
|
||||
padding: 48px 24px;
|
||||
text-align: center;
|
||||
color: var(--muted);
|
||||
background: var(--card-bg);
|
||||
border: 1px dashed var(--border);
|
||||
border-radius: 8px;
|
||||
}
|
||||
ol.timeline {
|
||||
list-style: none;
|
||||
margin: 0;
|
||||
padding: 0;
|
||||
position: relative;
|
||||
}
|
||||
ol.timeline::before {
|
||||
content: "";
|
||||
position: absolute;
|
||||
left: 11px;
|
||||
top: 6px;
|
||||
bottom: 6px;
|
||||
width: 2px;
|
||||
background: var(--border);
|
||||
}
|
||||
li.event {
|
||||
position: relative;
|
||||
padding: 12px 0 12px 40px;
|
||||
}
|
||||
li.event::before {
|
||||
content: "";
|
||||
position: absolute;
|
||||
left: 6px;
|
||||
top: 18px;
|
||||
width: 12px;
|
||||
height: 12px;
|
||||
border-radius: 50%;
|
||||
background: var(--dot, var(--muted));
|
||||
border: 2px solid var(--card-bg);
|
||||
box-shadow: 0 0 0 1px var(--border);
|
||||
}
|
||||
.card {
|
||||
background: var(--card-bg);
|
||||
border: 1px solid var(--border);
|
||||
border-left: 4px solid var(--dot, var(--muted));
|
||||
border-radius: 8px;
|
||||
padding: 12px 16px;
|
||||
}
|
||||
.card .row {
|
||||
display: flex;
|
||||
flex-wrap: wrap;
|
||||
align-items: center;
|
||||
gap: 8px;
|
||||
margin-bottom: 4px;
|
||||
}
|
||||
.seq {
|
||||
display: inline-block;
|
||||
min-width: 28px;
|
||||
padding: 2px 6px;
|
||||
font-size: 0.75rem;
|
||||
font-weight: 600;
|
||||
text-align: center;
|
||||
border-radius: 4px;
|
||||
background: #eef2ff;
|
||||
color: #3730a3;
|
||||
border: 1px solid #c7d2fe;
|
||||
}
|
||||
.chip {
|
||||
display: inline-block;
|
||||
padding: 2px 8px;
|
||||
font-size: 0.72rem;
|
||||
font-weight: 600;
|
||||
text-transform: uppercase;
|
||||
letter-spacing: 0.04em;
|
||||
border-radius: 999px;
|
||||
color: #fff;
|
||||
background: var(--dot, var(--muted));
|
||||
}
|
||||
.ts {
|
||||
font-size: 0.8rem;
|
||||
color: var(--muted);
|
||||
font-variant-numeric: tabular-nums;
|
||||
}
|
||||
.event-text {
|
||||
margin: 4px 0 6px;
|
||||
font-size: 0.95rem;
|
||||
}
|
||||
.hash {
|
||||
font-family: ui-monospace, SFMono-Regular, Menlo, monospace;
|
||||
font-size: 0.75rem;
|
||||
color: var(--muted);
|
||||
word-break: break-all;
|
||||
}
|
||||
footer {
|
||||
padding: 16px 32px 24px;
|
||||
border-top: 1px solid var(--border);
|
||||
color: var(--muted);
|
||||
font-size: 0.8rem;
|
||||
max-width: 900px;
|
||||
margin: 0 auto;
|
||||
}
|
||||
footer code {
|
||||
font-family: ui-monospace, SFMono-Regular, Menlo, monospace;
|
||||
background: #f1f5f9;
|
||||
padding: 1px 4px;
|
||||
border-radius: 3px;
|
||||
}
|
||||
</style>
|
||||
</head>
|
||||
<body>
|
||||
<header>
|
||||
<h1>ACDL Evidence Timeline</h1>
|
||||
<p>ACDL — Agentic Cloud Delivery Platform · Audit Timeline</p>
|
||||
</header>
|
||||
<div class="toolbar">
|
||||
<button id="refresh" type="button">Refresh</button>
|
||||
<span class="status" id="status"></span>
|
||||
</div>
|
||||
<main>
|
||||
<div id="container">
|
||||
<div class="empty">Loading…</div>
|
||||
</div>
|
||||
</main>
|
||||
<footer>
|
||||
<div id="footer"></div>
|
||||
</footer>
|
||||
<script>
|
||||
(function () {
|
||||
"use strict";
|
||||
|
||||
var AUDIT_URL = "./audit.json";
|
||||
var STAGE_COLORS = {
|
||||
dev: "var(--stage-dev)",
|
||||
qa: "var(--stage-qa)",
|
||||
prod: "var(--stage-prod)",
|
||||
finalize: "var(--stage-finalize)",
|
||||
genesis: "var(--stage-genesis)"
|
||||
};
|
||||
|
||||
function $(id) { return document.getElementById(id); }
|
||||
|
||||
function stageColor(stage, eventText) {
|
||||
var evt = (eventText || "").toString().toLowerCase();
|
||||
if (evt.indexOf("rejected") !== -1) {
|
||||
return "var(--stage-rejected)";
|
||||
}
|
||||
return STAGE_COLORS[stage] || "var(--stage-genesis)";
|
||||
}
|
||||
|
||||
function dash(v) {
|
||||
return (v === null || v === undefined || v === "") ? "—" : v;
|
||||
}
|
||||
|
||||
function hashPreview(hash) {
|
||||
if (hash === null || hash === undefined || hash === "") return "—";
|
||||
var s = String(hash);
|
||||
return s.slice(0, 12) + "…";
|
||||
}
|
||||
|
||||
function esc(s) {
|
||||
return String(s)
|
||||
.replace(/&/g, "&")
|
||||
.replace(/</g, "<")
|
||||
.replace(/>/g, ">")
|
||||
.replace(/"/g, """)
|
||||
.replace(/'/g, "'");
|
||||
}
|
||||
|
||||
function auditUrlDisplay() {
|
||||
try {
|
||||
var href = window.location.href;
|
||||
var slash = href.lastIndexOf("/");
|
||||
if (slash >= 0) {
|
||||
return href.slice(0, slash + 1) + "audit.json";
|
||||
}
|
||||
} catch (e) {}
|
||||
return AUDIT_URL;
|
||||
}
|
||||
|
||||
function renderEmpty(msg) {
|
||||
$("container").innerHTML =
|
||||
'<div class="empty">' + esc(msg) + "</div>";
|
||||
}
|
||||
|
||||
function renderTimeline(events) {
|
||||
if (!Array.isArray(events)) {
|
||||
renderEmpty("No audit data yet");
|
||||
return;
|
||||
}
|
||||
if (events.length === 0) {
|
||||
renderEmpty("No audit data yet");
|
||||
return;
|
||||
}
|
||||
var sorted = events.slice().sort(function (a, b) {
|
||||
var sa = (a && typeof a.seq === "number") ? a.seq : 0;
|
||||
var sb = (b && typeof b.seq === "number") ? b.seq : 0;
|
||||
return sa - sb;
|
||||
});
|
||||
var html = '<ol class="timeline">';
|
||||
for (var i = 0; i < sorted.length; i++) {
|
||||
var e = sorted[i] || {};
|
||||
var stage = dash(e.stage);
|
||||
var color = stageColor(e.stage, e.event);
|
||||
html += '<li class="event" style="--dot:' + color + ';">';
|
||||
html += '<div class="card" style="--dot:' + color + ';">';
|
||||
html += '<div class="row">';
|
||||
html += '<span class="seq">#' + esc(dash(e.seq)) + "</span>";
|
||||
html += '<span class="chip">' + esc(stage) + "</span>";
|
||||
html += '<span class="ts">' + esc(dash(e.ts)) + "</span>";
|
||||
html += "</div>";
|
||||
html += '<div class="event-text">' + esc(dash(e.event)) + "</div>";
|
||||
html += '<div class="hash">' + esc(hashPreview(e.hash)) + "</div>";
|
||||
html += "</div>";
|
||||
html += "</li>";
|
||||
}
|
||||
html += "</ol>";
|
||||
$("container").innerHTML = html;
|
||||
}
|
||||
|
||||
function renderFooter(ok) {
|
||||
var when = new Date().toISOString();
|
||||
var url = auditUrlDisplay();
|
||||
var prefix = "Fetched at " + when + " · audit.json: ";
|
||||
$("footer").innerHTML =
|
||||
esc(prefix) + '<code>' + esc(url) + "</code>" +
|
||||
(ok ? "" : " (fetch failed)");
|
||||
}
|
||||
|
||||
function setStatus(msg) {
|
||||
$("status").textContent = msg || "";
|
||||
}
|
||||
|
||||
function fetchAudit() {
|
||||
setStatus("Fetching…");
|
||||
fetch(AUDIT_URL, { cache: "no-store" })
|
||||
.then(function (res) {
|
||||
if (!res.ok) {
|
||||
throw new Error("HTTP " + res.status);
|
||||
}
|
||||
return res.json();
|
||||
})
|
||||
.then(function (data) {
|
||||
if (!Array.isArray(data)) {
|
||||
throw new Error("not an array");
|
||||
}
|
||||
renderTimeline(data);
|
||||
renderFooter(true);
|
||||
setStatus("Loaded " + data.length + " event(s)");
|
||||
})
|
||||
.catch(function (err) {
|
||||
renderEmpty("No audit data yet");
|
||||
renderFooter(false);
|
||||
setStatus("Fetch failed: " + (err && err.message ? err.message : "error"));
|
||||
});
|
||||
}
|
||||
|
||||
$("refresh").addEventListener("click", fetchAudit);
|
||||
fetchAudit();
|
||||
})();
|
||||
</script>
|
||||
</body>
|
||||
</html>
|
||||
@@ -1,10 +0,0 @@
|
||||
name: l1-api-gateway
|
||||
kind: l1
|
||||
description: HTTP routing primitive
|
||||
inputs:
|
||||
api_name:
|
||||
description: Name of the API Gateway REST/HTTP API
|
||||
type: string
|
||||
stage_name:
|
||||
description: Name of the deployment stage (e.g. dev, prod)
|
||||
type: string
|
||||
@@ -1,6 +0,0 @@
|
||||
#!/usr/bin/env bash
|
||||
set -euo pipefail
|
||||
echo "[L1: l1-api-gateway] applying..."
|
||||
sleep 1
|
||||
echo "[L1: l1-api-gateway] OK"
|
||||
exit 0
|
||||
@@ -1,10 +0,0 @@
|
||||
name: l1-cloudwatch
|
||||
kind: l1
|
||||
description: Observability primitive
|
||||
inputs:
|
||||
log_group_name:
|
||||
description: Name of the CloudWatch log group
|
||||
type: string
|
||||
metric_namespace:
|
||||
description: Namespace under which custom metrics are emitted
|
||||
type: string
|
||||
@@ -1,6 +0,0 @@
|
||||
#!/usr/bin/env bash
|
||||
set -euo pipefail
|
||||
echo "[L1: l1-cloudwatch] applying..."
|
||||
sleep 1
|
||||
echo "[L1: l1-cloudwatch] OK"
|
||||
exit 0
|
||||
@@ -1,13 +0,0 @@
|
||||
name: l1-eks-fargate
|
||||
kind: l1
|
||||
description: Serverless container compute substrate
|
||||
inputs:
|
||||
cluster_name:
|
||||
description: Name of the EKS cluster to target
|
||||
type: string
|
||||
region:
|
||||
description: AWS region the cluster runs in
|
||||
type: string
|
||||
cpu_arch:
|
||||
description: CPU architecture for Fargate pods (x86_64 or arm64)
|
||||
type: string
|
||||
@@ -1,6 +0,0 @@
|
||||
#!/usr/bin/env bash
|
||||
set -euo pipefail
|
||||
echo "[L1: l1-eks-fargate] applying..."
|
||||
sleep 1
|
||||
echo "[L1: l1-eks-fargate] OK"
|
||||
exit 0
|
||||
@@ -1,10 +0,0 @@
|
||||
name: l1-eventbridge
|
||||
kind: l1
|
||||
description: Event bus primitive
|
||||
inputs:
|
||||
bus_name:
|
||||
description: Name of the EventBridge bus
|
||||
type: string
|
||||
rule_name:
|
||||
description: Name of the event rule on the bus
|
||||
type: string
|
||||
@@ -1,6 +0,0 @@
|
||||
#!/usr/bin/env bash
|
||||
set -euo pipefail
|
||||
echo "[L1: l1-eventbridge] applying..."
|
||||
sleep 1
|
||||
echo "[L1: l1-eventbridge] OK"
|
||||
exit 0
|
||||
@@ -1,10 +0,0 @@
|
||||
name: l1-iam-role
|
||||
kind: l1
|
||||
description: Identity and access role primitive
|
||||
inputs:
|
||||
role_name:
|
||||
description: Name of the IAM role to create
|
||||
type: string
|
||||
trust_policy:
|
||||
description: JSON trust policy document defining who can assume the role
|
||||
type: string
|
||||
@@ -1,6 +0,0 @@
|
||||
#!/usr/bin/env bash
|
||||
set -euo pipefail
|
||||
echo "[L1: l1-iam-role] applying..."
|
||||
sleep 1
|
||||
echo "[L1: l1-iam-role] OK"
|
||||
exit 0
|
||||
@@ -1,13 +0,0 @@
|
||||
name: l1-lambda
|
||||
kind: l1
|
||||
description: Event-driven function primitive
|
||||
inputs:
|
||||
function_name:
|
||||
description: Name of the Lambda function
|
||||
type: string
|
||||
runtime:
|
||||
description: Lambda runtime identifier (e.g. python3.12, nodejs20.x)
|
||||
type: string
|
||||
handler:
|
||||
description: Handler entrypoint in the form module.function
|
||||
type: string
|
||||
@@ -1,6 +0,0 @@
|
||||
#!/usr/bin/env bash
|
||||
set -euo pipefail
|
||||
echo "[L1: l1-lambda] applying..."
|
||||
sleep 1
|
||||
echo "[L1: l1-lambda] OK"
|
||||
exit 0
|
||||
@@ -1,13 +0,0 @@
|
||||
name: l1-s3
|
||||
kind: l1
|
||||
description: Object store primitive
|
||||
inputs:
|
||||
bucket_name:
|
||||
description: Globally unique name of the S3 bucket
|
||||
type: string
|
||||
region:
|
||||
description: AWS region the bucket lives in
|
||||
type: string
|
||||
retention_days:
|
||||
description: Number of days to retain objects before expiration
|
||||
type: string
|
||||
@@ -1,6 +0,0 @@
|
||||
#!/usr/bin/env bash
|
||||
set -euo pipefail
|
||||
echo "[L1: l1-s3] applying..."
|
||||
sleep 1
|
||||
echo "[L1: l1-s3] OK"
|
||||
exit 0
|
||||
@@ -1,10 +0,0 @@
|
||||
name: l1-sqs
|
||||
kind: l1
|
||||
description: Queue primitive
|
||||
inputs:
|
||||
queue_name:
|
||||
description: Name of the SQS queue
|
||||
type: string
|
||||
visibility_timeout:
|
||||
description: Visibility timeout in seconds for in-flight messages
|
||||
type: string
|
||||
@@ -1,6 +0,0 @@
|
||||
#!/usr/bin/env bash
|
||||
set -euo pipefail
|
||||
echo "[L1: l1-sqs] applying..."
|
||||
sleep 1
|
||||
echo "[L1: l1-sqs] OK"
|
||||
exit 0
|
||||
@@ -1,27 +0,0 @@
|
||||
name: l2-commodity-price-feed
|
||||
kind: l2
|
||||
description: Real-time commodity price ingestion from Platts
|
||||
l1s:
|
||||
- name: l1-eks-fargate
|
||||
inputs:
|
||||
cluster_name: price-feed-cluster
|
||||
region: us-east-1
|
||||
cpu_arch: arm64
|
||||
- name: l1-lambda
|
||||
inputs:
|
||||
function_name: price-ingest
|
||||
runtime: python3.11
|
||||
handler: index.handler
|
||||
- name: l1-api-gateway
|
||||
inputs:
|
||||
api_name: platts-price-api
|
||||
stage_name: dev
|
||||
- name: l1-eventbridge
|
||||
inputs:
|
||||
bus_name: price-events
|
||||
rule_name: price-publish-rule
|
||||
- name: l1-s3
|
||||
inputs:
|
||||
bucket_name: acdl-price-archive
|
||||
region: us-east-1
|
||||
retention_days: "90"
|
||||
@@ -1,27 +0,0 @@
|
||||
name: l2-energy-analytics-api
|
||||
kind: l2
|
||||
description: Historical energy analytics query API
|
||||
l1s:
|
||||
- name: l1-eks-fargate
|
||||
inputs:
|
||||
cluster_name: analytics-cluster
|
||||
region: us-east-1
|
||||
cpu_arch: arm64
|
||||
- name: l1-api-gateway
|
||||
inputs:
|
||||
api_name: energy-analytics-api
|
||||
stage_name: dev
|
||||
- name: l1-lambda
|
||||
inputs:
|
||||
function_name: analytics-query
|
||||
runtime: python3.11
|
||||
handler: index.handler
|
||||
- name: l1-s3
|
||||
inputs:
|
||||
bucket_name: acdl-analytics-data
|
||||
region: us-east-1
|
||||
retention_days: "2555"
|
||||
- name: l1-cloudwatch
|
||||
inputs:
|
||||
log_group_name: /acdl/analytics-api
|
||||
metric_namespace: acdl/analytics
|
||||
@@ -1,27 +0,0 @@
|
||||
name: l2-invoice-service
|
||||
kind: l2
|
||||
description: Billing and invoicing microservice for energy trades
|
||||
l1s:
|
||||
- name: l1-eks-fargate
|
||||
inputs:
|
||||
cluster_name: invoice-cluster
|
||||
region: us-east-1
|
||||
cpu_arch: arm64
|
||||
- name: l1-iam-role
|
||||
inputs:
|
||||
role_name: invoice-service-role
|
||||
trust_policy: '{"Version":"2012-10-17","Statement":[{"Effect":"Allow","Principal":{"Service":"eks.amazonaws.com"},"Action":"sts:AssumeRole"}]}'
|
||||
- name: l1-lambda
|
||||
inputs:
|
||||
function_name: invoice-generator
|
||||
runtime: python3.11
|
||||
handler: index.handler
|
||||
- name: l1-sqs
|
||||
inputs:
|
||||
queue_name: invoice-queue
|
||||
visibility_timeout: "60"
|
||||
- name: l1-s3
|
||||
inputs:
|
||||
bucket_name: acdl-invoice-archive
|
||||
region: us-east-1
|
||||
retention_days: "365"
|
||||
@@ -1,27 +0,0 @@
|
||||
name: l2-regulatory-reporting
|
||||
kind: l2
|
||||
description: Regulatory compliance and reporting for energy trading
|
||||
l1s:
|
||||
- name: l1-eks-fargate
|
||||
inputs:
|
||||
cluster_name: regulatory-cluster
|
||||
region: us-east-1
|
||||
cpu_arch: arm64
|
||||
- name: l1-iam-role
|
||||
inputs:
|
||||
role_name: regulatory-reporting-role
|
||||
trust_policy: '{"Version":"2012-10-17","Statement":[{"Effect":"Allow","Principal":{"Service":"eks.amazonaws.com"},"Action":"sts:AssumeRole"}]}'
|
||||
- name: l1-lambda
|
||||
inputs:
|
||||
function_name: regulatory-reporter
|
||||
runtime: python3.11
|
||||
handler: index.handler
|
||||
- name: l1-sqs
|
||||
inputs:
|
||||
queue_name: regulatory-queue
|
||||
visibility_timeout: "120"
|
||||
- name: l1-s3
|
||||
inputs:
|
||||
bucket_name: acdl-regulatory-archive
|
||||
region: us-east-1
|
||||
retention_days: "2555"
|
||||
@@ -1,55 +0,0 @@
|
||||
#!/usr/bin/env python3
|
||||
"""confidence_signal.py — REQ-08 / D-024
|
||||
|
||||
Reads a contract.yaml, invokes policy_checker.py as a subprocess, and emits
|
||||
a deterministic JSON confidence score.
|
||||
|
||||
policy pass -> {"score": 0.90, "reason": "POLICY_PASS"}
|
||||
policy fail -> {"score": 0.40, "reason": "<violation code>"}
|
||||
|
||||
Exit 0 ALWAYS (per D-024): the pipeline decides the gate, not this script's
|
||||
exit code.
|
||||
|
||||
Input: argv[1] = path to a contract.yaml file.
|
||||
"""
|
||||
import json
|
||||
import os
|
||||
import subprocess
|
||||
import sys
|
||||
|
||||
|
||||
def main() -> int:
|
||||
if len(sys.argv) < 2:
|
||||
print("usage: confidence_signal.py <contract.yaml>", file=sys.stderr)
|
||||
return 1
|
||||
|
||||
contract_path = sys.argv[1]
|
||||
|
||||
# Resolve policy_checker.py relative to this script so it works regardless
|
||||
# of cwd. Use python3 + script path (not ./) per the contract.
|
||||
here = os.path.dirname(os.path.abspath(__file__))
|
||||
policy_checker = os.path.join(here, "policy_checker.py")
|
||||
|
||||
proc = subprocess.run(
|
||||
["python3", policy_checker, contract_path],
|
||||
capture_output=True,
|
||||
text=True,
|
||||
)
|
||||
|
||||
if proc.returncode == 0:
|
||||
score = "0.90"
|
||||
# POLICY_PASS is the expected stdout; strip any trailing whitespace.
|
||||
reason = proc.stdout.strip() or "POLICY_PASS"
|
||||
else:
|
||||
score = "0.40"
|
||||
# The violation code (e.g. "POLICY_VIOLATION:PUBLIC_INGRESS") is on stdout.
|
||||
reason = proc.stdout.strip() or "POLICY_VIOLATION:UNKNOWN"
|
||||
|
||||
# Emit with literal score (two-decimal form per the contract) and a quoted
|
||||
# reason. Constructed manually so json.dumps does not collapse 0.90 -> 0.9.
|
||||
print('{"score": ' + score + ', "reason": ' + json.dumps(reason) + '}')
|
||||
return 0
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
sys.exit(main())
|
||||
@@ -1,123 +0,0 @@
|
||||
#!/usr/bin/env python3
|
||||
"""evidence_writer.py — REQ-11 / D-023 / D-005
|
||||
|
||||
Appends a hash-chained event to audit.json.
|
||||
|
||||
Each event: {"seq": N, "ts": <iso8601 UTC>, "stage": "...", "event": "...",
|
||||
"prev_hash": "<sha256 or GENESIS>", "hash": "<sha256 of canonical json of this event with hash empty>"}
|
||||
|
||||
Hash chain (D-023):
|
||||
1. Build event dict with hash = "" (empty string).
|
||||
2. canonical = json.dumps(event, sort_keys=True, separators=(",", ":"))
|
||||
3. hash = sha256(canonical.encode("utf-8")).hexdigest()
|
||||
4. event["hash"] = hash
|
||||
5. append to audit.json
|
||||
|
||||
Auto-genesis: if audit.json is empty/missing and --stage is not "genesis",
|
||||
a genesis event (seq 0, prev_hash "GENESIS") is inserted first.
|
||||
|
||||
Input:
|
||||
--stage <dev|qa|prod|finalize|genesis> (required)
|
||||
--event "<text>" (required)
|
||||
--audit <path> (optional, default ./audit.json)
|
||||
Output: stdout {"seq": N, "hash": "..."}
|
||||
Exit: 0 on success, 1 on I/O error.
|
||||
"""
|
||||
import argparse
|
||||
import datetime
|
||||
import hashlib
|
||||
import json
|
||||
import os
|
||||
import sys
|
||||
|
||||
GENESIS_EVENT_TEXT = "audit log initialized"
|
||||
|
||||
|
||||
def now_iso8601_utc() -> str:
|
||||
return datetime.datetime.now(datetime.timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
|
||||
|
||||
|
||||
def compute_hash(event: dict) -> str:
|
||||
"""Compute the sha256 hash of an event using canonical JSON (D-023)."""
|
||||
tmp = dict(event)
|
||||
tmp["hash"] = ""
|
||||
canonical = json.dumps(tmp, sort_keys=True, separators=(",", ":"))
|
||||
return hashlib.sha256(canonical.encode("utf-8")).hexdigest()
|
||||
|
||||
|
||||
def make_event(seq: int, stage: str, event_text: str, prev_hash: str) -> dict:
|
||||
event = {
|
||||
"seq": seq,
|
||||
"ts": now_iso8601_utc(),
|
||||
"stage": stage,
|
||||
"event": event_text,
|
||||
"prev_hash": prev_hash,
|
||||
"hash": "",
|
||||
}
|
||||
event["hash"] = compute_hash(event)
|
||||
return event
|
||||
|
||||
|
||||
def load_audit(audit_path: str) -> list:
|
||||
if not os.path.exists(audit_path):
|
||||
return []
|
||||
try:
|
||||
with open(audit_path, "r", encoding="utf-8") as fh:
|
||||
data = json.load(fh)
|
||||
except (json.JSONDecodeError, ValueError):
|
||||
return []
|
||||
if not isinstance(data, list):
|
||||
return []
|
||||
return data
|
||||
|
||||
|
||||
def atomic_write(audit_path: str, data: list) -> None:
|
||||
tmp_path = audit_path + ".tmp"
|
||||
with open(tmp_path, "w", encoding="utf-8") as fh:
|
||||
json.dump(data, fh, indent=2)
|
||||
fh.write("\n")
|
||||
os.replace(tmp_path, audit_path)
|
||||
|
||||
|
||||
def main() -> int:
|
||||
parser = argparse.ArgumentParser(description="Append a hash-chained event to audit.json")
|
||||
parser.add_argument("--stage", required=True,
|
||||
choices=["dev", "qa", "prod", "finalize", "genesis"])
|
||||
parser.add_argument("--event", required=True)
|
||||
parser.add_argument("--audit", default="./audit.json")
|
||||
args = parser.parse_args()
|
||||
|
||||
events = load_audit(args.audit)
|
||||
|
||||
# Auto-genesis: if the log is empty and the caller did not ask for a
|
||||
# genesis event, seed one first.
|
||||
if len(events) == 0 and args.stage != "genesis":
|
||||
genesis = make_event(seq=0, stage="genesis", event_text=GENESIS_EVENT_TEXT,
|
||||
prev_hash="GENESIS")
|
||||
events.append(genesis)
|
||||
|
||||
# Determine the new seq + prev_hash.
|
||||
if events:
|
||||
last = events[-1]
|
||||
seq = last["seq"] + 1
|
||||
prev_hash = last["hash"]
|
||||
else:
|
||||
seq = 0
|
||||
prev_hash = "GENESIS"
|
||||
|
||||
new_event = make_event(seq=seq, stage=args.stage, event_text=args.event,
|
||||
prev_hash=prev_hash)
|
||||
events.append(new_event)
|
||||
|
||||
try:
|
||||
atomic_write(args.audit, events)
|
||||
except OSError as exc:
|
||||
print(f"evidence_writer: I/O error: {exc}", file=sys.stderr)
|
||||
return 1
|
||||
|
||||
print(json.dumps({"seq": new_event["seq"], "hash": new_event["hash"]}))
|
||||
return 0
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
sys.exit(main())
|
||||
@@ -1,182 +0,0 @@
|
||||
#!/usr/bin/env python3
|
||||
"""finalize_evidence.py — REQ-10 / D-028 / D-029
|
||||
|
||||
Uploads (PUT or POST) a local `audit.json` to the `acdl-evidence` repo on
|
||||
Gitea via the file-contents API. Used by the pipeline workflow steps to
|
||||
persist the hash-chained audit trail to `acdl-evidence` between dispatches
|
||||
(D-028 state-persistence across re-dispatches; D-029 finalize step).
|
||||
|
||||
Uses only the Python standard library (urllib.request) so it has no
|
||||
external dependency on `requests`. Auth header: `Authorization: token <token>`.
|
||||
|
||||
Input (argv flags):
|
||||
--audit <path> (required) local audit.json file to upload
|
||||
--owner <org> (optional, default continuous-intelligence)
|
||||
--repo <name> (optional, default acdl-evidence)
|
||||
--branch <name> (optional, default main)
|
||||
--path <remote path> (optional, default audit.json) path in the repo
|
||||
--token-env <env var> (optional, default ACDL_GITEA_TOKEN)
|
||||
--host <url> (optional, default https://git.cloudinit.dev)
|
||||
--message <commit msg> (optional, default chore(evidence): update audit.json)
|
||||
|
||||
Behavior:
|
||||
1. Read the token from os.environ[token_env]. Missing -> stderr + exit 1.
|
||||
2. Read the local audit file; base64-encode it.
|
||||
3. GET the current file at .../contents/<path>?ref=<branch> to discover
|
||||
the existing `sha`. 200 -> capture sha (update mode). 404 -> no sha
|
||||
(create mode). Other errors -> exit 1.
|
||||
4. If sha set: PUT with body {content, message, branch, sha}.
|
||||
If no sha: POST with body {content, message, branch}.
|
||||
5. Print {"uploaded": true, "path": "<path>", "sha": "<new sha>"} to
|
||||
stdout and exit 0.
|
||||
6. On any HTTP error: print
|
||||
{"uploaded": false, "status": <code>, "body": "<body>"} to stdout
|
||||
and exit 1.
|
||||
"""
|
||||
import argparse
|
||||
import base64
|
||||
import json
|
||||
import os
|
||||
import sys
|
||||
import urllib.error
|
||||
import urllib.parse
|
||||
import urllib.request
|
||||
|
||||
|
||||
def _request(method: str, url: str, token: str, body: dict = None):
|
||||
"""Perform an HTTP request with the Gitea auth header. Returns
|
||||
(status_code, response_body_text). Raises URLError on network failure."""
|
||||
data = None
|
||||
headers = {"Authorization": f"token {token}",
|
||||
"Accept": "application/json"}
|
||||
if body is not None:
|
||||
data = json.dumps(body).encode("utf-8")
|
||||
headers["Content-Type"] = "application/json"
|
||||
req = urllib.request.Request(url, data=data, method=method, headers=headers)
|
||||
try:
|
||||
with urllib.request.urlopen(req) as resp:
|
||||
return resp.getcode(), resp.read().decode("utf-8", "replace")
|
||||
except urllib.error.HTTPError as exc:
|
||||
# HTTPError carries the response body
|
||||
try:
|
||||
body_text = exc.read().decode("utf-8", "replace")
|
||||
except Exception:
|
||||
body_text = ""
|
||||
return exc.code, body_text
|
||||
except urllib.error.URLError as exc:
|
||||
# Network-level failure (connection refused, DNS, timeout). Return
|
||||
# a synthetic 0 status + the reason so callers can report cleanly
|
||||
# without a stack trace.
|
||||
return 0, f"URLError: {exc.reason}"
|
||||
|
||||
|
||||
def get_existing_sha(host: str, owner: str, repo: str, path: str,
|
||||
branch: str, token: str):
|
||||
"""Return (sha-or-None, error_status_or_None). On 200 returns the sha.
|
||||
On 404 returns (None, None). Other codes return (None, (status, body))."""
|
||||
qs = urllib.parse.urlencode({"ref": branch})
|
||||
url = f"{host}/api/v1/repos/{owner}/{repo}/contents/{path}?{qs}"
|
||||
status, body = _request("GET", url, token)
|
||||
if status == 200:
|
||||
try:
|
||||
data = json.loads(body)
|
||||
return data.get("sha"), None
|
||||
except (ValueError, TypeError):
|
||||
return None, (status, body)
|
||||
if status == 404:
|
||||
return None, None
|
||||
return None, (status, body)
|
||||
|
||||
|
||||
def upload(host: str, owner: str, repo: str, path: str, branch: str,
|
||||
message: str, content_b64: str, sha, token: str):
|
||||
"""PUT (update) or POST (create) the file. Returns (new_sha, None) on
|
||||
success or (None, (status, body)) on HTTP error."""
|
||||
url = f"{host}/api/v1/repos/{owner}/{repo}/contents/{path}"
|
||||
if sha:
|
||||
body = {"content": content_b64, "message": message,
|
||||
"branch": branch, "sha": sha}
|
||||
status, resp = _request("PUT", url, token, body)
|
||||
else:
|
||||
body = {"content": content_b64, "message": message, "branch": branch}
|
||||
status, resp = _request("POST", url, token, body)
|
||||
if status in (200, 201):
|
||||
try:
|
||||
data = json.loads(resp)
|
||||
# The file-contents API returns the new content object either at
|
||||
# top-level `content` (POST create) or `content` (PUT update).
|
||||
new_sha = None
|
||||
if isinstance(data, dict):
|
||||
content_obj = data.get("content") or data
|
||||
if isinstance(content_obj, dict):
|
||||
new_sha = content_obj.get("sha")
|
||||
return new_sha, None
|
||||
except (ValueError, TypeError):
|
||||
return None, None
|
||||
return None, (status, resp)
|
||||
|
||||
|
||||
def main() -> int:
|
||||
parser = argparse.ArgumentParser(
|
||||
description="Upload a local audit.json to the acdl-evidence Gitea "
|
||||
"repo via the file-contents API (D-028/D-029).")
|
||||
parser.add_argument("--audit", required=True,
|
||||
help="Local audit.json file to upload")
|
||||
parser.add_argument("--owner", default="continuous-intelligence",
|
||||
help="Gitea org (default: continuous-intelligence)")
|
||||
parser.add_argument("--repo", default="acdl-evidence",
|
||||
help="Gitea repo (default: acdl-evidence)")
|
||||
parser.add_argument("--branch", default="main",
|
||||
help="Target branch (default: main)")
|
||||
parser.add_argument("--path", default="audit.json",
|
||||
help="Remote path in the repo (default: audit.json)")
|
||||
parser.add_argument("--token-env", default="ACDL_GITEA_TOKEN",
|
||||
help="Env var name holding the Gitea token "
|
||||
"(default: ACDL_GITEA_TOKEN)")
|
||||
parser.add_argument("--host", default="https://git.cloudinit.dev",
|
||||
help="Gitea host URL (default: https://git.cloudinit.dev)")
|
||||
parser.add_argument("--message", default="chore(evidence): update audit.json",
|
||||
help="Commit message (default: chore(evidence): "
|
||||
"update audit.json)")
|
||||
args = parser.parse_args()
|
||||
|
||||
token = os.environ.get(args.token_env)
|
||||
if not token:
|
||||
print(f"finalize_evidence: required env var {args.token_env} is not "
|
||||
f"set", file=sys.stderr)
|
||||
return 1
|
||||
|
||||
# Read + base64-encode the local audit file. Missing/unreadable file is
|
||||
# a clean exit 1 (no stack trace).
|
||||
try:
|
||||
with open(args.audit, "rb") as fh:
|
||||
raw = fh.read()
|
||||
except OSError as exc:
|
||||
print(f"finalize_evidence: cannot read {args.audit}: {exc}",
|
||||
file=sys.stderr)
|
||||
return 1
|
||||
content_b64 = base64.b64encode(raw).decode("ascii")
|
||||
|
||||
# Discover existing sha (update vs create).
|
||||
sha, err = get_existing_sha(args.host, args.owner, args.repo,
|
||||
args.path, args.branch, token)
|
||||
if err is not None:
|
||||
status, body = err
|
||||
print(json.dumps({"uploaded": False, "status": status, "body": body}))
|
||||
return 1
|
||||
|
||||
# Upload (PUT if sha, POST otherwise).
|
||||
new_sha, err = upload(args.host, args.owner, args.repo, args.path,
|
||||
args.branch, args.message, content_b64, sha, token)
|
||||
if err is not None:
|
||||
status, body = err
|
||||
print(json.dumps({"uploaded": False, "status": status, "body": body}))
|
||||
return 1
|
||||
|
||||
print(json.dumps({"uploaded": True, "path": args.path,
|
||||
"sha": new_sha}))
|
||||
return 0
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
sys.exit(main())
|
||||
@@ -1,228 +0,0 @@
|
||||
#!/usr/bin/env bash
|
||||
# Phase 01 Gitea scaffolding. Idempotent.
|
||||
#
|
||||
# Creates the two new repos under the continuous-intelligence org, pushes a
|
||||
# placeholder index.html to acdl-evidence, and creates qa + prod branches on
|
||||
# acdl-contracts. Running against existing repos / branches / files is a
|
||||
# no-op (409 or 422 is treated as success).
|
||||
#
|
||||
# Usage: ACDL_GITEA_TOKEN=<token> scripts/gitea_setup.sh
|
||||
# Exit codes: 0 = success (created or already existed); 1 = unrecoverable error.
|
||||
|
||||
set -euo pipefail
|
||||
|
||||
GITEA_HOST="${GITEA_HOST:-https://git.cloudinit.dev}"
|
||||
ORG="continuous-intelligence"
|
||||
TOKEN="${ACDL_GITEA_TOKEN:?ACDL_GITEA_TOKEN is required}"
|
||||
API="${GITEA_HOST}/api/v1"
|
||||
|
||||
AUTH=(-H "Authorization: token ${TOKEN}" -H "Content-Type: application/json")
|
||||
|
||||
log() { printf '[setup] %s\n' "$*"; }
|
||||
warn() { printf '[setup][WARN] %s\n' "$*" >&2; }
|
||||
err() { printf '[setup][ERROR] %s\n' "$*" >&2; }
|
||||
|
||||
# --- helpers ----------------------------------------------------------------
|
||||
|
||||
# http_status_code URL
|
||||
http_get_status() {
|
||||
local url="$1"
|
||||
curl -sS -o /dev/null -w "%{http_code}" "${AUTH[@]}" "$url"
|
||||
}
|
||||
|
||||
# repo_exists NAME -> 0 if exists, 1 otherwise
|
||||
repo_exists() {
|
||||
local name="$1"
|
||||
local status
|
||||
status=$(http_get_status "${API}/repos/${ORG}/${name}")
|
||||
[ "$status" = "200" ]
|
||||
}
|
||||
|
||||
# create_repo NAME DESCRIPTION
|
||||
create_repo() {
|
||||
local name="$1"
|
||||
local description="$2"
|
||||
local body
|
||||
body=$(python3 -c "
|
||||
import json, sys
|
||||
print(json.dumps({
|
||||
'name': '${name}',
|
||||
'description': ${description@Q},
|
||||
'private': True,
|
||||
'default_branch': 'main',
|
||||
'auto_init': True,
|
||||
'gitignores': 'Python',
|
||||
'license': '',
|
||||
'readme': 'Default'
|
||||
}))
|
||||
")
|
||||
log "Creating repo ${ORG}/${name} (default_branch=main, auto_init=true)"
|
||||
local status body_out
|
||||
status=$(curl -sS -o /tmp/setup_repo_create.json -w "%{http_code}" \
|
||||
"${AUTH[@]}" -X POST -d "$body" \
|
||||
"${API}/orgs/${ORG}/repos")
|
||||
case "$status" in
|
||||
201) log " created (HTTP 201)" ;;
|
||||
409) log " already exists (HTTP 409); skipping" ;;
|
||||
*)
|
||||
err "create_repo ${name} failed: HTTP ${status}"
|
||||
cat /tmp/setup_repo_create.json >&2 || true
|
||||
return 1
|
||||
;;
|
||||
esac
|
||||
}
|
||||
|
||||
# set_repo_visibility REPO VISIBILITY (public|private)
|
||||
set_repo_visibility() {
|
||||
local repo="$1"
|
||||
local visibility="$2"
|
||||
local body
|
||||
body=$(python3 -c "
|
||||
import json
|
||||
is_private = ('${visibility}' == 'private')
|
||||
print(json.dumps({'private': is_private, 'visibility': '${visibility}'}))
|
||||
")
|
||||
log "Setting ${repo} visibility to ${visibility}"
|
||||
local status
|
||||
status=$(curl -sS -o /tmp/setup_vis.json -w "%{http_code}" \
|
||||
"${AUTH[@]}" -X PATCH -d "$body" \
|
||||
"${API}/repos/${ORG}/${repo}")
|
||||
case "$status" in
|
||||
200) log " ok (HTTP 200)" ;;
|
||||
*) warn "set_repo_visibility ${repo} -> ${visibility} returned HTTP ${status} (continuing)"; cat /tmp/setup_vis.json >&2 || true ;;
|
||||
esac
|
||||
}
|
||||
|
||||
# file_exists REPO PATH -> 0 if the file already exists on the default branch
|
||||
file_exists_on_default() {
|
||||
local repo="$1"
|
||||
local path="$2"
|
||||
local status
|
||||
status=$(http_get_status "${API}/repos/${ORG}/${repo}/contents/${path}?ref=main")
|
||||
[ "$status" = "200" ]
|
||||
}
|
||||
|
||||
# create_placeholder_index REPO
|
||||
create_placeholder_index() {
|
||||
local repo="$1"
|
||||
local path="index.html"
|
||||
local placeholder
|
||||
placeholder='<!DOCTYPE html>
|
||||
<html lang="en">
|
||||
<head>
|
||||
<meta charset="utf-8">
|
||||
<title>ACDL Evidence</title>
|
||||
<style>body{font-family:system-ui,sans-serif;margin:2rem;color:#333}</style>
|
||||
</head>
|
||||
<body>
|
||||
<h1>ACDL Evidence Stream</h1>
|
||||
<p>Evidence timeline will appear here in Phase 05.</p>
|
||||
<p>Placeholder served via Gitea raw file URL (D-012; Gitea has no native Pages).</p>
|
||||
</body>
|
||||
</html>'
|
||||
|
||||
if file_exists_on_default "$repo" "$path"; then
|
||||
log "index.html already exists on ${repo} main; skipping"
|
||||
return 0
|
||||
fi
|
||||
|
||||
local body
|
||||
body=$(python3 -c "
|
||||
import json, base64
|
||||
content = '''${placeholder}'''
|
||||
print(json.dumps({
|
||||
'content': base64.b64encode(content.encode('utf-8')).decode('ascii'),
|
||||
'message': 'Initial placeholder index.html (Phase 01, D-016)',
|
||||
'branch': 'main'
|
||||
}))
|
||||
")
|
||||
log "Pushing placeholder index.html to ${repo} main"
|
||||
local status
|
||||
status=$(curl -sS -o /tmp/setup_index_push.json -w "%{http_code}" \
|
||||
"${AUTH[@]}" -X POST -d "$body" \
|
||||
"${API}/repos/${ORG}/${repo}/contents/${path}")
|
||||
case "$status" in
|
||||
201) log " pushed (HTTP 201)" ;;
|
||||
409|422) log " already exists or conflict (HTTP ${status}); skipping" ;;
|
||||
*)
|
||||
err "create_placeholder_index on ${repo} failed: HTTP ${status}"
|
||||
cat /tmp/setup_index_push.json >&2 || true
|
||||
return 1
|
||||
;;
|
||||
esac
|
||||
}
|
||||
|
||||
# branch_exists REPO BRANCH -> 0 if exists
|
||||
branch_exists() {
|
||||
local repo="$1"
|
||||
local branch="$2"
|
||||
local status
|
||||
status=$(http_get_status "${API}/repos/${ORG}/${repo}/branches/${branch}")
|
||||
[ "$status" = "200" ]
|
||||
}
|
||||
|
||||
# create_branch REPO BRANCH FROM_REF
|
||||
create_branch() {
|
||||
local repo="$1"
|
||||
local branch="$2"
|
||||
local from_ref="$3"
|
||||
if branch_exists "$repo" "$branch"; then
|
||||
log "Branch ${branch} already exists on ${repo}; skipping"
|
||||
return 0
|
||||
fi
|
||||
local body
|
||||
body=$(python3 -c "
|
||||
import json
|
||||
print(json.dumps({'new_branch_name': '${branch}', 'old_branch_name': '${from_ref}'}))
|
||||
")
|
||||
log "Creating branch ${branch} on ${repo} from ${from_ref}"
|
||||
local status
|
||||
status=$(curl -sS -o /tmp/setup_branch.json -w "%{http_code}" \
|
||||
"${AUTH[@]}" -X POST -d "$body" \
|
||||
"${API}/repos/${ORG}/${repo}/branches")
|
||||
case "$status" in
|
||||
201) log " created (HTTP 201)" ;;
|
||||
409) log " already exists (HTTP 409); skipping" ;;
|
||||
*)
|
||||
err "create_branch ${branch} on ${repo} failed: HTTP ${status}"
|
||||
cat /tmp/setup_branch.json >&2 || true
|
||||
return 1
|
||||
;;
|
||||
esac
|
||||
}
|
||||
|
||||
# --- main -------------------------------------------------------------------
|
||||
|
||||
log "Host: ${GITEA_HOST}"
|
||||
log "Org: ${ORG}"
|
||||
log "Token: <set, ${#TOKEN} chars>"
|
||||
|
||||
# Step 1: create acdl-contracts
|
||||
if ! repo_exists acdl-contracts; then
|
||||
create_repo acdl-contracts "ACDL developer + agentic entry surface (contract.yaml + issue trigger)" || exit 1
|
||||
else
|
||||
log "acdl-contracts already exists; skipping create"
|
||||
fi
|
||||
|
||||
# Step 2: create acdl-evidence
|
||||
if ! repo_exists acdl-evidence; then
|
||||
create_repo acdl-evidence "ACDL hash-chained audit timeline served as a static site via raw file URLs" || exit 1
|
||||
else
|
||||
log "acdl-evidence already exists; skipping create"
|
||||
fi
|
||||
|
||||
# Step 2b: make acdl-evidence public so the Phase 05 UI (index.html) can
|
||||
# fetch audit.json from a browser without exposing the API token (D-012
|
||||
# raw-URL approach). acdl-contracts stays private.
|
||||
set_repo_visibility acdl-evidence public
|
||||
|
||||
# Step 3: push placeholder index.html to acdl-evidence
|
||||
create_placeholder_index acdl-evidence || exit 1
|
||||
|
||||
# Step 4: create qa + prod branches on acdl-contracts (visible stand-in for
|
||||
# the unsupported Gitea environments API; per D-013).
|
||||
create_branch acdl-contracts qa main || exit 1
|
||||
create_branch acdl-contracts prod main || exit 1
|
||||
|
||||
log "Done. Run scripts/verify_phase01.sh to confirm success criteria."
|
||||
exit 0
|
||||
@@ -1,118 +0,0 @@
|
||||
#!/usr/bin/env python3
|
||||
"""l3b_agent_stub.py — D-008 / D-026 / D-021
|
||||
|
||||
Parses a GitHub/Gitea Issue body by keywords and emits a contract.yaml that
|
||||
selects an L2 stack. This is the agentic (L3B) entry surface: deterministic
|
||||
keyword matching, no external AI APIs.
|
||||
|
||||
D-008 keyword map (priority order — first match wins):
|
||||
gas, price, ingest, data-lake -> l2-commodity-price-feed
|
||||
invoice, billing -> l2-invoice-service
|
||||
analytics, historical, query -> l2-energy-analytics-api
|
||||
regulatory, compliance, reporting, trading
|
||||
-> l2-regulatory-reporting
|
||||
(no match) -> l2-invoice-service (fallback)
|
||||
|
||||
Output contract.yaml (D-021 schema):
|
||||
stack: <mapped L2 name>
|
||||
inputs:
|
||||
environment: dev
|
||||
owner: citizen-developer
|
||||
source: l3b-agent-stub
|
||||
public-ingress: false
|
||||
|
||||
Input:
|
||||
argv[1] = issue body text (or stdin if argv[1] absent/empty)
|
||||
-o <path> = write the contract to a file (default: stdout)
|
||||
Exit:
|
||||
0 on success, 1 on empty input
|
||||
"""
|
||||
import sys
|
||||
|
||||
|
||||
# Ordered keyword groups -> L2 stack mapping (D-008). First match wins.
|
||||
KEYWORD_MAP = [
|
||||
(("gas", "price", "ingest", "data-lake"), "l2-commodity-price-feed"),
|
||||
(("invoice", "billing"), "l2-invoice-service"),
|
||||
(("analytics", "historical", "query"), "l2-energy-analytics-api"),
|
||||
(("regulatory", "compliance", "reporting", "trading"), "l2-regulatory-reporting"),
|
||||
]
|
||||
|
||||
FALLBACK_STACK = "l2-invoice-service"
|
||||
|
||||
|
||||
def map_issue_to_stack(text: str) -> str:
|
||||
lowered = text.lower()
|
||||
for keywords, stack in KEYWORD_MAP:
|
||||
for kw in keywords:
|
||||
if kw in lowered:
|
||||
return stack
|
||||
return FALLBACK_STACK
|
||||
|
||||
|
||||
def render_contract(stack: str) -> str:
|
||||
# Fixed-schema YAML (D-021). Emitted as text (no yaml dependency needed).
|
||||
return (
|
||||
f"stack: {stack}\n"
|
||||
"inputs:\n"
|
||||
" environment: dev\n"
|
||||
" owner: citizen-developer\n"
|
||||
" source: l3b-agent-stub\n"
|
||||
"public-ingress: false\n"
|
||||
)
|
||||
|
||||
|
||||
def read_issue_body(args: list) -> str:
|
||||
"""Read issue body from args[0] (already-stripped argv, no script name)
|
||||
or stdin. Empty -> error."""
|
||||
if len(args) >= 1 and args[0].strip():
|
||||
return args[0]
|
||||
# Fall back to stdin if argv body is absent or empty.
|
||||
if not sys.stdin.isatty():
|
||||
data = sys.stdin.read()
|
||||
if data.strip():
|
||||
return data
|
||||
return ""
|
||||
|
||||
|
||||
def parse_output_flag(argv: list):
|
||||
"""Extract -o <path> from argv (returns (rest, output_path))."""
|
||||
output_path = None
|
||||
rest = []
|
||||
i = 1
|
||||
while i < len(argv):
|
||||
arg = argv[i]
|
||||
if arg == "-o":
|
||||
if i + 1 < len(argv):
|
||||
output_path = argv[i + 1]
|
||||
i += 2
|
||||
continue
|
||||
else:
|
||||
print("l3b_agent_stub: -o requires a path argument", file=sys.stderr)
|
||||
sys.exit(1)
|
||||
rest.append(arg)
|
||||
i += 1
|
||||
return rest, output_path
|
||||
|
||||
|
||||
def main() -> int:
|
||||
rest, output_path = parse_output_flag(sys.argv)
|
||||
body = read_issue_body(rest)
|
||||
if not body.strip():
|
||||
print("l3b_agent_stub: empty issue body (no argv[1] and no stdin)", file=sys.stderr)
|
||||
return 1
|
||||
|
||||
stack = map_issue_to_stack(body)
|
||||
contract = render_contract(stack)
|
||||
|
||||
if output_path:
|
||||
with open(output_path, "w", encoding="utf-8") as fh:
|
||||
fh.write(contract)
|
||||
else:
|
||||
sys.stdout.write(contract)
|
||||
|
||||
return 0
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
sys.exit(main())
|
||||
@@ -1,126 +0,0 @@
|
||||
#!/usr/bin/env bash
|
||||
# mock_executor.sh — REQ-06 / D-022
|
||||
#
|
||||
# Reads a contract.yaml, resolves the L2 composition, invokes each L1's
|
||||
# mock_apply.sh in order, and writes state.json to the current working
|
||||
# directory.
|
||||
#
|
||||
# Input: argv[1] = path to a contract.yaml file.
|
||||
# Output:
|
||||
# - stdout: per-L1 progress (echoed from each mock_apply.sh)
|
||||
# - state.json in cwd: {"l2": "...", "l1s": [...], "contract": {...}}
|
||||
# Exit:
|
||||
# 0 if all L1s exit 0; 1 if any L1 exited non-zero (state.json is still
|
||||
# written with the recorded exit codes).
|
||||
set -euo pipefail
|
||||
|
||||
if [[ $# -lt 1 ]]; then
|
||||
echo "usage: mock_executor.sh <contract.yaml>" >&2
|
||||
exit 1
|
||||
fi
|
||||
|
||||
CONTRACT_PATH="$1"
|
||||
|
||||
if [[ ! -f "$CONTRACT_PATH" ]]; then
|
||||
echo "contract not found: $CONTRACT_PATH" >&2
|
||||
exit 1
|
||||
fi
|
||||
|
||||
# --- Parse the contract (stack + full contract dict) via python3 + yaml. ---
|
||||
# Emit stack on line 1 and the full contract JSON on line 2, then read both
|
||||
# lines into separate bash variables (so the JSON's internal spaces survive).
|
||||
CONTRACT_PARSED=$(python3 - "$CONTRACT_PATH" <<'PY'
|
||||
import sys, json, yaml
|
||||
path = sys.argv[1]
|
||||
with open(path, "r", encoding="utf-8") as fh:
|
||||
contract = yaml.safe_load(fh)
|
||||
if not isinstance(contract, dict):
|
||||
sys.stderr.write("contract is not a mapping\n")
|
||||
sys.exit(2)
|
||||
stack = contract.get("stack", "")
|
||||
# Use a compact JSON (no spaces) so the single-line contract survives bash
|
||||
# variable capture cleanly.
|
||||
print(stack)
|
||||
print(json.dumps(contract, sort_keys=True, separators=(",", ":")))
|
||||
PY
|
||||
)
|
||||
|
||||
STACK=$(printf '%s\n' "$CONTRACT_PARSED" | sed -n '1p')
|
||||
CONTRACT_JSON=$(printf '%s\n' "$CONTRACT_PARSED" | sed -n '2p')
|
||||
|
||||
if [[ -z "$STACK" ]]; then
|
||||
echo "contract missing 'stack' key" >&2
|
||||
exit 1
|
||||
fi
|
||||
|
||||
# --- Resolve the L2 manifest. ---
|
||||
L2_MANIFEST="modules/l2/${STACK}/manifest.yaml"
|
||||
if [[ ! -f "$L2_MANIFEST" ]]; then
|
||||
echo "L2_NOT_FOUND: ${STACK}" >&2
|
||||
exit 1
|
||||
fi
|
||||
|
||||
# --- Read the L2's l1s: list (ordered names) via python. ---
|
||||
L1_NAMES_JSON=$(python3 - "$L2_MANIFEST" <<'PY'
|
||||
import sys, json, yaml
|
||||
path = sys.argv[1]
|
||||
with open(path, "r", encoding="utf-8") as fh:
|
||||
manifest = yaml.safe_load(fh)
|
||||
l1s = manifest.get("l1s", []) if isinstance(manifest, dict) else []
|
||||
names = [entry.get("name", "") for entry in l1s if isinstance(entry, dict)]
|
||||
print(json.dumps(names))
|
||||
PY
|
||||
)
|
||||
|
||||
# --- Invoke each L1's mock_apply.sh in order, recording exit codes. ---
|
||||
# Build the l1s results array in JSON via python, appending as we go.
|
||||
RESULTS_JSON="[]"
|
||||
|
||||
ALL_OK=0
|
||||
while IFS= read -r L1_NAME; do
|
||||
L1_SCRIPT="modules/l1/${L1_NAME}/mock_apply.sh"
|
||||
if [[ ! -f "$L1_SCRIPT" ]]; then
|
||||
echo "L1_NOT_FOUND: ${L1_NAME}" >&2
|
||||
exit 1
|
||||
fi
|
||||
|
||||
# Capture stdout + exit code. stderr passes through.
|
||||
L1_OUT=$(bash "$L1_SCRIPT")
|
||||
L1_RC=$?
|
||||
|
||||
# Echo the L1's stdout so the pipeline sees the progress lines.
|
||||
printf '%s\n' "$L1_OUT"
|
||||
|
||||
# Record {"name": ..., "applied": true, "exit_code": ...}.
|
||||
RESULTS_JSON=$(python3 - "$RESULTS_JSON" "$L1_NAME" "$L1_RC" <<'PY'
|
||||
import sys, json
|
||||
results = json.loads(sys.argv[1])
|
||||
name = sys.argv[2]
|
||||
rc = int(sys.argv[3])
|
||||
results.append({"name": name, "applied": True, "exit_code": rc})
|
||||
print(json.dumps(results))
|
||||
PY
|
||||
)
|
||||
|
||||
if [[ $L1_RC -ne 0 ]]; then
|
||||
ALL_OK=1
|
||||
fi
|
||||
done < <(python3 -c "import sys, json; print('\n'.join(json.loads(sys.argv[1])))" "$L1_NAMES_JSON")
|
||||
|
||||
# --- Write state.json to the current working directory (D-022). ---
|
||||
python3 - "$RESULTS_JSON" "$STACK" "$CONTRACT_JSON" <<'PY'
|
||||
import sys, json
|
||||
results = json.loads(sys.argv[1])
|
||||
stack = sys.argv[2]
|
||||
contract = json.loads(sys.argv[3])
|
||||
state = {
|
||||
"l2": stack,
|
||||
"l1s": results,
|
||||
"contract": contract,
|
||||
}
|
||||
with open("state.json", "w", encoding="utf-8") as fh:
|
||||
json.dump(state, fh, indent=2)
|
||||
fh.write("\n")
|
||||
PY
|
||||
|
||||
exit "$ALL_OK"
|
||||
@@ -1,51 +0,0 @@
|
||||
#!/usr/bin/env python3
|
||||
"""policy_checker.py — REQ-07 / D-025
|
||||
|
||||
Reads a contract.yaml and enforces the single Phase-03 policy rule:
|
||||
`public-ingress: true` is forbidden.
|
||||
|
||||
Input: argv[1] = path to a contract.yaml file.
|
||||
Output: stdout "POLICY_PASS" or "POLICY_VIOLATION:PUBLIC_INGRESS"
|
||||
Exit: 0 on pass, 1 on violation.
|
||||
|
||||
Idempotent, no side effects (no file writes). Treats an absent or falsy
|
||||
`public-ingress` key as a pass.
|
||||
"""
|
||||
import sys
|
||||
import yaml
|
||||
|
||||
|
||||
def main() -> int:
|
||||
if len(sys.argv) < 2:
|
||||
print("usage: policy_checker.py <contract.yaml>", file=sys.stderr)
|
||||
return 2
|
||||
|
||||
contract_path = sys.argv[1]
|
||||
|
||||
try:
|
||||
with open(contract_path, "r", encoding="utf-8") as fh:
|
||||
contract = yaml.safe_load(fh)
|
||||
except FileNotFoundError:
|
||||
print(f"contract not found: {contract_path}", file=sys.stderr)
|
||||
return 2
|
||||
except yaml.YAMLError as exc:
|
||||
print(f"invalid yaml: {exc}", file=sys.stderr)
|
||||
return 2
|
||||
|
||||
# Treat missing/non-mapping as no policy violation.
|
||||
if not isinstance(contract, dict):
|
||||
print("POLICY_PASS")
|
||||
return 0
|
||||
|
||||
public_ingress = contract.get("public-ingress", False)
|
||||
|
||||
if public_ingress is True:
|
||||
print("POLICY_VIOLATION:PUBLIC_INGRESS")
|
||||
return 1
|
||||
|
||||
print("POLICY_PASS")
|
||||
return 0
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
sys.exit(main())
|
||||
@@ -1,258 +0,0 @@
|
||||
#!/usr/bin/env bash
|
||||
# scripts/run_demo.sh — Phase 05 dry-run simulation of the 4 demo acts (T-5.2).
|
||||
#
|
||||
# Simulates the full 4-act demo locally (no act_runner) by calling the core
|
||||
# scripts in sequence and writing hash-chained evidence events to audit.json,
|
||||
# then optionally uploads audit.json + evidence-ui/index.html to acdl-evidence
|
||||
# main via finalize_evidence.py (D-031, D-033).
|
||||
#
|
||||
# Usage: scripts/run_demo.sh [--no-upload]
|
||||
# --no-upload skip the Gitea API calls (useful for testing without a token)
|
||||
|
||||
set -uo pipefail
|
||||
|
||||
# -----------------------------------------------------------------------------
|
||||
# Parse args
|
||||
# -----------------------------------------------------------------------------
|
||||
UPLOAD=1
|
||||
for arg in "$@"; do
|
||||
case "$arg" in
|
||||
--no-upload)
|
||||
UPLOAD=0
|
||||
;;
|
||||
*)
|
||||
echo "run_demo.sh: unknown argument: $arg" >&2
|
||||
echo "usage: scripts/run_demo.sh [--no-upload]" >&2
|
||||
exit 2
|
||||
;;
|
||||
esac
|
||||
done
|
||||
|
||||
# -----------------------------------------------------------------------------
|
||||
# Paths
|
||||
# -----------------------------------------------------------------------------
|
||||
# Repo root = location of this script's parent dir.
|
||||
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
|
||||
REPO_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
|
||||
|
||||
WORKDIR="/tmp/acdl_demo_run"
|
||||
AUDIT="$WORKDIR/audit.json"
|
||||
CONTRACTS="$WORKDIR/contracts"
|
||||
|
||||
# Track failures so we can return non-zero at the end (we do NOT use set -e
|
||||
# because policy_checker intentionally exits 1 on Act 4).
|
||||
FAIL=0
|
||||
|
||||
# -----------------------------------------------------------------------------
|
||||
# Helpers
|
||||
# -----------------------------------------------------------------------------
|
||||
|
||||
# Write one evidence event. Args: <stage> <event-text>
|
||||
ev() {
|
||||
local stage="$1"
|
||||
local text="$2"
|
||||
if ! python3 "$SCRIPT_DIR/evidence_writer.py" --stage "$stage" --event "$text" --audit "$AUDIT"; then
|
||||
echo "run_demo.sh: evidence_writer failed for stage=$stage text=$text" >&2
|
||||
FAIL=1
|
||||
fi
|
||||
}
|
||||
|
||||
# Run a contract through the Act 2/3 pipeline (policy -> confidence -> executor).
|
||||
# Assumes the contract already passed policy (caller verifies). Writes the
|
||||
# standard 4-event sequence. Args: <act-label> <dev-applied-event-text>
|
||||
run_passing_pipeline() {
|
||||
local dev_event="$1"
|
||||
|
||||
ev dev "$dev_event"
|
||||
ev qa "qa approved"
|
||||
ev prod "prod approved"
|
||||
ev finalize "finalize: audit.json committed to acdl-evidence"
|
||||
}
|
||||
|
||||
# -----------------------------------------------------------------------------
|
||||
# Setup working directory
|
||||
# -----------------------------------------------------------------------------
|
||||
mkdir -p "$CONTRACTS"
|
||||
rm -f "$AUDIT"
|
||||
|
||||
# -----------------------------------------------------------------------------
|
||||
# Initialize audit (genesis)
|
||||
# -----------------------------------------------------------------------------
|
||||
echo "== run_demo.sh: initializing audit at $AUDIT =="
|
||||
ev genesis "audit log initialized"
|
||||
|
||||
# -----------------------------------------------------------------------------
|
||||
# Act 1 — Friction
|
||||
# -----------------------------------------------------------------------------
|
||||
echo "== Act 1 — Friction =="
|
||||
ev dev "Act 1 Friction: manual 2-week deployment (legacy process)"
|
||||
|
||||
# -----------------------------------------------------------------------------
|
||||
# Act 2 — Developer Self-Service
|
||||
# -----------------------------------------------------------------------------
|
||||
echo "== Act 2 — Developer Self-Service =="
|
||||
cat > "$CONTRACTS/act2.yaml" <<'YAML'
|
||||
stack: l2-commodity-price-feed
|
||||
inputs:
|
||||
environment: dev
|
||||
owner: platform-team
|
||||
public-ingress: false
|
||||
YAML
|
||||
|
||||
ACT2_POLICY="$(python3 "$SCRIPT_DIR/policy_checker.py" "$CONTRACTS/act2.yaml")"
|
||||
ACT2_POLICY_RC=$?
|
||||
echo " policy_checker: $ACT2_POLICY (rc=$ACT2_POLICY_RC)"
|
||||
if [ "$ACT2_POLICY" != "POLICY_PASS" ]; then
|
||||
echo "run_demo.sh: Act 2 expected POLICY_PASS, got '$ACT2_POLICY'" >&2
|
||||
FAIL=1
|
||||
fi
|
||||
|
||||
ACT2_CONF="$(python3 "$SCRIPT_DIR/confidence_signal.py" "$CONTRACTS/act2.yaml")"
|
||||
echo " confidence_signal: $ACT2_CONF"
|
||||
# Expected: {"score": 0.90, "reason": "POLICY_PASS"}
|
||||
|
||||
# mock_executor.sh resolves modules/l2/<stack>/manifest.yaml relative to its
|
||||
# cwd, so it must run from the repo root. It writes state.json to its cwd;
|
||||
# clean it up from the repo root afterward so no stray file is left there.
|
||||
(
|
||||
cd "$REPO_ROOT" && bash "$SCRIPT_DIR/mock_executor.sh" "$CONTRACTS/act2.yaml"
|
||||
)
|
||||
MOCK_RC=$?
|
||||
rm -f "$REPO_ROOT/state.json"
|
||||
if [ "$MOCK_RC" -ne 0 ]; then
|
||||
echo "run_demo.sh: Act 2 mock_executor failed (rc=$MOCK_RC)" >&2
|
||||
FAIL=1
|
||||
fi
|
||||
|
||||
run_passing_pipeline "dev applied: l2-commodity-price-feed"
|
||||
|
||||
# -----------------------------------------------------------------------------
|
||||
# Act 3 — Citizen Developer
|
||||
# -----------------------------------------------------------------------------
|
||||
echo "== Act 3 — Citizen Developer =="
|
||||
ISSUE_BODY="We need to ingest natural gas prices from Platts and report on compliance for the trading desk."
|
||||
if ! python3 "$SCRIPT_DIR/l3b_agent_stub.py" "$ISSUE_BODY" -o "$CONTRACTS/act3.yaml"; then
|
||||
echo "run_demo.sh: l3b_agent_stub failed for Act 3" >&2
|
||||
FAIL=1
|
||||
fi
|
||||
|
||||
# Confirm the generated contract's stack (D-008: gas/price matches first).
|
||||
ACT3_STACK="$(python3 -c "import yaml,sys; print(yaml.safe_load(open('$CONTRACTS/act3.yaml'))['stack'])" 2>/dev/null || echo "")"
|
||||
echo " l3b generated stack: $ACT3_STACK"
|
||||
if [ "$ACT3_STACK" != "l2-commodity-price-feed" ]; then
|
||||
echo "run_demo.sh: WARNING Act 3 expected stack l2-commodity-price-feed, got '$ACT3_STACK'" >&2
|
||||
# Continue anyway per the task spec.
|
||||
fi
|
||||
|
||||
ACT3_POLICY="$(python3 "$SCRIPT_DIR/policy_checker.py" "$CONTRACTS/act3.yaml")"
|
||||
ACT3_POLICY_RC=$?
|
||||
echo " policy_checker: $ACT3_POLICY (rc=$ACT3_POLICY_RC)"
|
||||
if [ "$ACT3_POLICY" != "POLICY_PASS" ]; then
|
||||
echo "run_demo.sh: Act 3 expected POLICY_PASS, got '$ACT3_POLICY'" >&2
|
||||
FAIL=1
|
||||
fi
|
||||
|
||||
ACT3_CONF="$(python3 "$SCRIPT_DIR/confidence_signal.py" "$CONTRACTS/act3.yaml")"
|
||||
echo " confidence_signal: $ACT3_CONF"
|
||||
|
||||
(
|
||||
cd "$REPO_ROOT" && bash "$SCRIPT_DIR/mock_executor.sh" "$CONTRACTS/act3.yaml"
|
||||
)
|
||||
MOCK_RC=$?
|
||||
rm -f "$REPO_ROOT/state.json"
|
||||
if [ "$MOCK_RC" -ne 0 ]; then
|
||||
echo "run_demo.sh: Act 3 mock_executor failed (rc=$MOCK_RC)" >&2
|
||||
FAIL=1
|
||||
fi
|
||||
|
||||
run_passing_pipeline "dev applied: l2-commodity-price-feed (Act 3 from issue)"
|
||||
|
||||
# -----------------------------------------------------------------------------
|
||||
# Act 4 — Safety Net
|
||||
# -----------------------------------------------------------------------------
|
||||
echo "== Act 4 — Safety Net =="
|
||||
cat > "$CONTRACTS/act4.yaml" <<'YAML'
|
||||
stack: l2-regulatory-reporting
|
||||
inputs:
|
||||
environment: dev
|
||||
owner: platform-team
|
||||
public-ingress: true
|
||||
YAML
|
||||
|
||||
# policy_checker exits 1 on violation; capture without failing the script.
|
||||
ACT4_POLICY="$(python3 "$SCRIPT_DIR/policy_checker.py" "$CONTRACTS/act4.yaml" 2>&1 || true)"
|
||||
echo " policy_checker: $ACT4_POLICY"
|
||||
if [ "$ACT4_POLICY" != "POLICY_VIOLATION:PUBLIC_INGRESS" ]; then
|
||||
echo "run_demo.sh: Act 4 expected POLICY_VIOLATION:PUBLIC_INGRESS, got '$ACT4_POLICY'" >&2
|
||||
FAIL=1
|
||||
fi
|
||||
|
||||
ACT4_CONF="$(python3 "$SCRIPT_DIR/confidence_signal.py" "$CONTRACTS/act4.yaml")"
|
||||
echo " confidence_signal: $ACT4_CONF"
|
||||
# Expected: {"score": 0.40, "reason": "POLICY_VIOLATION:PUBLIC_INGRESS"}
|
||||
|
||||
# Score < 0.50 -> dev rejects. Do NOT run mock_executor, do NOT write qa/prod/finalize.
|
||||
ev dev "dev rejected: POLICY_VIOLATION:PUBLIC_INGRESS (confidence 0.40 < 0.50)"
|
||||
|
||||
# -----------------------------------------------------------------------------
|
||||
# Summary
|
||||
# -----------------------------------------------------------------------------
|
||||
echo "== Summary =="
|
||||
python3 - "$AUDIT" <<'PY'
|
||||
import json, sys
|
||||
audit = json.load(open(sys.argv[1]))
|
||||
for e in audit:
|
||||
print(f"{e['seq']} | {e['stage']} | {e['event']} | {e['hash'][:12]}")
|
||||
print(f"total events: {len(audit)}")
|
||||
PY
|
||||
|
||||
EVENT_COUNT="$(python3 -c "import json; print(len(json.load(open('$AUDIT'))))")"
|
||||
echo "event count: $EVENT_COUNT"
|
||||
|
||||
if [ "$EVENT_COUNT" -lt 11 ]; then
|
||||
echo "run_demo.sh: expected >= 11 events, got $EVENT_COUNT" >&2
|
||||
FAIL=1
|
||||
fi
|
||||
|
||||
# -----------------------------------------------------------------------------
|
||||
# Upload (optional)
|
||||
# -----------------------------------------------------------------------------
|
||||
if [ "$UPLOAD" -eq 1 ]; then
|
||||
echo "== Upload =="
|
||||
if [ -z "${ACDL_GITEA_TOKEN:-}" ]; then
|
||||
echo "run_demo.sh: ACDL_GITEA_TOKEN not set; skipping upload (use --no-upload to silence)" >&2
|
||||
else
|
||||
# Upload audit.json to acdl-evidence main.
|
||||
if python3 "$SCRIPT_DIR/finalize_evidence.py" --audit "$AUDIT"; then
|
||||
echo " audit.json uploaded"
|
||||
else
|
||||
echo "run_demo.sh: finalize_evidence failed for audit.json" >&2
|
||||
FAIL=1
|
||||
fi
|
||||
# Upload index.html (the --audit flag accepts any local file path; --path
|
||||
# sets the remote destination).
|
||||
if python3 "$SCRIPT_DIR/finalize_evidence.py" \
|
||||
--audit "$REPO_ROOT/evidence-ui/index.html" \
|
||||
--path index.html \
|
||||
--message "chore(ui): update index.html (demo dry run)"; then
|
||||
echo " index.html uploaded"
|
||||
else
|
||||
echo "run_demo.sh: finalize_evidence failed for index.html" >&2
|
||||
FAIL=1
|
||||
fi
|
||||
echo "Uploaded audit.json + index.html to acdl-evidence main"
|
||||
echo " raw URL: https://git.cloudinit.dev/continuous-intelligence/acdl-evidence/raw/branch/main/index.html"
|
||||
fi
|
||||
else
|
||||
echo "== Upload skipped (--no-upload) =="
|
||||
fi
|
||||
|
||||
# -----------------------------------------------------------------------------
|
||||
# Exit
|
||||
# -----------------------------------------------------------------------------
|
||||
if [ "$FAIL" -ne 0 ]; then
|
||||
echo "run_demo.sh: one or more steps failed (see warnings above)" >&2
|
||||
exit 1
|
||||
fi
|
||||
echo "run_demo.sh: OK ($EVENT_COUNT events)"
|
||||
exit 0
|
||||
@@ -1,109 +0,0 @@
|
||||
#!/usr/bin/env bash
|
||||
# Phase 01 verification script.
|
||||
# Confirms the three-repo scaffold exists under the continuous-intelligence
|
||||
# Gitea org and that the Phase 01 visible artifacts (placeholder index.html on
|
||||
# acdl-evidence; qa + prod branches on acdl-contracts) are present.
|
||||
#
|
||||
# Usage: ACDL_GITEA_TOKEN=<token> scripts/verify_phase01.sh
|
||||
# Exit codes: 0 = all checks passed; 1 = one or more checks failed.
|
||||
|
||||
set -euo pipefail
|
||||
|
||||
GITEA_HOST="${GITEA_HOST:-https://git.cloudinit.dev}"
|
||||
ORG="continuous-intelligence"
|
||||
TOKEN="${ACDL_GITEA_TOKEN:-}"
|
||||
|
||||
fail_count=0
|
||||
note() { printf ' [%s] %s\n' "$1" "$2"; }
|
||||
pass() { note "PASS" "$1"; }
|
||||
fail() { note "FAIL" "$1"; fail_count=$((fail_count + 1)); }
|
||||
warn() { printf ' [WARN] %s\n' "$1" >&2; }
|
||||
|
||||
echo "== Phase 01 verification =="
|
||||
echo "Host: $GITEA_HOST"
|
||||
echo "Org: $ORG"
|
||||
if [ -n "$TOKEN" ]; then
|
||||
echo "Token: <set, ${#TOKEN} chars>"
|
||||
else
|
||||
echo "Token: <unset>"
|
||||
fi
|
||||
echo
|
||||
|
||||
# --- Check 1: acdl-contracts repo exists ---
|
||||
echo "-- Check 1: acdl-contracts repo exists --"
|
||||
status=$(curl -sS -o /tmp/p01_contracts.json -w "%{http_code}" \
|
||||
-H "Authorization: token ${TOKEN}" \
|
||||
"${GITEA_HOST}/api/v1/repos/${ORG}/acdl-contracts")
|
||||
if [ "$status" = "200" ]; then
|
||||
default_branch=$(python3 -c "import json; print(json.load(open('/tmp/p01_contracts.json')).get('default_branch','?'))")
|
||||
pass "acdl-contracts exists (default_branch=${default_branch})"
|
||||
else
|
||||
fail "acdl-contracts GET returned HTTP ${status}"
|
||||
fi
|
||||
|
||||
# --- Check 2: acdl-evidence repo exists ---
|
||||
echo "-- Check 2: acdl-evidence repo exists --"
|
||||
status=$(curl -sS -o /tmp/p01_evidence.json -w "%{http_code}" \
|
||||
-H "Authorization: token ${TOKEN}" \
|
||||
"${GITEA_HOST}/api/v1/repos/${ORG}/acdl-evidence")
|
||||
if [ "$status" = "200" ]; then
|
||||
default_branch=$(python3 -c "import json; print(json.load(open('/tmp/p01_evidence.json')).get('default_branch','?'))")
|
||||
pass "acdl-evidence exists (default_branch=${default_branch})"
|
||||
else
|
||||
fail "acdl-evidence GET returned HTTP ${status}"
|
||||
fi
|
||||
|
||||
# --- Check 3: acdl-evidence raw index.html returns 200 (Pages substitute per D-012/D-016) ---
|
||||
# acdl-evidence is public per gitea_setup.sh step 2b, so the raw URL should
|
||||
# work without auth. We also try with the auth header as a fallback so the
|
||||
# check does not spuriously fail if the repo visibility was reset.
|
||||
echo "-- Check 3: acdl-evidence raw index.html returns 200 --"
|
||||
index_url="${GITEA_HOST}/${ORG}/acdl-evidence/raw/branch/main/index.html"
|
||||
status=$(curl -sS -o /tmp/p01_index.html -w "%{http_code}" "${index_url}")
|
||||
if [ "$status" != "200" ] && [ -n "$TOKEN" ]; then
|
||||
warn "raw URL returned ${status} unauth; retrying with Authorization header"
|
||||
status=$(curl -sS -o /tmp/p01_index.html -w "%{http_code}" \
|
||||
-H "Authorization: token ${TOKEN}" "${index_url}")
|
||||
fi
|
||||
if [ "$status" = "200" ]; then
|
||||
body_size=$(wc -c < /tmp/p01_index.html)
|
||||
if grep -q "ACDL Evidence" /tmp/p01_index.html; then
|
||||
pass "raw index.html returns 200 with placeholder body (${body_size} bytes)"
|
||||
else
|
||||
fail "raw index.html returns 200 but body does not contain 'ACDL Evidence' marker"
|
||||
fi
|
||||
else
|
||||
fail "GET ${index_url} returned HTTP ${status}"
|
||||
fi
|
||||
|
||||
# --- Check 4: qa + prod branches exist on acdl-contracts ---
|
||||
echo "-- Check 4: qa + prod branches exist on acdl-contracts --"
|
||||
status=$(curl -sS -o /tmp/p01_branches.json -w "%{http_code}" \
|
||||
-H "Authorization: token ${TOKEN}" \
|
||||
"${GITEA_HOST}/api/v1/repos/${ORG}/acdl-contracts/branches?limit=50")
|
||||
if [ "$status" != "200" ]; then
|
||||
fail "list branches on acdl-contracts returned HTTP ${status}"
|
||||
else
|
||||
for want in qa prod; do
|
||||
if python3 -c "
|
||||
import json, sys
|
||||
branches = json.load(open('/tmp/p01_branches.json'))
|
||||
names = [b.get('name', '') for b in branches]
|
||||
sys.exit(0 if '${want}' in names else 1)
|
||||
"; then
|
||||
pass "branch '${want}' exists on acdl-contracts"
|
||||
else
|
||||
fail "branch '${want}' missing on acdl-contracts"
|
||||
fi
|
||||
done
|
||||
fi
|
||||
|
||||
echo
|
||||
echo "== Summary =="
|
||||
if [ "$fail_count" -eq 0 ]; then
|
||||
echo "Phase 01 verification PASSED (all checks ok)"
|
||||
exit 0
|
||||
else
|
||||
echo "Phase 01 verification FAILED (${fail_count} check(s) failed)"
|
||||
exit 1
|
||||
fi
|
||||
@@ -1,135 +0,0 @@
|
||||
#!/usr/bin/env bash
|
||||
# Phase 02 verification script.
|
||||
# Confirms the 8 L1 module folders exist under modules/l1/ with the exact
|
||||
# names from REQ-02, each containing a valid manifest.yaml (D-017 schema)
|
||||
# and a uniform mock_apply.sh (D-007 + D-018) that exits 0 with the
|
||||
# expected echo markers.
|
||||
#
|
||||
# Usage: scripts/verify_phase02.sh
|
||||
# Exit codes: 0 = all checks passed; 1 = one or more checks failed.
|
||||
|
||||
set -euo pipefail
|
||||
|
||||
ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
|
||||
L1_DIR="${ROOT}/modules/l1"
|
||||
|
||||
# Expected L1 names per REQ-02 / D-019.
|
||||
EXPECTED_L1S=(
|
||||
l1-eks-fargate
|
||||
l1-iam-role
|
||||
l1-lambda
|
||||
l1-api-gateway
|
||||
l1-eventbridge
|
||||
l1-sqs
|
||||
l1-s3
|
||||
l1-cloudwatch
|
||||
)
|
||||
|
||||
fail_count=0
|
||||
pass() { printf ' [PASS] %s\n' "$1"; }
|
||||
fail() { printf ' [FAIL] %s\n' "$1"; fail_count=$((fail_count + 1)); }
|
||||
|
||||
echo "== Phase 02 verification =="
|
||||
echo "L1 dir: ${L1_DIR}"
|
||||
echo
|
||||
|
||||
# --- Check 1: exactly 8 L1 folders with the expected names ---
|
||||
echo "-- Check 1: 8 L1 folders with expected names --"
|
||||
if [ ! -d "$L1_DIR" ]; then
|
||||
fail "modules/l1/ does not exist"
|
||||
echo
|
||||
echo "== Summary =="
|
||||
echo "Phase 02 verification FAILED (${fail_count} check(s) failed)"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
actual_folders=$(ls "$L1_DIR" | sort | tr '\n' ' ')
|
||||
expected_folders=$(printf '%s\n' "${EXPECTED_L1S[@]}" | sort | tr '\n' ' ')
|
||||
if [ "$actual_folders" = "$expected_folders" ]; then
|
||||
pass "exactly 8 L1 folders present and named correctly"
|
||||
else
|
||||
fail "L1 folder list mismatch"
|
||||
echo " expected: $expected_folders"
|
||||
echo " actual: $actual_folders"
|
||||
fi
|
||||
|
||||
# --- Per-L1 checks ---
|
||||
for l1 in "${EXPECTED_L1S[@]}"; do
|
||||
echo "-- L1: ${l1} --"
|
||||
dir="${L1_DIR}/${l1}"
|
||||
|
||||
# Check 2a: folder exists
|
||||
if [ ! -d "$dir" ]; then
|
||||
fail "${l1}: folder missing"
|
||||
continue
|
||||
fi
|
||||
pass "${l1}: folder exists"
|
||||
|
||||
# Check 2b: manifest.yaml exists + parses + name matches folder + kind=l1
|
||||
manifest="${dir}/manifest.yaml"
|
||||
if [ ! -f "$manifest" ]; then
|
||||
fail "${l1}: manifest.yaml missing"
|
||||
else
|
||||
manifest_ok=$(python3 -c "
|
||||
import yaml, sys
|
||||
try:
|
||||
d = yaml.safe_load(open('${manifest}'))
|
||||
name = d.get('name') == '${l1}'
|
||||
kind = d.get('kind') == 'l1'
|
||||
has_inputs = isinstance(d.get('inputs'), dict)
|
||||
sys.exit(0 if (name and kind and has_inputs) else 1)
|
||||
except Exception as e:
|
||||
print(f' parse error: {e}', file=sys.stderr)
|
||||
sys.exit(2)
|
||||
" 2>/dev/null; echo $?)
|
||||
if [ "$manifest_ok" = "0" ]; then
|
||||
pass "${l1}: manifest.yaml valid (name=${l1}, kind=l1, inputs present)"
|
||||
else
|
||||
fail "${l1}: manifest.yaml invalid (name/kind/inputs check failed; rc=${manifest_ok})"
|
||||
fi
|
||||
fi
|
||||
|
||||
# Check 2c: mock_apply.sh exists + executable + bash -n clean
|
||||
apply="${dir}/mock_apply.sh"
|
||||
if [ ! -f "$apply" ]; then
|
||||
fail "${l1}: mock_apply.sh missing"
|
||||
continue
|
||||
fi
|
||||
if [ ! -x "$apply" ]; then
|
||||
fail "${l1}: mock_apply.sh not executable"
|
||||
else
|
||||
pass "${l1}: mock_apply.sh is executable"
|
||||
fi
|
||||
if ! bash -n "$apply" 2>/dev/null; then
|
||||
fail "${l1}: mock_apply.sh bash -n failed"
|
||||
else
|
||||
pass "${l1}: mock_apply.sh bash -n clean"
|
||||
fi
|
||||
|
||||
# Check 2d: end-to-end run: exit 0 + expected markers, completes in <2s
|
||||
start=$(date +%s)
|
||||
output=$("$apply" 2>&1)
|
||||
rc=$?
|
||||
elapsed=$(( $(date +%s) - start ))
|
||||
if [ "$rc" -ne 0 ]; then
|
||||
fail "${l1}: mock_apply.sh exited ${rc}"
|
||||
elif ! echo "$output" | grep -qF "[L1: ${l1}] applying..."; then
|
||||
fail "${l1}: missing '[L1: ${l1}] applying...' marker"
|
||||
elif ! echo "$output" | grep -qF "[L1: ${l1}] OK"; then
|
||||
fail "${l1}: missing '[L1: ${l1}] OK' marker"
|
||||
elif [ "$elapsed" -lt 1 ] || [ "$elapsed" -gt 2 ]; then
|
||||
fail "${l1}: run took ${elapsed}s (expected ~1s; 1<=t<=2 ok)"
|
||||
else
|
||||
pass "${l1}: mock_apply.sh runs, exits 0, markers correct (${elapsed}s)"
|
||||
fi
|
||||
done
|
||||
|
||||
echo
|
||||
echo "== Summary =="
|
||||
if [ "$fail_count" -eq 0 ]; then
|
||||
echo "Phase 02 verification PASSED (8 L1 modules, all checks ok)"
|
||||
exit 0
|
||||
else
|
||||
echo "Phase 02 verification FAILED (${fail_count} check(s) failed)"
|
||||
exit 1
|
||||
fi
|
||||
@@ -1,240 +0,0 @@
|
||||
#!/usr/bin/env bash
|
||||
# Phase 03 verification script.
|
||||
# Confirms the 4 L2 modules and the 5 core scripts conform to their contracts.
|
||||
#
|
||||
# Usage: scripts/verify_phase03.sh
|
||||
# Exit codes: 0 = all checks passed; 1 = one or more checks failed.
|
||||
|
||||
set -uo pipefail
|
||||
|
||||
ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
|
||||
cd "$ROOT"
|
||||
|
||||
fail_count=0
|
||||
pass() { printf ' [PASS] %s\n' "$1"; }
|
||||
fail() { printf ' [FAIL] %s\n' "$1"; fail_count=$((fail_count + 1)); }
|
||||
|
||||
# Expected L2 names per REQ-04.
|
||||
EXPECTED_L2S=(
|
||||
l2-invoice-service
|
||||
l2-commodity-price-feed
|
||||
l2-energy-analytics-api
|
||||
l2-regulatory-reporting
|
||||
)
|
||||
|
||||
echo "== Phase 03 verification =="
|
||||
echo "Root: ${ROOT}"
|
||||
echo
|
||||
|
||||
# --- Check 1: exactly 4 L2 folders with the expected names ---
|
||||
echo "-- Check 1: 4 L2 folders with expected names --"
|
||||
actual=$(ls modules/l2/ 2>/dev/null | sort | tr '\n' ' ')
|
||||
expected=$(printf '%s\n' "${EXPECTED_L2S[@]}" | sort | tr '\n' ' ')
|
||||
if [ "$actual" = "$expected" ]; then
|
||||
pass "exactly 4 L2 folders present and named correctly"
|
||||
else
|
||||
fail "L2 folder list mismatch"
|
||||
echo " expected: $expected"
|
||||
echo " actual: $actual"
|
||||
fi
|
||||
|
||||
# --- Check 2: each L2 manifest.yaml validates + references 5 existing L1s ---
|
||||
echo "-- Check 2: L2 manifests reference 5 existing L1s --"
|
||||
l2_validate=$(python3 << 'PYEOF' || true
|
||||
import yaml, glob, os, sys
|
||||
ok = True
|
||||
l1s = set(os.listdir('modules/l1'))
|
||||
for f in sorted(glob.glob('modules/l2/*/manifest.yaml')):
|
||||
d = yaml.safe_load(open(f))
|
||||
folder = os.path.basename(os.path.dirname(f))
|
||||
problems = []
|
||||
if d.get('name') != folder: problems.append(f"name != {folder}")
|
||||
if d.get('kind') != 'l2': problems.append("kind != l2")
|
||||
refs = [x.get('name') for x in d.get('l1s', [])]
|
||||
if len(refs) != 5: problems.append(f"expected 5 l1s, got {len(refs)}")
|
||||
unknown = [r for r in refs if r not in l1s]
|
||||
if unknown: problems.append(f"unknown L1 refs: {unknown}")
|
||||
# each l1 entry must have an inputs: map
|
||||
for x in d.get('l1s', []):
|
||||
if not isinstance(x.get('inputs'), dict): problems.append(f"l1 {x.get('name')} missing inputs map")
|
||||
status = 'OK' if not problems else 'FAIL: ' + '; '.join(problems)
|
||||
print(f' [{status}] {f}')
|
||||
if problems: ok = False
|
||||
sys.exit(0 if ok else 1)
|
||||
PYEOF
|
||||
)
|
||||
echo "$l2_validate"
|
||||
if [ "$l2_validate" = "" ] || echo "$l2_validate" | grep -q FAIL; then
|
||||
if ! echo "$l2_validate" | grep -q PASS; then
|
||||
fail "one or more L2 manifests invalid (see above)"
|
||||
fi
|
||||
else
|
||||
pass "all 4 L2 manifests valid"
|
||||
fi
|
||||
# Re-run for the explicit pass/fail count
|
||||
python3 << 'PYEOF' > /tmp/l2_check.txt 2>&1 || true
|
||||
import yaml, glob, os, sys
|
||||
ok = True
|
||||
l1s = set(os.listdir('modules/l1'))
|
||||
for f in sorted(glob.glob('modules/l2/*/manifest.yaml')):
|
||||
d = yaml.safe_load(open(f))
|
||||
folder = os.path.basename(os.path.dirname(f))
|
||||
if d.get('name') != folder: ok = False
|
||||
if d.get('kind') != 'l2': ok = False
|
||||
refs = [x.get('name') for x in d.get('l1s', [])]
|
||||
if len(refs) != 5: ok = False
|
||||
if any(r not in l1s for r in refs): ok = False
|
||||
for x in d.get('l1s', []):
|
||||
if not isinstance(x.get('inputs'), dict): ok = False
|
||||
sys.exit(0 if ok else 1)
|
||||
PYEOF
|
||||
if [ $? -eq 0 ]; then pass "all 4 L2 manifests pass structural + reference checks"; else fail "L2 manifest structural check"; fi
|
||||
|
||||
# --- Check 3: typecheck (bash -n + py_compile + yaml load) ---
|
||||
echo "-- Check 3: typecheck --"
|
||||
if bash -n scripts/mock_executor.sh; then pass "bash -n mock_executor.sh"; else fail "bash -n mock_executor.sh"; fi
|
||||
if python3 -m py_compile scripts/policy_checker.py scripts/confidence_signal.py scripts/evidence_writer.py scripts/l3b_agent_stub.py 2>/dev/null; then
|
||||
pass "py_compile all 4 python scripts"
|
||||
else
|
||||
fail "py_compile"
|
||||
fi
|
||||
if python3 -c "import yaml, glob; [yaml.safe_load(open(f)) for f in glob.glob('modules/l2/*/manifest.yaml')]" 2>/dev/null; then
|
||||
pass "yaml load all L2 manifests"
|
||||
else
|
||||
fail "yaml load L2 manifests"
|
||||
fi
|
||||
|
||||
# --- Check 4: policy_checker (D-025) ---
|
||||
echo "-- Check 4: policy_checker behavior (D-025) --"
|
||||
WORK="$(mktemp -d)"
|
||||
trap 'rm -rf "$WORK" "$ROOT/tmp_pass_contract.yaml" "$ROOT/tmp_fail_contract.yaml" "$ROOT/state.json" 2>/dev/null || true' EXIT
|
||||
printf 'stack: l2-commodity-price-feed\npublic-ingress: false\n' > "$WORK/pass.yaml"
|
||||
printf 'stack: l2-regulatory-reporting\npublic-ingress: true\n' > "$WORK/fail.yaml"
|
||||
out=$(python3 scripts/policy_checker.py "$WORK/pass.yaml" 2>&1); rc=$?
|
||||
if [ "$out" = "POLICY_PASS" ] && [ "$rc" = "0" ]; then
|
||||
pass "policy_checker pass contract -> POLICY_PASS exit 0"
|
||||
else
|
||||
fail "policy_checker pass contract: got '$out' exit=$rc"
|
||||
fi
|
||||
out=$(python3 scripts/policy_checker.py "$WORK/fail.yaml" 2>&1); rc=$?
|
||||
if [ "$out" = "POLICY_VIOLATION:PUBLIC_INGRESS" ] && [ "$rc" = "1" ]; then
|
||||
pass "policy_checker fail contract -> POLICY_VIOLATION:PUBLIC_INGRESS exit 1"
|
||||
else
|
||||
fail "policy_checker fail contract: got '$out' exit=$rc"
|
||||
fi
|
||||
|
||||
# --- Check 5: confidence_signal (D-024) ---
|
||||
echo "-- Check 5: confidence_signal behavior (D-024) --"
|
||||
out=$(python3 scripts/confidence_signal.py "$WORK/pass.yaml" 2>&1); rc=$?
|
||||
if echo "$out" | grep -q '"score": 0.90' && [ "$rc" = "0" ]; then
|
||||
pass "confidence_signal pass -> score 0.90 exit 0"
|
||||
else
|
||||
fail "confidence_signal pass: got '$out' exit=$rc"
|
||||
fi
|
||||
out=$(python3 scripts/confidence_signal.py "$WORK/fail.yaml" 2>&1); rc=$?
|
||||
if echo "$out" | grep -q '"score": 0.40' && [ "$rc" = "0" ]; then
|
||||
pass "confidence_signal fail -> score 0.40 exit 0"
|
||||
else
|
||||
fail "confidence_signal fail: got '$out' exit=$rc"
|
||||
fi
|
||||
|
||||
# --- Check 6: evidence_writer hash chain (D-023) ---
|
||||
echo "-- Check 6: evidence_writer hash chain (D-023) --"
|
||||
rm -f "$WORK/audit.json"
|
||||
python3 scripts/evidence_writer.py --stage dev --event "dev start" --audit "$WORK/audit.json" > /dev/null
|
||||
python3 scripts/evidence_writer.py --stage qa --event "qa approved" --audit "$WORK/audit.json" > /dev/null
|
||||
python3 scripts/evidence_writer.py --stage prod --event "prod approved" --audit "$WORK/audit.json" > /dev/null
|
||||
chain_ok=$(python3 << PYEOF
|
||||
import json, hashlib, sys
|
||||
try:
|
||||
events = json.load(open("$WORK/audit.json"))
|
||||
assert len(events) == 4, f"expected 4 (genesis + 3), got {len(events)}"
|
||||
assert events[0]['prev_hash'] == 'GENESIS', "genesis prev_hash"
|
||||
for i in range(1, len(events)):
|
||||
assert events[i]['prev_hash'] == events[i-1]['hash'], f"chain break at {i}"
|
||||
e = dict(events[i]); h = e.pop('hash'); e['hash'] = ''
|
||||
canon = json.dumps(e, sort_keys=True, separators=(',',':'))
|
||||
assert hashlib.sha256(canon.encode()).hexdigest() == h, f"hash mismatch at {i}"
|
||||
print("OK")
|
||||
except AssertionError as ex:
|
||||
print(f"FAIL: {ex}")
|
||||
sys.exit(1)
|
||||
PYEOF
|
||||
)
|
||||
if [ "$chain_ok" = "OK" ]; then
|
||||
pass "evidence_writer: 4 events, GENESIS + 3, chain links + hashes valid"
|
||||
else
|
||||
fail "evidence_writer chain: $chain_ok"
|
||||
fi
|
||||
|
||||
# --- Check 7: mock_executor (D-022) ---
|
||||
echo "-- Check 7: mock_executor writes state.json (D-022) --"
|
||||
rm -f "$ROOT/state.json"
|
||||
out=$(bash scripts/mock_executor.sh "$WORK/pass.yaml" 2>&1); rc=$?
|
||||
if [ "$rc" != "0" ]; then
|
||||
fail "mock_executor exit $rc (expected 0)"
|
||||
else
|
||||
me_ok=$(python3 << PYEOF
|
||||
import json, sys
|
||||
try:
|
||||
s = json.load(open("$ROOT/state.json"))
|
||||
assert s['l2'] == 'l2-commodity-price-feed', f"l2 mismatch: {s.get('l2')}"
|
||||
assert 'l1s' in s and len(s['l1s']) == 5, f"expected 5 l1s, got {len(s.get('l1s', []))}"
|
||||
assert all(x['applied'] is True and x['exit_code'] == 0 for x in s['l1s']), "l1 not all applied+0"
|
||||
assert 'contract' in s, "missing contract field"
|
||||
print("OK")
|
||||
except Exception as ex:
|
||||
print(f"FAIL: {ex}")
|
||||
sys.exit(1)
|
||||
PYEOF
|
||||
)
|
||||
if [ "$me_ok" = "OK" ]; then
|
||||
pass "mock_executor: state.json with l2 + 5 l1s (all exit 0) + contract"
|
||||
else
|
||||
fail "mock_executor state.json: $me_ok"
|
||||
fi
|
||||
fi
|
||||
rm -f "$ROOT/state.json"
|
||||
|
||||
# --- Check 8: l3b_agent_stub D-008 keyword map ---
|
||||
echo "-- Check 8: l3b_agent_stub keyword map (D-008) --"
|
||||
act3=$(python3 scripts/l3b_agent_stub.py "We need to ingest natural gas prices from Platts and report on compliance." 2>&1)
|
||||
if echo "$act3" | grep -q 'stack: l2-commodity-price-feed'; then
|
||||
pass "l3b Act 3 example -> l2-commodity-price-feed"
|
||||
else
|
||||
fail "l3b Act 3 example: got '$act3'"
|
||||
fi
|
||||
fallback=$(python3 scripts/l3b_agent_stub.py "please deploy something" 2>&1)
|
||||
if echo "$fallback" | grep -q 'stack: l2-invoice-service'; then
|
||||
pass "l3b fallback (no keywords) -> l2-invoice-service"
|
||||
else
|
||||
fail "l3b fallback: got '$fallback'"
|
||||
fi
|
||||
regulatory=$(python3 scripts/l3b_agent_stub.py "regulatory compliance reporting for trading desk" 2>&1)
|
||||
if echo "$regulatory" | grep -q 'stack: l2-regulatory-reporting'; then
|
||||
pass "l3b regulatory keywords -> l2-regulatory-reporting"
|
||||
else
|
||||
fail "l3b regulatory: got '$regulatory'"
|
||||
fi
|
||||
invoice=$(python3 scripts/l3b_agent_stub.py "monthly invoice and billing reconciliation" 2>&1)
|
||||
if echo "$invoice" | grep -q 'stack: l2-invoice-service'; then
|
||||
pass "l3b invoice keywords -> l2-invoice-service"
|
||||
else
|
||||
fail "l3b invoice: got '$invoice'"
|
||||
fi
|
||||
analytics=$(python3 scripts/l3b_agent_stub.py "historical analytics and query API" 2>&1)
|
||||
if echo "$analytics" | grep -q 'stack: l2-energy-analytics-api'; then
|
||||
pass "l3b analytics keywords -> l2-energy-analytics-api"
|
||||
else
|
||||
fail "l3b analytics: got '$analytics'"
|
||||
fi
|
||||
|
||||
echo
|
||||
echo "== Summary =="
|
||||
if [ "$fail_count" -eq 0 ]; then
|
||||
echo "Phase 03 verification PASSED (4 L2s + 5 core scripts, all checks ok)"
|
||||
exit 0
|
||||
else
|
||||
echo "Phase 03 verification FAILED (${fail_count} check(s) failed)"
|
||||
exit 1
|
||||
fi
|
||||
@@ -1,186 +0,0 @@
|
||||
#!/usr/bin/env bash
|
||||
# Phase 04 verification script.
|
||||
# Confirms the pipeline workflow + issue trigger + finalize_evidence.py
|
||||
# conform to the Phase 04 plan and the Gitea Actions topology in
|
||||
# ARCHITECTURE.md. Does NOT execute a real Gitea Actions run (act_runner
|
||||
# is not registered in this environment); validates structure + syntax
|
||||
# + a dry-run of finalize_evidence.py against a dead host.
|
||||
#
|
||||
# Usage: scripts/verify_phase04.sh
|
||||
# Exit codes: 0 = all checks passed; 1 = one or more checks failed.
|
||||
|
||||
set -uo pipefail
|
||||
|
||||
ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
|
||||
cd "$ROOT"
|
||||
|
||||
fail_count=0
|
||||
pass() { printf ' [PASS] %s\n' "$1"; }
|
||||
fail() { printf ' [FAIL] %s\n' "$1"; fail_count=$((fail_count + 1)); }
|
||||
|
||||
echo "== Phase 04 verification =="
|
||||
echo "Root: ${ROOT}"
|
||||
echo
|
||||
|
||||
# --- Check 1: typecheck ---
|
||||
echo "-- Check 1: typecheck --"
|
||||
if bash -n scripts/finalize_evidence.py 2>/dev/null || python3 -m py_compile scripts/finalize_evidence.py 2>/dev/null; then
|
||||
pass "py_compile finalize_evidence.py"
|
||||
else
|
||||
fail "py_compile finalize_evidence.py"
|
||||
fi
|
||||
if python3 -c "import yaml; yaml.safe_load(open('.gitea/workflows/pipeline.yml')); yaml.safe_load(open('contracts-repo/.gitea/workflows/issue-to-contract.yml'))" 2>/dev/null; then
|
||||
pass "yaml load both workflows"
|
||||
else
|
||||
fail "yaml load workflows"
|
||||
fi
|
||||
|
||||
# --- Check 2: pipeline.yml structure ---
|
||||
echo "-- Check 2: pipeline.yml structure (D-027, D-028) --"
|
||||
p_struct=$(python3 << 'PYEOF'
|
||||
import yaml, sys
|
||||
try:
|
||||
d = yaml.safe_load(open('.gitea/workflows/pipeline.yml'))
|
||||
on = d.get('on', d.get(True)) or {}
|
||||
assert 'workflow_dispatch' in on, 'no workflow_dispatch trigger'
|
||||
inputs = on['workflow_dispatch']['inputs']
|
||||
assert set(inputs.keys()) == {'contract-ref', 'approve_qa', 'approve_prod'}, f'inputs: {set(inputs.keys())}'
|
||||
assert inputs['contract-ref']['type'] == 'string', 'contract-ref type'
|
||||
assert inputs['approve_qa']['type'] == 'boolean', 'approve_qa type'
|
||||
assert inputs['approve_prod']['type'] == 'boolean', 'approve_prod type'
|
||||
jobs = d['jobs']
|
||||
assert set(jobs.keys()) == {'dev', 'qa-gate', 'prod-gate', 'finalize'}, f'jobs: {set(jobs.keys())}'
|
||||
dev_if = jobs['dev'].get('if', '')
|
||||
assert 'approve_qa' in dev_if and 'approve_prod' in dev_if, f'dev.if: {dev_if}'
|
||||
qa_if = jobs['qa-gate'].get('if', '')
|
||||
assert 'approve_qa' in qa_if, f'qa-gate.if: {qa_if}'
|
||||
prod_if = jobs['prod-gate'].get('if', '')
|
||||
assert 'approve_prod' in prod_if, f'prod-gate.if: {prod_if}'
|
||||
fin_needs = jobs['finalize'].get('needs', [])
|
||||
assert fin_needs == ['prod-gate'] or fin_needs == 'prod-gate', f'finalize.needs: {fin_needs}'
|
||||
# All jobs runs-on ubuntu-latest
|
||||
for name, job in jobs.items():
|
||||
assert job.get('runs-on') == 'ubuntu-latest', f'{name} runs-on: {job.get("runs-on")}'
|
||||
print('OK')
|
||||
except AssertionError as ex:
|
||||
print(f'FAIL: {ex}')
|
||||
sys.exit(1)
|
||||
except Exception as ex:
|
||||
print(f'FAIL: {ex}')
|
||||
sys.exit(1)
|
||||
PYEOF
|
||||
)
|
||||
if [ "$p_struct" = "OK" ]; then
|
||||
pass "pipeline.yml: 3 inputs + 4 jobs + correct if: conditions + finalize.needs=prod-gate"
|
||||
else
|
||||
fail "pipeline.yml structure: $p_struct"
|
||||
fi
|
||||
|
||||
# --- Check 3: pipeline.yml references core scripts ---
|
||||
echo "-- Check 3: pipeline.yml references core scripts (D-029) --"
|
||||
text=$(cat .gitea/workflows/pipeline.yml)
|
||||
missing=""
|
||||
for ref in policy_checker.py confidence_signal.py mock_executor.sh evidence_writer.py finalize_evidence.py; do
|
||||
if ! echo "$text" | grep -qF "$ref"; then
|
||||
missing="$missing $ref"
|
||||
fi
|
||||
done
|
||||
if [ -z "$missing" ]; then
|
||||
pass "pipeline.yml references all 5 core scripts"
|
||||
else
|
||||
fail "pipeline.yml missing references:$missing"
|
||||
fi
|
||||
# Branch-pin documentation
|
||||
if echo "$text" | grep -q 'milestone/v1.0-initial'; then
|
||||
pass "pipeline.yml documents branch-pin to milestone/v1.0-initial"
|
||||
else
|
||||
fail "pipeline.yml missing branch-pin reference"
|
||||
fi
|
||||
|
||||
# --- Check 4: issue-to-contract.yml structure ---
|
||||
echo "-- Check 4: issue-to-contract.yml structure (D-030) --"
|
||||
i_struct=$(python3 << 'PYEOF'
|
||||
import yaml, sys
|
||||
try:
|
||||
d = yaml.safe_load(open('contracts-repo/.gitea/workflows/issue-to-contract.yml'))
|
||||
on = d.get('on', d.get(True)) or {}
|
||||
assert 'issues' in on, 'no issues trigger'
|
||||
assert on['issues']['types'] == ['opened'], f'types: {on["issues"]["types"]}'
|
||||
assert 'parse-and-trigger' in d['jobs'], 'no parse-and-trigger job'
|
||||
assert d['jobs']['parse-and-trigger'].get('runs-on') == 'ubuntu-latest', 'runs-on'
|
||||
print('OK')
|
||||
except AssertionError as ex:
|
||||
print(f'FAIL: {ex}')
|
||||
sys.exit(1)
|
||||
PYEOF
|
||||
)
|
||||
if [ "$i_struct" = "OK" ]; then
|
||||
pass "issue-to-contract.yml: issues[opened] + parse-and-trigger job"
|
||||
else
|
||||
fail "issue-to-contract.yml structure: $i_struct"
|
||||
fi
|
||||
|
||||
# --- Check 5: issue-to-contract.yml references + dispatch endpoint ---
|
||||
echo "-- Check 5: issue-to-contract.yml references + dispatch (D-014, D-030) --"
|
||||
text=$(cat contracts-repo/.gitea/workflows/issue-to-contract.yml)
|
||||
missing=""
|
||||
for ref in l3b_agent_stub.py 'actions/workflows/pipeline.yml/dispatches' 'contract-ref' 'gitea.event.issue.number' 'GITEA_TOKEN' 'new_branch'; do
|
||||
if ! echo "$text" | grep -qF "$ref"; then
|
||||
missing="$missing $ref"
|
||||
fi
|
||||
done
|
||||
if [ -z "$missing" ]; then
|
||||
pass "issue-to-contract.yml: l3b_agent_stub + dispatch + contract-ref + issue number + token + new_branch"
|
||||
else
|
||||
fail "issue-to-contract.yml missing references:$missing"
|
||||
fi
|
||||
|
||||
# --- Check 6: finalize_evidence.py --help + clean failure ---
|
||||
echo "-- Check 6: finalize_evidence.py CLI + clean failure modes ---"
|
||||
out=$(python3 scripts/finalize_evidence.py --help 2>&1); rc=$?
|
||||
if [ "$rc" = "0" ] && echo "$out" | grep -qi 'usage\|--audit\|--owner'; then
|
||||
pass "finalize_evidence.py --help exits 0 with usage"
|
||||
else
|
||||
fail "finalize_evidence.py --help: rc=$rc"
|
||||
fi
|
||||
|
||||
# Missing audit file (with a fake token so it gets past the env check) → exit 1, no stack trace
|
||||
out=$(ACDL_GITEA_TOKEN=fake python3 scripts/finalize_evidence.py --audit /tmp/definitely_nonexistent_audit.json 2>&1); rc=$?
|
||||
if [ "$rc" = "1" ] && ! echo "$out" | grep -q 'Traceback'; then
|
||||
pass "finalize_evidence.py missing file → exit 1, no stack trace"
|
||||
else
|
||||
fail "finalize_evidence.py missing file: rc=$rc, out='$out'"
|
||||
fi
|
||||
|
||||
# Missing token env (audit file present) → exit 1, no stack trace
|
||||
printf '[]\n' > /tmp/empty_audit.json
|
||||
out=$(env -u ACDL_GITEA_TOKEN python3 scripts/finalize_evidence.py --audit /tmp/empty_audit.json 2>&1); rc=$?
|
||||
if [ "$rc" = "1" ] && ! echo "$out" | grep -q 'Traceback'; then
|
||||
pass "finalize_evidence.py missing token env → exit 1, no stack trace"
|
||||
else
|
||||
fail "finalize_evidence.py missing token: rc=$rc, out='$out'"
|
||||
fi
|
||||
|
||||
# --- Check 7: finalize_evidence.py dry-run against a dead host (clean failure) ---
|
||||
echo "-- Check 7: finalize_evidence.py dry-run against dead host ---"
|
||||
# Use a real audit.json but point at a host that will refuse the connection.
|
||||
printf '[{"seq":0,"ts":"2026-07-21T00:00:00Z","stage":"genesis","event":"init","prev_hash":"GENESIS","hash":"x"}]\n' > /tmp/real_audit.json
|
||||
out=$(ACDL_GITEA_TOKEN=fake GITEA_HOST=http://127.0.0.1:0 python3 scripts/finalize_evidence.py --audit /tmp/real_audit.json --host http://127.0.0.1:0 2>&1); rc=$?
|
||||
if [ "$rc" = "1" ] && ! echo "$out" | grep -q 'Traceback'; then
|
||||
pass "finalize_evidence.py dead host → exit 1, no stack trace (clean API failure)"
|
||||
else
|
||||
fail "finalize_evidence.py dead host: rc=$rc, out='$out'"
|
||||
fi
|
||||
|
||||
# Cleanup
|
||||
rm -f /tmp/empty_audit.json /tmp/real_audit.json
|
||||
|
||||
echo
|
||||
echo "== Summary =="
|
||||
if [ "$fail_count" -eq 0 ]; then
|
||||
echo "Phase 04 verification PASSED (pipeline + issue trigger + finalize helper, all checks ok)"
|
||||
exit 0
|
||||
else
|
||||
echo "Phase 04 verification FAILED (${fail_count} check(s) failed)"
|
||||
exit 1
|
||||
fi
|
||||
@@ -1,213 +0,0 @@
|
||||
#!/usr/bin/env bash
|
||||
# Phase 05 verification script.
|
||||
# Validates the evidence UI + the 4-act demo dry-run.
|
||||
#
|
||||
# Usage: scripts/verify_phase05.sh
|
||||
# Exit codes: 0 = all checks passed; 1 = one or more checks failed.
|
||||
|
||||
set -uo pipefail
|
||||
|
||||
ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
|
||||
cd "$ROOT"
|
||||
|
||||
fail_count=0
|
||||
pass() { printf ' [PASS] %s\n' "$1"; }
|
||||
fail() { printf ' [FAIL] %s\n' "$1"; fail_count=$((fail_count + 1)); }
|
||||
|
||||
GITEA_HOST="${GITEA_HOST:-https://git.cloudinit.dev}"
|
||||
ORG="continuous-intelligence"
|
||||
EVIDENCE_REPO="acdl-evidence"
|
||||
|
||||
echo "== Phase 05 verification =="
|
||||
echo "Root: ${ROOT}"
|
||||
echo
|
||||
|
||||
# --- Check 1: evidence-ui/index.html structure ---
|
||||
echo "-- Check 1: evidence-ui/index.html structure (D-032, REQ-14) --"
|
||||
UI="evidence-ui/index.html"
|
||||
if [ ! -f "$UI" ]; then
|
||||
fail "$UI missing"
|
||||
else
|
||||
pass "$UI exists"
|
||||
size=$(wc -c < "$UI")
|
||||
if [ "$size" -ge 1000 ] && [ "$size" -le 30000 ]; then
|
||||
pass "$UI size ${size} bytes (within 1-30 KB range)"
|
||||
else
|
||||
fail "$UI size ${size} bytes (expected 1-30 KB)"
|
||||
fi
|
||||
ui_check=$(python3 << 'PYEOF'
|
||||
import re, sys
|
||||
content = open('evidence-ui/index.html').read()
|
||||
problems = []
|
||||
if '<style>' not in content or '</style>' not in content: problems.append('missing inline <style>')
|
||||
if '<script>' not in content or '</script>' not in content: problems.append('missing inline <script>')
|
||||
if 'fetch(' not in content: problems.append('missing fetch call')
|
||||
if "'./audit.json'" not in content and '"./audit.json"' not in content: problems.append('missing relative ./audit.json fetch')
|
||||
external = re.findall(r'(?:src|href)\s*=\s*["\']https?://', content)
|
||||
if external: problems.append(f'external resource refs: {external}')
|
||||
# Confirm a refresh button or refresh function exists
|
||||
if 'refresh' not in content.lower(): problems.append('no refresh button/function')
|
||||
print('OK' if not problems else 'FAIL: ' + '; '.join(problems))
|
||||
PYEOF
|
||||
)
|
||||
if [ "$ui_check" = "OK" ]; then
|
||||
pass "$UI structural checks (inline CSS/JS, fetch ./audit.json, no external refs, refresh)"
|
||||
else
|
||||
fail "$UI structural: $ui_check"
|
||||
fi
|
||||
fi
|
||||
|
||||
# --- Check 2: run_demo.sh syntax ---
|
||||
echo "-- Check 2: run_demo.sh syntax + flags --"
|
||||
if bash -n scripts/run_demo.sh 2>/dev/null; then
|
||||
pass "run_demo.sh bash -n clean"
|
||||
else
|
||||
fail "run_demo.sh bash -n"
|
||||
fi
|
||||
if grep -q -- '--no-upload' scripts/run_demo.sh; then
|
||||
pass "run_demo.sh supports --no-upload flag"
|
||||
else
|
||||
fail "run_demo.sh missing --no-upload flag"
|
||||
fi
|
||||
|
||||
# --- Check 3: run_demo.sh dry-run (no upload) ---
|
||||
echo "-- Check 3: run_demo.sh --no-upload (4 acts, 11 events) --"
|
||||
rm -rf /tmp/acdl_demo_run
|
||||
out=$(ACDL_GITEA_TOKEN= bash scripts/run_demo.sh --no-upload 2>&1); rc=$?
|
||||
if [ "$rc" = "0" ]; then
|
||||
pass "run_demo.sh --no-upload exits 0"
|
||||
else
|
||||
fail "run_demo.sh --no-upload exit $rc"
|
||||
echo "$out" | tail -10
|
||||
fi
|
||||
audit="/tmp/acdl_demo_run/audit.json"
|
||||
if [ -f "$audit" ]; then
|
||||
pass "audit.json written to $audit"
|
||||
else
|
||||
fail "audit.json missing at $audit"
|
||||
fi
|
||||
|
||||
# --- Check 4: audit.json event count + Act 4 rejection ---
|
||||
echo "-- Check 4: audit.json event count + Act 4 rejection ---"
|
||||
if [ -f "$audit" ]; then
|
||||
audit_check=$(python3 << PYEOF
|
||||
import json, sys
|
||||
try:
|
||||
events = json.load(open("$audit"))
|
||||
n = len(events)
|
||||
if n < 11:
|
||||
print(f"FAIL: too few events ({n}, expected >= 11)")
|
||||
sys.exit(1)
|
||||
if not any('POLICY_VIOLATION:PUBLIC_INGRESS' in x.get('event', '') for x in events):
|
||||
print("FAIL: no Act 4 rejection event")
|
||||
sys.exit(1)
|
||||
if not any('Act 1 Friction' in x.get('event', '') for x in events):
|
||||
print("FAIL: no Act 1 event")
|
||||
sys.exit(1)
|
||||
if not any('Act 3' in x.get('event', '') for x in events):
|
||||
print("FAIL: no Act 3 event")
|
||||
sys.exit(1)
|
||||
if not any('l2-commodity-price-feed' in x.get('event', '') for x in events):
|
||||
print("FAIL: no l2-commodity-price-feed event")
|
||||
sys.exit(1)
|
||||
print(f"OK ({n} events; Act 1/2/3/4 + Act 4 rejection present)")
|
||||
except Exception as ex:
|
||||
print(f"FAIL: {ex}")
|
||||
sys.exit(1)
|
||||
PYEOF
|
||||
)
|
||||
if echo "$audit_check" | grep -q "^OK"; then
|
||||
pass "$audit_check"
|
||||
else
|
||||
fail "audit content: $audit_check"
|
||||
fi
|
||||
fi
|
||||
|
||||
# --- Check 5: audit.json hash chain integrity ---
|
||||
echo "-- Check 5: audit.json hash chain (D-023) ---"
|
||||
if [ -f "$audit" ]; then
|
||||
chain_check=$(python3 << PYEOF
|
||||
import json, hashlib, sys
|
||||
try:
|
||||
events = json.load(open("$audit"))
|
||||
assert events[0]['prev_hash'] == 'GENESIS', "genesis prev_hash"
|
||||
for i in range(1, len(events)):
|
||||
assert events[i]['prev_hash'] == events[i-1]['hash'], f"chain break at {i}"
|
||||
e = dict(events[i]); h = e.pop('hash'); e['hash'] = ''
|
||||
canon = json.dumps(e, sort_keys=True, separators=(',',':'))
|
||||
assert hashlib.sha256(canon.encode()).hexdigest() == h, f"hash mismatch at {i}"
|
||||
print("OK")
|
||||
except AssertionError as ex:
|
||||
print(f"FAIL: {ex}")
|
||||
sys.exit(1)
|
||||
PYEOF
|
||||
)
|
||||
if [ "$chain_check" = "OK" ]; then
|
||||
pass "audit.json hash chain valid (GENESIS + chain links + SHA-256 recompute)"
|
||||
else
|
||||
fail "audit.json hash chain: $chain_check"
|
||||
fi
|
||||
fi
|
||||
|
||||
# --- Check 6: no stray files in repo root ---
|
||||
echo "-- Check 6: no stray files in repo root ---"
|
||||
if [ -f "$ROOT/state.json" ]; then
|
||||
fail "state.json left in repo root"
|
||||
else
|
||||
pass "no state.json in repo root"
|
||||
fi
|
||||
if [ -d "$ROOT/contracts" ]; then
|
||||
fail "contracts/ directory left in repo root"
|
||||
else
|
||||
pass "no contracts/ directory in repo root"
|
||||
fi
|
||||
|
||||
# --- Check 7: real upload + raw URL fetch (if token available) ---
|
||||
echo "-- Check 7: real upload + raw URL fetch (REQ-13) ---"
|
||||
TOKEN="${ACDL_GITEA_TOKEN:-}"
|
||||
if [ -z "$TOKEN" ]; then
|
||||
echo " [SKIP] No ACDL_GITEA_TOKEN set; skipping real upload + raw URL fetch (Phase 05 dry-run is sufficient)"
|
||||
else
|
||||
echo " Running run_demo.sh (with upload)..."
|
||||
upload_out=$(bash scripts/run_demo.sh 2>&1); upload_rc=$?
|
||||
if [ "$upload_rc" = "0" ]; then
|
||||
pass "run_demo.sh (with upload) exits 0"
|
||||
else
|
||||
fail "run_demo.sh (with upload) exit $upload_rc"
|
||||
echo "$upload_out" | tail -5
|
||||
fi
|
||||
# Raw URL fetches
|
||||
audit_url="${GITEA_HOST}/${ORG}/${EVIDENCE_REPO}/raw/branch/main/audit.json"
|
||||
index_url="${GITEA_HOST}/${ORG}/${EVIDENCE_REPO}/raw/branch/main/index.html"
|
||||
audit_status=$(curl -sS -o /tmp/p05_audit_remote.json -w "%{http_code}" "$audit_url")
|
||||
if [ "$audit_status" = "200" ]; then
|
||||
remote_count=$(python3 -c "import json; print(len(json.load(open('/tmp/p05_audit_remote.json'))))" 2>/dev/null || echo "?")
|
||||
if [ "$remote_count" = "11" ] || [ "$remote_count" -ge 11 ] 2>/dev/null; then
|
||||
pass "raw audit.json returns 200 with ${remote_count} events"
|
||||
else
|
||||
pass "raw audit.json returns 200 (events: ${remote_count})"
|
||||
fi
|
||||
else
|
||||
fail "raw audit.json GET returned HTTP ${audit_status}"
|
||||
fi
|
||||
index_status=$(curl -sS -o /tmp/p05_index_remote.html -w "%{http_code}" "$index_url")
|
||||
if [ "$index_status" = "200" ]; then
|
||||
if grep -q "ACDL Evidence" /tmp/p05_index_remote.html && grep -q "audit.json" /tmp/p05_index_remote.html; then
|
||||
pass "raw index.html returns 200 with ACDL Evidence + audit.json reference"
|
||||
else
|
||||
fail "raw index.html returns 200 but missing ACDL Evidence / audit.json markers"
|
||||
fi
|
||||
else
|
||||
fail "raw index.html GET returned HTTP ${index_status}"
|
||||
fi
|
||||
fi
|
||||
|
||||
echo
|
||||
echo "== Summary =="
|
||||
if [ "$fail_count" -eq 0 ]; then
|
||||
echo "Phase 05 verification PASSED (UI + 4-act dry-run, all checks ok)"
|
||||
exit 0
|
||||
else
|
||||
echo "Phase 05 verification FAILED (${fail_count} check(s) failed)"
|
||||
exit 1
|
||||
fi
|
||||
@@ -0,0 +1,359 @@
|
||||
# Consumer Guide — Declare intent, deploy to AWS
|
||||
|
||||
This guide walks a consumer through creating their pipeline and defining a
|
||||
contract that deploys any ACDL module to AWS. It is **generic** across all
|
||||
L2 modules in the registry; `static-asset` is the worked example, but every
|
||||
step applies to `microservice` and any future L2 composition.
|
||||
|
||||
## The model
|
||||
|
||||
Consumers have their own repos and consume ACDL by referencing `uses:` the
|
||||
central pipeline definitions. The consumer declares a **contract** (which
|
||||
module, which environment, which inputs); the ACDL platform owns the
|
||||
pipelines, modules, Terraform adapter, and evidence stream.
|
||||
|
||||
You do not write Terraform, workflow YAML, or adapter code. You write a
|
||||
contract YAML file and the platform does the rest. Your repository contains
|
||||
only your application code and that one contract.
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
A["your repo<br/>(app code + contract.yaml)"] -->|uses: acdl/.gitea/workflows/deploy.yml@v1.4| B
|
||||
B["ACDL platform runners<br/>(modules/ + pipelines/ + adapters/ + schemas/)"] -->|contract -> resolver -> stack -> adapter<br/>-> terraform plan -> Checkov -> confidence<br/>-> apply -> evidence event to outbox| C
|
||||
C["your resources in AWS"]
|
||||
```
|
||||
|
||||
## Versioning the `uses:` reference
|
||||
|
||||
The central deployment pipeline is **always versioned with floating MAJOR
|
||||
and MINOR tags** (e.g. `acdl/pipelines/deploy.yaml@v1.4`). Version
|
||||
constraints cannot be expressed inside the contract, so the tag in
|
||||
`uses:` is the only immutability lever a consumer has.
|
||||
|
||||
**Unversioned references are discouraged.** Do not use `@main` or a bare
|
||||
`acdl/pipelines/deploy.yaml` — `main` is constantly updated and can cause
|
||||
unexpected failures in your deployment. Pinning to a MAJOR+MINOR tag means:
|
||||
|
||||
- **Immutability** — the pipeline behavior you tested is the behavior you
|
||||
get. Patch fixes flow within the tag; breaking changes land under the
|
||||
next MINOR tag (`@v1.5`), which you opt into explicitly.
|
||||
- **Resilience** — your deployment does not break because an unrelated
|
||||
change landed on `main`.
|
||||
- **DX** — your setup is stable and reproducible. You upgrade on your
|
||||
schedule by bumping the tag.
|
||||
|
||||
All examples in this guide use `@v1.4`. When a new MINOR tag is released
|
||||
(e.g. `@v1.5`), review its changelog and bump your `uses:` reference when
|
||||
ready.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
These are the **only** prerequisites for a consumer repo. You do **not**
|
||||
need an AWS account, Terraform, Checkov, boto3, or a rotated runner key —
|
||||
those are platform-repo concerns, provided by the platform runners.
|
||||
|
||||
- **A consumer GitHub or Gitea repository** for your application code +
|
||||
`contract.yaml`.
|
||||
- **An ACDL platform runner available to your org.** The platform team
|
||||
provides runners with Terraform, Checkov, Python, and the AWS auth
|
||||
already configured. You do not install any of these.
|
||||
- **Authorization to reference the central pipeline.** Onboarding grants
|
||||
your repo the right to `uses: acdl/.gitea/workflows/deploy.yml@v1.4`.
|
||||
Contact the platform team if you have not been onboarded.
|
||||
|
||||
## Step 1 — Create a consumer repo
|
||||
|
||||
Create a repository for your application. The top level holds your app
|
||||
code; your contract lives at `.acdl/contract.yaml`. Example for a static
|
||||
site:
|
||||
|
||||
```
|
||||
my-static-site/
|
||||
index.html
|
||||
assets/
|
||||
style.css
|
||||
logo.png
|
||||
.acdl/
|
||||
contract.yaml
|
||||
```
|
||||
|
||||
Example for a microservice:
|
||||
|
||||
```
|
||||
my-microservice/
|
||||
app.py
|
||||
Dockerfile
|
||||
.acdl/
|
||||
contract.yaml
|
||||
```
|
||||
|
||||
Your app code lives at the top level. Your contract lives at
|
||||
`.acdl/contract.yaml` regardless of the module you deploy.
|
||||
|
||||
## Step 2 — Reference the central pipeline
|
||||
|
||||
In your contract YAML, declare `uses:` pointing at the central ACDL
|
||||
deployment pipeline with a **versioned tag** (floating MAJOR + MINOR):
|
||||
|
||||
```yaml
|
||||
uses: acdl/pipelines/deploy.yaml@v1.4
|
||||
```
|
||||
|
||||
This tells the platform to run the standard deployment pipeline:
|
||||
validate-contract -> resolve-stack -> terraform-plan -> checkov ->
|
||||
confidence -> apply.
|
||||
|
||||
## Step 3 — Define the contract
|
||||
|
||||
Write `.acdl/contract.yaml`. The `static-asset` example:
|
||||
|
||||
```yaml
|
||||
uses: acdl/pipelines/deploy.yaml@v1.4
|
||||
module: static-asset
|
||||
environment: dev
|
||||
inputs:
|
||||
bucket_name: my-static-site-assets
|
||||
region: us-east-1
|
||||
```
|
||||
|
||||
A `microservice` example:
|
||||
|
||||
```yaml
|
||||
uses: acdl/pipelines/deploy.yaml@v1.4
|
||||
module: microservice
|
||||
environment: dev
|
||||
inputs:
|
||||
image: my-registry/my-microservice:latest
|
||||
port: 8080
|
||||
env:
|
||||
LOG_LEVEL: info
|
||||
```
|
||||
|
||||
### Contract fields
|
||||
|
||||
| Field | Type | Required | Description |
|
||||
|-------|------|----------|-------------|
|
||||
| `uses` | string | yes | Reference to the central deployment pipeline, **versioned** with a floating MAJOR+MINOR tag (e.g. `acdl/pipelines/deploy.yaml@v1.4`). Bare or `@main` references are discouraged. |
|
||||
| `module` | string | yes | Module name from the registry — any L1 primitive or L2 composition (e.g. `static-asset`, `microservice`, `s3`). See the [module catalog](../modules/README.md). |
|
||||
| `environment` | enum | yes | `dev` (autonomous), `qa` (QA HITL), `prod` (SRE HITL), `dr` (SRE HITL). |
|
||||
| `inputs` | object | yes | Module-specific inputs (see below). |
|
||||
|
||||
### Module inputs
|
||||
|
||||
Each module declares its inputs in its `interface.json` (L1) or
|
||||
`composition.json` (L2). Consult the [module catalog](../modules/README.md)
|
||||
for the full list, or read the module's own README under `modules/l1/<name>/`
|
||||
or `modules/l2/<name>/`.
|
||||
|
||||
**`static-asset` inputs** (the worked example):
|
||||
|
||||
| Input | Type | Required | Description |
|
||||
|-------|------|----------|-------------|
|
||||
| `bucket_name` | string | yes | Globally-unique S3 bucket name. |
|
||||
| `region` | string | yes | AWS region the bucket is created in. |
|
||||
|
||||
The contract is validated against `schemas/contract.schema.json`. An
|
||||
invalid contract (missing field, unknown module, wrong type) fails at the
|
||||
validate-contract stage with a clear error.
|
||||
|
||||
## Step 4 — Run the pipeline
|
||||
|
||||
You do **not** run platform scripts locally for the happy path. The
|
||||
central deploy workflow is a **reusable workflow** that the platform
|
||||
runners fetch and execute for you.
|
||||
|
||||
### The consumer workflow
|
||||
|
||||
Add a thin workflow file to **your** repo that invokes the reusable ACDL
|
||||
deploy workflow with a **versioned tag**. For Gitea Actions
|
||||
(`.gitea/workflows/deploy.yml`):
|
||||
|
||||
```yaml
|
||||
name: deploy
|
||||
on:
|
||||
push:
|
||||
branches: [main]
|
||||
jobs:
|
||||
deploy:
|
||||
uses: acdl/.gitea/workflows/deploy.yml@v1.4
|
||||
with:
|
||||
contract: .acdl/contract.yaml
|
||||
```
|
||||
|
||||
For GitHub Actions (`.github/workflows/deploy.yml`), the `uses:` line is
|
||||
identical — only the directory differs:
|
||||
|
||||
```yaml
|
||||
name: deploy
|
||||
on:
|
||||
push:
|
||||
branches: [main]
|
||||
jobs:
|
||||
deploy:
|
||||
uses: acdl/.github/workflows/deploy.yml@v1.4
|
||||
with:
|
||||
contract: .acdl/contract.yaml
|
||||
```
|
||||
|
||||
That is the entire consumer-side workflow. When you push to `main`:
|
||||
|
||||
1. The forge resolves `uses: acdl/.gitea/workflows/deploy.yml@v1.4` (or
|
||||
the GitHub equivalent) to the reusable workflow **at the pinned tag**.
|
||||
2. A **platform-provided runner** checks out **your** repo (the consumer
|
||||
repo).
|
||||
3. The runner checks out the **ACDL platform repo** into the workspace
|
||||
(`acdl-platform/`) — this is how the pipeline fetches the platform code
|
||||
at run time. You never clone the platform repo yourself.
|
||||
4. The runner installs the runtime dependencies (Python, Terraform,
|
||||
Checkov) that the platform requires.
|
||||
5. The runner invokes `scripts/run_platform.sh` against your
|
||||
`.acdl/contract.yaml`.
|
||||
|
||||
You see the streamed output (terraform plan, Checkov results, confidence
|
||||
signal) in your forge run logs. The `--check-only` and `--plan-only` flags
|
||||
are platform-side modes visible in the pipeline logs; you do not pass them
|
||||
yourself — the reusable workflow selects the mode based on the
|
||||
`environment` in your contract (`dev` = full apply; higher environments
|
||||
hold for HITL).
|
||||
|
||||
### Local validation (optional)
|
||||
|
||||
A consumer *may* clone the ACDL platform repo to run `--check-only`
|
||||
against their contract before pushing — this is optional and not required
|
||||
for the happy path. If you do this, the runtime dependencies (Python,
|
||||
`jsonschema`, `pyyaml`, `boto3`) must be installed locally, and any AWS
|
||||
credentials follow the [Credentials](../README.md#credentials--zero-trust)
|
||||
override model: a static key in `.env.secrets` (gitignored) is rotated
|
||||
**out of band by you** — the platform guarantees daily rotation for forge
|
||||
runs, not for locally-held copies.
|
||||
|
||||
```bash
|
||||
# Optional pre-push validation (clone the platform repo first):
|
||||
bash scripts/run_platform.sh --check-only path/to/your/.acdl/contract.yaml
|
||||
# Expected: "=== PLATFORM CHECK OK ==="
|
||||
```
|
||||
|
||||
## Step 5 — What the pipeline does
|
||||
|
||||
Each stage of the central deployment pipeline (`pipelines/deploy.yaml`):
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
S1["validate-contract<br/>schema check vs contract.schema.json"] --> S2
|
||||
S2["resolve-stack<br/>contract_resolver.py -> Target Stack JSON"] --> S3
|
||||
S3["terraform-plan<br/>adapter.py compiles stack -> terraform plan (real AWS)"] --> S4
|
||||
S4["checkov<br/>policy checks -> PolicyCheckResult records"] --> S5
|
||||
S5["confidence<br/>confidence_signal.py -> score + band (dev >= 0.50)"] --> S6
|
||||
S6["apply<br/>dev only: terraform apply + evidence event to outbox"]
|
||||
```
|
||||
|
||||
1. **validate-contract** — validates your contract YAML against
|
||||
`schemas/contract.schema.json`. Fails fast on missing fields, unknown
|
||||
modules, or wrong types.
|
||||
|
||||
2. **resolve-stack** — the contract resolver
|
||||
(`acdl_platform/contract_resolver.py`) resolves your contract to a
|
||||
Target Stack instance. It loads the module's composition, expands its
|
||||
children, wires your contract inputs to the children's inputs, and
|
||||
emits a stack JSON instance.
|
||||
|
||||
3. **terraform-plan** — the Terraform adapter
|
||||
(`adapters/terraform/adapter.py`) compiles the stack to Terraform
|
||||
(`main.tf`, `terraform.tf`, `providers.tf`) and runs `terraform plan`
|
||||
against real AWS. You see the plan in your run logs.
|
||||
|
||||
4. **checkov** — Checkov runs policy checks on the emitted Terraform. The
|
||||
results are normalized to `PolicyCheckResult` records by the Checkov
|
||||
adapter. Each result has a severity, rule ID, and pass/fail status.
|
||||
|
||||
5. **confidence** — the confidence signal
|
||||
(`acdl_platform/confidence_signal.py`) computes a score from 6 inputs
|
||||
(policy, validation, freshness, source, history, NFRs). For `dev`, the
|
||||
threshold is >= 0.50. If the band is `pass`, the pipeline proceeds.
|
||||
|
||||
6. **apply** — (dev only, autonomous per the environment model) Terraform
|
||||
applies the plan, creating the resources in your AWS account. An
|
||||
evidence event (hash-chained) is written to the DynamoDB outbox.
|
||||
|
||||
## Step 6 — What gets created
|
||||
|
||||
After a successful `dev` run, the resources declared by your module's
|
||||
composition exist in your AWS account, and an evidence event is recorded.
|
||||
|
||||
For the `static-asset` example:
|
||||
|
||||
- **An S3 bucket** named `my-static-site-assets` in `us-east-1` with
|
||||
versioning enabled.
|
||||
- **An evidence event** in the DynamoDB outbox (`acdl-outbox` table) with
|
||||
the contract ID, stack name (`static-asset`), confidence score, and band.
|
||||
- **A confidence band** of `pass` (score >= 0.50 for dev).
|
||||
|
||||
For other modules, consult the module's README
|
||||
(`modules/l1/<name>/README.md` or `modules/l2/<name>/README.md`) for the
|
||||
exact resources created.
|
||||
|
||||
## Step 7 — Upload your content (static-asset example)
|
||||
|
||||
The platform provisions the infrastructure; you upload your content. For
|
||||
the `static-asset` module:
|
||||
|
||||
```bash
|
||||
aws s3 sync ./assets s3://my-static-site-assets/ --acl public-read
|
||||
```
|
||||
|
||||
(For a proper static site, configure the bucket for website hosting or
|
||||
put a CloudFront distribution in front — both are future compliance
|
||||
extension points for the `static-asset` module.)
|
||||
|
||||
For a `microservice`, the platform provisions the ECS service and ALB; you
|
||||
push your container image to the ECR repo the platform created.
|
||||
|
||||
## Step 8 — Promote to qa / prod
|
||||
|
||||
Change `environment` in your contract (keeping the same versioned `uses:`):
|
||||
|
||||
```yaml
|
||||
uses: acdl/pipelines/deploy.yaml@v1.4
|
||||
environment: qa # QA HITL gate + confidence >= 0.75
|
||||
environment: prod # SRE HITL gate + confidence >= 0.90
|
||||
```
|
||||
|
||||
Higher environments require human attestation (forge deployment approval)
|
||||
and higher confidence thresholds. The platform enforces separation of
|
||||
duties (qaApprover != prodApprover) via the DynamoDB outbox.
|
||||
|
||||
| Environment | Autonomy | Gate |
|
||||
|-------------|----------|------|
|
||||
| dev | Full autonomy | Confidence >= 0.50 |
|
||||
| qa | QA HITL | Confidence >= 0.75 |
|
||||
| prod | SRE HITL | Confidence >= 0.90 |
|
||||
| dr | SRE HITL | Confidence >= 0.95 + dr-drill |
|
||||
|
||||
## Step 9 — Compliance extensions
|
||||
|
||||
Each module lists compliance extension points for the future compliance
|
||||
milestone (GDPR, SOX, SOC2, HIPAA, DORA). See each module's README under
|
||||
`modules/l1/<name>/README.md` or `modules/l2/<name>/README.md` for the
|
||||
per-module extension points. Common examples:
|
||||
|
||||
- **KMS key** — shared encryption key for SSE.
|
||||
- **S3 access logs** — access logging to a separate audit bucket.
|
||||
- **Object Lock** — 7-year immutable retention for evidence.
|
||||
- **Public access block** — prevent data exfiltration.
|
||||
|
||||
## Reference
|
||||
|
||||
| Resource | Path | Description |
|
||||
|----------|------|-------------|
|
||||
| Central deployment pipeline contract | `pipelines/deploy.yaml` | The pipeline stages your contract references. |
|
||||
| Reusable deploy workflow (Gitea) | `.gitea/workflows/deploy.yml` | The workflow your repo invokes via `uses:`. |
|
||||
| Reusable deploy workflow (GitHub) | `.github/workflows/deploy.yml` | The workflow your repo invokes via `uses:`. |
|
||||
| Contract schema | `schemas/contract.schema.json` | JSON Schema for consumer contracts. |
|
||||
| Stack schema | `schemas/stack.schema.json` | JSON Schema for the resolved stack instance. |
|
||||
| Module catalog | `modules/README.md` | All L1 primitives and L2 compositions. |
|
||||
| Sample contract | `contracts/static-asset.yaml` | The reference example contract (uses `@v1.4`). |
|
||||
| Contract resolver | `acdl_platform/contract_resolver.py` | Resolves contracts to stack instances. |
|
||||
| Terraform adapter | `adapters/terraform/adapter.py` | Compiles stack instances to Terraform. |
|
||||
| Platform pipeline runner | `scripts/run_platform.sh` | The pipeline runner (platform-side; consumers do not invoke it directly). |
|
||||
| Platform README | `README.md` | How the platform works + how to run the platform repo locally. |
|
||||
| Credentials & zero-trust | `README.md#credentials--zero-trust` | The OIDC/ABAC default + static-key override model. |
|
||||
+19
-19
@@ -33,7 +33,7 @@ Resolution session log (v1.0 snapshot — see PROJECT.md for full text):
|
||||
| BA.C | On-call / operational ownership | ✅ RESOLVED — platform on-call = Infra & Ops; L3A/L3B halt → platform on-call (Sev2); consumer-visible outage → consumer on-call (Sev1) + platform support. |
|
||||
| BA.D | Cost / capacity governance | ✅ RESOLVED — FinOps owns cloud cost; per-contract monthly reporting; runaway spend hard-halts at 120% of declared budget via the confidence signal; override = FinOps + SRE joint sign-off. |
|
||||
| BA.E | Consumer onboarding | ✅ RESOLVED — developer (L3A): `getting-started` → contract schema + central pipeline template; citizen (L3B): scoped agent + skill catalog, no workflow authoring; both end in a sandbox dev submission that must pass the confidence gate. |
|
||||
| BA.F | Cross-platform evolution | ✅ RESOLVED — contract schema, IR, PolicyCheckResult, confidence signal, audit stream are portable (forge-agnostic); forge-specific code = workflow YAML, OIDC trust, CODEOWNERS, Environments; a second forge needs a forge adapter + workflow-template translator, no change to L1/L2/IR/confidence/audit. |
|
||||
| BA.F | Cross-platform evolution | ✅ RESOLVED — contract schema, stack, PolicyCheckResult, confidence signal, audit stream are portable (forge-agnostic); forge-specific code = workflow YAML, OIDC trust, CODEOWNERS, Environments; a second forge needs a forge adapter + workflow-template translator, no change to L1/L2/stack/confidence/audit. |
|
||||
| Q1.3 | OpenTofu timing | ✅ RESOLVED (deferred) — not in v1 or v1.1; the substrate abstraction (§12) makes OpenTofu a future adapter, not an architecture change; revisit when an OpenTofu adapter is requested. |
|
||||
|
||||
---
|
||||
@@ -74,7 +74,7 @@ Locked commitments (unchanged from v0.1):
|
||||
|
||||
✅ RESOLVED (see PROJECT.md W1.A): AI-refinement operational trigger — joint condition: N ≥ 50 consecutive changes with zero rollbacks AND no L1/L2 incident in last 6 months AND Infra & Ops holds a unilateral override.
|
||||
|
||||
✅ RESOLVED (sub-decision): The L1 module's interface field is defined against the Target Stack IR, not against Terraform's variable block directly. In v1, the IR is shaped to round-trip cleanly to Terraform, but the schema is substrate-agnostic. Pending v1 implementation details in Section 12.
|
||||
✅ RESOLVED (sub-decision): The L1 module's interface field is defined against the Target Stack, not against Terraform's variable block directly. In v1, the stack is shaped to round-trip cleanly to Terraform, but the schema is substrate-agnostic. Pending v1 implementation details in Section 12.
|
||||
|
||||
## 3. Layer 2 — Composed Stacks
|
||||
|
||||
@@ -96,7 +96,7 @@ Locked commitments (unchanged from v0.1):
|
||||
|
||||
✅ RESOLVED (see PROJECT.md W1.B): Multi-stack edge case rule — permitted only for (a) DR-region mirror, (b) time-boxed experimental stack with TTL ≤ 30 days, (c) explicit Infra & Ops approval for a documented reason captured in multiStack.justification.
|
||||
|
||||
✅ RESOLVED (sub-decision): The L2 thin-composition tree's wires field is defined against the IR's relationship type, not against a Terraform module block. The IR → Terraform translation is the Terraform adapter's job (Section 12). The thin-composition pipeline itself is substrate-agnostic.
|
||||
✅ RESOLVED (sub-decision): The L2 composition tree's wires field is defined against the stack's relationship type, not against a Terraform module block. The stack → Terraform translation is the Terraform adapter's job (Section 12). The composition pipeline itself is substrate-agnostic.
|
||||
|
||||
## 4. Layer 3A — Developer Consumer Surface
|
||||
|
||||
@@ -297,7 +297,7 @@ Purpose. The technical execution layer for the L1/L2 substrate, including the su
|
||||
|
||||
### 12.1 Substrate abstraction (locked this revision)
|
||||
|
||||
L1/L2 are substrate-agnostic in shape. The architecture defines a Target Stack Intermediate Representation (IR) — a substrate-neutral description of:
|
||||
L1/L2 are substrate-agnostic in shape. The architecture defines a Target Stack — a substrate-neutral description of:
|
||||
|
||||
- Resources with typed input contracts, typed output contracts, and declared NFRs.
|
||||
|
||||
@@ -307,25 +307,25 @@ L1/L2 are substrate-agnostic in shape. The architecture defines a Target Stack I
|
||||
|
||||
- Policy hooks (the points in the composition where policy checks attach).
|
||||
|
||||
The L1 registry, the L2 thin-composition tree, the YML standard, and the policy check result schema are all defined against the IR. None of them is defined against any specific substrate.
|
||||
The L1 registry, the L2 thin-composition tree, the YML standard, and the policy check result schema are all defined against the stack schema. None of them is defined against any specific substrate.
|
||||
|
||||
Substrate adapters are the only substrate-specific code. An adapter compiles the IR into a substrate execution plan. v1 ships exactly one adapter: the Terraform adapter. v2+ may add additional adapters (OpenTofu, Pulumi, K8s CRDs) without architectural change.
|
||||
Substrate adapters are the only substrate-specific code. An adapter compiles the stack into a substrate execution plan. v1 ships exactly one adapter: the Terraform adapter. v2+ may add additional adapters (OpenTofu, Pulumi, K8s CRDs) without architectural change.
|
||||
|
||||
v1 implementation reality: the IR is shaped to round-trip cleanly to Terraform because there is no other adapter to differentiate from. The IR and the Terraform output are nearly isomorphic in v1. As additional adapters appear in v2+, the IR gets more expressive (e.g., substrate-specific output types) and the adapters gain translation logic, but the L1 module content, the YML standard, and the thin-composition tree do not change. This is the design that prevents the polyglot mess.
|
||||
v1 implementation reality: the stack is shaped to round-trip cleanly to Terraform because there is no other adapter to differentiate from. The stack and the Terraform output are nearly isomorphic in v1. As additional adapters appear in v2+, the stack gets more expressive (e.g., substrate-specific output types) and the adapters gain translation logic, but the L1 module content, the YML standard, and the composition tree do not change. This is the design that prevents the polyglot mess.
|
||||
|
||||
Why not build the abstraction earlier? Building a substrate-agnostic IR before there is a second adapter to test against is speculative generality. The v1 commitment is: (1) the L1 module interface is defined against the IR even though the only adapter is Terraform, and (2) the central pipeline, registry, and policy schema consume the IR-typed contracts. The adapter is the only place where substrate terminology appears in v1.
|
||||
Why not build the abstraction earlier? Building a substrate-agnostic stack before there is a second adapter to test against is speculative generality. The v1 commitment is: (1) the L1 module interface is defined against the stack schema even though the only adapter is Terraform, and (2) the central pipeline, registry, and policy schema consume the stack-typed contracts. The adapter is the only place where substrate terminology appears in v1.
|
||||
|
||||
### 12.2 Terraform adapter (v1)
|
||||
|
||||
The Terraform adapter:
|
||||
|
||||
- Translates the IR-typed L1 module interface to a Terraform variable block and a Terraform output block.
|
||||
- Translates the stack-typed L1 module interface to a Terraform variable block and a Terraform output block.
|
||||
|
||||
- Translates the IR-typed L2 thin-composition tree to a Terraform root module that calls the L1 modules.
|
||||
- Translates the stack-typed L2 composition tree to a Terraform root module that calls the L1 modules.
|
||||
|
||||
- Translates the IR-typed relationships to Terraform module references.
|
||||
- Translates the stack-typed relationships to Terraform module references.
|
||||
|
||||
- Emits a Terraform plan from the IR.
|
||||
- Emits a Terraform plan from the stack.
|
||||
|
||||
The adapter is a thin layer. It does not own L1/L2 content; it only translates.
|
||||
|
||||
@@ -372,7 +372,7 @@ Schema (canonical form, lives in the central pipeline repo):
|
||||
"result": "pass | fail | skipped | error",
|
||||
"message": "human-readable",
|
||||
"evidence": { "...engine-specific payload, opaque to the signal..." },
|
||||
"resourceRef": "IR-typed resource identifier"
|
||||
"resourceRef": "stack-typed resource identifier"
|
||||
}
|
||||
```
|
||||
|
||||
@@ -380,11 +380,11 @@ The Checkov adapter runs in the same GitHub Actions step as Checkov itself and t
|
||||
|
||||
### 12.7 Registry maintenance
|
||||
|
||||
Locked: L1 module publication updates the L1 registry in the same PR as the module. Registry and module land together. The registry is the IR-typed contract, not a Terraform-specific variable schema. The L1 registry, the central pipeline, and the policy schema all consume the same IR-typed contract — there is one source of truth for the L1 interface, not multiple substrate-specific copies.
|
||||
Locked: L1 module publication updates the L1 registry in the same PR as the module. Registry and module land together. The registry is the stack-typed contract, not a Terraform-specific variable schema. The L1 registry, the central pipeline, and the policy schema all consume the same stack-typed contract — there is one source of truth for the L1 interface, not multiple substrate-specific copies.
|
||||
|
||||
### 12.8 Contract-schema-to-IR resolution
|
||||
### 12.8 Contract-schema-to-stack resolution
|
||||
|
||||
The contract schema declares the consumer's intent in IR-typed terms. The central pipeline resolves the contract to a target stack (a list of L1 module instances with their inputs and the relationships between them). The Terraform adapter compiles the target stack to a Terraform execution plan. This resolution is substrate-agnostic — the target stack is in the IR.
|
||||
The contract schema declares the consumer's intent in stack-typed terms. The central pipeline resolves the contract to a target stack (a list of L1 module instances with their inputs and the relationships between them). The Terraform adapter compiles the target stack to a Terraform execution plan. This resolution is substrate-agnostic — the target stack is in the stack schema.
|
||||
|
||||
## 13. Consolidated Open Design Decisions
|
||||
|
||||
@@ -420,7 +420,7 @@ by `✅ RESOLVED (see PROJECT.md)`.
|
||||
|
||||
- (BA.E) Consumer onboarding. ✅ RESOLVED (see PROJECT.md) — developer (L3A): getting-started → contract schema + central pipeline template; citizen (L3B): scoped agent + skill catalog; both end in a sandbox dev submission that must pass the confidence gate.
|
||||
|
||||
- (BA.F) Cross-platform evolution. ✅ RESOLVED (see PROJECT.md) — contract schema, IR, PolicyCheckResult, confidence signal, audit stream are portable; forge-specific code = workflow YAML, OIDC trust, CODEOWNERS, Environments; a second forge needs a forge adapter + workflow-template translator.
|
||||
- (BA.F) Cross-platform evolution. ✅ RESOLVED (see PROJECT.md) — contract schema, stack, PolicyCheckResult, confidence signal, audit stream are portable; forge-specific code = workflow YAML, OIDC trust, CODEOWNERS, Environments; a second forge needs a forge adapter + workflow-template translator.
|
||||
|
||||
- (Q1.3) OpenTofu timing. ✅ RESOLVED (deferred — see PROJECT.md) — not in v1 or v1.1; the substrate abstraction makes OpenTofu a future adapter, not an architecture change.
|
||||
|
||||
@@ -428,7 +428,7 @@ by `✅ RESOLVED (see PROJECT.md)`.
|
||||
|
||||
Status: **v1.0**. All 11 open items in §13 are resolved. The architecture is
|
||||
internally consistent; the v1.1 implementation spike (ACDL Phases 08-10)
|
||||
validates the locked substrate abstraction + contract→IR→adapter path
|
||||
validates the locked substrate abstraction + contract→stack→adapter path
|
||||
against real AWS via a per-run-rotated key (D-039; OIDC deferred to v1.2).
|
||||
The v1.2 build-out (S3 Object Lock, JWS, HITL wiring, L3B skill catalog,
|
||||
Kyverno/OPA, real OIDC federation, multi-region) is design-authored in
|
||||
@@ -447,7 +447,7 @@ Phase 07):
|
||||
|
||||
| REQ | File | Owner persona |
|
||||
|-----|------|--------------|
|
||||
| REQ-17 | `schemas/ir.schema.json` | platform-engineer |
|
||||
| REQ-17 | `schemas/stack.schema.json` | platform-engineer |
|
||||
| REQ-18 | `schemas/policy_check_result.schema.json` + `adapters/terraform/policy/checkov_adapter.py` | security-engineer |
|
||||
| REQ-19 | `platform/confidence_signal.py` | backend-engineer + security-engineer (co-authored) |
|
||||
| REQ-20 | `platform/audit_ledger_design.md` | security-engineer |
|
||||
|
||||
+18
-18
@@ -2,7 +2,7 @@
|
||||
|
||||
Three things to set up before I deliver the document, because they determine how I write the doc:
|
||||
|
||||
1. What is locked from the resolution session. Eight items: environment model (Path A — dev-only autonomous, no staging), substrate abstraction (Target Stack IR + adapter pattern, Terraform adapter in v1), policy toolchain (Checkov for Terraform plan, Kyverno for K8s, OPA last resort), separation of duties (CODEOWNERS for routing + DynamoDB outbox for identity distinctness), policy normalization PolicyCheckResult schema with engine adapters), HITL matrix (full 8-concern matrix with evidence, freshness, source), HITL timeout (1d warn, 2d freeze), HITL rollback (pre-execution model, audit chain extended, no partial deploy).
|
||||
1. What is locked from the resolution session. Eight items: environment model (Path A — dev-only autonomous, no staging), substrate abstraction (Target Stack + adapter pattern, Terraform adapter in v1), policy toolchain (Checkov for Terraform plan, Kyverno for K8s, OPA last resort), separation of duties (CODEOWNERS for routing + DynamoDB outbox for identity distinctness), policy normalization PolicyCheckResult schema with engine adapters), HITL matrix (full 8-concern matrix with evidence, freshness, source), HITL timeout (1d warn, 2d freeze), HITL rollback (pre-execution model, audit chain extended, no partial deploy).
|
||||
|
||||
2. What is still open after the session. Eleven items, listed in the updated Section 13. They are the gating items for v1.0.
|
||||
|
||||
@@ -25,7 +25,7 @@ Resolution session log (this revision):
|
||||
| ID | Question | Resolution |
|
||||
|---|---|---|
|
||||
| Q1 | Environment model | Path A locked. Dev is the only autonomous environment. QA HITL at qa. SRE HITL at prod and dr. Staging does not exist. |
|
||||
| Q1.2 | Substrate trajectory | Substrate abstraction locked. L1/L2 are defined against a Target Stack IR. Substrate adapters compile the IR to a substrate execution plan. v1 ships only the Terraform adapter. |
|
||||
| Q1.2 | Substrate trajectory | Substrate abstraction locked. L1/L2 are defined against a Target Stack. Substrate adapters compile the stack to a substrate execution plan. v1 ships only the Terraform adapter. |
|
||||
| Q1.3 | OpenTofu timing | 🟡 OPEN (W3.D-adjacent). No specific version or trigger committed. |
|
||||
| Q2.1 | Policy toolchain | Locked. Checkov for Terraform plan policy. Kyverno for K8s-native and platform-internal policy. OPA/Rego reserved for cross-resource cases; explicitly last resort due to Rego complexity. |
|
||||
| Q2.2 | Separation of duties | Locked. GitHub CODEOWNERS routes the right reviewer to the right environment. Platform-internal identity record in DynamoDB outbox enforces qaApprover ≠ prodApprover for the same contract. |
|
||||
@@ -76,7 +76,7 @@ Locked commitments (unchanged from v0.1):
|
||||
|
||||
🟡 OPEN (W1.A): AI-refinement operational trigger. The criterion for flipping aiRefinement from false to true needs a falsifiable operational signal. Recommendation: joint condition — N ≥ 50 consecutive changes with zero rollbacks AND no L1/L2 incident in the last 6 months AND Infra & Ops holds a unilateral override. Pending sign-off.
|
||||
|
||||
🟡 OPEN (sub-decision surfaced this revision): The L1 module's interface field is defined against the Target Stack IR, not against Terraform's variable block directly. In v1, the IR is shaped to round-trip cleanly to Terraform, but the schema is substrate-agnostic. Pending v1 implementation details in Section 12.
|
||||
🟡 OPEN (sub-decision surfaced this revision): The L1 module's interface field is defined against the Target Stack, not against Terraform's variable block directly. In v1, the stack is shaped to round-trip cleanly to Terraform, but the schema is substrate-agnostic. Pending v1 implementation details in Section 12.
|
||||
|
||||
## 3. Layer 2 — Composed Stacks
|
||||
|
||||
@@ -98,7 +98,7 @@ Locked commitments (unchanged from v0.1):
|
||||
|
||||
🟡 OPEN (W1.B): Multi-stack edge case rule. The multiStack: true exception needs a falsifiable rule. Recommendation: permitted only for (a) DR-region mirror of the primary stack, (b) time-boxed experimental stack with TTL ≤ 30 days, (c) explicit Infra & Ops approval for a documented reason captured in multiStack.justification. Pending sign-off.
|
||||
|
||||
🟡 OPEN (sub-decision surfaced this revision): The L2 thin-composition tree's wires field is defined against the IR's relationship type, not against a Terraform module block. The IR → Terraform translation is the Terraform adapter's job (Section 12). The thin-composition pipeline itself is substrate-agnostic.
|
||||
🟡 OPEN (sub-decision surfaced this revision): The L2 composition tree's wires field is defined against the stack's relationship type, not against a Terraform module block. The stack → Terraform translation is the Terraform adapter's job (Section 12). The composition pipeline itself is substrate-agnostic.
|
||||
|
||||
## 4. Layer 3A — Developer Consumer Surface
|
||||
|
||||
@@ -301,7 +301,7 @@ Purpose. The technical execution layer for the L1/L2 substrate, including the su
|
||||
|
||||
### 12.1 Substrate abstraction (locked this revision)
|
||||
|
||||
L1/L2 are substrate-agnostic in shape. The architecture defines a Target Stack Intermediate Representation (IR) — a substrate-neutral description of:
|
||||
L1/L2 are substrate-agnostic in shape. The architecture defines a Target Stack — a substrate-neutral description of:
|
||||
|
||||
- Resources with typed input contracts, typed output contracts, and declared NFRs.
|
||||
|
||||
@@ -311,25 +311,25 @@ L1/L2 are substrate-agnostic in shape. The architecture defines a Target Stack I
|
||||
|
||||
- Policy hooks (the points in the composition where policy checks attach).
|
||||
|
||||
The L1 registry, the L2 thin-composition tree, the YML standard, and the policy check result schema are all defined against the IR. None of them is defined against any specific substrate.
|
||||
The L1 registry, the L2 composition tree, the YML standard, and the policy check result schema are all defined against the stack schema. None of them is defined against any specific substrate.
|
||||
|
||||
Substrate adapters are the only substrate-specific code. An adapter compiles the IR into a substrate execution plan. v1 ships exactly one adapter: the Terraform adapter. v2+ may add additional adapters (OpenTofu, Pulumi, K8s CRDs) without architectural change.
|
||||
Substrate adapters are the only substrate-specific code. An adapter compiles the stack into a substrate execution plan. v1 ships exactly one adapter: the Terraform adapter. v2+ may add additional adapters (OpenTofu, Pulumi, K8s CRDs) without architectural change.
|
||||
|
||||
v1 implementation reality: the IR is shaped to round-trip cleanly to Terraform because there is no other adapter to differentiate from. The IR and the Terraform output are nearly isomorphic in v1. As additional adapters appear in v2+, the IR gets more expressive (e.g., substrate-specific output types) and the adapters gain translation logic, but the L1 module content, the YML standard, and the thin-composition tree do not change. This is the design that prevents the polyglot mess.
|
||||
v1 implementation reality: the stack is shaped to round-trip cleanly to Terraform because there is no other adapter to differentiate from. The stack and the Terraform output are nearly isomorphic in v1. As additional adapters appear in v2+, the stack gets more expressive (e.g., substrate-specific output types) and the adapters gain translation logic, but the L1 module content, the YML standard, and the composition tree do not change. This is the design that prevents the polyglot mess.
|
||||
|
||||
Why not build the abstraction earlier? Building a substrate-agnostic IR before there is a second adapter to test against is speculative generality. The v1 commitment is: (1) the L1 module interface is defined against the IR even though the only adapter is Terraform, and (2) the central pipeline, registry, and policy schema consume the IR-typed contracts. The adapter is the only place where substrate terminology appears in v1.
|
||||
Why not build the abstraction earlier? Building a substrate-agnostic stack before there is a second adapter to test against is speculative generality. The v1 commitment is: (1) the L1 module interface is defined against the stack schema even though the only adapter is Terraform, and (2) the central pipeline, registry, and policy schema consume the stack-typed contracts. The adapter is the only place where substrate terminology appears in v1.
|
||||
|
||||
### 12.2 Terraform adapter (v1)
|
||||
|
||||
The Terraform adapter:
|
||||
|
||||
- Translates the IR-typed L1 module interface to a Terraform variable block and a Terraform output block.
|
||||
- Translates the stack-typed L1 module interface to a Terraform variable block and a Terraform output block.
|
||||
|
||||
- Translates the IR-typed L2 thin-composition tree to a Terraform root module that calls the L1 modules.
|
||||
- Translates the stack-typed L2 composition tree to a Terraform root module that calls the L1 modules.
|
||||
|
||||
- Translates the IR-typed relationships to Terraform module references.
|
||||
- Translates the stack-typed relationships to Terraform module references.
|
||||
|
||||
- Emits a Terraform plan from the IR.
|
||||
- Emits a Terraform plan from the stack.
|
||||
|
||||
The adapter is a thin layer. It does not own L1/L2 content; it only translates.
|
||||
|
||||
@@ -367,7 +367,7 @@ Schema (canonical form, lives in the central pipeline repo):
|
||||
"result": "pass | fail | skipped | error",
|
||||
"message": "human-readable",
|
||||
"evidence": { "...engine-specific payload, opaque to the signal..." },
|
||||
"resourceRef": "IR-typed resource identifier"
|
||||
"resourceRef": "stack-typed resource identifier"
|
||||
}
|
||||
```
|
||||
|
||||
@@ -375,11 +375,11 @@ The Checkov adapter runs in the same GitHub Actions step as Checkov itself and t
|
||||
|
||||
### 12.7 Registry maintenance
|
||||
|
||||
Locked: L1 module publication updates the L1 registry in the same PR as the module. Registry and module land together. The registry is the IR-typed contract, not a Terraform-specific variable schema. The L1 registry, the central pipeline, and the policy schema all consume the same IR-typed contract — there is one source of truth for the L1 interface, not multiple substrate-specific copies.
|
||||
Locked: L1 module publication updates the L1 registry in the same PR as the module. Registry and module land together. The registry is the stack-typed contract, not a Terraform-specific variable schema. The L1 registry, the central pipeline, and the policy schema all consume the same stack-typed contract — there is one source of truth for the L1 interface, not multiple substrate-specific copies.
|
||||
|
||||
### 12.8 Contract-schema-to-IR resolution
|
||||
### 12.8 Contract-schema-to-stack resolution
|
||||
|
||||
The contract schema declares the consumer's intent in IR-typed terms. The central pipeline resolves the contract to a target stack (a list of L1 module instances with their inputs and the relationships between them). The Terraform adapter compiles the target stack to a Terraform execution plan. This resolution is substrate-agnostic — the target stack is in the IR.
|
||||
The contract schema declares the consumer's intent in stack-typed terms. The central pipeline resolves the contract to a target stack (a list of L1 module instances with their inputs and the relationships between them). The Terraform adapter compiles the target stack to a Terraform execution plan. This resolution is substrate-agnostic — the target stack is in the stack schema.
|
||||
|
||||
🟡 OPEN (W3.D): L1/L2 standard versioning details, including pin model and evolution compatibility contract.
|
||||
|
||||
@@ -429,7 +429,7 @@ To finalize to v1.0:
|
||||
|
||||
1. Resolve the 11 open items in Section 13.
|
||||
|
||||
2. Validate the locked substrate abstraction against a real v1 implementation spike (one L1 module, one L2 thin-composition, one Terraform adapter, one contract submission end-to-end). The spike validates that the IR-shaped commitments do not require a polyglot mess.
|
||||
2. Validate the locked substrate abstraction against a real v1 implementation spike (one L1 module, one L2 composition, one Terraform adapter, one contract submission end-to-end). The spike validates that the stack commitments do not require a polyglot mess.
|
||||
|
||||
3. Validate the locked HITL matrix against a tabletop exercise with QA and SRE.
|
||||
|
||||
|
||||
@@ -1,56 +0,0 @@
|
||||
# l1-alb — Application Load Balancer primitive (multi-resource L1)
|
||||
|
||||
An L1 module for an Application Load Balancer (load balancer + target
|
||||
group + listener). Substrate-agnostic (the IR types are
|
||||
`aws:elbv2:loadbalancer`, `aws:elbv2:listener`, `aws:elbv2:targetgroup`,
|
||||
not Terraform resource types). This is a multi-resource L1: the
|
||||
interface declares the group's inputs/outputs plus a `resources` array
|
||||
listing the IR types it emits. The IR instance (Phase 14/15) will have
|
||||
multiple `resources` entries all with `module: "l1-alb@1.0.0"`.
|
||||
|
||||
## Interface (the IR-typed contract)
|
||||
|
||||
See `interface.json`: inputs `name` (string), `subnets` (string,
|
||||
comma-separated, ref to l1-vpc), `security_group` (string), `port`
|
||||
(number, default 80), `protocol` (string, default "HTTP"), `region`
|
||||
(string); outputs `lb_arn` (arn) + `listener_arn` (arn) +
|
||||
`target_group_arn` (arn); no NFRs.
|
||||
|
||||
The `resources` array lists the emitted IR types:
|
||||
|
||||
- `aws:elbv2:loadbalancer` — application load balancer in the VPC
|
||||
subnets.
|
||||
- `aws:elbv2:targetgroup` — target group for the ECS service tasks.
|
||||
- `aws:elbv2:listener` — listener forwarding the LB port to the target
|
||||
group.
|
||||
|
||||
## IR → Terraform mapping (performed by the adapter)
|
||||
|
||||
The Terraform adapter (`adapters/terraform/adapter.py`) translates each
|
||||
emitted IR resource to Terraform:
|
||||
|
||||
| IR | Terraform |
|
||||
|----|-----------|
|
||||
| `resource.type = aws:elbv2:loadbalancer` | `resource "aws_lb" "<id>" { ... }` |
|
||||
| `resource.inputs.name` | `name = <value>` arg |
|
||||
| `resource.inputs.subnets` | `subnets = [<value>]` arg (comma-split) |
|
||||
| `resource.inputs.security_group` | `security_groups = [<value>]` arg (comma-split) |
|
||||
| `resource.outputs.lb_arn` | `output "lb_arn" { value = aws_lb.<id>.id }` |
|
||||
| `resource.type = aws:elbv2:targetgroup` | `resource "aws_lb_target_group" "<id>" { ... }` |
|
||||
| `resource.inputs.port` | `port = <value>` arg |
|
||||
| `resource.inputs.protocol` | `protocol = <value>` arg |
|
||||
| `resource.outputs.target_group_arn` | `output "target_group_arn" { value = aws_lb_target_group.<id>.arn }` |
|
||||
| `resource.type = aws:elbv2:listener` | `resource "aws_lb_listener" "<id>" { ... }` |
|
||||
| `resource.inputs.lb_arn` | `load_balancer_arn = <value>` arg (identity) |
|
||||
| `resource.inputs.port` | `port = <value>` arg |
|
||||
| `resource.inputs.protocol` | `protocol = <value>` arg |
|
||||
| `resource.outputs.listener_arn` | `output "listener_arn" { value = aws_lb_listener.<id>.id }` |
|
||||
|
||||
The adapter is a thin layer (ARCHITECTURE.md §12.2); it does not own L1
|
||||
content — it only translates.
|
||||
|
||||
## Versioning (W3.D)
|
||||
|
||||
`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.
|
||||
@@ -1,32 +0,0 @@
|
||||
# l1-ecr — ECR repository primitive
|
||||
|
||||
An L1 module for an ECR repository that hosts the ECS task image.
|
||||
Single-purpose, substrate-agnostic (the IR type is
|
||||
`aws:ecr:repository`, not a Terraform resource type).
|
||||
|
||||
## Interface (the IR-typed contract)
|
||||
|
||||
See `interface.json`: inputs `name` + `region` (strings), outputs
|
||||
`repository_url` (string) + `repository_arn` (arn), no NFRs.
|
||||
|
||||
## IR → Terraform mapping (performed by the adapter)
|
||||
|
||||
The Terraform adapter (`adapters/terraform/adapter.py`) translates this
|
||||
L1's IR shape to Terraform:
|
||||
|
||||
| IR | Terraform |
|
||||
|----|-----------|
|
||||
| `resource.type = aws:ecr:repository` | `resource "aws_ecr_repository" "<id>" { ... }` |
|
||||
| `resource.inputs.name` | `name = <value>` arg |
|
||||
| `resource.inputs.region` | `provider "aws" { region = <value> }` |
|
||||
| `resource.outputs.repository_url` | `output "repository_url" { value = aws_ecr_repository.<id>.repository_url }` |
|
||||
| `resource.outputs.repository_arn` | `output "repository_arn" { value = aws_ecr_repository.<id>.arn }` |
|
||||
|
||||
The adapter is a thin layer (ARCHITECTURE.md §12.2); it does not own L1
|
||||
content — it only translates.
|
||||
|
||||
## Versioning (W3.D)
|
||||
|
||||
`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.
|
||||
@@ -1,32 +0,0 @@
|
||||
# l1-ecs-cluster — ECS Fargate cluster primitive
|
||||
|
||||
An L1 module for an ECS Fargate cluster. Single-purpose,
|
||||
substrate-agnostic (the IR type is `aws:ecs:cluster`, not a Terraform
|
||||
resource type).
|
||||
|
||||
## Interface (the IR-typed contract)
|
||||
|
||||
See `interface.json`: inputs `name` + `region` (strings), outputs
|
||||
`cluster_arn` (arn) + `cluster_id` (string), no NFRs.
|
||||
|
||||
## IR → Terraform mapping (performed by the adapter)
|
||||
|
||||
The Terraform adapter (`adapters/terraform/adapter.py`) translates this
|
||||
L1's IR shape to Terraform:
|
||||
|
||||
| IR | Terraform |
|
||||
|----|-----------|
|
||||
| `resource.type = aws:ecs:cluster` | `resource "aws_ecs_cluster" "<id>" { ... }` |
|
||||
| `resource.inputs.name` | `name = <value>` arg |
|
||||
| `resource.inputs.region` | `provider "aws" { region = <value> }` |
|
||||
| `resource.outputs.cluster_arn` | `output "cluster_arn" { value = aws_ecs_cluster.<id>.arn }` |
|
||||
| `resource.outputs.cluster_id` | `output "cluster_id" { value = aws_ecs_cluster.<id>.id }` |
|
||||
|
||||
The adapter is a thin layer (ARCHITECTURE.md §12.2); it does not own L1
|
||||
content — it only translates.
|
||||
|
||||
## Versioning (W3.D)
|
||||
|
||||
`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.
|
||||
@@ -1,55 +0,0 @@
|
||||
# l1-ecs-service — ECS Fargate service primitive (multi-resource L1)
|
||||
|
||||
An L1 module for an ECS Fargate service (task definition + service).
|
||||
Substrate-agnostic (the IR types are `aws:ecs:task_definition` and
|
||||
`aws:ecs:service`, not Terraform resource types). This is a
|
||||
multi-resource L1: the interface declares the group's inputs/outputs
|
||||
plus a `resources` array listing the IR types it emits. The IR instance
|
||||
(Phase 14/15) will have multiple `resources` entries all with
|
||||
`module: "l1-ecs-service@1.0.0"`.
|
||||
|
||||
## Interface (the IR-typed contract)
|
||||
|
||||
See `interface.json`: inputs `image` (string, ECR image URL), `port`
|
||||
(number), `cpu` (number, default 256), `memory` (number, default 512),
|
||||
`env` (optional JSON map string), `cluster_arn` (arn, ref to
|
||||
l1-ecs-cluster), `subnets` (string, ref to l1-vpc), `security_group`
|
||||
(string), `lb_target_group_arn` (arn, optional, ref to l1-alb), `region`
|
||||
(string); outputs `service_arn` (arn) + `task_def_arn` (arn); no NFRs.
|
||||
|
||||
The `resources` array lists the emitted IR types:
|
||||
|
||||
- `aws:ecs:task_definition` — Fargate task definition. The adapter
|
||||
jsonencodes `image`/`port`/`env` into `container_definitions`.
|
||||
- `aws:ecs:service` — Fargate service running the task definition in the
|
||||
cluster + subnets (+ optional ALB target group wiring).
|
||||
|
||||
## IR → Terraform mapping (performed by the adapter)
|
||||
|
||||
The Terraform adapter (`adapters/terraform/adapter.py`) translates each
|
||||
emitted IR resource to Terraform:
|
||||
|
||||
| IR | Terraform |
|
||||
|----|-----------|
|
||||
| `resource.type = aws:ecs:task_definition` | `resource "aws_ecs_task_definition" "<id>" { ... }` |
|
||||
| `resource.inputs.image` + `port` + `env` | `container_definitions = jsonencode(...)` (adapter-built) |
|
||||
| `resource.inputs.cpu` | `cpu = <value>` arg |
|
||||
| `resource.inputs.memory` | `memory = <value>` arg |
|
||||
| `resource.outputs.task_def_arn` | `output "task_def_arn" { value = aws_ecs_task_definition.<id>.arn }` |
|
||||
| `resource.type = aws:ecs:service` | `resource "aws_ecs_service" "<id>" { ... }` |
|
||||
| `resource.inputs.cluster_arn` | `cluster = <value>` arg (identity) |
|
||||
| `resource.inputs.subnets` | `network_configuration { subnets = [...] }` (emit as-is) |
|
||||
| `resource.inputs.security_group` | `network_configuration { security_groups = [...] }` (emit as-is) |
|
||||
| `resource.inputs.lb_target_group_arn` | `load_balancer { target_group_arn = <value> }` (emit as-is) |
|
||||
| `resource.outputs.service_arn` | `output "service_arn" { value = aws_ecs_service.<id>.id }` |
|
||||
|
||||
The adapter is a thin layer (ARCHITECTURE.md §12.2); it does not own L1
|
||||
content — it only translates. The `container_definitions` JSON is built
|
||||
by the adapter from the IR `image`/`port`/`env` inputs (the one
|
||||
transformation the adapter owns for ECS task definitions).
|
||||
|
||||
## Versioning (W3.D)
|
||||
|
||||
`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.
|
||||
@@ -1,36 +0,0 @@
|
||||
# l1-iam-role — IAM role primitive
|
||||
|
||||
An L1 module for an IAM role (used as the ECS task execution role).
|
||||
Single-purpose, substrate-agnostic (the IR type is `aws:iam:role`, not a
|
||||
Terraform resource type).
|
||||
|
||||
## Interface (the IR-typed contract)
|
||||
|
||||
See `interface.json`: inputs `role_name` (string), `assume_role_policy`
|
||||
(JSON string), `managed_policies` (optional comma-separated ARNs),
|
||||
`region` (string); outputs `role_arn` (arn) + `role_id` (string), no
|
||||
NFRs.
|
||||
|
||||
## IR → Terraform mapping (performed by the adapter)
|
||||
|
||||
The Terraform adapter (`adapters/terraform/adapter.py`) translates this
|
||||
L1's IR shape to Terraform:
|
||||
|
||||
| IR | Terraform |
|
||||
|----|-----------|
|
||||
| `resource.type = aws:iam:role` | `resource "aws_iam_role" "<id>" { ... }` |
|
||||
| `resource.inputs.role_name` | `name = <value>` arg |
|
||||
| `resource.inputs.assume_role_policy` | `assume_role_policy = <value>` arg (JSON string) |
|
||||
| `resource.inputs.managed_policies` | `managed_policy_arns = [<arns>]` arg (comma-split) |
|
||||
| `resource.inputs.region` | `provider "aws" { region = <value> }` |
|
||||
| `resource.outputs.role_arn` | `output "role_arn" { value = aws_iam_role.<id>.arn }` |
|
||||
| `resource.outputs.role_id` | `output "role_id" { value = aws_iam_role.<id>.id }` |
|
||||
|
||||
The adapter is a thin layer (ARCHITECTURE.md §12.2); it does not own L1
|
||||
content — it only translates.
|
||||
|
||||
## Versioning (W3.D)
|
||||
|
||||
`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.
|
||||
@@ -1,40 +0,0 @@
|
||||
# l1-s3 — S3 bucket primitive
|
||||
|
||||
The first real L1 module for the v1.1 spike. Single-purpose,
|
||||
substrate-agnostic (the IR type is `aws:s3:bucket`, not a Terraform
|
||||
resource type).
|
||||
|
||||
## Interface (the IR-typed contract)
|
||||
|
||||
See `interface.json`: inputs `bucket_name` + `region` (strings), outputs
|
||||
`bucket_arn` (arn) + `bucket_name` (string), NFR `versioning` (bool,
|
||||
default true).
|
||||
|
||||
## IR → Terraform mapping (performed by the adapter)
|
||||
|
||||
The Terraform adapter (`adapters/terraform/adapter.py`) translates this
|
||||
L1's IR shape to Terraform:
|
||||
|
||||
| IR | Terraform |
|
||||
|----|-----------|
|
||||
| `resource.type = aws:s3:bucket` | `resource "aws_s3_bucket" "<id>" { ... }` |
|
||||
| `resource.inputs.bucket_name` | `bucket = <value>` arg |
|
||||
| `resource.inputs.region` | `provider "aws" { region = <value> }` |
|
||||
| `resource.outputs.bucket_arn` | `output "bucket_arn" { value = aws_s3_bucket.<id>.arn }` |
|
||||
| `resource.outputs.bucket_name` | `output "bucket_name" { value = aws_s3_bucket.<id>.id }` |
|
||||
|
||||
The adapter is a thin layer (ARCHITECTURE.md §12.2); it does not own L1
|
||||
content — it only translates.
|
||||
|
||||
## Spike instance
|
||||
|
||||
`spike_instance.json` is a concrete stack instance (with values
|
||||
`bucket_name=acdl-spike-bucket`, `region=us-east-1`) that validates
|
||||
against `schemas/ir.schema.json`. The adapter consumes this instance
|
||||
(not the interface contract) to emit Terraform.
|
||||
|
||||
## Versioning (W3.D)
|
||||
|
||||
`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.
|
||||
@@ -1,52 +0,0 @@
|
||||
# l1-vpc — VPC primitive (multi-resource L1)
|
||||
|
||||
An L1 module for a VPC with subnets and a route table. Substrate-agnostic
|
||||
(the IR types are `aws:ec2:vpc`, `aws:ec2:subnet`, `aws:ec2:routetable`,
|
||||
not Terraform resource types). This is a multi-resource L1: the
|
||||
interface declares the group's inputs/outputs plus a `resources` array
|
||||
listing the IR types it emits. The IR instance (Phase 14/15) will have
|
||||
multiple `resources` entries all with `module: "l1-vpc@1.0.0"`.
|
||||
|
||||
## Interface (the IR-typed contract)
|
||||
|
||||
See `interface.json`: inputs `cidr` (string, e.g. "10.0.0.0/16"), `azs`
|
||||
(string, comma-separated, e.g. "us-east-1a,us-east-1b"), `name` (string,
|
||||
used for tagging), `region` (string); outputs `vpc_id` (string),
|
||||
`subnet_ids` (string, comma-separated), `igw_id` (string); no NFRs.
|
||||
|
||||
The `resources` array lists the emitted IR types:
|
||||
|
||||
- `aws:ec2:vpc` — the VPC itself (cidr → cidr_block, name → tag).
|
||||
- `aws:ec2:subnet` — one subnet per availability zone (`azs` split on
|
||||
comma); inputs include the parent VPC id.
|
||||
- `aws:ec2:routetable` — route table bound to the VPC with an internet
|
||||
gateway + default route (0.0.0.0/0 → igw).
|
||||
|
||||
## IR → Terraform mapping (performed by the adapter)
|
||||
|
||||
The Terraform adapter (`adapters/terraform/adapter.py`) translates each
|
||||
emitted IR resource to Terraform:
|
||||
|
||||
| IR | Terraform |
|
||||
|----|-----------|
|
||||
| `resource.type = aws:ec2:vpc` | `resource "aws_vpc" "<id>" { ... }` |
|
||||
| `resource.inputs.cidr` | `cidr_block = <value>` arg |
|
||||
| `resource.inputs.name` | `tags = { Name = <value> }` (emit as-is) |
|
||||
| `resource.outputs.vpc_id` | `output "vpc_id" { value = aws_vpc.<id>.id }` |
|
||||
| `resource.type = aws:ec2:subnet` | `resource "aws_subnet" "<id>" { ... }` |
|
||||
| `resource.inputs.cidr` | `cidr_block = <value>` arg |
|
||||
| `resource.inputs.az` | `availability_zone = <value>` arg |
|
||||
| `resource.outputs.subnet_id` | `output "subnet_id" { value = aws_subnet.<id>.id }` |
|
||||
| `resource.type = aws:ec2:routetable` | `resource "aws_route_table" "<id>" { ... }` |
|
||||
| `resource.inputs.vpc_id` | `vpc_id = <value>` arg |
|
||||
|
||||
The internet gateway + default route are emitted as part of the route
|
||||
table resource's IR (the `igw_id` output is wired via the route table's
|
||||
inputs). The adapter is a thin layer (ARCHITECTURE.md §12.2); it does
|
||||
not own L1 content — it only translates.
|
||||
|
||||
## Versioning (W3.D)
|
||||
|
||||
`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.
|
||||
@@ -1,85 +0,0 @@
|
||||
# l2-microservice — thin-composition (ECS Fargate microservice)
|
||||
|
||||
The v1.2 L2. A thin-composition that references 6 L1s (depth 1):
|
||||
`l1-vpc`, `l1-ecs-cluster`, `l1-ecr`, `l1-iam-role`, `l1-alb`,
|
||||
`l1-ecs-service`. The contract's inputs (`name`, `cidr`, `azs`,
|
||||
`image`, `port`, `cpu`, `memory`, `env`, `protocol`, `region`,
|
||||
`role_name`, `assume_role_policy`, `managed_policies`) map to the
|
||||
children's inputs through two wire kinds.
|
||||
|
||||
## Composition (the IR-typed thin-composition tree)
|
||||
|
||||
See `composition.json`: `kind=l2`, `depth=1`, six children.
|
||||
|
||||
### Children
|
||||
|
||||
| child id | L1 module | IR type(s) |
|
||||
|----------|-----------|------------|
|
||||
| `vpc` | `l1-vpc@1.0.0` | `aws:ec2:vpc`, `aws:ec2:subnet`, `aws:ec2:routetable` |
|
||||
| `cluster` | `l1-ecs-cluster@1.0.0` | `aws:ecs:cluster` |
|
||||
| `ecr` | `l1-ecr@1.0.0` | `aws:ecr:repository` |
|
||||
| `roles` | `l1-iam-role@1.0.0` | `aws:iam:role` |
|
||||
| `alb` | `l1-alb@1.0.0` | `aws:elbv2:loadbalancer`, `aws:elbv2:listener`, `aws:elbv2:targetgroup` |
|
||||
| `service` | `l1-ecs-service@1.0.0` | `aws:ecs:task_definition`, `aws:ecs:service` |
|
||||
|
||||
Multi-resource L1s (`vpc`, `alb`, `service`) declare a `resources`
|
||||
array in their `interface.json`; the resolver expands each child into
|
||||
one IR resource per `resources` entry (id scheme `<child_id>-<type_suffix>`
|
||||
where `type_suffix` is the last segment of the IR type with underscores
|
||||
stripped — e.g. `vpc-vpc`, `vpc-subnet`, `vpc-routetable`,
|
||||
`alb-loadbalancer`, `alb-targetgroup`, `alb-listener`,
|
||||
`service-taskdefinition`, `service-service`. The hyphen separator keeps
|
||||
the id valid against `schemas/ir.schema.json`'s
|
||||
`^[a-z][a-z0-9-]*$` resource id pattern). Single-resource L1s keep the
|
||||
child id verbatim (`cluster`, `ecr`, `roles`).
|
||||
|
||||
### Wire kinds
|
||||
|
||||
1. **Contract→child passthrough** — wire name = contract input name;
|
||||
target = child id, input = child's input name. For contract inputs
|
||||
that fan out to multiple children (`name`, `port`, `region`), the
|
||||
wire value is an array of `{target, input}` objects; otherwise a
|
||||
single object. Resolves to the concrete contract value.
|
||||
|
||||
2. **Child→child references** — wire with `source: "child:<id>.<output>"`.
|
||||
The value is only known at apply time, so the resolver emits the IR
|
||||
input as the string `ref:<ir_resource_id>.<output>` (the IR resource
|
||||
id of the *producing* child's first resource — for single-resource
|
||||
L1s that is the child id, for multi-resource L1s it is
|
||||
`<child_id>-<type_suffix>` of the first resource in the `resources`
|
||||
array that declares the output). The adapter translates `ref:` to a
|
||||
Terraform interpolation.
|
||||
|
||||
Wires used by this composition:
|
||||
|
||||
- Passthrough: `name` (→vpc/cluster/ecr/alb), `cidr` (→vpc), `azs`
|
||||
(→vpc), `image` (→service), `port` (→service/alb), `cpu` (→service),
|
||||
`memory` (→service), `env` (→service), `protocol` (→alb), `region`
|
||||
(→all 6), `role_name` (→roles), `assume_role_policy` (→roles),
|
||||
`managed_policies` (→roles).
|
||||
- Child→child: `cluster_arn` (cluster→service), `subnet_ids`
|
||||
(vpc→service/alb `subnets`), `target_group_arn` (alb→service
|
||||
`lb_target_group_arn`), `role_arn` (roles→service/alb
|
||||
`security_group`).
|
||||
|
||||
## IR → Terraform mapping (D-P10-1)
|
||||
|
||||
The Terraform adapter consumes the *resolved IR instance* (which has
|
||||
`kind=l2` + all 6 L1s expanded into one IR resource per entry in each
|
||||
L1's `resources` array, with `ref:` strings on the consumer inputs).
|
||||
For a depth-1 thin-composition, the L2 root module **IS** the union of
|
||||
the L1 resources — no separate `module "l1_x" { source = "..." }`
|
||||
blocks. The existing adapter `TYPE_MAP` + `INPUT_MAP` + `OUTPUT_MAP`
|
||||
tables handle every IR type. `ref:<id>.<output>` inputs are translated
|
||||
to `${<tf_type>.<id>.<attr>}` (attribute mapped through `OUTPUT_MAP`
|
||||
for the referenced resource's type). The `relationships` array records
|
||||
the parent composition tree; ordering is implicit in the resource list.
|
||||
|
||||
v1.3+ may emit real `module "l1_x" { source = "..." }` blocks once L1s
|
||||
are published Terraform modules rather than inline resources.
|
||||
|
||||
## Versioning (W3.D)
|
||||
|
||||
`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.
|
||||
@@ -1,55 +0,0 @@
|
||||
{
|
||||
"name": "l2-microservice",
|
||||
"version": "1.0.0",
|
||||
"kind": "l2",
|
||||
"depth": 1,
|
||||
"description": "Thin-composition: an ECS Fargate microservice. References 6 L1s (vpc, cluster, ecr, roles, alb, service).",
|
||||
"children": [
|
||||
{"id": "vpc", "module": "l1-vpc@1.0.0"},
|
||||
{"id": "cluster", "module": "l1-ecs-cluster@1.0.0"},
|
||||
{"id": "ecr", "module": "l1-ecr@1.0.0"},
|
||||
{"id": "roles", "module": "l1-iam-role@1.0.0"},
|
||||
{"id": "alb", "module": "l1-alb@1.0.0"},
|
||||
{"id": "service", "module": "l1-ecs-service@1.0.0"}
|
||||
],
|
||||
"wires": {
|
||||
"name": [
|
||||
{"target": "vpc", "input": "name"},
|
||||
{"target": "cluster", "input": "name"},
|
||||
{"target": "ecr", "input": "name"},
|
||||
{"target": "alb", "input": "name"}
|
||||
],
|
||||
"cidr": {"target": "vpc", "input": "cidr"},
|
||||
"azs": {"target": "vpc", "input": "azs"},
|
||||
"image": {"target": "service", "input": "image"},
|
||||
"port": [
|
||||
{"target": "service", "input": "port"},
|
||||
{"target": "alb", "input": "port"}
|
||||
],
|
||||
"cpu": {"target": "service", "input": "cpu"},
|
||||
"memory": {"target": "service", "input": "memory"},
|
||||
"env": {"target": "service", "input": "env"},
|
||||
"protocol": {"target": "alb", "input": "protocol"},
|
||||
"region": [
|
||||
{"target": "vpc", "input": "region"},
|
||||
{"target": "cluster", "input": "region"},
|
||||
{"target": "ecr", "input": "region"},
|
||||
{"target": "roles", "input": "region"},
|
||||
{"target": "alb", "input": "region"},
|
||||
{"target": "service", "input": "region"}
|
||||
],
|
||||
"role_name": {"target": "roles", "input": "role_name"},
|
||||
"assume_role_policy": {"target": "roles", "input": "assume_role_policy"},
|
||||
"managed_policies": {"target": "roles", "input": "managed_policies"},
|
||||
"cluster_arn": {"target": "service", "input": "cluster_arn", "source": "child:cluster.cluster_arn"},
|
||||
"subnet_ids": [
|
||||
{"target": "service", "input": "subnets", "source": "child:vpc.subnet_ids"},
|
||||
{"target": "alb", "input": "subnets", "source": "child:vpc.subnet_ids"}
|
||||
],
|
||||
"target_group_arn": {"target": "service", "input": "lb_target_group_arn", "source": "child:alb.target_group_arn"},
|
||||
"role_arn": [
|
||||
{"target": "service", "input": "security_group", "source": "child:roles.role_arn"},
|
||||
{"target": "alb", "input": "security_group", "source": "child:roles.role_arn"}
|
||||
]
|
||||
}
|
||||
}
|
||||
@@ -1,31 +0,0 @@
|
||||
# l2-static-asset — thin-composition (S3 static asset)
|
||||
|
||||
The v1.1 spike's L2. A thin-composition that references `l1-s3` only
|
||||
(depth 1). The contract's inputs (`bucket_name`, `region`) map 1:1
|
||||
through the wires to the L1's inputs.
|
||||
|
||||
## Composition (the IR-typed thin-composition tree)
|
||||
|
||||
See `composition.json`: `kind=l2`, `depth=1`, one child `l1-s3@1.0.0`,
|
||||
wires `{bucket_name → s3.inputs.bucket_name, region → s3.inputs.region}`
|
||||
(passthrough).
|
||||
|
||||
## IR → Terraform mapping (D-P10-1)
|
||||
|
||||
The Terraform adapter consumes the *resolved IR instance* (which has
|
||||
`kind=l2` + the L1 resource `s3` in its `resources` array). For a
|
||||
depth-1 thin-composition, the L2 root module **IS** the L1's resource —
|
||||
no separate `module "l1_s3" { source = "..." }` block. The existing
|
||||
adapter `TYPE_MAP` + resource emission handle both l1 and l2 instances
|
||||
(the resources array is the same shape). The `relationships` array is
|
||||
ignored at the Terraform level for the spike (composition ordering is
|
||||
implicit in the single resource).
|
||||
|
||||
v1.2 may emit a real `module "l1_s3" { source = "..." }` block when L1s
|
||||
become published Terraform modules rather than inline resources.
|
||||
|
||||
## Versioning (W3.D)
|
||||
|
||||
`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.
|
||||
@@ -1,17 +0,0 @@
|
||||
{
|
||||
"name": "l2-static-asset",
|
||||
"version": "1.0.0",
|
||||
"kind": "l2",
|
||||
"depth": 1,
|
||||
"description": "Thin-composition: a single S3 bucket for static asset hosting. References l1-s3 only (depth 1).",
|
||||
"children": [
|
||||
{
|
||||
"id": "s3",
|
||||
"module": "l1-s3@1.0.0"
|
||||
}
|
||||
],
|
||||
"wires": {
|
||||
"bucket_name": {"target": "s3", "input": "bucket_name"},
|
||||
"region": {"target": "s3", "input": "region"}
|
||||
}
|
||||
}
|
||||
@@ -1,65 +0,0 @@
|
||||
{
|
||||
"l1-s3": {
|
||||
"1.0.0": {
|
||||
"interface": "modules-ir/l1/l1-s3/interface.json",
|
||||
"published_at": "2026-07-21T19:00:00Z",
|
||||
"deprecated": false
|
||||
}
|
||||
},
|
||||
"l1-vpc": {
|
||||
"1.0.0": {
|
||||
"interface": "modules-ir/l1/l1-vpc/interface.json",
|
||||
"published_at": "2026-07-21T21:30:00Z",
|
||||
"deprecated": false
|
||||
}
|
||||
},
|
||||
"l1-ecs-cluster": {
|
||||
"1.0.0": {
|
||||
"interface": "modules-ir/l1/l1-ecs-cluster/interface.json",
|
||||
"published_at": "2026-07-21T21:30:00Z",
|
||||
"deprecated": false
|
||||
}
|
||||
},
|
||||
"l1-ecs-service": {
|
||||
"1.0.0": {
|
||||
"interface": "modules-ir/l1/l1-ecs-service/interface.json",
|
||||
"published_at": "2026-07-21T21:30:00Z",
|
||||
"deprecated": false
|
||||
}
|
||||
},
|
||||
"l1-iam-role": {
|
||||
"1.0.0": {
|
||||
"interface": "modules-ir/l1/l1-iam-role/interface.json",
|
||||
"published_at": "2026-07-21T21:30:00Z",
|
||||
"deprecated": false
|
||||
}
|
||||
},
|
||||
"l1-alb": {
|
||||
"1.0.0": {
|
||||
"interface": "modules-ir/l1/l1-alb/interface.json",
|
||||
"published_at": "2026-07-21T21:30:00Z",
|
||||
"deprecated": false
|
||||
}
|
||||
},
|
||||
"l1-ecr": {
|
||||
"1.0.0": {
|
||||
"interface": "modules-ir/l1/l1-ecr/interface.json",
|
||||
"published_at": "2026-07-21T21:30:00Z",
|
||||
"deprecated": false
|
||||
}
|
||||
},
|
||||
"l2-static-asset": {
|
||||
"1.0.0": {
|
||||
"composition": "modules-ir/l2/l2-static-asset/composition.json",
|
||||
"published_at": "2026-07-21T19:30:00Z",
|
||||
"deprecated": false
|
||||
}
|
||||
},
|
||||
"l2-microservice": {
|
||||
"1.0.0": {
|
||||
"composition": "modules-ir/l2/l2-microservice/composition.json",
|
||||
"published_at": "2026-07-21T22:00:00Z",
|
||||
"deprecated": false
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,50 @@
|
||||
# <module-name> — <plain-language description>
|
||||
|
||||
> **Module kind:** L1 primitive | **Version:** 1.0.0
|
||||
|
||||
## Overview
|
||||
|
||||
One or two sentences describing what this module provisions, in plain
|
||||
language. No jargon. A reader should know after this paragraph whether
|
||||
this module is what they need.
|
||||
|
||||
## Resources
|
||||
|
||||
Terraform resources this module creates:
|
||||
|
||||
| Resource | Type | Purpose |
|
||||
|----------|------|---------|
|
||||
| `<name>` | `aws_<type>` | what it does |
|
||||
|
||||
## Inputs
|
||||
|
||||
| Name | Type | Required | Default | Description |
|
||||
|------|------|----------|---------|-------------|
|
||||
| `<name>` | string | yes | — | description |
|
||||
|
||||
## Outputs
|
||||
|
||||
| Name | Type | Description |
|
||||
|------|------|-------------|
|
||||
| `<name>` | string | description |
|
||||
|
||||
## Usage
|
||||
|
||||
```
|
||||
# A concrete snippet showing how to reference this module or what a
|
||||
# consumer writes to use it.
|
||||
```
|
||||
|
||||
## Compliance extension points
|
||||
|
||||
Resources this module could be extended with for the future compliance
|
||||
milestone (GDPR, SOX, SOC2, HIPAA, DORA). Not implemented yet — listed
|
||||
so the redesign can plan for them.
|
||||
|
||||
- **<area>** — <what could be added, e.g. KMS key for encryption>
|
||||
|
||||
## 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,50 @@
|
||||
# ACDL Modules
|
||||
|
||||
Reusable building blocks for cloud infrastructure. Each module is
|
||||
self-documented with a `README.md` following the
|
||||
[template](README-TEMPLATE.md).
|
||||
|
||||
## How the modules work
|
||||
|
||||
There are two kinds of module:
|
||||
|
||||
- **L1 primitives** — a single cloud resource or a small group of
|
||||
related resources (e.g. a VPC with subnets and routing). Each L1 has
|
||||
an `interface.json` declaring its inputs and outputs, and a `README.md`
|
||||
in plain language.
|
||||
- **L2 compositions** — a composition that references multiple L1s to
|
||||
deploy a complete stack (e.g. an ECS Fargate microservice). Each L2
|
||||
has a `composition.json` declaring its children and wires.
|
||||
|
||||
The Terraform adapter (`adapters/terraform/adapter.py`) compiles a
|
||||
module instance to Terraform. Each module's README documents which
|
||||
Terraform resources it creates.
|
||||
|
||||
## L1 primitives
|
||||
|
||||
| Module | What it creates | README |
|
||||
|--------|----------------|--------|
|
||||
| `s3` | `aws_s3_bucket` — a single S3 bucket | [README](l1/s3/README.md) |
|
||||
| `vpc` | `aws_vpc` + `aws_subnet` + `aws_route_table` + `aws_internet_gateway` — VPC with subnets and routing | [README](l1/vpc/README.md) |
|
||||
| `ecs-cluster` | `aws_ecs_cluster` — ECS Fargate cluster | [README](l1/ecs-cluster/README.md) |
|
||||
| `ecs-service` | `aws_ecs_task_definition` + `aws_ecs_service` — Fargate service with task definition | [README](l1/ecs-service/README.md) |
|
||||
| `iam-role` | `aws_iam_role` — IAM role with assume-role policy | [README](l1/iam-role/README.md) |
|
||||
| `alb` | `aws_lb` + `aws_lb_target_group` + `aws_lb_listener` — Application Load Balancer | [README](l1/alb/README.md) |
|
||||
| `ecr` | `aws_ecr_repository` — ECR container image repository | [README](l1/ecr/README.md) |
|
||||
|
||||
## L2 compositions
|
||||
|
||||
| Module | What it references | README |
|
||||
|--------|--------------------|--------|
|
||||
| `microservice` | 6 L1s (vpc, cluster, ecr, iam-role, alb, ecs-service) | [README](l2/microservice/README.md) |
|
||||
| `static-asset` | 1 L1 (s3) | [README](l2/static-asset/README.md) |
|
||||
|
||||
## Registry
|
||||
|
||||
Module versions are tracked in `registry.json`. Both L1 and L2 entries
|
||||
are registered.
|
||||
|
||||
## Template
|
||||
|
||||
New modules should use [README-TEMPLATE.md](README-TEMPLATE.md) as
|
||||
their starting point.
|
||||
@@ -0,0 +1,71 @@
|
||||
# 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 `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 `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": "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 `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.
|
||||
@@ -1,9 +1,9 @@
|
||||
{
|
||||
"name": "l1-alb",
|
||||
"name": "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).",
|
||||
"description": "Application Load Balancer primitive (substrate-agnostic stack 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",
|
||||
@@ -12,7 +12,7 @@
|
||||
},
|
||||
"subnets": {
|
||||
"type": "string",
|
||||
"description": "Comma-separated subnet ids (ref to l1-vpc).",
|
||||
"description": "Comma-separated subnet ids (ref to vpc).",
|
||||
"required": true
|
||||
},
|
||||
"security_group": {
|
||||
@@ -0,0 +1,58 @@
|
||||
# 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": "ecr@1.0.0",
|
||||
"inputs": {
|
||||
"name": "acdl-microservice",
|
||||
"region": "us-east-1"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
The `repository_url` output is used to build the `image` input for
|
||||
`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.
|
||||
@@ -1,9 +1,9 @@
|
||||
{
|
||||
"name": "l1-ecr",
|
||||
"name": "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).",
|
||||
"description": "ECR repository primitive (substrate-agnostic stack type aws:ecr:repository; the Terraform adapter translates to aws_ecr_repository).",
|
||||
"inputs": {
|
||||
"name": {
|
||||
"type": "string",
|
||||
@@ -0,0 +1,56 @@
|
||||
# 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 `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": "ecs-cluster@1.0.0",
|
||||
"inputs": {
|
||||
"name": "acdl-microservice",
|
||||
"region": "us-east-1"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
The `cluster_arn` output is referenced by `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.
|
||||
@@ -1,9 +1,9 @@
|
||||
{
|
||||
"name": "l1-ecs-cluster",
|
||||
"name": "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).",
|
||||
"description": "ECS Fargate cluster primitive (substrate-agnostic stack type aws:ecs:cluster; the Terraform adapter translates to aws_ecs_cluster).",
|
||||
"inputs": {
|
||||
"name": {
|
||||
"type": "string",
|
||||
@@ -0,0 +1,78 @@
|
||||
# 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 `ecs-cluster`) |
|
||||
| `subnets` | string | yes | — | Comma-separated subnet ids (from `vpc`) |
|
||||
| `security_group` | string | yes | — | Security group id for the service ENIs |
|
||||
| `lb_target_group_arn` | arn | no | — | Optional ALB target group ARN (from `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": "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.
|
||||
@@ -1,9 +1,9 @@
|
||||
{
|
||||
"name": "l1-ecs-service",
|
||||
"name": "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).",
|
||||
"description": "ECS Fargate service primitive (substrate-agnostic stack types aws:ecs:task_definition + aws:ecs:service; the Terraform adapter translates to aws_ecs_task_definition/aws_ecs_service).",
|
||||
"inputs": {
|
||||
"image": {
|
||||
"type": "string",
|
||||
@@ -34,12 +34,12 @@
|
||||
},
|
||||
"cluster_arn": {
|
||||
"type": "arn",
|
||||
"description": "ECS cluster ARN (ref to l1-ecs-cluster).",
|
||||
"description": "ECS cluster ARN (ref to ecs-cluster).",
|
||||
"required": true
|
||||
},
|
||||
"subnets": {
|
||||
"type": "string",
|
||||
"description": "Comma-separated subnet ids (ref to l1-vpc).",
|
||||
"description": "Comma-separated subnet ids (ref to vpc).",
|
||||
"required": true
|
||||
},
|
||||
"security_group": {
|
||||
@@ -49,7 +49,7 @@
|
||||
},
|
||||
"lb_target_group_arn": {
|
||||
"type": "arn",
|
||||
"description": "Optional ALB target group ARN (ref to l1-alb).",
|
||||
"description": "Optional ALB target group ARN (ref to alb).",
|
||||
"required": false
|
||||
},
|
||||
"region": {
|
||||
@@ -0,0 +1,64 @@
|
||||
# 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": "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.
|
||||
@@ -1,9 +1,9 @@
|
||||
{
|
||||
"name": "l1-iam-role",
|
||||
"name": "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).",
|
||||
"description": "IAM role primitive (substrate-agnostic stack type aws:iam:role; the Terraform adapter translates to aws_iam_role).",
|
||||
"inputs": {
|
||||
"role_name": {
|
||||
"type": "string",
|
||||
@@ -0,0 +1,63 @@
|
||||
# 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": "s3@1.0.0",
|
||||
"inputs": {
|
||||
"bucket_name": "acdl-spike-bucket",
|
||||
"region": "us-east-1"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
A concrete instance is at `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.
|
||||
@@ -1,7 +1,7 @@
|
||||
{
|
||||
"version": "1.0.0",
|
||||
"stack": {
|
||||
"name": "l1-s3",
|
||||
"name": "s3",
|
||||
"kind": "l1",
|
||||
"depth": 1
|
||||
},
|
||||
@@ -9,7 +9,7 @@
|
||||
{
|
||||
"id": "s3",
|
||||
"type": "aws:s3:bucket",
|
||||
"module": "l1-s3@1.0.0",
|
||||
"module": "s3@1.0.0",
|
||||
"inputs": {
|
||||
"bucket_name": "acdl-spike-bucket",
|
||||
"region": "us-east-1"
|
||||
@@ -1,9 +1,9 @@
|
||||
{
|
||||
"name": "l1-s3",
|
||||
"name": "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).",
|
||||
"description": "S3 bucket primitive (substrate-agnostic stack type aws:s3:bucket; the Terraform adapter translates to aws_s3_bucket).",
|
||||
"inputs": {
|
||||
"bucket_name": {
|
||||
"type": "string",
|
||||
@@ -0,0 +1,67 @@
|
||||
# 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": "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.
|
||||
@@ -1,9 +1,9 @@
|
||||
{
|
||||
"name": "l1-vpc",
|
||||
"name": "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).",
|
||||
"description": "VPC primitive (substrate-agnostic stack 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",
|
||||
@@ -0,0 +1,70 @@
|
||||
# microservice — ECS Fargate microservice
|
||||
|
||||
> **Module kind:** L2 composition | **Version:** 1.0.0
|
||||
|
||||
A composition that references multiple L1 primitives to deploy an ECS
|
||||
Fargate microservice end-to-end (VPC, cluster, ECR, IAM role, ALB,
|
||||
ECS service).
|
||||
|
||||
## Resources
|
||||
|
||||
The composition references these L1 primitives:
|
||||
|
||||
| L1 module | Purpose | README |
|
||||
|-----------|---------|--------|
|
||||
| `vpc` | VPC, subnets, routing | [README](../l1/vpc/README.md) |
|
||||
| `ecs-cluster` | ECS Fargate cluster | [README](../l1/ecs-cluster/README.md) |
|
||||
| `ecr` | ECR image repository | [README](../l1/ecr/README.md) |
|
||||
| `iam-role` | IAM task execution role | [README](../l1/iam-role/README.md) |
|
||||
| `alb` | Application Load Balancer | [README](../l1/alb/README.md) |
|
||||
| `ecs-service` | ECS task definition + service | [README](../l1/ecs-service/README.md) |
|
||||
|
||||
## Inputs
|
||||
|
||||
| Name | Type | Required | Description |
|
||||
|------|------|----------|-------------|
|
||||
| `image` | string | yes | ECR image URL for the task container |
|
||||
| `port` | number | yes | Container port the service listens on |
|
||||
| `region` | string | yes | AWS region |
|
||||
| `cidr` | string | no | VPC CIDR block (default 10.0.0.0/16) |
|
||||
| `azs` | string | no | Comma-separated availability zones |
|
||||
|
||||
## Outputs
|
||||
|
||||
| Name | Type | Description |
|
||||
|------|------|-------------|
|
||||
| `lb_arn` | arn | The load balancer ARN |
|
||||
| `service_arn` | arn | The ECS service ARN |
|
||||
|
||||
## Usage
|
||||
|
||||
Define a contract referencing this composition:
|
||||
|
||||
```yaml
|
||||
uses: acdl/pipelines/deploy.yaml@v1
|
||||
module: microservice
|
||||
environment: dev
|
||||
inputs:
|
||||
image: 581513795199.dkr.ecr.us-east-1.amazonaws.com/acdl-microservice:latest
|
||||
port: 8080
|
||||
region: us-east-1
|
||||
```
|
||||
|
||||
## Compliance extension points
|
||||
|
||||
The composition can wire compliance resources across L1s when the
|
||||
compliance milestone (GDPR, SOX, SOC2, HIPAA, DORA) lands:
|
||||
|
||||
- **KMS key** — shared encryption key referenced by S3, ECR, CloudWatch Logs, and Secrets Manager.
|
||||
- **CloudTrail** — management-plane audit trail for the entire stack.
|
||||
- **VPC Flow Logs** — network audit trail.
|
||||
- **Security groups** — proper network segmentation between ALB, service, and data tiers.
|
||||
- **Private subnets** — ECS tasks in private subnets with NAT egress.
|
||||
|
||||
See each L1 module's README for per-module compliance extension points.
|
||||
|
||||
## 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,34 @@
|
||||
{
|
||||
"name": "microservice",
|
||||
"version": "1.0.0",
|
||||
"kind": "l2",
|
||||
"depth": 1,
|
||||
"description": "A composition that references six L1 primitives to deploy an ECS Fargate microservice end-to-end.",
|
||||
"children": [
|
||||
{"id": "vpc", "module": "vpc@1.0.0"},
|
||||
{"id": "cluster", "module": "ecs-cluster@1.0.0"},
|
||||
{"id": "ecr", "module": "ecr@1.0.0"},
|
||||
{"id": "roles", "module": "iam-role@1.0.0"},
|
||||
{"id": "alb", "module": "alb@1.0.0"},
|
||||
{"id": "service", "module": "ecs-service@1.0.0"}
|
||||
],
|
||||
"wires": [
|
||||
{"from": "contract.inputs.bucket_name", "to": "vpc.inputs.cidr", "default": "10.0.0.0/16"},
|
||||
{"from": "contract.inputs.region", "to": "vpc.inputs.region"},
|
||||
{"from": "contract.inputs.region", "to": "cluster.inputs.region"},
|
||||
{"from": "contract.inputs.region", "to": "ecr.inputs.region"},
|
||||
{"from": "contract.inputs.region", "to": "roles.inputs.region"},
|
||||
{"from": "contract.inputs.region", "to": "alb.inputs.region"},
|
||||
{"from": "contract.inputs.region", "to": "service.inputs.region"},
|
||||
{"from": "vpc.outputs.subnet_ids", "to": "alb.inputs.subnets"},
|
||||
{"from": "vpc.outputs.subnet_ids", "to": "service.inputs.subnets"},
|
||||
{"from": "cluster.outputs.cluster_arn", "to": "service.inputs.cluster_arn"},
|
||||
{"from": "ecr.outputs.repository_url", "to": "service.inputs.image"},
|
||||
{"from": "roles.outputs.role_arn", "to": "service.inputs.security_group"},
|
||||
{"from": "alb.outputs.target_group_arn", "to": "service.inputs.lb_target_group_arn"}
|
||||
],
|
||||
"outputs": [
|
||||
{"from": "alb.outputs.lb_arn", "to": "stack.outputs.lb_arn"},
|
||||
{"from": "service.outputs.service_arn", "to": "stack.outputs.service_arn"}
|
||||
]
|
||||
}
|
||||
@@ -0,0 +1,64 @@
|
||||
# static-asset — S3 static asset
|
||||
|
||||
> **Module kind:** L2 composition | **Version:** 1.0.0
|
||||
|
||||
A composition that references the `s3` L1 primitive to deploy a single
|
||||
S3 bucket for static asset hosting.
|
||||
|
||||
## Resources
|
||||
|
||||
The composition references this L1 primitive:
|
||||
|
||||
| L1 module | Purpose | README |
|
||||
|-----------|---------|--------|
|
||||
| `s3` | S3 bucket | [README](../l1/s3/README.md) |
|
||||
|
||||
## Inputs
|
||||
|
||||
| Name | Type | Required | 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) |
|
||||
|
||||
## Usage
|
||||
|
||||
Define a contract referencing this composition:
|
||||
|
||||
```yaml
|
||||
uses: acdl/pipelines/deploy.yaml@v1
|
||||
module: static-asset
|
||||
environment: dev
|
||||
inputs:
|
||||
bucket_name: my-static-assets
|
||||
region: us-east-1
|
||||
```
|
||||
|
||||
See the [consumer guide](../../docs/CONSUMER_GUIDE.md) for a
|
||||
step-by-step walkthrough, and the [s3 README](../l1/s3/README.md) for the
|
||||
underlying L1 primitive.
|
||||
|
||||
## Compliance extension points
|
||||
|
||||
The composition can wire compliance resources when the compliance
|
||||
milestone (GDPR, SOX, SOC2, HIPAA, DORA) lands:
|
||||
|
||||
- **KMS key** — shared encryption key for S3 SSE.
|
||||
- **S3 access logs** — access logging to a separate audit bucket.
|
||||
- **Object Lock** — 7-year immutable retention for evidence.
|
||||
- **Public access block** — prevent data exfiltration.
|
||||
|
||||
See the [s3 README](../l1/s3/README.md) for per-module compliance extension
|
||||
points.
|
||||
|
||||
## 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,21 @@
|
||||
{
|
||||
"name": "static-asset",
|
||||
"version": "1.0.0",
|
||||
"kind": "l2",
|
||||
"depth": 1,
|
||||
"description": "A composition that references the s3 L1 primitive to deploy a single S3 bucket for static asset hosting.",
|
||||
"children": [
|
||||
{
|
||||
"id": "s3",
|
||||
"module": "s3@1.0.0"
|
||||
}
|
||||
],
|
||||
"wires": [
|
||||
{"from": "contract.inputs.bucket_name", "to": "s3.inputs.bucket_name"},
|
||||
{"from": "contract.inputs.region", "to": "s3.inputs.region"}
|
||||
],
|
||||
"outputs": [
|
||||
{"from": "s3.outputs.bucket_arn", "to": "stack.outputs.bucket_arn"},
|
||||
{"from": "s3.outputs.bucket_name", "to": "stack.outputs.bucket_name"}
|
||||
]
|
||||
}
|
||||
@@ -0,0 +1,65 @@
|
||||
{
|
||||
"s3": {
|
||||
"1.0.0": {
|
||||
"interface": "modules/l1/s3/interface.json",
|
||||
"published_at": "2026-07-21T19:00:00Z",
|
||||
"deprecated": false
|
||||
}
|
||||
},
|
||||
"vpc": {
|
||||
"1.0.0": {
|
||||
"interface": "modules/l1/vpc/interface.json",
|
||||
"published_at": "2026-07-21T21:30:00Z",
|
||||
"deprecated": false
|
||||
}
|
||||
},
|
||||
"ecs-cluster": {
|
||||
"1.0.0": {
|
||||
"interface": "modules/l1/ecs-cluster/interface.json",
|
||||
"published_at": "2026-07-21T21:30:00Z",
|
||||
"deprecated": false
|
||||
}
|
||||
},
|
||||
"ecs-service": {
|
||||
"1.0.0": {
|
||||
"interface": "modules/l1/ecs-service/interface.json",
|
||||
"published_at": "2026-07-21T21:30:00Z",
|
||||
"deprecated": false
|
||||
}
|
||||
},
|
||||
"iam-role": {
|
||||
"1.0.0": {
|
||||
"interface": "modules/l1/iam-role/interface.json",
|
||||
"published_at": "2026-07-21T21:30:00Z",
|
||||
"deprecated": false
|
||||
}
|
||||
},
|
||||
"alb": {
|
||||
"1.0.0": {
|
||||
"interface": "modules/l1/alb/interface.json",
|
||||
"published_at": "2026-07-21T21:30:00Z",
|
||||
"deprecated": false
|
||||
}
|
||||
},
|
||||
"ecr": {
|
||||
"1.0.0": {
|
||||
"interface": "modules/l1/ecr/interface.json",
|
||||
"published_at": "2026-07-21T21:30:00Z",
|
||||
"deprecated": false
|
||||
}
|
||||
},
|
||||
"static-asset": {
|
||||
"1.0.0": {
|
||||
"interface": "modules/l2/static-asset/composition.json",
|
||||
"published_at": "2026-07-22T15:00:00Z",
|
||||
"deprecated": false
|
||||
}
|
||||
},
|
||||
"microservice": {
|
||||
"1.0.0": {
|
||||
"interface": "modules/l2/microservice/composition.json",
|
||||
"published_at": "2026-07-22T15:00:00Z",
|
||||
"deprecated": false
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,50 @@
|
||||
# ACDL Central CI Pipeline Contract (v1.5)
|
||||
#
|
||||
# This is the single source of truth for the CI/CD pipeline. Both
|
||||
# .gitea/workflows/ci.yml (Gitea Actions, dev) and
|
||||
# .github/workflows/ci.yml (GitHub Actions, production) implement the
|
||||
# stages, commands, triggers, and runner declared here.
|
||||
# scripts/run_ci.sh mirrors the same stages for shell reproducibility.
|
||||
#
|
||||
# A test (tests/test_pipeline_contract.py) validates that both workflow
|
||||
# YAMLs conform to this contract and that run_ci.sh runs the same commands.
|
||||
#
|
||||
# The contract does NOT replace workflow YAML syntax — it declares the
|
||||
# *intent* that the forge-specific workflows implement. The workflow files
|
||||
# use Gitea/GitHub Actions syntax (checkout, setup-python, run blocks);
|
||||
# this contract declares what those blocks must contain.
|
||||
#
|
||||
# Validated against schemas/pipeline.schema.json.
|
||||
|
||||
name: acdl-ci
|
||||
environment: dev
|
||||
triggers:
|
||||
push: [main]
|
||||
pull_request: [main]
|
||||
runner: ubuntu-latest
|
||||
python_version: "3.12"
|
||||
|
||||
stages:
|
||||
- name: lint
|
||||
description: Compile all Python files (py_compile)
|
||||
command: |
|
||||
python3 -m py_compile \
|
||||
acdl_platform/confidence_signal.py \
|
||||
acdl_platform/outbox_writer.py \
|
||||
acdl_platform/contract_resolver.py \
|
||||
adapters/terraform/adapter.py \
|
||||
adapters/terraform/policy/checkov_adapter.py \
|
||||
scripts/push_consumer_image.py
|
||||
required: true
|
||||
|
||||
- name: test
|
||||
description: Run the pytest test suite offline
|
||||
command: python3 -m pytest tests/ -v --tb=short
|
||||
install: pip install -r requirements-test.txt
|
||||
required: true
|
||||
|
||||
- name: check-only
|
||||
description: Run the platform pipeline offline (no AWS/Checkov/DynamoDB)
|
||||
command: bash scripts/run_platform.sh --check-only
|
||||
install: pip install jsonschema pyyaml boto3
|
||||
required: true
|
||||
@@ -0,0 +1,51 @@
|
||||
# ACDL Central Deployment Pipeline Contract (v1.5)
|
||||
#
|
||||
# This is the single source of truth for the deployment pipeline. It
|
||||
# declares the stages that run when a consumer submits a contract:
|
||||
# validate-contract -> resolve-stack -> terraform-plan -> checkov ->
|
||||
# confidence -> apply (dev only)
|
||||
#
|
||||
# Consumers reference this pipeline via `uses: acdl/pipelines/deploy.yaml@v1`
|
||||
# in their contract YAML. The platform (scripts/run_platform.sh) implements
|
||||
# these stages.
|
||||
#
|
||||
# Validated against schemas/deploy-pipeline.schema.json.
|
||||
|
||||
name: acdl-deploy
|
||||
environment: dev
|
||||
triggers:
|
||||
push: [main]
|
||||
pull_request: [main]
|
||||
runner: ubuntu-latest
|
||||
python_version: "3.12"
|
||||
|
||||
stages:
|
||||
- name: validate-contract
|
||||
description: Validate the consumer contract against the contract schema
|
||||
command: python3 -c "import jsonschema, yaml; jsonschema.validate(yaml.safe_load(open('contracts/static-asset.yaml')), json.load(open('schemas/contract.schema.json')))"
|
||||
required: true
|
||||
|
||||
- name: resolve-stack
|
||||
description: Resolve the contract to a Target Stack instance via the contract resolver
|
||||
command: python3 acdl_platform/contract_resolver.py contracts/static-asset.yaml /tmp/acdl-stack.json
|
||||
required: true
|
||||
|
||||
- name: terraform-plan
|
||||
description: Compile the stack to Terraform and run terraform plan
|
||||
command: bash scripts/run_platform.sh --plan-only contracts/static-asset.yaml
|
||||
required: true
|
||||
|
||||
- name: checkov
|
||||
description: Run Checkov policy checks on the emitted Terraform
|
||||
command: checkov -f terraform/spike/main.tf --framework terraform -o json --soft-fail
|
||||
required: false
|
||||
|
||||
- name: confidence
|
||||
description: Compute the confidence signal from policy + validation inputs
|
||||
command: python3 acdl_platform/confidence_signal.py /tmp/acdl-deploy-inputs.json dev
|
||||
required: true
|
||||
|
||||
- name: apply
|
||||
description: Apply the Terraform plan (dev environment only, autonomous per §10)
|
||||
command: terraform -chdir=terraform/spike apply -auto-approve -lock=false
|
||||
required: false
|
||||
Some files were not shown because too many files have changed in this diff Show More
Reference in New Issue
Block a user