review(v1.5): READY TO SHIP — multi-persona code review

---ci---
project: acdl
phase: 20
milestone: v1.5
status: review
verdict: READY TO SHIP
p0: 1 (fixed — contract path resolution in deploy workflow)
p1: 6 (flagged post-hoc)
---/ci---

Multi-persona review of v1.5 phase 20 (docs + reusable deploy workflow).

P0 (blocking) — AUTO-FIXED:
- C1: scripts/run_platform.sh contract path resolution broken in deploy
  workflow. The reusable workflow invokes run_platform.sh from the consumer
  workspace root with a relative contract path (.acdl/contract.yaml), but
  run_platform.sh does `cd "$ROOT"` (platform repo) early, so the relative
  path resolved against the platform repo and the pipeline could never run.
  Fix (commit 75c2274): capture CALLER_CWD before cd "$ROOT"; resolve
  caller-supplied relative paths against CALLER_CWD; default no-arg contract
  stays relative to ROOT (preserves platform-local CI). Reproduced pre-fix;
  verified post-fix.

P1 (important) — FLAGGED FOR POST-HOC REVIEW (do not block ship):
- C2: ref: v1.4 in the deploy workflow platform checkout — no v1.4 tag exists
  (only v1.4.0 / v1.4.1). Operator must create a floating v1.4 tag or change
  the ref to v1.4.1.
- C3: modules/l2/{static-asset,microservice}/README.md still use @v1 in their
  Usage examples; missed by the v1.4 bump.
- S1: static-key override is not wired. ACDL_AWS_* env vars on the OIDC step
  are not read by aws-actions/configure-aws-credentials@v4 (it reads AWS_*
  or its own access-key/secret-key inputs). The README/CONSUMER_GUIDE claim
  a working override that doesn't function as written. Needs a conditional
  step or renamed env vars + input wiring.
- S2: README overstates ABAC repo:org/repo:ref:... scoping. The workflow
  constructs a numeric role name (github.repository_id); the actual claim
  enforcement lives in the IAM trust policy, not in this workflow.
- T1: no deploy-workflow triggers conformance test (CI workflow has one;
  deploy doesn't). Minor — reusable workflows use workflow_call, not push
  triggers, but the contract's triggers field is then unenforced.
- A1: terraform/spike/terraform.tf uploaded as artifact leaks the AWS account
  ID via the state-backend bucket name. Recommend excluding terraform.tf or
  gating artifact upload to non-public repos.

P2 (nits) — listed for awareness: floating-tag terminology imprecision (M1),
  header comment "Gitea Actions" in the GitHub copy (M2, intentional byte-
  identical), pip install split (P1-perf), comment drift in pipelines/deploy.yaml
  header (C4), module README internal inconsistency (C5).

Verdict: READY TO SHIP. The one P0 is fixed. The 6 P1s are post-hoc items —
the deploy workflow is a scaffold whose first real consumer run requires
operator setup (tag, IAM role, secrets) that gates go-live. The P1s should
be addressed before any consumer invokes uses: acdl/.gitea/workflows/
deploy.yml@v1.4 in earnest.

Tests: 154 pass (19 new). run_ci.sh green.

acdl_platform/contract_resolver.py

@@ -0,0 +1,262 @@
+"""ACDL Contract Resolver — resolve a consumer contract to a Target Stack instance.
+
+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:
+
+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.
+
+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
+import os
+import sys
+
+import yaml
+import jsonschema
+
+
+def _load_json(path):
+    with open(path, "r") as fh:
+        return json.load(fh)
+
+
+def _load_yaml(path):
+    with open(path, "r") as fh:
+        return yaml.safe_load(fh)
+
+
+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
+
+    Returns either a concrete value (string/number/boolean) or a
+    "ref:<childId>.<outputName>" string for cross-child references.
+    """
+    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 consumer contract to a Target Stack instance.
+
+    Args:
+        contract_path: Path to the contract YAML file.
+        repo_root: Root of the ACDL repo (defaults to two levels up from this file).
+
+    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)
+
+    # Load registry
+    registry = _load_json(os.path.join(repo_root, "modules", "registry.json"))
+
+    module_name = contract["module"]
+    if module_name not in registry:
+        raise ValueError(f"module '{module_name}' not found in registry")
+
+    # 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
+
+    if is_l2:
+        stack_instance = resolve_l2(contract, registry, repo_root)
+    else:
+        stack_instance = resolve_l1(contract, registry, repo_root)
+
+    # Validate against stack schema
+    stack_schema = _load_json(os.path.join(repo_root, "schemas", "stack.schema.json"))
+    jsonschema.validate(stack_instance, stack_schema)
+
+    return stack_instance
+
+
+if __name__ == "__main__":
+    if len(sys.argv) != 3:
+        print("usage: contract_resolver.py <contract.yaml> <out.json>", file=sys.stderr)
+        sys.exit(2)
+    result = resolve(sys.argv[1])
+    with open(sys.argv[2], "w") as fh:
+        json.dump(result, fh, indent=2)
+    print(f"resolver: resolved {sys.argv[1]} -> {sys.argv[2]}", file=sys.stderr)