continuous-intelligence/acdl
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 128 Wiki Activity

refactor(P57): contract surface redesign + rename + .yml repo-wide

Browse Source 
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---
This commit is contained in:
Jon Chery
2026-07-27 21:37:40 +00:00
parent 7f36df5610
commit 031887ec56
127 changed files with 1597 additions and 1100 deletions
Download Patch File Download Diff File Expand all files Collapse all files
core/contract_resolver.py
+210 -77
View File
@@ -5,17 +5,27 @@ The contract resolver is the bridge between the consumer's declared intent
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.
2. For each module in the contract's `infrastructure` map:
a. Looks up the module name + version in modules/registry.json
(version defaults to the latest non-deprecated entry when omitted).
b. If the module is an L1 primitive: builds a stack fragment from
the interface.json + module inputs.
c. If the module is an L2 composition: loads the composition.json,
expands children to stack resources, resolves wires to ref:
expressions, and emits the fragment.
3. Merges all module fragments into a single Target Stack instance:
- stack.name = contract.id (the short operational acronym)
- stack.title = contract.name (the full human-readable name)
- When the contract has one module: resource IDs are unprefixed
(backward-compatible with existing stack consumers).
- When the contract has multiple modules: resource IDs are prefixed
with the module name (e.g. `microservice-vpc`) to avoid collisions,
and all ref:/parent references are rewritten to match.
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>
CLI: contract_resolver.py <contract.yml> <out.json>
"""
import json
@@ -150,68 +160,77 @@ def _resolve_wire_value(wire, contract_inputs, child_outputs):
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")
def _latest_version(registry, module_name):
"""Return the latest non-deprecated version string for a module.
Falls back to the highest version even if all are deprecated.
"""
versions = registry[module_name]
non_deprecated = [(v, e) for v, e in versions.items()
if not e.get("deprecated", False)]
if not non_deprecated:
non_deprecated = list(versions.items())
non_deprecated.sort(key=lambda x: [int(p) for p in x[0].split(".")],
reverse=True)
return non_deprecated[0][0]
def _resolve_l1(module_name, version, inputs, registry, repo_root):
"""Resolve a single L1 primitive module to a stack-fragment (resources list)."""
module_ref = f"{module_name}@{version}"
# Load the interface
entry = registry[module_name]["1.0.0"]
entry = registry[module_name][version]
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,
# Build the resource
resource = {
"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()
},
"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
resource["nfrs"] = nfrs
return stack_instance
return {
"kind": "l1",
"depth": 1,
"resources": [resource],
"features": {},
"outputs": {},
}
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", {})
def _resolve_l2(module_name, version, inputs, registry, repo_root):
"""Resolve a single L2 composition module to a stack-fragment.
Returns a dict with: kind, depth, resources, features, outputs.
The caller is responsible for merging fragments and setting stack.name/title.
"""
# Load the composition
entry = registry[module_name]["1.0.0"]
entry = registry[module_name][version]
comp_path = os.path.join(repo_root, entry["interface"])
composition = _load_json(comp_path)
# Track child outputs for wire resolution
# child_outputs[childId] = {outputName: resourceId}
# child_outputs[childId] = {outputName -> resourceId}
# For single-resource L1s, resourceId == childId
# For multi-resource L1s, resourceId is the expanded sub-resource id
child_outputs = {}
# child_input_map[childId] = {inputName: sub_resource_id} for multi-resource L1s
# child_input_map[childId] = {inputName -> sub_resource_id} for multi-resource L1s
# so a wire targeting <childId>.inputs.<name> routes to the sub-resource
# that actually declares that input (P1-1 — desired_count → aws:ecs:service,
# family → aws:ecs:task_definition).
# that actually declares that input (P1-1 — desired_count -> aws:ecs:service,
# family -> aws:ecs:task_definition).
child_input_map = {}
resources = []
@@ -220,9 +239,10 @@ def resolve_l2(contract, registry, repo_root):
child_id = child["id"]
child_module = child["module"]
child_name = child_module.split("@")[0]
child_version = child_module.split("@")[1] if "@" in child_module else "1.0.0"
# Load the child's interface to get type and outputs
child_entry = registry[child_name]["1.0.0"]
child_entry = registry[child_name][child_version]
child_iface_path = os.path.join(repo_root, child_entry["interface"])
child_iface = _load_json(child_iface_path)
@@ -309,20 +329,10 @@ def resolve_l2(contract, registry, repo_root):
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,
}
# REQ-87: Propagate deletion_protection feature flag from contract inputs
# to all children's NFRs. When inputs.deletion_protection is false,
# all resources get deletion_protection=false (used by decommission).
features = {}
deletion_protection_input = inputs.get("deletion_protection", True)
if deletion_protection_input is not True:
for res in resources:
@@ -331,9 +341,7 @@ def resolve_l2(contract, registry, repo_root):
res["nfrs"]["deletion_protection"] = deletion_protection_input
# Also record the feature flag on the stack object for introspection.
if "deletion_protection" in inputs:
stack_instance["stack"]["features"] = {
"deletion_protection": deletion_protection_input
}
features["deletion_protection"] = deletion_protection_input
# P1-7: Process the composition's outputs[] array to build stack.outputs.
# Each output wire: {"from": "<childId>.outputs.<name>", "to": "stack.outputs.<outName>"}
@@ -363,10 +371,55 @@ def resolve_l2(contract, registry, repo_root):
"from": src_resource_id,
"output": src_output,
}
if stack_outputs:
stack_instance["outputs"] = stack_outputs
return stack_instance
return {
"kind": "l2",
"depth": composition.get("depth", 1),
"resources": resources,
"features": features,
"outputs": stack_outputs,
}
def _namespace_resources(resources, module_name):
"""Prefix all resource IDs with the module name for multi-module contracts.
Rewrites resource 'id', 'parent', and ref: expressions in inputs/outputs
so cross-references stay consistent within the module fragment.
"""
prefix = f"{module_name}-"
# Build the old->new id mapping
id_map = {res["id"]: f"{prefix}{res['id']}" for res in resources}
def _rewrite_ref(val):
"""Recursively rewrite ref:<id>.<out> and parent:<id> strings."""
if isinstance(val, str):
if val.startswith("ref:"):
# ref:<resourceId>.<outputName>
rest = val[4:]
if "." in rest:
rid, outname = rest.split(".", 1)
if rid in id_map:
return f"ref:{id_map[rid]}.{outname}"
return val
return val
if isinstance(val, dict):
return {k: _rewrite_ref(v) for k, v in val.items()}
if isinstance(val, list):
return [_rewrite_ref(v) for v in val]
return val
for res in resources:
res["id"] = id_map[res["id"]]
# Rewrite parent
if "parent" in res and res["parent"] in id_map:
res["parent"] = id_map[res["parent"]]
# Rewrite all ref: expressions in inputs and outputs
res["inputs"] = _rewrite_ref(res.get("inputs", {}))
if "outputs" in res:
res["outputs"] = _rewrite_ref(res["outputs"])
return resources, id_map
def decommission_transform(stack_instance):
@@ -432,24 +485,105 @@ def resolve(contract_path, repo_root=None, environment_override=None):
# reference the environment by ${env.environment}).
env["environment"] = env.get("name", env_name)
context = {"env": env, "contract": contract}
contract["inputs"] = _expand_vars(contract.get("inputs", {}), context)
# Expand interpolation tokens in each module's inputs
infrastructure = contract.get("infrastructure", {})
for module_name, module_entry in infrastructure.items():
module_entry["inputs"] = _expand_vars(
module_entry.get("inputs", {}), context)
# 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")
# Validate every module exists in the registry, then resolve each
module_names = list(infrastructure.keys())
fragments = []
for module_name in module_names:
if module_name not in registry:
raise ValueError(f"module '{module_name}' not found in registry")
module_entry = infrastructure[module_name]
# Default version to latest non-deprecated
version = module_entry.get("version")
if version is None:
version = _latest_version(registry, module_name)
elif version not in registry[module_name]:
raise ValueError(
f"module '{module_name}' version '{version}' not found in registry")
module_inputs = module_entry.get("inputs", {})
# 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
# Determine if L1 or L2
entry = registry[module_name][version]
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)
if is_l2:
fragment = _resolve_l2(module_name, version, module_inputs,
registry, repo_root)
else:
fragment = _resolve_l1(module_name, version, module_inputs,
registry, repo_root)
fragments.append((module_name, fragment))
# Merge fragments into a single stack instance
all_resources = []
max_depth = 1
any_l2 = False
merged_features = {}
merged_outputs = {}
multi_module = len(fragments) > 1
for module_name, fragment in fragments:
if fragment["kind"] == "l2":
any_l2 = True
max_depth = max(max_depth, fragment["depth"])
merged_features.update(fragment.get("features", {}))
if multi_module:
# Namespace resource IDs to avoid cross-module collisions
namespaced, id_map = _namespace_resources(
fragment["resources"], module_name)
# Namespace the fragment's stack outputs (from refs)
for out_name, out_spec in fragment.get("outputs", {}).items():
src_id = out_spec.get("from", "")
if src_id in id_map:
out_spec["from"] = id_map[src_id]
merged_outputs[f"{module_name}-{out_name}"] = out_spec
all_resources.extend(namespaced)
else:
# Single module: keep IDs as-is (backward compatible)
merged_outputs.update(fragment.get("outputs", {}))
all_resources.extend(fragment["resources"])
# Determine stack kind: L2 if any module is L2 or if multi-module
if multi_module:
kind = "l2"
elif any_l2:
kind = "l2"
else:
stack_instance = resolve_l1(contract, registry, repo_root)
kind = "l1"
stack_instance = {
"version": "1.0.0",
"stack": {
"name": contract["id"],
"kind": kind,
"depth": max_depth,
},
"resources": all_resources,
}
# Add the human-readable title
if contract.get("name"):
stack_instance["stack"]["title"] = contract["name"]
# Add features if any were set
if merged_features:
stack_instance["stack"]["features"] = merged_features
# Add stack-level outputs
if merged_outputs:
stack_instance["outputs"] = merged_outputs
# Validate against stack schema
stack_schema = _load_json(os.path.join(repo_root, "schemas", "stack.schema.json"))
@@ -460,7 +594,7 @@ def resolve(contract_path, repo_root=None, environment_override=None):
if __name__ == "__main__":
if len(sys.argv) < 3:
print("usage: contract_resolver.py <contract.yaml> <out.json> [--environment <name>]", file=sys.stderr)
print("usage: contract_resolver.py <contract.yml> <out.json> [--environment <name>]", file=sys.stderr)
sys.exit(2)
contract_path = sys.argv[1]
out_path = sys.argv[2]
@@ -474,5 +608,4 @@ if __name__ == "__main__":
env_override = os.environ["ACDL_ENVIRONMENT_OVERRIDE"]
result = resolve(contract_path, environment_override=env_override)
with open(out_path, "w") as fh:
json.dump(result, fh, indent=2)
print(f"resolver: resolved {contract_path} -> {out_path}", file=sys.stderr)
json.dump(result, fh, indent=2)
core/local_emulators.py
+1 -1
View File
@@ -488,7 +488,7 @@ def run_local_e2e(contract_path: str, repo_root: Optional[Path] = None) -> Dict[
if __name__ == "__main__":
contract = sys.argv[1] if len(sys.argv) > 1 else "contracts/microservice.yaml"
contract = sys.argv[1] if len(sys.argv) > 1 else "contracts/microservice.yml"
os.environ["ACDL_LOCAL_TIER"] = "1"
result = run_local_e2e(contract)
print(json.dumps(result, indent=2))
core/regression_verify.py
+8 -8
View File
@@ -120,7 +120,7 @@ def _check_contract_schema_validation() -> Tuple[Status, str]:
"import json, yaml, jsonschema; "
"s=json.load(open('schemas/contract.schema.json')); "
"[jsonschema.validate(yaml.safe_load(open(f)), s) "
" for f in ['contracts/static-assets.yaml','contracts/microservice.yaml']]; "
" for f in ['contracts/static-assets.yml','contracts/microservice.yml']]; "
"print('2 sample contracts validate')",
])
@@ -144,7 +144,7 @@ def _check_resolver_static_assets() -> Tuple[Status, str]:
try:
return _check_subprocess([
"python3", "core/contract_resolver.py",
"contracts/static-assets.yaml", out,
"contracts/static-assets.yml", out,
])
finally:
try:
@@ -160,7 +160,7 @@ def _check_resolver_microservice() -> Tuple[Status, str]:
try:
return _check_subprocess([
"python3", "core/contract_resolver.py",
"contracts/microservice.yaml", out,
"contracts/microservice.yml", out,
])
finally:
try:
@@ -177,7 +177,7 @@ def _check_adapter_emits_terraform() -> Tuple[Status, str]:
os.makedirs(tf_dir, exist_ok=True)
rc, out, err = _run_subprocess([
"python3", "core/contract_resolver.py",
"contracts/static-assets.yaml", stack_path,
"contracts/static-assets.yml", stack_path,
])
if rc != 0:
return "Broken", f"resolver failed: {err.strip()[-200:]}"
@@ -276,7 +276,7 @@ def _check_local_e2e_microservice() -> Tuple[Status, str]:
This is the local-tier half of the headline E2E; the live-AWS half
lands in Phase 54 (D-093)."""
return _check_subprocess(
["python3", "core/local_emulators.py", "contracts/microservice.yaml"],
["python3", "core/local_emulators.py", "contracts/microservice.yml"],
timeout=60,
)
@@ -284,7 +284,7 @@ def _check_local_e2e_microservice() -> Tuple[Status, str]:
def _check_local_e2e_static_assets() -> Tuple[Status, str]:
"""CAP-012: local E2E on the static-assets stack (no ECS service)."""
return _check_subprocess(
["python3", "core/local_emulators.py", "contracts/static-assets.yaml"],
["python3", "core/local_emulators.py", "contracts/static-assets.yml"],
timeout=60,
)
@@ -324,7 +324,7 @@ def _check_live_terraform_plan_microservice() -> Tuple[Status, str]:
os.makedirs(tf_dir, exist_ok=True)
rc, out, err = _run_subprocess([
"python3", "core/contract_resolver.py",
"contracts/microservice.yaml", stack_path,
"contracts/microservice.yml", stack_path,
])
if rc != 0:
return "Broken", f"resolver failed: {err.strip()[-200:]}"
@@ -364,7 +364,7 @@ def _check_live_terraform_plan_static_assets() -> Tuple[Status, str]:
os.makedirs(tf_dir, exist_ok=True)
rc, out, err = _run_subprocess([
"python3", "core/contract_resolver.py",
"contracts/static-assets.yaml", stack_path,
"contracts/static-assets.yml", stack_path,
])
if rc != 0:
return "Broken", f"resolver failed: {err.strip()[-200:]}"