acdl/.ciagent/nova-blockchain-exchange/README.md

nova-blockchain-exchange — Consumer Onboarding Guide

Milestone: v1.26 — the first real Nova consumer estate. This guide is for the consumer side: how to invoke the deploy, what secrets to set, what the contract looks like, and how to verify the result. The platform side is documented in .ciagent/ARCHITECTURE.md §12.8; the live-pilot evidence is in .ciagent/P4-PILOT-RUN-EVIDENCE.md.

This is a consumer of the Nova platform, not a fork. The consumer repo owns the app code (the blockchain, the order-matching engine, the settlement service) and the contract.yaml that declares the infrastructure. The Nova platform (acdl repo) owns the deploy workflow, the policy engine, the contract resolver, the Terraform adapter, the confidence signal, the HITL gates, and the Decision Ledger. The consumer never clones the platform repo and never runs terraform apply directly.

---

1. Invoke the deploy

The consumer's .github/workflows/deploy.yml (and its byte-identical .gitea/workflows/deploy.yml mirror) is a workflow_dispatch workflow. It does not use cross-repo uses: (SPEC §10 Q1 — the Gitea forge rejects it). Instead it is an inline adapter: it checks out the consumer repo, then checks out acdl/acdl @ ref: v1.25 into platform/, then runs bash platform/scripts/run_platform.sh.

To run a deploy:

1. In the consumer repo's Actions UI, pick the Deploy workflow.
2. Click Run workflow.
3. Inputs:
   • mode = full (the default — applies the Terraform). Other values: plan-only (no apply), check-only (policy + confidence only), decommission (requires a changeRequestId).
   • environment = dev (the pilot scope — equities only, dev only, D-020/D-200). Leave empty to use the contract's environment field.
4. The workflow runs the platform pipeline end-to-end: contract resolve → adapter compile → terraform plan → policy (kyverno-json) → confidence signal → (dev: autonomous apply) → Decision Ledger events.

For the pilot, the documented invocation is mode=full, environment=dev. The first live run was blkex-pilot-apply-v0.2 (2026-08-19).

---

2. Secrets to set

Set these in the forge's Actions secret store (the consumer repo's "Secrets and variables → Actions" page). The platform-managed scheduled workflow rotate-aws-key.yml rotates the NOVA_AWS_* key daily (SPEC §5.9 — the v0.2 deploy uses the currently-active key).

Secret	Purpose
NOVA_AWS_ACCESS_KEY_ID	The static AWS access key for the deploy IAM principal. Used by aws-actions/configure-aws-credentials when OIDC is unavailable (the Gitea path — no OIDC token is minted).
NOVA_AWS_SECRET_ACCESS_KEY	The matching secret key. Rotated by workflows-src/rotate-aws-key.yml.
AWS_DEFAULT_REGION	The target region (us-east-1 for the pilot).

The platform's .github/workflows/deploy.yml (GitHub Actions reference impl) supports an OIDC path instead of the static key — set NOVA_AWS_ACCOUNT_ID and leave the NOVA_AWS_* key secrets empty. The Gitea inline adapter uses the static-key path.

---

3. The contract shape

The consumer declares its infrastructure in contract.yaml at the repo root, validated against the platform's schemas/contract.schema.json. The pilot contract has the shape:

id: blkex
name: blockchain-exchange
environment: dev
infrastructure:
  microservice:   # the L2 composition (ECS Fargate + ALB + roles)
    ...
  dynamodb:       # the L1 DynamoDB table (the ledger)
    ...
  s3:             # the L1 S3 bucket (block storage)
    ...

Three infrastructure.* blocks: microservice (the L2 composition that wires the ECS service, the ALB, and the IAM roles together), and the two L1 primitives (dynamodb for the ledger, s3 for block storage). Per-environment variants live in contracts/blockchain-exchange.{dev,qa,prod}.yml (the per-env promotion model, REQ-105). The pilot runs the dev variant.

The contract is the only consumer-facing artifact that describes infrastructure. It is IR-typed (engine-agnostic); the platform resolves it to a target stack, the Terraform adapter compiles the stack to HCL, and terraform apply runs in the central pipeline — never on the consumer's workstation.

---

4. What the platform does

When run_platform.sh runs against contract.yaml:

1. Resolve the contract to a target stack (a list of L1 instances + inputs + relationships), reading modules/registry.json for each L1's terraform_dir.
2. Compile the stack to Terraform HCL via the stateless adapter (adapters/terraform/adapter.py) — emits module "<rid>" { source } blocks + wired ref: refs. No TYPE_MAP — each L1 owns its shape.
3. Plan — terraform plan against the live AWS account. Infracost runs on the plan JSON and emits nova.cost.estimated.
4. Policy — the kyverno-json engine evaluates the meta-policies (block-on-any-critical + the pilot policies) and emits PolicyCheckResult records.
5. Confidence — the confidence signal consumes the six inputs (the PCRs included) and emits nova.confidence.computed with { score, band, perInput, reasonCodes }. Dev threshold = 0.50.
6. Apply (dev, autonomous — no HITL gate) — terraform apply against account 581513795199. On success, nova.ai.decision.made
   • nova.run.completed land in the Decision Ledger.
7. Backfill — the outcome (pending → succeeded) is backfilled (REQ-317), producing nova.outcome.backfilled. The SQLite hash-chain is extended, not torn up.

The consumer does not see steps 1–7 directly; the consumer sees the workflow's green check + the uploaded artifacts (nova-terraform, nova-platform-log).

---

5. How to verify post-deploy

Two independent verifications — read the AWS API and read the Decision Ledger. Neither trusts the other.

AWS API (the infrastructure landed):

• aws elbv2 describe-load-balancers — the ALB (app-254671247.us-east-1.elb.amazonaws.com for the pilot).
• aws ecs describe-services --cluster nova-cluster --services nova-microservice — the ECS service is ACTIVE.
• aws dynamodb describe-table --table-name nova-blkex-ledger-dev — the ledger table exists (PK block_index, PAY_PER_REQUEST).
• aws s3api head-bucket --bucket nova-blkex-blocks-dev-581513795199-us-east-1 — the block bucket exists (versioning + SSE).

Decision Ledger (the trust record):

• The SQLite hash-chain at metrics/decision_ledger.db has the nova.ai.decision.made row for blkex-pilot-apply-v0.2 (chosen action pass, human_override false) + the nova.outcome.backfilled row (outcome pending → succeeded).
• The chain is valid (prev_event_hash links, 0 breaks). The Trust Snapshot (metrics/TRUST_SNAPSHOT.md) records the verdict.

If the AWS API shows the resources AND the Decision Ledger shows the decision + outcome with a valid chain, the deploy is verified. See .ciagent/P4-PILOT-RUN-EVIDENCE.md for the full pilot-evidence checklist (every ARN, the confidence JSON, the backfill timestamp).

---

References

• .ciagent/ARCHITECTURE.md §12.8 — the pilot-estate architecture (this guide is the consumer-facing companion to that section).
• .ciagent/P4-PILOT-RUN-EVIDENCE.md — the live-pilot evidence (run blkex-pilot-apply-v0.2).
• .ciagent/nova-blockchain-exchange/PROJECT.md — the consumer project charter (vision, scope, decisions D-200..D-205).
• .ciagent/nova-blockchain-exchange/REQUIREMENTS.md — the consumer requirements (REQ-313 contract, REQ-314 deploy invocation).
• adapters/README.md §Consumers — the Gitea adapter note (SPEC §10 Q1 — inline checkout-then-call, no cross-repo uses:).