@guanlin4924/devflow-pi 0.1.19 → 0.1.21

package/plugins/devflow-core/skills/workflow-orchestrator/scripts/api_test_matrix.py

@@ -0,0 +1,829 @@
+#!/usr/bin/env python3
+"""Compile a testable API contract into complete, portable acceptance cases.
+
+This is deliberately a deterministic Core script, not a prompt convention.  A
+plain Markdown request shape cannot prove a maximum length, a minimum value or
+an error-code assertion.  API nodes therefore carry a narrow ``test_schema``
+which supplies the facts needed to derive those cases.  The compiler creates:
+
+* one valid pairwise set (valid values only),
+* one negative case for every required/null/type/range/format/enum partition,
+* one scenario case for every remaining declared error code, and
+* portable HTTP execution definitions plus a binding template.
+
+Invalid values are intentionally never mixed into pairwise rows: two invalid
+inputs make the expected error ambiguous and hide a server accepting one of
+them.  They are tested one defect at a time and must map to exactly one error
+catalogue entry.
+"""
+from __future__ import annotations
+
+import argparse
+import copy
+import hashlib
+import json
+import re
+from itertools import product
+from pathlib import Path
+from typing import Any, Iterable
+
+
+FEATURE_RE = re.compile(r"^[^/\\\x00-\x1f\x7f]+$")
+TYPES = {"string", "integer", "number", "boolean", "array", "object"}
+LOCATIONS = {"body", "query", "path", "headers"}
+MISSING = object()
+
+
+def canonical(value: Any) -> str:
+    return json.dumps(value, ensure_ascii=False, separators=(",", ":"))
+
+
+def digest(value: Any) -> str:
+    return hashlib.sha256(canonical(value).encode("utf-8")).hexdigest()
+
+
+def read_json(path: Path, errors: list[str], label: str) -> dict[str, Any] | None:
+    try:
+        value = json.loads(path.read_text(encoding="utf-8"))
+    except FileNotFoundError:
+        errors.append(f"missing {label}: {path.as_posix()}")
+        return None
+    except json.JSONDecodeError as error:
+        errors.append(f"invalid {label}: {error.msg}")
+        return None
+    if not isinstance(value, dict):
+        errors.append(f"invalid {label}: root must be an object")
+        return None
+    return value
+
+
+def write_json(path: Path, value: dict[str, Any]) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    temporary = path.with_name(f".{path.name}.tmp")
+    temporary.write_text(json.dumps(value, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
+    temporary.replace(path)
+
+
+def write_text(path: Path, value: str) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    temporary = path.with_name(f".{path.name}.tmp")
+    temporary.write_text(value, encoding="utf-8")
+    temporary.replace(path)
+
+
+def paths(root: Path, feature: str) -> tuple[Path, Path, Path, Path]:
+    requirements = root / ".planning" / "requirements" / feature
+    feature_dir = root / ".planning" / "features" / feature
+    return (
+        requirements / "governance.json",
+        requirements / "api-test-matrix.json",
+        feature_dir / "完整API验收测试用例.md",
+        feature_dir / "api-acceptance-bindings.template.json",
+    )
+
+
+def json_pointer_tokens(pointer: str) -> list[str]:
+    if pointer == "":
+        return []
+    if not isinstance(pointer, str) or not pointer.startswith("/"):
+        raise ValueError("pointer must be an RFC 6901 JSON pointer")
+    return [part.replace("~1", "/").replace("~0", "~") for part in pointer[1:].split("/")]
+
+
+def pointer_get(document: Any, pointer: str) -> Any:
+    current = document
+    for token in json_pointer_tokens(pointer):
+        if isinstance(current, list):
+            if not token.isdigit() or int(token) >= len(current):
+                raise KeyError(pointer)
+            current = current[int(token)]
+        elif isinstance(current, dict):
+            if token not in current:
+                raise KeyError(pointer)
+            current = current[token]
+        else:
+            raise KeyError(pointer)
+    return current
+
+
+def pointer_set(document: Any, pointer: str, value: Any) -> None:
+    tokens = json_pointer_tokens(pointer)
+    if not tokens:
+        raise ValueError("root replacement is not supported")
+    current = document
+    for token in tokens[:-1]:
+        if isinstance(current, list):
+            if not token.isdigit() or int(token) >= len(current):
+                raise KeyError(pointer)
+            current = current[int(token)]
+        elif isinstance(current, dict):
+            if token not in current:
+                raise KeyError(pointer)
+            current = current[token]
+        else:
+            raise KeyError(pointer)
+    tail = tokens[-1]
+    if isinstance(current, list):
+        if not tail.isdigit() or int(tail) >= len(current):
+            raise KeyError(pointer)
+        current[int(tail)] = value
+    elif isinstance(current, dict):
+        current[tail] = value
+    else:
+        raise KeyError(pointer)
+
+
+def pointer_remove(document: Any, pointer: str) -> None:
+    tokens = json_pointer_tokens(pointer)
+    if not tokens:
+        raise ValueError("root removal is not supported")
+    current = document
+    for token in tokens[:-1]:
+        if isinstance(current, list):
+            if not token.isdigit() or int(token) >= len(current):
+                raise KeyError(pointer)
+            current = current[int(token)]
+        elif isinstance(current, dict):
+            if token not in current:
+                raise KeyError(pointer)
+            current = current[token]
+        else:
+            raise KeyError(pointer)
+    tail = tokens[-1]
+    if isinstance(current, list):
+        if not tail.isdigit() or int(tail) >= len(current):
+            raise KeyError(pointer)
+        current.pop(int(tail))
+    elif isinstance(current, dict):
+        if tail not in current:
+            raise KeyError(pointer)
+        del current[tail]
+    else:
+        raise KeyError(pointer)
+
+
+def unique(values: Iterable[Any]) -> list[Any]:
+    result: list[Any] = []
+    seen: set[str] = set()
+    for value in values:
+        key = "<omit>" if value is MISSING else canonical(value)
+        if key not in seen:
+            seen.add(key)
+            result.append(value)
+    return result
+
+
+def stable_value(value: Any) -> str:
+    return "<omit>" if value is MISSING else canonical(value)
+
+
+def api_nodes(graph: dict[str, Any]) -> list[dict[str, Any]]:
+    return [node for node in graph.get("nodes", []) if isinstance(node, dict) and node.get("kind") == "api"]
+
+
+def api_fingerprint(graph: dict[str, Any]) -> str:
+    source = [
+        {"id": node.get("id"), "data": node.get("data")}
+        for node in api_nodes(graph)
+    ]
+    return hashlib.sha256(json.dumps(source, ensure_ascii=False, separators=(",", ":"), sort_keys=True).encode("utf-8")).hexdigest()
+
+
+def obligation_id(api_id: str, field_id: str, partition: str) -> str:
+    return f"OBL-{api_id}-{field_id}-{partition}".upper().replace("_", "-")
+
+
+def case_key(api_id: str, category: str, sequence: int) -> str:
+    return f"ATC-{api_id}-{category}-{sequence:04d}".upper().replace("_", "-")
+
+
+def error_code_error(api_id: str, field_id: str, partition: str) -> str:
+    return f"{api_id}: field {field_id} partition {partition} has no unique error mapping"
+
+
+def standard_invalid_format(name: str) -> Any | None:
+    return {
+        "uuid": "not-a-uuid",
+        "email": "not-an-email",
+        "date": "2026-99-99",
+        "date-time": "not-a-datetime",
+        "ipv4": "999.999.999.999",
+        "ipv6": "not-an-ip",
+        "uri": "not a uri",
+        "url": "not a url",
+    }.get(name)
+
+
+def wrong_type(value_type: str) -> Any:
+    return {
+        "string": {"unexpected": "object"},
+        "integer": "not-an-integer",
+        "number": "not-a-number",
+        "boolean": "not-a-boolean",
+        "array": "not-an-array",
+        "object": "not-an-object",
+    }[value_type]
+
+
+def boundary_keys(value_type: str) -> list[str]:
+    if value_type == "string":
+        return ["min_length", "max_length", "format", "pattern", "enum"]
+    if value_type in {"integer", "number"}:
+        return ["minimum", "maximum", "enum"]
+    if value_type == "array":
+        return ["min_items", "max_items"]
+    return []
+
+
+def coverage_declared(field: dict[str, Any], key: str) -> bool:
+    constraints = field.get("constraints") if isinstance(field.get("constraints"), dict) else {}
+    if key in constraints:
+        return True
+    coverage = field.get("coverage") if isinstance(field.get("coverage"), dict) else {}
+    item = coverage.get(key)
+    return isinstance(item, dict) and item.get("state") == "not_applicable" and isinstance(item.get("reason"), str) and bool(item["reason"].strip())
+
+
+def validate_field(api_id: str, schema: dict[str, Any], field: Any, seen: set[str], errors: list[str]) -> None:
+    if not isinstance(field, dict):
+        errors.append(f"{api_id}: test_schema.fields entries must be objects")
+        return
+    field_id = field.get("field_key")
+    if not isinstance(field_id, str) or not field_id.strip():
+        errors.append(f"{api_id}: test_schema field_key is required")
+        return
+    if field_id in seen:
+        errors.append(f"{api_id}: duplicate test_schema field id {field_id}")
+    seen.add(field_id)
+    value_type = field.get("type")
+    if value_type not in TYPES:
+        errors.append(f"{api_id}: field {field_id} type is invalid")
+    if field.get("location") not in LOCATIONS:
+        errors.append(f"{api_id}: field {field_id} location is invalid")
+    pointer = field.get("pointer")
+    base_value: Any = MISSING
+    try:
+        json_pointer_tokens(pointer)
+        request = schema.get("valid_request") if isinstance(schema.get("valid_request"), dict) else {}
+        location_value = request.get(field.get("location")) if isinstance(field.get("location"), str) else None
+        base_value = pointer_get(location_value, pointer)
+    except (KeyError, TypeError, ValueError):
+        errors.append(f"{api_id}: field {field_id} pointer must resolve in valid_request.{field.get('location')}")
+    if not isinstance(field.get("required"), bool):
+        errors.append(f"{api_id}: field {field_id} required must be boolean")
+    if not isinstance(field.get("nullable"), bool):
+        errors.append(f"{api_id}: field {field_id} nullable must be boolean")
+    constraints = field.get("constraints", {})
+    if not isinstance(constraints, dict):
+        errors.append(f"{api_id}: field {field_id} constraints must be an object")
+        constraints = {}
+    for key in boundary_keys(value_type if isinstance(value_type, str) else ""):
+        if not coverage_declared(field, key):
+            errors.append(f"{api_id}: field {field_id} must declare {key} or coverage.{key}=not_applicable with a reason")
+    for key in ("min_length", "max_length", "min_items", "max_items"):
+        if key in constraints and (not isinstance(constraints[key], int) or constraints[key] < 0):
+            errors.append(f"{api_id}: field {field_id} constraint {key} must be a non-negative integer")
+    for key in ("minimum", "maximum"):
+        if key in constraints and (not isinstance(constraints[key], (int, float)) or isinstance(constraints[key], bool)):
+            errors.append(f"{api_id}: field {field_id} constraint {key} must be a number")
+    if isinstance(constraints.get("minimum"), (int, float)) and isinstance(constraints.get("maximum"), (int, float)) and constraints["minimum"] > constraints["maximum"]:
+        errors.append(f"{api_id}: field {field_id} minimum cannot exceed maximum")
+    if isinstance(constraints.get("min_length"), int) and isinstance(constraints.get("max_length"), int) and constraints["min_length"] > constraints["max_length"]:
+        errors.append(f"{api_id}: field {field_id} min_length cannot exceed max_length")
+    if isinstance(constraints.get("min_items"), int) and isinstance(constraints.get("max_items"), int) and constraints["min_items"] > constraints["max_items"]:
+        errors.append(f"{api_id}: field {field_id} min_items cannot exceed max_items")
+    if "enum" in constraints and (not isinstance(constraints["enum"], list) or not constraints["enum"]):
+        errors.append(f"{api_id}: field {field_id} enum must be a non-empty array")
+    if "pattern" in constraints:
+        examples = field.get("examples") if isinstance(field.get("examples"), dict) else {}
+        if not isinstance(examples.get("invalid_pattern"), (str, int, float, bool, list, dict)) and examples.get("invalid_pattern") is not None:
+            errors.append(f"{api_id}: field {field_id} examples.invalid_pattern must be JSON data")
+        if "invalid_pattern" not in examples:
+            errors.append(f"{api_id}: field {field_id} pattern requires examples.invalid_pattern")
+    if "enum" in constraints:
+        examples = field.get("examples") if isinstance(field.get("examples"), dict) else {}
+        if "invalid_enum" not in examples:
+            errors.append(f"{api_id}: field {field_id} enum requires examples.invalid_enum")
+    # A generic "xxxx" can accidentally violate a format/pattern/enum at the
+    # same time as a length/range boundary.  In such intersecting constraints
+    # require the contract author to supply an isolating value; this is the
+    # only honest alternative to asserting an arbitrary error code.
+    examples = field.get("examples") if isinstance(field.get("examples"), dict) else {}
+    intersecting = any(key in constraints for key in ("format", "pattern", "enum"))
+    if intersecting and value_type == "string":
+        for constraint, example in (("min_length", "at_min_length"), ("min_length", "below_min_length"), ("max_length", "at_max_length"), ("max_length", "above_max_length")):
+            if constraint in constraints and example not in examples:
+                errors.append(f"{api_id}: field {field_id} {constraint} with format/pattern/enum requires examples.{example} to isolate the boundary")
+    if "enum" in constraints and value_type in {"integer", "number"}:
+        for constraint, example in (("minimum", "at_minimum"), ("minimum", "below_minimum"), ("maximum", "at_maximum"), ("maximum", "above_maximum")):
+            if constraint in constraints and example not in examples:
+                errors.append(f"{api_id}: field {field_id} {constraint} with enum requires examples.{example} to isolate the boundary")
+    if value_type == "string":
+        checks = (("min_length", "at_min_length", lambda value, limit: len(value) == limit), ("min_length", "below_min_length", lambda value, limit: len(value) < limit), ("max_length", "at_max_length", lambda value, limit: len(value) == limit), ("max_length", "above_max_length", lambda value, limit: len(value) > limit))
+        for constraint, example, predicate in checks:
+            if constraint in constraints and example in examples and (not isinstance(examples[example], str) or not predicate(examples[example], constraints[constraint])):
+                errors.append(f"{api_id}: field {field_id} examples.{example} does not satisfy its declared {constraint} boundary")
+    if value_type in {"integer", "number"}:
+        checks = (("minimum", "at_minimum", lambda value, limit: value == limit), ("minimum", "below_minimum", lambda value, limit: value < limit), ("maximum", "at_maximum", lambda value, limit: value == limit), ("maximum", "above_maximum", lambda value, limit: value > limit))
+        for constraint, example, predicate in checks:
+            if constraint in constraints and example in examples and (not isinstance(examples[example], (int, float)) or isinstance(examples[example], bool) or not predicate(examples[example], constraints[constraint])):
+                errors.append(f"{api_id}: field {field_id} examples.{example} does not satisfy its declared {constraint} boundary")
+    if base_value is not MISSING:
+        type_matches = {
+            "string": isinstance(base_value, str),
+            "integer": isinstance(base_value, int) and not isinstance(base_value, bool),
+            "number": isinstance(base_value, (int, float)) and not isinstance(base_value, bool),
+            "boolean": isinstance(base_value, bool),
+            "array": isinstance(base_value, list),
+            "object": isinstance(base_value, dict),
+        }
+        if base_value is None:
+            if field.get("nullable") is False:
+                errors.append(f"{api_id}: field {field_id} valid_request cannot be null when nullable is false")
+        elif value_type in TYPES and not type_matches[value_type]:
+            errors.append(f"{api_id}: field {field_id} valid_request value does not match declared type {value_type}")
+        else:
+            if isinstance(constraints.get("enum"), list) and base_value not in constraints["enum"]:
+                errors.append(f"{api_id}: field {field_id} valid_request violates enum")
+            if value_type == "string":
+                if isinstance(constraints.get("min_length"), int) and len(base_value) < constraints["min_length"]:
+                    errors.append(f"{api_id}: field {field_id} valid_request is below min_length")
+                if isinstance(constraints.get("max_length"), int) and len(base_value) > constraints["max_length"]:
+                    errors.append(f"{api_id}: field {field_id} valid_request is above max_length")
+            if value_type in {"integer", "number"}:
+                if isinstance(constraints.get("minimum"), (int, float)) and base_value < constraints["minimum"]:
+                    errors.append(f"{api_id}: field {field_id} valid_request is below minimum")
+                if isinstance(constraints.get("maximum"), (int, float)) and base_value > constraints["maximum"]:
+                    errors.append(f"{api_id}: field {field_id} valid_request is above maximum")
+            if value_type == "array":
+                if isinstance(constraints.get("min_items"), int) and len(base_value) < constraints["min_items"]:
+                    errors.append(f"{api_id}: field {field_id} valid_request has too few array items")
+                if isinstance(constraints.get("max_items"), int) and len(base_value) > constraints["max_items"]:
+                    errors.append(f"{api_id}: field {field_id} valid_request has too many array items")
+
+
+def validate_schema(api: dict[str, Any], errors: list[str]) -> None:
+    api_id = str(api.get("id", "API-unknown"))
+    data = api.get("data") if isinstance(api.get("data"), dict) else {}
+    schema = data.get("test_schema")
+    if not isinstance(schema, dict):
+        errors.append(f"{api_id}: API contract requires test_schema for complete field/error tests")
+        return
+    if schema.get("schema_version") != 1:
+        errors.append(f"{api_id}: test_schema.schema_version must be 1")
+    if not isinstance(schema.get("method"), str) or not re.fullmatch(r"[A-Z]+", schema["method"]):
+        errors.append(f"{api_id}: test_schema.method must be uppercase HTTP method")
+    if not isinstance(schema.get("path"), str) or not schema["path"].startswith("/"):
+        errors.append(f"{api_id}: test_schema.path must start with /")
+    request = schema.get("valid_request")
+    if not isinstance(request, dict):
+        errors.append(f"{api_id}: test_schema.valid_request must be an object")
+    else:
+        for location in LOCATIONS:
+            if location in request and not isinstance(request[location], dict):
+                errors.append(f"{api_id}: valid_request.{location} must be an object")
+    success = schema.get("success")
+    if not isinstance(success, dict) or not isinstance(success.get("http_status"), int) or not 100 <= success["http_status"] <= 599:
+        errors.append(f"{api_id}: test_schema.success.http_status must be an HTTP status")
+    preconditions = schema.get("preconditions")
+    if not isinstance(preconditions, list) or not preconditions or not all(isinstance(item, str) and item.strip() for item in preconditions):
+        errors.append(f"{api_id}: test_schema.preconditions must be a non-empty string array")
+    fields = schema.get("fields")
+    if not isinstance(fields, list):
+        errors.append(f"{api_id}: test_schema.fields must be an array")
+        fields = []
+    seen: set[str] = set()
+    for field in fields:
+        validate_field(api_id, schema, field, seen, errors)
+    catalog = schema.get("errors")
+    if not isinstance(catalog, list):
+        errors.append(f"{api_id}: test_schema.errors must be an array (use [] only when no error contract exists)")
+        return
+    error_ids: set[str] = set()
+    for item in catalog:
+        if not isinstance(item, dict):
+            errors.append(f"{api_id}: error catalogue entries must be objects")
+            continue
+        error_id = item.get("error_key")
+        if not isinstance(error_id, str) or not error_id.strip():
+            errors.append(f"{api_id}: error catalogue error_key is required")
+        elif error_id in error_ids:
+            errors.append(f"{api_id}: duplicate error catalogue id {error_id}")
+        else:
+            error_ids.add(error_id)
+        if not isinstance(item.get("code"), str) or not item["code"].strip():
+            errors.append(f"{api_id}: error catalogue {error_id or '<unknown>'} code is required")
+        if not isinstance(item.get("http_status"), int) or not 100 <= item["http_status"] <= 599:
+            errors.append(f"{api_id}: error catalogue {error_id or '<unknown>'} http_status is invalid")
+        covers = item.get("covers")
+        scenario = item.get("scenario")
+        if bool(covers) == bool(scenario):
+            errors.append(f"{api_id}: error catalogue {error_id or '<unknown>'} needs exactly one of covers or scenario")
+        if covers is not None and (not isinstance(covers, list) or not covers or not all(isinstance(value, str) and value for value in covers)):
+            errors.append(f"{api_id}: error catalogue {error_id or '<unknown>'} covers must be a non-empty string array")
+        if scenario is not None:
+            if not isinstance(scenario, dict):
+                errors.append(f"{api_id}: error catalogue {error_id or '<unknown>'} scenario must be an object")
+            else:
+                pre = scenario.get("preconditions")
+                mutations = scenario.get("request_mutations")
+                if not isinstance(pre, list) or not pre or not all(isinstance(value, str) and value.strip() for value in pre):
+                    errors.append(f"{api_id}: error catalogue {error_id or '<unknown>'} scenario.preconditions must be non-empty")
+                if not isinstance(mutations, list) or not mutations:
+                    errors.append(f"{api_id}: error catalogue {error_id or '<unknown>'} scenario.request_mutations must be non-empty")
+
+
+def valid_values(field: dict[str, Any], base_value: Any) -> list[Any]:
+    constraints = field.get("constraints") if isinstance(field.get("constraints"), dict) else {}
+    examples = field.get("examples") if isinstance(field.get("examples"), dict) else {}
+    values: list[Any] = [base_value]
+    value_type = field.get("type")
+    if value_type == "string":
+        if "min_length" in constraints:
+            values.append(examples.get("at_min_length", "x" * constraints["min_length"]))
+        if "max_length" in constraints:
+            values.append(examples.get("at_max_length", "x" * constraints["max_length"]))
+    if value_type in {"integer", "number"} and "enum" not in constraints:
+        if "minimum" in constraints:
+            values.append(examples.get("at_minimum", constraints["minimum"]))
+        if "maximum" in constraints:
+            values.append(examples.get("at_maximum", constraints["maximum"]))
+    if value_type == "array" and isinstance(base_value, list):
+        if "min_items" in constraints:
+            values.append(examples.get("at_min_items", base_value[: constraints["min_items"]]))
+        if "max_items" in constraints:
+            fill = list(base_value) or [examples.get("array_item", "__devflow_item__")]
+            values.append(examples.get("at_max_items", (fill * (constraints["max_items"] + 1))[: constraints["max_items"]]))
+    if isinstance(constraints.get("enum"), list):
+        values.extend(constraints["enum"])
+    if value_type == "boolean":
+        values.extend([False, True])
+    if isinstance(field.get("valid_values"), list):
+        values.extend(field["valid_values"])
+    if field.get("required") is False:
+        values.append(MISSING)
+    if field.get("nullable") is True:
+        values.append(None)
+    return unique(values)
+
+
+def pairwise(domains: list[list[Any]]) -> list[list[Any]]:
+    """Small deterministic IPOG-style generator for valid equivalence classes."""
+    if not domains:
+        return [[]]
+    if len(domains) == 1:
+        return [[value] for value in domains[0]]
+    rows = [list(pair) for pair in product(domains[0], domains[1])]
+    for index in range(2, len(domains)):
+        domain = domains[index]
+        uncovered = {(prior, prior_value, value) for prior in range(index) for prior_value in domains[prior] for value in domain}
+        for row in rows:
+            best = max(domain, key=lambda value: sum((prior, row[prior], value) in uncovered for prior in range(index)))
+            row.append(best)
+            for prior in range(index):
+                uncovered.discard((prior, row[prior], best))
+        while uncovered:
+            prior, prior_value, value = sorted(uncovered, key=lambda item: (item[0], stable_value(item[1]), stable_value(item[2])))[0]
+            row = [domain_values[0] for domain_values in domains[:index]] + [value]
+            row[prior] = prior_value
+            rows.append(row)
+            for previous in range(index):
+                uncovered.discard((previous, row[previous], value))
+    return rows
+
+
+def request_from_mutations(schema: dict[str, Any], mutations: list[dict[str, Any]]) -> dict[str, Any]:
+    request = copy.deepcopy(schema["valid_request"])
+    for mutation in mutations:
+        if not isinstance(mutation, dict):
+            raise ValueError("request mutation must be an object")
+        location = mutation.get("location")
+        pointer = mutation.get("pointer")
+        operation = mutation.get("op")
+        if location not in LOCATIONS or not isinstance(pointer, str) or operation not in {"replace", "remove"}:
+            raise ValueError("request mutation requires location, pointer and replace/remove op")
+        container = request.setdefault(location, {})
+        if operation == "remove":
+            pointer_remove(container, pointer)
+        else:
+            pointer_set(container, pointer, copy.deepcopy(mutation.get("value")))
+    return request
+
+
+def request_for_field(schema: dict[str, Any], field: dict[str, Any], value: Any) -> dict[str, Any]:
+    request = copy.deepcopy(schema["valid_request"])
+    container = request.setdefault(field["location"], {})
+    if value is MISSING:
+        pointer_remove(container, field["pointer"])
+    else:
+        pointer_set(container, field["pointer"], copy.deepcopy(value))
+    return request
+
+
+def request_execution(schema: dict[str, Any], request: dict[str, Any], expect: dict[str, Any]) -> dict[str, Any]:
+    return {
+        "protocol": "http",
+        "request": {
+            "method": schema["method"],
+            "path": schema["path"],
+            "path_params": request.get("path", {}),
+            "query": request.get("query", {}),
+            "headers": request.get("headers", {}),
+            "body": request.get("body", {}),
+        },
+        "expect": expect,
+    }
+
+
+def tc_candidate(api: dict[str, Any], graph: dict[str, Any], key: str, obligation_refs: list[str], execution: dict[str, Any], title: str, preconditions: list[str], oracle: str) -> dict[str, Any]:
+    data = api.get("data", {})
+    requirement_refs = list(data.get("requirement_refs", []))
+    acceptance_refs = [
+        node["id"]
+        for node in graph.get("nodes", [])
+        if isinstance(node, dict) and node.get("kind") == "acceptance" and isinstance(node.get("data"), dict) and node["data"].get("requirement_ref") in requirement_refs
+    ]
+    return {
+        "generated_case_key": key,
+        "test_obligation_refs": obligation_refs,
+        "acceptance_refs": acceptance_refs,
+        "requirement_refs": requirement_refs,
+        "test_type": "api",
+        "target": f"{execution['request']['method']} {execution['request']['path']}: {title}",
+        "preconditions": preconditions,
+        "steps": ["发送 execution.request 中定义的 HTTP 请求"],
+        "oracle": oracle,
+        "automation_mode": "automated",
+        "api_refs": [api["id"]],
+        "execution": execution,
+    }
+
+
+def expected_error(entry: dict[str, Any]) -> dict[str, Any]:
+    return {"http_status": entry["http_status"], "error_code": entry["code"], "error_code_pointer": "/error/code"}
+
+
+def derive_api_cases(api: dict[str, Any], graph: dict[str, Any], errors: list[str]) -> list[dict[str, Any]]:
+    api_id = api["id"]
+    schema = api["data"]["test_schema"]
+    fields = schema.get("fields", [])
+    catalog = schema.get("errors", [])
+    mapping: dict[str, dict[str, Any]] = {}
+    used_mapping: set[str] = set()
+    scenario_errors: list[dict[str, Any]] = []
+    for error in catalog:
+        if not isinstance(error, dict):
+            continue
+        if isinstance(error.get("covers"), list):
+            for cover in error["covers"]:
+                if cover in mapping:
+                    errors.append(f"{api_id}: partition {cover} is mapped by more than one error code")
+                mapping[cover] = error
+        elif isinstance(error.get("scenario"), dict):
+            scenario_errors.append(error)
+    result: list[dict[str, Any]] = []
+    number = 0
+
+    # Valid equivalence classes first.  This is the only place pairwise mixes
+    # fields, and all values in its domains are valid by construction.
+    domains: list[list[Any]] = []
+    valid_field_data: list[tuple[dict[str, Any], Any]] = []
+    for field in fields:
+        base = pointer_get(schema["valid_request"].get(field["location"], {}), field["pointer"])
+        domains.append(valid_values(field, base))
+        valid_field_data.append((field, base))
+    for row in pairwise(domains):
+        request = copy.deepcopy(schema["valid_request"])
+        labels: list[str] = []
+        for (field, _base), value in zip(valid_field_data, row):
+            container = request.setdefault(field["location"], {})
+            if value is MISSING:
+                pointer_remove(container, field["pointer"])
+                labels.append(f"{field['field_key']}=omit")
+            else:
+                pointer_set(container, field["pointer"], copy.deepcopy(value))
+                labels.append(f"{field['field_key']}=valid")
+        number += 1
+        key = case_key(api_id, "pairwise", number)
+        refs = [obligation_id(api_id, "pairwise", f"{number:04d}")]
+        execution = request_execution(schema, request, {"http_status": schema["success"]["http_status"]})
+        result.append({
+            "key": key,
+            "category": "pairwise",
+            "title": "valid pairwise: " + ", ".join(labels),
+            "obligation_refs": refs,
+            "test_case": tc_candidate(api, graph, key, refs, execution, "valid pairwise", list(schema["preconditions"]), f"HTTP {schema['success']['http_status']}"),
+        })
+
+    def add_negative(field: dict[str, Any], partition: str, value: Any, label: str) -> None:
+        nonlocal number
+        map_key = f"{field['field_key']}:{partition}"
+        error = mapping.get(map_key)
+        if error is None:
+            errors.append(error_code_error(api_id, field["field_key"], partition))
+            return
+        used_mapping.add(map_key)
+        number += 1
+        key = case_key(api_id, "negative", number)
+        ref = obligation_id(api_id, field["field_key"], partition)
+        execution = request_execution(schema, request_for_field(schema, field, value), expected_error(error))
+        result.append({
+            "key": key,
+            "category": "negative",
+            "title": f"{field['field_key']}: {label}",
+            "obligation_refs": [ref],
+            "test_case": tc_candidate(api, graph, key, [ref], execution, f"{field['field_key']} {label}", list(schema["preconditions"]), f"HTTP {error['http_status']} and error code {error['code']}"),
+        })
+
+    for field in fields:
+        constraints = field.get("constraints", {})
+        examples = field.get("examples", {}) if isinstance(field.get("examples"), dict) else {}
+        value_type = field["type"]
+        if field.get("required"):
+            add_negative(field, "missing", MISSING, "required value omitted")
+        if not field.get("nullable"):
+            add_negative(field, "null", None, "null value")
+        add_negative(field, "wrong_type", wrong_type(value_type), "wrong type")
+        if value_type == "string":
+            if "min_length" in constraints and constraints["min_length"] > 0:
+                add_negative(field, "below_min_length", examples.get("below_min_length", "x" * (constraints["min_length"] - 1)), "below minimum length")
+            if "max_length" in constraints:
+                add_negative(field, "above_max_length", examples.get("above_max_length", "x" * (constraints["max_length"] + 1)), "above maximum length")
+            if "format" in constraints:
+                invalid = examples.get("invalid_format", standard_invalid_format(str(constraints["format"])))
+                if invalid is None:
+                    errors.append(f"{api_id}: field {field['field_key']} format {constraints['format']} requires examples.invalid_format")
+                else:
+                    add_negative(field, "invalid_format", invalid, "invalid format")
+            if "pattern" in constraints:
+                add_negative(field, "invalid_pattern", examples.get("invalid_pattern"), "invalid pattern")
+        if value_type in {"integer", "number"}:
+            if "minimum" in constraints:
+                add_negative(field, "below_minimum", examples.get("below_minimum", constraints["minimum"] - 1), "below minimum")
+            if "maximum" in constraints:
+                add_negative(field, "above_maximum", examples.get("above_maximum", constraints["maximum"] + 1), "above maximum")
+        if value_type == "array":
+            base = pointer_get(schema["valid_request"].get(field["location"], {}), field["pointer"])
+            if "min_items" in constraints and constraints["min_items"] > 0:
+                add_negative(field, "below_min_items", list(base)[: constraints["min_items"] - 1], "below minimum item count")
+            if "max_items" in constraints:
+                fill = list(base) or [examples.get("array_item", "__devflow_item__")]
+                expanded = (fill * (constraints["max_items"] + 1))[: constraints["max_items"] + 1]
+                add_negative(field, "above_max_items", expanded, "above maximum item count")
+        if "enum" in constraints:
+            add_negative(field, "invalid_enum", examples.get("invalid_enum"), "value outside enum")
+
+    for mapped_partition in sorted(set(mapping) - used_mapping):
+        errors.append(f"{api_id}: error mapping {mapped_partition} does not name a derivable negative partition")
+
+    for error in scenario_errors:
+        scenario = error["scenario"]
+        try:
+            request = request_from_mutations(schema, scenario["request_mutations"])
+        except (KeyError, TypeError, ValueError) as failure:
+            errors.append(f"{api_id}: scenario error {error.get('id', '<unknown>')} has invalid request mutation: {failure}")
+            continue
+        number += 1
+        key = case_key(api_id, "error", number)
+        ref = obligation_id(api_id, "error", str(error["error_key"]))
+        execution = request_execution(schema, request, expected_error(error))
+        preconditions = [*schema["preconditions"], *scenario["preconditions"]]
+        result.append({
+            "key": key,
+            "category": "error",
+            "title": f"error code {error['code']}",
+            "obligation_refs": [ref],
+            "test_case": tc_candidate(api, graph, key, [ref], execution, f"error {error['code']}", preconditions, f"HTTP {error['http_status']} and error code {error['code']}"),
+        })
+    return result
+
+
+def compile_matrix(graph: dict[str, Any], feature: str) -> tuple[dict[str, Any], list[str]]:
+    errors: list[str] = []
+    APIs = api_nodes(graph)
+    for api in APIs:
+        validate_schema(api, errors)
+    cases: list[dict[str, Any]] = []
+    if not errors:
+        for api in APIs:
+            cases.extend(derive_api_cases(api, graph, errors))
+    source = {"api_contract_fingerprint": api_fingerprint(graph), "api_ids": [node.get("id") for node in APIs]}
+    case_manifest = [
+        {"key": item["key"], "obligation_refs": item["obligation_refs"], "test_case": item["test_case"]}
+        for item in cases
+    ]
+    matrix = {
+        "schema_version": 1,
+        "origin": "core_api_test_matrix",
+        "feature": feature,
+        "source": source,
+        "case_set_fingerprint": digest(case_manifest),
+        "cases": cases,
+        "errors": errors,
+    }
+    return matrix, errors
+
+
+def render_markdown(matrix: dict[str, Any]) -> str:
+    lines = ["# 完整 API 验收测试用例", "", f"- Feature: `{matrix['feature']}`", f"- API 契约指纹: `{matrix['source']['api_contract_fingerprint']}`", f"- 用例集指纹: `{matrix['case_set_fingerprint']}`", f"- 用例数: {len(matrix['cases'])}", "", "| 用例键 | 类型 | 覆盖义务 | 请求/预期 |", "|---|---|---|---|"]
+    for item in matrix["cases"]:
+        execution = item["test_case"]["execution"]
+        request = execution["request"]
+        expect = execution["expect"]
+        expected = f"HTTP {expect['http_status']}" + (f", {expect['error_code']}" if "error_code" in expect else "")
+        lines.append(f"| `{item['key']}` | {item['category']} | {', '.join(f'`{ref}`' for ref in item['obligation_refs'])} | `{request['method']} {request['path']}` → {expected} |")
+    if matrix["errors"]:
+        lines.extend(["", "## 契约缺口（不可冻结）", "", *[f"- {error}" for error in matrix["errors"]]])
+    lines.extend(["", "## 执行方式", "", "每条用例均含 `execution.protocol=http`、完整请求和可观察预期。导入后的 TC ID 写入同目录的 `api-acceptance-bindings.template.json`；为该文件填写测试环境基地址和鉴权环境变量后，`run-acceptance-tests` 可逐条执行。需要专用夹具的数据前置条件不会被省略，必须由绑定中的 setup 命令或测试环境准备满足。", ""])
+    return "\n".join(lines)
+
+
+def binding_template(matrix: dict[str, Any]) -> dict[str, Any]:
+    cases = []
+    for item in matrix["cases"]:
+        tc_id = item.get("tc_id")
+        if isinstance(tc_id, str) and tc_id:
+            cases.append({"tc_id": tc_id, "mode": "automated", "adapter": {"kind": "http", "base_url_env": "DEVFLOW_TEST_BASE_URL", "headers_env": {"Authorization": "DEVFLOW_TEST_AUTHORIZATION"}}})
+        else:
+            cases.append({"generated_case_key": item["key"], "mode": "automated", "adapter": {"kind": "http", "base_url_env": "DEVFLOW_TEST_BASE_URL", "headers_env": {"Authorization": "DEVFLOW_TEST_AUTHORIZATION"}}})
+    return {"schema_version": 1, "origin": "core_api_test_matrix_template", "feature": matrix["feature"], "case_set_fingerprint": matrix["case_set_fingerprint"], "cases": cases}
+
+
+def validate_imported(matrix: dict[str, Any], graph: dict[str, Any], errors: list[str]) -> None:
+    expected, compile_errors = compile_matrix(graph, matrix.get("feature", ""))
+    errors.extend(compile_errors)
+    if matrix.get("origin") != "core_api_test_matrix" or matrix.get("schema_version") != 1:
+        errors.append("API test matrix identity is invalid")
+        return
+    if matrix.get("source") != expected.get("source"):
+        errors.append("API test matrix is stale for the current API contract")
+    if matrix.get("case_set_fingerprint") != expected.get("case_set_fingerprint"):
+        errors.append("API test matrix cases differ from the deterministic compiler output")
+    expected_by_key = {item["key"]: item for item in expected.get("cases", [])}
+    actual_cases = matrix.get("cases") if isinstance(matrix.get("cases"), list) else []
+    actual_by_key = {item.get("key"): item for item in actual_cases if isinstance(item, dict) and isinstance(item.get("key"), str)}
+    if set(actual_by_key) != set(expected_by_key):
+        errors.append("API test matrix does not contain exactly the derived test cases")
+        return
+    graph_cases = {
+        node.get("data", {}).get("generated_case_key"): node
+        for node in graph.get("nodes", [])
+        if isinstance(node, dict) and node.get("kind") == "test_case" and isinstance(node.get("data"), dict) and isinstance(node["data"].get("generated_case_key"), str)
+    }
+    for key, expected_case in expected_by_key.items():
+        actual = actual_by_key[key]
+        tc_id = actual.get("tc_id")
+        node = graph_cases.get(key)
+        if not isinstance(tc_id, str) or not tc_id:
+            errors.append(f"{key}: has not been imported as a TC candidate")
+            continue
+        if not isinstance(node, dict) or node.get("id") != tc_id:
+            errors.append(f"{key}: imported TC does not match matrix tc_id")
+            continue
+        data = node.get("data", {})
+        if data.get("test_obligation_refs") != expected_case["obligation_refs"]:
+            errors.append(f"{key}: TC obligation refs differ from the deterministic matrix")
+        if data.get("execution") != expected_case["test_case"]["execution"]:
+            errors.append(f"{key}: TC execution definition differs from the deterministic matrix")
+
+
+def run(action: str, root: Path, feature: str, write: bool) -> dict[str, Any]:
+    governance_path, matrix_path, markdown_path, template_path = paths(root, feature)
+    errors: list[str] = []
+    graph = read_json(governance_path, errors, "requirement graph")
+    if graph is None:
+        return {"ok": False, "feature": feature, "errors": errors}
+    matrix, compile_errors = compile_matrix(graph, feature)
+    if action == "check":
+        return {"ok": not compile_errors, "feature": feature, "errors": compile_errors, "case_count": len(matrix["cases"]), "case_set_fingerprint": matrix["case_set_fingerprint"]}
+    if action == "compile":
+        if write:
+            write_json(matrix_path, matrix)
+            write_text(markdown_path, render_markdown(matrix))
+            write_json(template_path, binding_template(matrix))
+        return {"ok": not compile_errors, "feature": feature, "errors": compile_errors, "paths": {"matrix": str(matrix_path.relative_to(root)), "view": str(markdown_path.relative_to(root)), "binding_template": str(template_path.relative_to(root))}, "case_count": len(matrix["cases"]), "case_set_fingerprint": matrix["case_set_fingerprint"]}
+    persisted = read_json(matrix_path, errors, "API test matrix")
+    if persisted is not None:
+        validate_imported(persisted, graph, errors)
+    return {"ok": not errors, "feature": feature, "errors": errors, "case_count": len(matrix["cases"]), "case_set_fingerprint": matrix["case_set_fingerprint"]}
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("action", choices=("check", "compile", "validate"))
+    parser.add_argument("--feature", required=True)
+    parser.add_argument("--write", action="store_true")
+    parser.add_argument("--json", action="store_true")
+    args = parser.parse_args()
+    if not FEATURE_RE.fullmatch(args.feature):
+        result = {"ok": False, "errors": ["invalid feature"]}
+    elif args.action == "compile" and not args.write:
+        result = {"ok": False, "errors": ["compile requires --write"]}
+    else:
+        result = run(args.action, Path.cwd().resolve(), args.feature, args.write)
+    print(json.dumps(result, ensure_ascii=False, indent=2))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())