acdl/.ciagent/RESEARCH.md

# Nova — v1.26 Research Findings

> Phase: research (pre-execution). Milestone: v1.26 (Live Pilot Estate
> Activation). Status: research. Researcher: ci-researcher.
> Autonomy: full.

---

## 1. Domain — Homegrown PoA Blockchain for Securities Settlement

### 1.1 Why a homegrown chain (not Ethereum/Solana/Hyperledger)

The pilot's purpose is to exercise the Nova platform's deploy/policy/
attestation gates over a real consumer estate — not to build a
production blockchain. A homegrown PoA ledger is the minimal viable
chain: append-only blocks, single validator (pilot), SHA-256 hash chain,
deterministic block production. It records every order, match, and
settlement as transactions; settlement finality = block commit. This
is sufficient to demonstrate that Nova's policy engine (kyverno-json)
can assert settlement finality declaratively (REQ-315) and that the
Decision Ledger captures the apply decision.

A production chain (Ethereum/Solana/Hyperledger) would be the *consumer
app's* choice, not the platform's. The platform is chain-agnostic — it
deploys whatever the consumer's `contract.yaml` declares. For the pilot,
the homegrown chain is the simplest way to produce a real consumer
estate without a heavyweight external dependency.

### 1.2 PoA consensus — single validator (pilot)

Proof-of-Authority with a single validator is the minimal consensus
model: the validator proposes + commits blocks. No Byzantine fault
tolerance (single validator = no forks). Deterministic block
production: same ordered transactions → same block (same hash). This
makes the chain auditable (the hash chain is verifiable) and
reproducible (a replay produces the same chain). Multi-validator BFT
is a future milestone (D-201).

### 1.3 T+1 settlement finality

Equities settle T+1 (trade date + 1 business day). The pilot's
settlement service records matches as transactions on the chain; a
settlement is final when its block is committed. The settlement-finality
kyverno-json policy (REQ-315) asserts `all_committed: true` before any
promotion (qa→prod) — the declarative gate that turns settlement
finality into a policy artifact. This is the securities-specific
extension of v1.25's policy engine: the same `KyvernoJsonEngine`
evaluates a policy over a new payload shape (settlement-service status
JSON).

### 1.4 Equities-only scope (D-200)

Bonds (T+2), derivatives (varying), and options (exercise models) have
different settlement models. A pilot should demonstrate the Nova
platform's gates over the simplest case (equities T+1) before
expanding. "All types of securities" is the product vision; v1.26 is
the pilot (equities first). Future milestones add other security types
with their settlement models.

---

## 2. Nova Consumer Deploy Model

### 2.1 The reusable `deploy.yml@v1.25` workflow

The platform's `.github/workflows/deploy.yml` is a `workflow_call` —
a reusable workflow that a consumer repo invokes via
`uses: acdl/.github/workflows/deploy.yml@v1.25`. Inputs: `contract`
(default `.nova/contract.yml`), `mode` (default `full`; enum
`full|plan-only|check-only|decommission`), `environment` (override).
The workflow checks out the consumer repo + the platform repo, runs
`scripts/run_platform.sh`, and records the apply decision +
attestation in the Decision Ledger. Secrets: `NOVA_AWS_*`
(account + access key + secret) + `NOVA_LAMBDA_URL` (error reporting).

The pilot consumer (`nova-blockchain-exchange`) invokes this workflow
with `mode: full` for `dev` (D-209). The `.gitea/workflows/deploy.yml`
mirror is byte-identical (the platform's deploy workflow is
forge-agnostic — Gitea + GitHub).

### 2.2 `run_platform.sh --apply` path (confirmed)

`scripts/run_platform.sh:431-455` — the `--apply` (or `mode: full`)
path runs `terraform apply -auto-approve` after the HITL gate
(`:438`). For `dev` (autonomous, no HITL gate), the apply proceeds
directly. The apply records the env via `core/env_transition.py record`
(`:450`). The full pipeline (no `--apply` flag) continues to Step 7
(confidence signal) + Step 8 (outbox write).

**Gap (noted in RESEARCH §4):** the `--apply` path exits before the
outbox write (Step 8). The pilot runs the full pipeline (not `--apply`
alone), so the outbox write happens. The `run.completed` event lands in
the JSONL Decision Ledger (not the DynamoDB outbox) — this is by design
(the outbox is the platform-run evidence stream; the Decision Ledger is
the cold store for metrics).

### 2.3 Contract schema — multi-module manifest

`schemas/contract.schema.json:7,24-48` — required fields: `id`,
`name`, `environment`, `infrastructure`. The `infrastructure` block is
`minProperties: 1` with `patternProperties` accepting any module name
key. Multi-module manifest is supported: one contract can declare
`infrastructure: { microservice: {...}, dynamodb: {...}, s3: {...} }`.
The constraint is the `modules/registry.json` (the module must be
registered), not the schema.

---

## 3. Platform Module Readiness (the critical finding)

### 3.1 The adapter is stateless (v1.11 rewrite)

`adapters/terraform/adapter.py:1-11` — the adapter is a "STATELESS
ASSEMBLER" that owns no module content. There is **no `TYPE_MAP`**,
`INPUT_MAP`, or `OUTPUT_MAP` (deleted in the v1.11 stateless rewrite;
`modules/STANDARDS.md:212-214` confirms). A new stack type requires a
new L1 module (`modules/l1/<name>/` with `interface.json` +
`terraform/main.tf` + `README.md` + `instance.json`) + a
`modules/registry.json` entry — not an adapter change.

### 3.2 ECS — ready

`modules/l1/ecs-service/terraform/main.tf:1,11` —
`aws_ecs_task_definition` + `aws_ecs_service`. `interface.json:5-6` —
`type: aws:ecs:task_definition`. `registry.json:29-37` — registered.
Tests: `test_adapter.py:164-185,257-360`, `test_contract_resolver.py:61-92`.
The `microservice` L2 (`modules/l2/microservice/composition.json`)
references 6 L1 children (ecs-cluster, ecr, iam-role, alb, ecs-service,
kms-key) — the ECS pattern is fully wired end-to-end.

### 3.3 S3 — ready

`modules/l1/s3/terraform/main.tf:1` — `aws_s3_bucket` (+ versioning +
SSE). `interface.json:5-6` — `type: aws:s3:bucket`. `registry.json:2-10`
— registered. Tests: `test_adapter.py:56-110,241-257`,
`test_contract_resolver.py:36-51,92-130`.

### 3.4 DynamoDB — GAP (REQ-322)

**No `modules/l1/dynamodb/` directory, no `registry.json` key, no
`interface.json`, no `terraform/`, no tests.** The blockchain exchange's
ledger table needs this primitive. REQ-322 authors it: `interface.json`
(stack type `aws:dynamodb:table`), `terraform/main.tf`
(`aws_dynamodb_table` with PK + optional SK, `PAY_PER_REQUEST` default,
encryption + PITR enabled per v1.8 NFR defaults), `README.md`,
`instance.json`, + `registry.json` entry. The adapter needs no change
(stateless); the contract's `infrastructure.dynamodb` block references
this primitive. This is the single platform-side module build-out for
the milestone.

### 3.5 Stale doc (not a blocker)

`adapters/README.md:49-54` references the deleted `TYPE_MAP`/
`INPUT_MAP`/`OUTPUT_MAP` — contradicts `adapter.py:1-11` +
`modules/STANDARDS.md:212-214`. REQ-321 (docs) should fix this.

---

## 4. Metric Pipeline Grounding (Post-Pilot targets)

### 4.1 AI Decision Accuracy — outcome backfill (REQ-317)

`core/metrics/decision_ledger.py:210-211` documents the event chain:
`confidence.computed → ai.decision.made → attestation.recorded →
run.completed/failed`. `collector.py:262` inserts `fact_decision.outcome`
as `"pending"` — **there is no outcome-backfill step** wiring
`run.completed`/`run.failed` back into `fact_decision.outcome`. The AI
Decision Accuracy metric (`trust_snapshot.py:70-85`, `_get_ai_decision_accuracy`)
reads `decisions WHERE outcome='succeeded' ÷ total` — so it reads 0%
today (all pending). REQ-317 adds `core/metrics/outcome_backfill.py`
that reads run-manifest events and updates `fact_decision.outcome` +
`fact_decision.backfilled_at`. The PCR schema is unchanged (D-211).

### 4.2 Human Escalation Frequency — `reason='confidence'` tag (REQ-318)

`core/confidence_signal.py:184` — a `block` band sets
`human_override=True` in the `ai.decision.made` event.
`run_platform.sh:636` fails the pipeline on `block`. The Human
Escalation Frequency metric (`docs/metrics/human_escalation_frequency.md:11-12`)
is defined as `count(runs WHERE hitl_block=1 AND reason='confidence') ÷
total runs`. The `reason='confidence'` discriminator is **not currently
stored** — `hitl_block` is a boolean from the manifest. REQ-318 adds
`escalation_reason: 'confidence'` to the `ai.decision.made` event when
`band == 'block'` + persists it into `fact_run` via the collector.

### 4.3 Touchless Resolution Rate — denominator activates post-pilot

`docs/metrics/touchless_resolution_rate.md:12-15` — defined as a SQL
query over `fact_run` (`runs WHERE hitl_block=0 ÷ total runs`). The data
lands in `fact_run.hitl_block` via `collector.py:216-227`. No dedicated
emitter computes the ratio — it's a downstream query. The denominator
is 0 today (no consumer runs). The pilot run activates the denominator.

---

## 5. kyverno-json Policy Extensibility

`adapters/kyverno-json/kyverno_json_engine.py:74-80` — the engine is
**policy-dir agnostic**: it loads whatever subdir the caller passes.
Existing subdirs: `contract/`, `stack-ir/`, `plan-json/`, `meta/`,
`regression/`. Adding a new subdir (e.g. `pilot-readiness/`,
`settlement-finality/`) requires: (1) `mkdir
adapters/kyverno-json/policies/<name>/`, (2) drop `ValidatingPolicy`
YAML/JSON files, (3) wire a caller. No engine code change needed.
Test pattern: one test file per subdir (`tests/test_<name>_policies.py`).

The pilot adds two new policy subdirs: `pilot-readiness/`
(REQ-320, no-placeholder-account) + `settlement-finality/` (REQ-315,
all-matches-committed). Both follow the established pattern.

---

## 6. Env-JSON Wiring Reconciliation (REQ-319)

`core/environments/dev.json:4` — `account_id: "000000000000"` (placeholder).
`core/environment_check.py:48-53` warns (non-fatal) when account_id is
placeholder + env != dev. `adapters/terraform/adapter.py:116-117` —
computes the state bucket as `nova-tfstate-<AWS_ACCOUNT_ID>-us-east-1`
from the `AWS_ACCOUNT_ID` env var, **not** from the env JSON's
`state_backend.bucket`. This is the wiring gap: the env JSON's
`state_backend` field is currently unused by the live apply path.
REQ-319 makes the adapter read `env.state_backend.bucket` when present
(falling back to the computed name for backwards compat) + updates
`dev.json` to the real account `581513795199` + real bucket
`nova-tfstate-581513795199-us-east-1`.

---

## 7. Risk Analysis

| Risk | Likelihood | Impact | Mitigation |
|---|---|---|---|
| `NOVA_AWS_*` key lacks a needed IAM permission mid-pilot | Low (bootstrap succeeded → root-equivalent) | High (blocks apply) | D-207; the key has root-equivalent perms (empirically confirmed). |
| DynamoDB primitive takes longer than expected (new module) | Medium | Medium | REQ-322 is the single platform-side build-out; the `s3`/`rds` primitives are the template — straightforward. |
| Homegrown chain has a correctness bug (hash chain breaks) | Low | High | REQ-310 tests cover chain integrity, hash determinism, genesis, append/verify. |
| `deploy.yml@v1.25` ref doesn't resolve (floating tag) | Low | High | The platform's `release.yml` creates + force-moves the `v1.25` + `v1` floating tags on merge to main. The pilot contract uses `@v1.25`. |
| Settlement-finality policy false-negatives (blocks a valid promotion) | Medium | Medium | REQ-315 tests cover passing + failing fixtures; the policy is skip-when-kj-absent (graceful). |
| D-083 deferral challenged (audit ledger not tamper-evident) | Low | Low | D-204; the SQLite hash-chain + DynamoDB outbox is the pilot's audit record. Tamper-evidence is a future milestone. |

---

## 8. Persona Assessment

See `PERSONAS.md` (next section, produced by the lead-developer at the
end of RESEARCH). The active roster: backend-engineer (blockchain core
+ settlement + outcome backfill), data-engineer (DynamoDB primitive +
metrics cold store), policy-engineer (kyverno-json policies), +
blockchain-engineer (custom, phase-specific — chain consensus, order
matching, settlement finality). frontend-engineer is deactivated (no
UI in the pilot).