Files

T

Jon Chery 031887ec56 refactor(P57): contract surface redesign + rename + .yml repo-wide

Contract surface redesign:
- New top-level fields: id (3-6 char acronym → stack.name), name (full → stack.title),
  infrastructure (map keyed by module name, replaces module:)
- Drop uses: field (dead reference; version pin lives in CI workflow uses: line)
- Drop top-level module/inputs (now nested under infrastructure map)
- Per-module optional version (defaults to latest published from registry)
- Multi-module contracts: one file deploys N modules in one pipeline run,
  resource IDs namespaced with module name to avoid collisions
- stack.schema.json: add optional title field for display name

Rename:
- pipelines/deploy.yaml → pipelines/contract.yml (declarative spec, not a pipeline)
- pipelines/ci.yaml → pipelines/ci.yml
- All 44 .yaml files → .yml repo-wide (contracts, module examples, kyverno policies)
- .acdl/contract.yaml → .acdl/contract.yml

Resolver (core/contract_resolver.py):
- Rewrite resolve() to loop infrastructure map, default version to latest,
  merge module fragments into one stack with namespaced resource IDs
- _latest_version() picks highest non-deprecated from registry
- _namespace_resources() prefixes IDs + rewrites ref: expressions for multi-module
- Single-module path: unprefixed IDs (backward compatible)

Verification:
- 494 tests pass (0 contract-shape failures)
- Local E2E passes (contract → resolver → adapter → local ECS HTTP 200 → outbox)

---ci---
project: acdl
phase: 57
milestone: v1.10.2
status: execute
---/ci---

2026-07-27 21:37:40 +00:00

4.1 KiB

Raw Blame History

Pipeline

The platform runs two pipelines, both defined by declarative contracts that are the single source of truth for the workflow files.

CI pipeline

The CI pipeline runs on every push and pull request to main. It is defined by pipelines/ci.yml, validated against schemas/pipeline.schema.json. Both platform-runner workflow files implement the same contract and are byte-identical:

.github/workflows/ci.yml — GitHub Actions (production)

Three stages run in sequence:

lint — py_compile across the platform's Python files.
test — pytest across the offline test suite.
check-only — run_platform.sh --check-only (offline, no AWS).

scripts/run_ci.sh mirrors the CI pipeline locally so the pipeline is fully reproducible from the shell:

bash scripts/run_ci.sh           # run all 3 stages
bash scripts/run_ci.sh --quiet    # suppress per-stage banners

Deployment pipeline

The deployment pipeline runs when a consumer submits a contract. It is defined by pipelines/contract.yml, validated against schemas/deploy-pipeline.schema.json. It is exposed to consumer repos as a reusable workflow:

.github/workflows/deploy.yml — GitHub Actions (production)

A consumer repo invokes the reusable workflow via a versioned tag (floating MAJOR + MINOR, e.g. acdl/.github/workflows/deploy.yml@v1.6). 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 for the end-to-end happy path.

Deployment stages

flowchart TD
    S1["validate-contract<br/>schema check"] --> S2
    S2["resolve-stack<br/>contract -&gt; Target Stack"] --> S3
    S3["security checks<br/>(adapter)"] --> S4
    S4["infrastructure plan<br/>(adapter compiles the stack)"] --> S5
    S5["policy checks<br/>(adapter -&gt; PolicyCheckResult)"] --> S6
    S6["confidence<br/>score + band"] --> S7
    S7["evidence event<br/>to the audit outbox"] --> S8
    S8["infrastructure apply<br/>(dev only)"]

validate-contract — validates the contract YAML against the contract schema. Fails fast on missing fields, unknown modules, or wrong types.
resolve-stack — the contract resolver resolves the contract to a Target Stack instance (loads the module's pattern, expands its children, wires the contract inputs, emits a stack JSON instance).
security checks (adapter) — security checks run on the resolved stack before any infrastructure is planned.
infrastructure plan (adapter) — the engine adapter compiles the stack to an infrastructure plan.
policy checks (adapter) — policy checks run on the plan. Results are normalized to PolicyCheckResult records (severity, rule ID, pass/fail).
confidence — the confidence signal 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.
evidence event — a hash-chained evidence event is written to the audit outbox.
infrastructure apply (dev only) — the infrastructure plan is applied, creating the resources. An evidence event for the apply is recorded.

Higher environments hold for human attestation (see Environments).

Output streaming

scripts/run_platform.sh streams output by default so the user can see what the platform is doing:

--check-only: streams the emitted infrastructure file content.
--plan-only and full mode: streams the infrastructure plan output.
Full mode: prints policy-check results with severity, rule ID, and pass/fail status.

A --quiet flag suppresses streaming (output to log files only).

4.1 KiB Raw Blame History