acdl/adapters/README.md

# Nova Adapters

## Overview

Adapters translate the engine-agnostic Target Stack IR to engine-specific formats. The Terraform adapter is the primary adapter (IR → HCL). Policy adapters translate security tool output into normalized `PolicyCheckResult` records that the confidence signal consumes in an engine-agnostic way.

## Existing Adapters

| Adapter | Path | Input | Output | Purpose |
| --- | --- | --- | --- | --- |
| Terraform adapter | `adapters/terraform/adapter.py` | Stack instance JSON | Terraform HCL (`main.tf`, `terraform.tf`, `providers.tf`) | Compiles IR to Terraform |
| Checkov adapter | `adapters/terraform/policy/checkov_adapter.py` | Checkov JSON | `PolicyCheckResult` records | Translates Checkov results |
| Wiz adapter | `adapters/wiz/wiz_adapter.py` | Wiz API issues JSON | `PolicyCheckResult` records | Translates Wiz security findings |
| Kyverno adapter | `adapters/kyverno/kyverno_adapter.py` | Kyverno PolicyReport JSON | `PolicyCheckResult` records | K8s-native policy translation |
| kyverno-json engine | `adapters/kyverno-json/kyverno_json_engine.py` | Any JSON/YAML payload | `PolicyCheckResult` records | **v1.25 primary policy engine** (swappable via `PolicyEngine` protocol) |

## Policy Engine Protocol (v1.25)

The `core/policy_engine.py` module defines the **swap boundary** between
Nova and its policy engines. A `PolicyEngine` Python Protocol (PEP 544)
with three members (`name`, `is_configured()`, `evaluate()`) is the
contract; a `PolicyEngineRegistry` selects the active engine from
`config.json`'s `policy.engine` key. The confidence signal and pipeline
never import an engine directly — they go through the registry.

**Implementations:**
- `KyvernoJsonEngine` (`adapters/kyverno-json/`) — shells to the `kj`
  CLI; the v1.25 default.
- `NullEngine` (`core/policy_engine.py`) — fallback when the `policy`
  key is absent (emits `SKIPPED`).
- Future: `OpaEngine` — implements the same protocol, shells to
  `opa eval`. The OPA-equivalent surface is documented in
  `.ciagent/RESEARCH.md` §4.2.

**How to add a new engine:**
1. Create `adapters/<name>/<name>_engine.py` implementing the
   `PolicyEngine` protocol (`name`, `is_configured()`, `evaluate()`).
2. `evaluate()` returns `list[dict]` where each dict conforms to
   `schemas/policy_check_result.schema.json`.
3. Register the engine in `core/policy_engine.py`'s `_autoload_*`
   function (or call `register(name, factory)` at startup).
4. Set `config.json.policy.engine` to the engine's `name`.
5. Add the engine to the `engine` enum in
   `schemas/policy_check_result.schema.json` if it needs a distinct
   enum value (v1.25 reuses `"kyverno"` — see D-116).

## How to Write an Adapter

### Terraform Adapter Extension (stateless assembler — v1.11 rewrite)

> The adapter owns **no module content**. There is no `TYPE_MAP`, no
> `INPUT_MAP`, no `OUTPUT_MAP`, and no per-type branch logic (all deleted
> in the v1.11 rewrite — the 918-line monolith collapsed to a ~80-line
> assembler). Engine-specific shape lives in each L1 module's own
> `terraform/` dir (`versions.tf`/`variables.tf`/`locals.tf`/`main.tf`/
> `outputs.tf`); the adapter only assembles them.

To extend the Terraform adapter, **do not edit the adapter** — instead:

1. Add an L1 module with a real `terraform/` dir (owning its resource
   shape, nested HCL blocks, and defaults).
2. Register it in `modules/registry.json` under the module name with its
   `terraform_dir` path. The adapter reads `registry.json` to find each
   module's directory.
3. The adapter emits `module "<rid>" { source = "<path>" }` blocks at
   the root, with resolved inputs + wired `ref:` refs between modules.
   No type-specific translation lives in the adapter.

> If you find yourself reaching for a "TYPE_MAP"-style constant, the L1
> module is missing a piece — fix the module, not the adapter.

### Policy Adapter Pattern

1. Define `SEVERITY_MAP` and `RESULT_MAP` dicts that translate the engine's native severity/result vocabulary to the `PolicyCheckResult` enums.
2. Implement `_to_pcr(raw_record, contract_id)` → `PolicyCheckResult` dict.
3. Implement `adapt(input_path, contract_id)` → list of `PolicyCheckResult` dicts.
4. Implement `is_configured()` → bool (env var check) so the platform can skip the adapter when credentials are absent.

## How to Wire an Adapter

- **Terraform adapter** — invoked by `scripts/run_platform.sh` Step 3 (`terraform-plan`).
- **Checkov adapter** — invoked by `scripts/run_platform.sh` Step 5 (`checkov`).
- **Wiz / Kyverno adapters** — optional Steps 5b/5c, run only when the relevant env vars are set.
- All policy adapters output records that are validated against `schemas/policy_check_result.schema.json`.

## Dependencies

- `jsonschema`, `pyyaml` — used by all adapters for loading and validating inputs.
- `boto3` — used by the Wiz adapter for AWS API access.
- `checkov` — used by the Checkov adapter to run policy scans.
- No external deps for the Terraform adapter (pure Python).

## How to Test Adapters

- `tests/test_adapter.py` — Terraform adapter (stateless assembly: registry read, `module "<rid>" { source }` emission, `ref:` wiring, outputs). No `TYPE_MAP`/`INPUT_MAP` tests — the adapter owns no type mappings.
- `tests/test_checkov_adapter.py` — Checkov adapter.
- `tests/test_wiz_adapter.py` — Wiz adapter.
- `tests/test_kyverno_adapter.py` — Kyverno adapter.
- All adapter tests load fixtures from `tests/fixtures/` and use `moto` for AWS mocking.

## Where to Write Tests

- `tests/test_<adapter_name>.py` paired with `tests/fixtures/<adapter>_fixture.json`.

## Adding a New Adapter

1. Create `adapters/<name>/<name>_adapter.py`.
2. Implement `adapt()` and (for policy adapters) `is_configured()`.
3. Add the adapter's engine name to the `engine` enum in `schemas/policy_check_result.schema.json` if it is a policy adapter.
4. Write a test (`tests/test_<name>_adapter.py`) plus a fixture (`tests/fixtures/<name>_fixture.json`).
5. Add it to `scripts/run_platform.sh` if it is invoked at runtime.
6. Update this README.

## Consumers

The Terraform adapter compiles contract IR for consumer estates. The
first real consumer estate is now live:

| Consumer | Version | Environment | Account | Forge / Adapter | Status |
| --- | --- | --- | --- | --- | --- |
| `nova-blockchain-exchange` | v0.2 | dev | `581513795199` | inline adapter (see note below) | **live** (pilot apply `blkex-pilot-apply-v0.2`, 2026-08-19) |

### Forge adapter note (SPEC §10 Q1)

Forge Actions (the consumer's forge runtime) does **not** support
cross-repo `uses:` references — the forge rejects
`uses: <owner>/<repo>/.github/workflows/<file>@<ref>` with
`expected format {owner}/{repo}/.{git_platform}/workflows/{filename}@{ref}`.
The consumer (`nova-blockchain-exchange`) therefore uses an **inline
adapter** in its `deploy.yml`: the workflow does `actions/checkout@v4`
on the consumer, then `actions/checkout@v4` `acdl/acdl` @ `ref: v1.25`
into `platform/`, and runs `bash platform/scripts/run_platform.sh ...`
directly — no `uses:` indirection.

The platform's own `.github/workflows/deploy.yml` (this repo) stays as
the **GitHub Actions reference implementation** — the reusable
`workflow_call` workflow used by GitHub-hosted consumers. The two
files share the same contract shape; the only declared difference is
the forge/runtime, not the stages or commands. See
`.ciagent/ARCHITECTURE.md` §12.8 for the live pilot-estate wiring.