@guanlin4924/devflow-pi 0.1.40 → 0.1.47

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

@@ -0,0 +1,1063 @@
+#!/usr/bin/env python3
+"""Strict structural validator and canonicalizer for Devflow business models.
+
+P0-01 intentionally validates only schema shape, strict keys, local union
+semantics, and deterministic serialization. Source resolution and business
+closure checks are added by P0-02 through P0-04.
+"""
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+import re
+import subprocess
+import sys
+import unicodedata
+from pathlib import Path
+from typing import Any
+
+
+DEFAULT_SCHEMA = Path(__file__).resolve().parents[1] / "contracts" / "business-model.schema.yaml"
+SOURCE_RESOLVER = Path(__file__).resolve().with_name("business_source_resolver.rb")
+
+
+def load_yaml(path: Path) -> Any:
+    try:
+        import yaml  # type: ignore
+
+        return yaml.safe_load(path.read_text(encoding="utf-8"))
+    except ImportError:
+        result = subprocess.run(
+            [
+                "ruby",
+                "-ryaml",
+                "-rjson",
+                "-e",
+                "puts JSON.generate(YAML.safe_load(File.read(ARGV.fetch(0))))",
+                str(path),
+            ],
+            text=True,
+            capture_output=True,
+            check=False,
+        )
+        if result.returncode != 0:
+            raise ValueError(result.stderr.strip() or "YAML parse failed")
+        return json.loads(result.stdout)
+
+
+def add_error(errors: list[dict[str, str]], code: str, path: str, message: str) -> None:
+    errors.append({"code": code, "path": path, "message": message})
+
+
+def object_spec(schema: dict[str, Any], name: str) -> dict[str, Any]:
+    value = schema.get("objects", {}).get(name, {})
+    return value if isinstance(value, dict) else {}
+
+
+def strict_object(
+    value: Any,
+    spec: dict[str, Any],
+    path: str,
+    errors: list[dict[str, str]],
+    *,
+    missing_code: str = "BUSINESS_REQUIRED_FIELD_MISSING",
+) -> bool:
+    if not isinstance(value, dict):
+        add_error(errors, "BUSINESS_INVALID_FIELD_VALUE", path, "object required")
+        return False
+    properties = spec.get("properties", {})
+    allowed = set(properties) if isinstance(properties, dict) else set()
+    for key in value:
+        if key not in allowed:
+            add_error(errors, "BUSINESS_UNKNOWN_FIELD", f"{path}.{key}", f"unknown field {key}")
+    for key in spec.get("required", []):
+        if key not in value:
+            add_error(errors, missing_code, f"{path}.{key}", f"required field {key} is missing")
+    return True
+
+
+def validate_id(value: Any, path: str, pattern: re.Pattern[str], errors: list[dict[str, str]]) -> bool:
+    if not isinstance(value, str) or not pattern.fullmatch(value):
+        add_error(errors, "BUSINESS_ID_INVALID", path, "value must match the business ID pattern")
+        return False
+    return True
+
+
+def validate_string(value: Any, path: str, errors: list[dict[str, str]], *, non_empty: bool = True) -> None:
+    if not isinstance(value, str) or (non_empty and not value.strip()):
+        add_error(errors, "BUSINESS_INVALID_FIELD_VALUE", path, "non-empty string required")
+
+
+def validate_id_list(
+    value: Any,
+    path: str,
+    pattern: re.Pattern[str],
+    errors: list[dict[str, str]],
+    *,
+    min_items: int = 0,
+) -> None:
+    if not isinstance(value, list):
+        add_error(errors, "BUSINESS_INVALID_FIELD_VALUE", path, "array required")
+        return
+    if len(value) < min_items:
+        add_error(errors, "BUSINESS_INVALID_FIELD_VALUE", path, f"at least {min_items} item(s) required")
+    seen: set[str] = set()
+    for index, item in enumerate(value):
+        if validate_id(item, f"{path}[{index}]", pattern, errors):
+            if item in seen:
+                add_error(errors, "BUSINESS_DUPLICATE_ID", f"{path}[{index}]", f"duplicate reference {item}")
+            seen.add(item)
+
+
+def validate_source_refs(value: Any, path: str, pattern: re.Pattern[str], errors: list[dict[str, str]]) -> None:
+    validate_id_list(value, path, pattern, errors, min_items=1)
+
+
+def register_id(value: Any, path: str, pattern: re.Pattern[str], errors: list[dict[str, str]], seen: set[str]) -> None:
+    if validate_id(value, path, pattern, errors):
+        if value in seen:
+            add_error(errors, "BUSINESS_DUPLICATE_ID", path, f"duplicate ID {value}")
+        else:
+            seen.add(value)
+
+
+def validate_simple_object(
+    value: Any,
+    kind: str,
+    path: str,
+    schema: dict[str, Any],
+    pattern: re.Pattern[str],
+    errors: list[dict[str, str]],
+    seen: set[str],
+) -> None:
+    spec = object_spec(schema, kind)
+    if not strict_object(value, spec, path, errors):
+        return
+    register_id(value.get("id"), f"{path}.id", pattern, errors, seen)
+    if "name" in value:
+        validate_string(value.get("name"), f"{path}.name", errors)
+    validate_source_refs(value.get("source_refs"), f"{path}.source_refs", pattern, errors)
+
+
+def validate_entity(
+    value: Any,
+    path: str,
+    schema: dict[str, Any],
+    pattern: re.Pattern[str],
+    errors: list[dict[str, str]],
+    seen: set[str],
+) -> None:
+    spec = object_spec(schema, "entity")
+    if not strict_object(value, spec, path, errors):
+        return
+    register_id(value.get("id"), f"{path}.id", pattern, errors, seen)
+    if "name" in value:
+        validate_string(value.get("name"), f"{path}.name", errors)
+    validate_source_refs(value.get("source_refs"), f"{path}.source_refs", pattern, errors)
+    states = value.get("states")
+    if not isinstance(states, list):
+        add_error(errors, "BUSINESS_INVALID_FIELD_VALUE", f"{path}.states", "array required")
+        return
+    state_spec = object_spec(schema, "state")
+    for index, state in enumerate(states):
+        state_path = f"{path}.states[{index}]"
+        if not strict_object(state, state_spec, state_path, errors):
+            continue
+        register_id(state.get("id"), f"{state_path}.id", pattern, errors, seen)
+        validate_string(state.get("name"), f"{state_path}.name", errors)
+        if "terminal" in state and not isinstance(state.get("terminal"), bool):
+            add_error(errors, "BUSINESS_INVALID_FIELD_VALUE", f"{state_path}.terminal", "boolean required")
+        validate_source_refs(state.get("source_refs"), f"{state_path}.source_refs", pattern, errors)
+
+
+def validate_origin(
+    value: Any,
+    path: str,
+    schema: dict[str, Any],
+    pattern: re.Pattern[str],
+    errors: list[dict[str, str]],
+) -> None:
+    variants = schema.get("unions", {}).get("resource_origin", {}).get("variants", {})
+    if not isinstance(value, dict):
+        add_error(errors, "BUSINESS_INVALID_ORIGIN", path, "resource origin must be an object")
+        return
+    kind = value.get("kind")
+    spec = variants.get(kind) if isinstance(variants, dict) else None
+    if not isinstance(spec, dict):
+        add_error(errors, "BUSINESS_INVALID_ORIGIN", f"{path}.kind", f"unknown resource origin {kind}")
+        return
+    properties = spec.get("properties", {})
+    allowed = set(properties) if isinstance(properties, dict) else set()
+    for key in value:
+        if key not in allowed:
+            add_error(errors, "BUSINESS_UNKNOWN_FIELD", f"{path}.{key}", f"field {key} is not valid for origin {kind}")
+    for key in spec.get("required", []):
+        if key not in value:
+            add_error(errors, "BUSINESS_REQUIRED_FIELD_MISSING", f"{path}.{key}", f"required field {key} is missing")
+    for key, item in value.items():
+        if key != "kind":
+            validate_id(item, f"{path}.{key}", pattern, errors)
+
+
+def validate_resource(
+    value: Any,
+    path: str,
+    schema: dict[str, Any],
+    pattern: re.Pattern[str],
+    errors: list[dict[str, str]],
+    seen: set[str],
+) -> None:
+    spec = object_spec(schema, "resource")
+    if not strict_object(value, spec, path, errors):
+        return
+    register_id(value.get("id"), f"{path}.id", pattern, errors, seen)
+    if "name" in value:
+        validate_string(value.get("name"), f"{path}.name", errors)
+    validate_origin(value.get("origin"), f"{path}.origin", schema, pattern, errors)
+    validate_source_refs(value.get("source_refs"), f"{path}.source_refs", pattern, errors)
+
+
+def validate_operand(
+    value: Any,
+    path: str,
+    schema: dict[str, Any],
+    pattern: re.Pattern[str],
+    errors: list[dict[str, str]],
+) -> None:
+    variants = schema.get("conditions", {}).get("operand_variants", {})
+    if not isinstance(value, dict):
+        add_error(errors, "BUSINESS_RULE_INVALID", path, "operand must be an object")
+        return
+    kind = value.get("kind")
+    allowed_fields = variants.get(kind) if isinstance(variants, dict) else None
+    if not isinstance(allowed_fields, list):
+        add_error(errors, "BUSINESS_RULE_INVALID", f"{path}.kind", f"unknown operand kind {kind}")
+        return
+    allowed = set(allowed_fields)
+    for key in value:
+        if key not in allowed:
+            add_error(errors, "BUSINESS_UNKNOWN_FIELD", f"{path}.{key}", f"field {key} is not valid for operand {kind}")
+    for key in allowed - {"value"}:
+        if key not in value:
+            add_error(errors, "BUSINESS_REQUIRED_FIELD_MISSING", f"{path}.{key}", f"required field {key} is missing")
+    if kind == "literal":
+        if "value" not in value:
+            add_error(errors, "BUSINESS_REQUIRED_FIELD_MISSING", f"{path}.value", "literal value is required")
+    else:
+        for key in allowed - {"kind", "attribute"}:
+            if key in value:
+                validate_id(value[key], f"{path}.{key}", pattern, errors)
+        if "attribute" in allowed and "attribute" in value:
+            validate_string(value["attribute"], f"{path}.attribute", errors)
+
+
+def validate_condition(
+    value: Any,
+    path: str,
+    schema: dict[str, Any],
+    pattern: re.Pattern[str],
+    errors: list[dict[str, str]],
+) -> None:
+    if not isinstance(value, dict):
+        add_error(errors, "BUSINESS_RULE_INVALID", path, "condition must be an object")
+        return
+    allowed = {"op", "args", "operand", "left", "right"}
+    for key in value:
+        if key not in allowed:
+            add_error(errors, "BUSINESS_UNKNOWN_FIELD", f"{path}.{key}", f"unknown condition field {key}")
+    op = value.get("op")
+    operators = set(schema.get("conditions", {}).get("operators", []))
+    if op not in operators:
+        add_error(errors, "BUSINESS_RULE_INVALID", f"{path}.op", f"unsupported operator {op}")
+        return
+    if op in {"and", "or", "not"}:
+        args = value.get("args")
+        expected = 1 if op == "not" else 2
+        if not isinstance(args, list) or len(args) < expected or (op == "not" and len(args) != 1):
+            add_error(errors, "BUSINESS_RULE_INVALID", f"{path}.args", f"{op} requires {'one' if op == 'not' else 'at least two'} argument(s)")
+            return
+        if set(value) - {"op", "args"}:
+            add_error(errors, "BUSINESS_RULE_INVALID", path, f"{op} only accepts args")
+        for index, item in enumerate(args):
+            validate_condition(item, f"{path}.args[{index}]", schema, pattern, errors)
+    elif op == "exists":
+        if set(value) - {"op", "operand"}:
+            add_error(errors, "BUSINESS_RULE_INVALID", path, "exists only accepts operand")
+        validate_operand(value.get("operand"), f"{path}.operand", schema, pattern, errors)
+    else:
+        if set(value) - {"op", "left", "right"}:
+            add_error(errors, "BUSINESS_RULE_INVALID", path, f"{op} only accepts left/right operands")
+        validate_operand(value.get("left"), f"{path}.left", schema, pattern, errors)
+        validate_operand(value.get("right"), f"{path}.right", schema, pattern, errors)
+
+
+def validate_rule(
+    value: Any,
+    path: str,
+    schema: dict[str, Any],
+    pattern: re.Pattern[str],
+    errors: list[dict[str, str]],
+    seen: set[str],
+) -> None:
+    spec = object_spec(schema, "rule")
+    if not strict_object(value, spec, path, errors):
+        return
+    register_id(value.get("id"), f"{path}.id", pattern, errors, seen)
+    if "name" in value:
+        validate_string(value.get("name"), f"{path}.name", errors)
+    kind = value.get("kind")
+    if kind not in {"constraint", "decision"}:
+        add_error(errors, "BUSINESS_RULE_INVALID", f"{path}.kind", "kind must be constraint or decision")
+    validate_source_refs(value.get("source_refs"), f"{path}.source_refs", pattern, errors)
+    if "input_refs" in value:
+        validate_id_list(value.get("input_refs"), f"{path}.input_refs", pattern, errors)
+    if kind == "decision":
+        if value.get("evaluation") != "first_match":
+            add_error(errors, "BUSINESS_RULE_INVALID", f"{path}.evaluation", "decision evaluation must be first_match")
+        if "expression" in value:
+            add_error(errors, "BUSINESS_RULE_INVALID", f"{path}.expression", "decision rule cannot define expression")
+        branches = value.get("branches")
+        if not isinstance(branches, list) or not branches:
+            add_error(errors, "BUSINESS_RULE_INVALID", f"{path}.branches", "decision branches must be a non-empty array")
+            return
+        branch_spec = object_spec(schema, "branch")
+        defaults: list[int] = []
+        branch_ids: set[str] = set()
+        for index, branch in enumerate(branches):
+            branch_path = f"{path}.branches[{index}]"
+            if not strict_object(branch, branch_spec, branch_path, errors):
+                continue
+            branch_id = branch.get("id")
+            if validate_id(branch_id, f"{branch_path}.id", pattern, errors):
+                if branch_id in branch_ids:
+                    add_error(errors, "BUSINESS_DUPLICATE_ID", f"{branch_path}.id", f"duplicate branch ID {branch_id}")
+                branch_ids.add(branch_id)
+            validate_id_list(branch.get("next_action_refs"), f"{branch_path}.next_action_refs", pattern, errors, min_items=1)
+            validate_source_refs(branch.get("source_refs"), f"{branch_path}.source_refs", pattern, errors)
+            if branch.get("default") is True:
+                defaults.append(index)
+                if "when" in branch:
+                    add_error(errors, "BUSINESS_RULE_INVALID", f"{branch_path}.when", "default branch cannot define when")
+            else:
+                if branch.get("default") not in {None, False}:
+                    add_error(errors, "BUSINESS_RULE_INVALID", f"{branch_path}.default", "default must be boolean")
+                validate_condition(branch.get("when"), f"{branch_path}.when", schema, pattern, errors)
+        if defaults != [len(branches) - 1]:
+            add_error(errors, "BUSINESS_RULE_INVALID", f"{path}.branches", "exactly one default branch is required and it must be last")
+    elif kind == "constraint":
+        if "branches" in value or "evaluation" in value:
+            add_error(errors, "BUSINESS_RULE_INVALID", path, "constraint rule cannot define branches or evaluation")
+        validate_condition(value.get("expression"), f"{path}.expression", schema, pattern, errors)
+
+
+def validate_routing(value: Any, path: str, schema: dict[str, Any], pattern: re.Pattern[str], errors: list[dict[str, str]]) -> None:
+    spec = object_spec(schema, "routing")
+    if not strict_object(value, spec, path, errors):
+        return
+    choices = 0
+    if "next_action_refs" in value:
+        validate_id_list(value.get("next_action_refs"), f"{path}.next_action_refs", pattern, errors, min_items=1)
+        choices += 1
+    if "decision_rule_ref" in value:
+        validate_id(value.get("decision_rule_ref"), f"{path}.decision_rule_ref", pattern, errors)
+        choices += 1
+    if "terminal" in value:
+        if value.get("terminal") is not True:
+            add_error(errors, "BUSINESS_ROUTING_INVALID", f"{path}.terminal", "terminal must be true when present")
+        choices += 1
+    if choices != 1:
+        add_error(errors, "BUSINESS_ROUTING_INVALID", path, "routing must choose exactly one of next_action_refs, decision_rule_ref, or terminal")
+
+
+def validate_failure_mode(value: Any, path: str, schema: dict[str, Any], pattern: re.Pattern[str], errors: list[dict[str, str]]) -> None:
+    spec = object_spec(schema, "failure_mode")
+    if not strict_object(value, spec, path, errors):
+        return
+    validate_id(value.get("code"), f"{path}.code", pattern, errors)
+    validate_source_refs(value.get("source_refs"), f"{path}.source_refs", pattern, errors)
+    recovery = "recovery_action_ref" in value
+    terminal = value.get("terminal") is True and "terminal_state_ref" in value
+    if recovery == terminal:
+        add_error(errors, "BUSINESS_FAILURE_OUTCOME_MISSING", path, "failure must define either recovery_action_ref or terminal=true with terminal_state_ref")
+    if recovery:
+        validate_id(value.get("recovery_action_ref"), f"{path}.recovery_action_ref", pattern, errors)
+        if "terminal_state_ref" in value or "terminal" in value:
+            add_error(errors, "BUSINESS_FAILURE_OUTCOME_MISSING", path, "recoverable failure cannot also be terminal")
+    if terminal:
+        validate_id(value.get("terminal_state_ref"), f"{path}.terminal_state_ref", pattern, errors)
+
+
+def validate_action(
+    value: Any,
+    path: str,
+    schema: dict[str, Any],
+    pattern: re.Pattern[str],
+    errors: list[dict[str, str]],
+    seen: set[str],
+) -> None:
+    spec = object_spec(schema, "action")
+    if not strict_object(value, spec, path, errors):
+        return
+    register_id(value.get("id"), f"{path}.id", pattern, errors, seen)
+    if "name" in value:
+        validate_string(value.get("name"), f"{path}.name", errors)
+    for key in ("requirement_refs", "consumes", "produces", "constraint_rule_refs", "source_refs"):
+        validate_id_list(value.get(key), f"{path}.{key}", pattern, errors, min_items=1 if key in {"requirement_refs", "source_refs"} else 0)
+    for key in ("actor_ref", "owner_ref"):
+        validate_id(value.get(key), f"{path}.{key}", pattern, errors)
+    validate_string(value.get("trigger"), f"{path}.trigger", errors)
+    state_keys = {"entity_ref", "from_state_ref", "to_state_ref"}
+    present = state_keys.intersection(value)
+    if present and present != state_keys:
+        add_error(errors, "BUSINESS_STATE_REF_PARTIAL", path, "entity_ref, from_state_ref, and to_state_ref must be all present or all absent")
+    for key in present:
+        validate_id(value.get(key), f"{path}.{key}", pattern, errors)
+    validate_routing(value.get("routing"), f"{path}.routing", schema, pattern, errors)
+    failures = value.get("failure_modes")
+    if not isinstance(failures, list):
+        add_error(errors, "BUSINESS_INVALID_FIELD_VALUE", f"{path}.failure_modes", "array required")
+    else:
+        failure_codes: set[str] = set()
+        for index, failure in enumerate(failures):
+            failure_path = f"{path}.failure_modes[{index}]"
+            validate_failure_mode(failure, failure_path, schema, pattern, errors)
+            if isinstance(failure, dict) and isinstance(failure.get("code"), str):
+                if failure["code"] in failure_codes:
+                    add_error(errors, "BUSINESS_DUPLICATE_ID", f"{failure_path}.code", f"duplicate failure code {failure['code']}")
+                failure_codes.add(failure["code"])
+
+
+def validate_assumption(value: Any, path: str, schema: dict[str, Any], pattern: re.Pattern[str], errors: list[dict[str, str]], seen: set[str]) -> None:
+    spec = object_spec(schema, "assumption")
+    if not strict_object(value, spec, path, errors):
+        return
+    register_id(value.get("id"), f"{path}.id", pattern, errors, seen)
+    validate_string(value.get("statement"), f"{path}.statement", errors)
+    validate_string(value.get("proposed_by"), f"{path}.proposed_by", errors)
+    validate_id_list(value.get("affected_refs"), f"{path}.affected_refs", pattern, errors, min_items=1)
+    if value.get("status") != "unresolved":
+        add_error(errors, "BUSINESS_INVALID_FIELD_VALUE", f"{path}.status", "AI proposal assumptions must remain unresolved")
+
+
+def validate_conflict(value: Any, path: str, schema: dict[str, Any], pattern: re.Pattern[str], errors: list[dict[str, str]], seen: set[str]) -> None:
+    spec = object_spec(schema, "conflict")
+    if not strict_object(value, spec, path, errors):
+        return
+    register_id(value.get("id"), f"{path}.id", pattern, errors, seen)
+    validate_id(value.get("subject_ref"), f"{path}.subject_ref", pattern, errors)
+    validate_string(value.get("field"), f"{path}.field", errors)
+    if value.get("status") not in {"unresolved", "resolved"}:
+        add_error(errors, "BUSINESS_INVALID_FIELD_VALUE", f"{path}.status", "invalid conflict status")
+    alternatives = value.get("alternatives")
+    if not isinstance(alternatives, list) or len(alternatives) < 2:
+        add_error(errors, "BUSINESS_INVALID_FIELD_VALUE", f"{path}.alternatives", "at least two alternatives are required")
+        return
+    alternative_spec = object_spec(schema, "alternative")
+    for index, alternative in enumerate(alternatives):
+        alt_path = f"{path}.alternatives[{index}]"
+        if strict_object(alternative, alternative_spec, alt_path, errors):
+            validate_string(alternative.get("proposal_ref"), f"{alt_path}.proposal_ref", errors)
+
+
+def validate_model(data: Any, schema: dict[str, Any]) -> list[dict[str, str]]:
+    errors: list[dict[str, str]] = []
+    top = schema.get("top_level", {})
+    if not isinstance(data, dict):
+        add_error(errors, "BUSINESS_SCHEMA_INVALID", "$", "root must be an object")
+        return errors
+    allowed = set(top.get("properties", {}))
+    forbidden = set(top.get("forbidden_derived", []))
+    for key in data:
+        if key in forbidden:
+            add_error(errors, "BUSINESS_DERIVED_FIELD_FORBIDDEN", key, f"derived field {key} cannot be authored")
+        elif key not in allowed:
+            add_error(errors, "BUSINESS_UNKNOWN_FIELD", key, f"unknown field {key}")
+    for key in top.get("required", []):
+        if key not in data:
+            add_error(errors, "BUSINESS_REQUIRED_FIELD_MISSING", key, f"required field {key} is missing")
+    if data.get("schema_version") != schema.get("schema_version", 1):
+        add_error(errors, "BUSINESS_SCHEMA_VERSION_INVALID", "schema_version", "schema version must match the contract")
+    feature = data.get("feature")
+    validate_string(feature, "feature", errors)
+    if isinstance(feature, str) and (re.search(r"[\\/\x00-\x1F\x7F]", feature) or feature in {".", ".."}):
+        add_error(errors, "BUSINESS_FEATURE_INVALID", "feature", "feature must be a single safe path segment")
+    validate_string(data.get("source_registry_ref"), "source_registry_ref", errors)
+    pattern = re.compile(str(schema.get("id_pattern", r"^[A-Za-z][A-Za-z0-9_-]*$")))
+    seen: set[str] = set()
+    collection_handlers = {
+        "actors": lambda value, path: validate_simple_object(value, "actor", path, schema, pattern, errors, seen),
+        "entities": lambda value, path: validate_entity(value, path, schema, pattern, errors, seen),
+        "components": lambda value, path: validate_simple_object(value, "component", path, schema, pattern, errors, seen),
+        "boundaries": lambda value, path: validate_simple_object(value, "boundary", path, schema, pattern, errors, seen),
+        "resources": lambda value, path: validate_resource(value, path, schema, pattern, errors, seen),
+        "rules": lambda value, path: validate_rule(value, path, schema, pattern, errors, seen),
+        "actions": lambda value, path: validate_action(value, path, schema, pattern, errors, seen),
+        "assumptions": lambda value, path: validate_assumption(value, path, schema, pattern, errors, seen),
+    }
+    for collection, handler in collection_handlers.items():
+        values = data.get(collection, [])
+        if not isinstance(values, list):
+            add_error(errors, "BUSINESS_INVALID_FIELD_VALUE", collection, "array required")
+            continue
+        for index, value in enumerate(values):
+            handler(value, f"{collection}[{index}]")
+    for key in ("requirement_refs", "decision_refs", "resolved_assumption_refs"):
+        validate_id_list(data.get(key), key, pattern, errors)
+    return errors
+
+
+def normalize(value: Any) -> Any:
+    if isinstance(value, str):
+        return unicodedata.normalize("NFKC", value).rstrip()
+    if isinstance(value, list):
+        return [normalize(item) for item in value]
+    if isinstance(value, dict):
+        return {key: normalize(item) for key, item in value.items()}
+    return value
+
+
+def canonical_order(data: dict[str, Any], schema: dict[str, Any]) -> dict[str, Any]:
+    canonical = schema.get("canonical", {})
+    orders = canonical.get("object_orders", {})
+
+    def ordered(value: Any, kind: str) -> Any:
+        if not isinstance(value, dict):
+            return value
+        order = orders.get(kind, [])
+        keys = [key for key in order if key in value]
+        keys.extend(sorted(key for key in value if key not in keys))
+        result: dict[str, Any] = {}
+        for key in keys:
+            item = value[key]
+            if kind == "entity" and key == "states":
+                result[key] = [ordered(x, "state") for x in item]
+            elif kind == "resource" and key == "origin":
+                result[key] = ordered(item, "resource_origin")
+            elif kind == "rule" and key == "branches":
+                result[key] = [ordered(x, "branch") for x in item]
+            elif kind in {"rule", "branch"} and key in {"expression", "when"}:
+                result[key] = ordered_condition(item)
+            elif kind == "action" and key == "routing":
+                result[key] = ordered(item, "routing")
+            elif kind == "action" and key == "failure_modes":
+                result[key] = [ordered(x, "failure_mode") for x in item]
+            elif kind == "conflict" and key == "alternatives":
+                result[key] = [ordered(x, "alternative") for x in item]
+            else:
+                result[key] = item
+        return result
+
+    def ordered_operand(value: Any) -> Any:
+        return ordered(value, "operand")
+
+    def ordered_condition(value: Any) -> Any:
+        if not isinstance(value, dict):
+            return value
+        order = orders.get("condition", [])
+        keys = [key for key in order if key in value]
+        keys.extend(sorted(key for key in value if key not in keys))
+        result: dict[str, Any] = {}
+        for key in keys:
+            item = value[key]
+            if key == "args":
+                result[key] = [ordered_condition(x) for x in item]
+            elif key in {"operand", "left", "right"}:
+                result[key] = ordered_operand(item)
+            else:
+                result[key] = item
+        return result
+
+    root_order = canonical.get("root_order", [])
+    keys = [key for key in root_order if key in data]
+    keys.extend(sorted(key for key in data if key not in keys))
+    collection_kinds = {
+        "actors": "actor",
+        "entities": "entity",
+        "components": "component",
+        "boundaries": "boundary",
+        "resources": "resource",
+        "rules": "rule",
+        "actions": "action",
+        "assumptions": "assumption",
+    }
+    result: dict[str, Any] = {}
+    for key in keys:
+        if key in collection_kinds:
+            result[key] = [ordered(item, collection_kinds[key]) for item in data[key]]
+        else:
+            result[key] = data[key]
+    return result
+
+
+def canonical_payload(data: dict[str, Any], schema: dict[str, Any]) -> tuple[dict[str, Any], bytes, str]:
+    normalized = normalize(data)
+    ordered = canonical_order(normalized, schema)
+    encoded = (json.dumps(ordered, ensure_ascii=False, separators=(",", ":")) + "\n").encode("utf-8")
+    return ordered, encoded, "sha256:" + hashlib.sha256(encoded).hexdigest()
+
+
+def add_violation(violations: list[dict[str, Any]], code: str, subject_ref: str, **facts: Any) -> None:
+    violations.append({"code": code, "subject_ref": subject_ref, "facts": facts})
+
+
+def load_json(path: Path) -> Any:
+    return json.loads(path.read_text(encoding="utf-8"))
+
+
+def requirement_nodes(root: Path, feature: str, violations: list[dict[str, Any]]) -> set[str]:
+    requirements_root = (root / ".planning" / "requirements").resolve()
+    path = (requirements_root / feature / "governance.json").resolve()
+    if not path.is_relative_to(requirements_root):
+        add_violation(violations, "BUSINESS_REQUIREMENT_GRAPH_INVALID", feature, path=str(path), message="feature escapes requirements directory")
+        return set()
+    try:
+        graph = load_json(path)
+    except (OSError, json.JSONDecodeError) as exc:
+        add_violation(violations, "BUSINESS_REQUIREMENT_GRAPH_INVALID", feature, path=str(path), message=str(exc))
+        return set()
+    return {
+        node.get("id")
+        for node in graph.get("nodes", [])
+        if isinstance(node, dict)
+        and node.get("kind") == "requirement"
+        and node.get("status") in {"confirmed", "approved"}
+        and isinstance(node.get("id"), str)
+    }
+
+
+def resolve_sources(root: Path, feature: str, registry_ref: str, violations: list[dict[str, Any]]) -> set[str]:
+    result = subprocess.run(
+        ["ruby", str(SOURCE_RESOLVER), "--root", str(root), "--feature", feature, "--registry", registry_ref, "--json"],
+        text=True,
+        capture_output=True,
+        check=False,
+    )
+    try:
+        payload = json.loads(result.stdout)
+    except json.JSONDecodeError:
+        add_violation(
+            violations,
+            "BUSINESS_PROVENANCE_SOURCE_INVALID",
+            "SOURCE-REGISTRY",
+            resolver_error=result.stderr.strip() or "invalid resolver output",
+        )
+        return set()
+    if result.returncode != 0 or not payload.get("ok"):
+        for error in payload.get("errors", []):
+            add_violation(
+                violations,
+                "BUSINESS_PROVENANCE_SOURCE_INVALID",
+                error.get("source_id") or "SOURCE-REGISTRY",
+                resolver_code=error.get("code"),
+                message=error.get("message"),
+                path=error.get("path"),
+            )
+        return set()
+    registry_path = root / registry_ref
+    try:
+        registry = load_yaml(registry_path)
+    except (OSError, ValueError) as exc:
+        add_violation(violations, "BUSINESS_PROVENANCE_SOURCE_INVALID", "SOURCE-REGISTRY", message=str(exc))
+        return set()
+    return {item.get("id") for item in registry.get("sources", []) if isinstance(item, dict) and isinstance(item.get("id"), str)}
+
+
+def all_sourced_facts(model: dict[str, Any]):
+    for collection in ("actors", "components", "boundaries", "resources", "rules", "actions"):
+        for item in model.get(collection, []):
+            if isinstance(item, dict):
+                yield item.get("id", collection), item.get("source_refs", []), f"{collection}.{item.get('id', '?')}"
+    for entity in model.get("entities", []):
+        if not isinstance(entity, dict):
+            continue
+        yield entity.get("id", "entities"), entity.get("source_refs", []), f"entities.{entity.get('id', '?')}"
+        for state in entity.get("states", []):
+            if isinstance(state, dict):
+                yield state.get("id", "state"), state.get("source_refs", []), f"states.{state.get('id', '?')}"
+    for rule in model.get("rules", []):
+        if isinstance(rule, dict):
+            for branch in rule.get("branches", []):
+                if isinstance(branch, dict):
+                    yield branch.get("id", "branch"), branch.get("source_refs", []), f"branches.{branch.get('id', '?')}"
+    for action in model.get("actions", []):
+        if isinstance(action, dict):
+            for failure in action.get("failure_modes", []):
+                if isinstance(failure, dict):
+                    subject = f"{action.get('id', '?')}#{failure.get('code', '?')}"
+                    yield subject, failure.get("source_refs", []), f"failure_modes.{subject}"
+
+
+def condition_refs(value: Any):
+    if not isinstance(value, dict):
+        return
+    for key, expected in (
+        ("resource_ref", "resource"),
+        ("entity_ref", "entity"),
+        ("state_ref", "state"),
+        ("actor_ref", "actor"),
+    ):
+        if isinstance(value.get(key), str):
+            yield value[key], expected, key
+    for key in ("args",):
+        for item in value.get(key, []) if isinstance(value.get(key), list) else []:
+            yield from condition_refs(item)
+    for key in ("operand", "left", "right"):
+        if key in value:
+            yield from condition_refs(value[key])
+
+
+def check_reference_closure(model: dict[str, Any], violations: list[dict[str, Any]]) -> dict[str, Any]:
+    actors = {item["id"] for item in model.get("actors", [])}
+    entities = {item["id"] for item in model.get("entities", [])}
+    components = {item["id"] for item in model.get("components", [])}
+    boundaries = {item["id"] for item in model.get("boundaries", [])}
+    resources = {item["id"] for item in model.get("resources", [])}
+    rules = {item["id"] for item in model.get("rules", [])}
+    actions = {item["id"] for item in model.get("actions", [])}
+    state_owner: dict[str, str] = {}
+    state_terminal: dict[str, bool] = {}
+    for entity in model.get("entities", []):
+        for state in entity.get("states", []):
+            state_owner[state["id"]] = entity["id"]
+            state_terminal[state["id"]] = state.get("terminal") is True
+    namespaces = {
+        "actor": actors,
+        "entity": entities,
+        "component": components,
+        "boundary": boundaries,
+        "resource": resources,
+        "rule": rules,
+        "action": actions,
+        "state": set(state_owner),
+    }
+
+    def require(subject: str, field: str, ref: Any, expected: str):
+        if ref not in namespaces[expected]:
+            add_violation(violations, "BUSINESS_REF_NOT_FOUND", subject, field=field, ref=ref, expected=expected)
+
+    for resource in model.get("resources", []):
+        origin = resource["origin"]
+        kind = origin["kind"]
+        subject = resource["id"]
+        if kind == "produced_in_flow":
+            require(subject, "origin.lifecycle_owner_ref", origin.get("lifecycle_owner_ref"), "component")
+        elif kind == "user_supplied":
+            require(subject, "origin.actor_ref", origin.get("actor_ref"), "actor")
+            require(subject, "origin.intake_action_ref", origin.get("intake_action_ref"), "action")
+        elif kind == "external_system":
+            require(subject, "origin.boundary_ref", origin.get("boundary_ref"), "boundary")
+            require(subject, "origin.receive_action_ref", origin.get("receive_action_ref"), "action")
+        elif kind == "preexisting_project":
+            require(subject, "origin.lifecycle_owner_ref", origin.get("lifecycle_owner_ref"), "component")
+
+    for rule in model.get("rules", []):
+        subject = rule["id"]
+        for ref in rule.get("input_refs", []):
+            require(subject, "input_refs", ref, "resource")
+        for branch in rule.get("branches", []):
+            for ref in branch.get("next_action_refs", []):
+                require(branch["id"], "next_action_refs", ref, "action")
+            for ref, expected, field in condition_refs(branch.get("when")):
+                require(branch["id"], field, ref, expected)
+        for ref, expected, field in condition_refs(rule.get("expression")):
+            require(subject, field, ref, expected)
+
+    for action in model.get("actions", []):
+        subject = action["id"]
+        require(subject, "actor_ref", action.get("actor_ref"), "actor")
+        require(subject, "owner_ref", action.get("owner_ref"), "component")
+        for field in ("consumes", "produces"):
+            for ref in action.get(field, []):
+                require(subject, field, ref, "resource")
+        for ref in action.get("constraint_rule_refs", []):
+            require(subject, "constraint_rule_refs", ref, "rule")
+        routing = action.get("routing", {})
+        for ref in routing.get("next_action_refs", []):
+            require(subject, "routing.next_action_refs", ref, "action")
+        if routing.get("decision_rule_ref"):
+            require(subject, "routing.decision_rule_ref", routing["decision_rule_ref"], "rule")
+        if action.get("entity_ref"):
+            require(subject, "entity_ref", action["entity_ref"], "entity")
+            require(subject, "from_state_ref", action["from_state_ref"], "state")
+            require(subject, "to_state_ref", action["to_state_ref"], "state")
+            for field in ("from_state_ref", "to_state_ref"):
+                ref = action[field]
+                if ref in state_owner and state_owner[ref] != action["entity_ref"]:
+                    add_violation(violations, "BUSINESS_STATE_ENTITY_MISMATCH", subject, field=field, state_ref=ref, entity_ref=action["entity_ref"])
+        for failure in action.get("failure_modes", []):
+            if failure.get("recovery_action_ref"):
+                require(subject, "failure.recovery_action_ref", failure["recovery_action_ref"], "action")
+            if failure.get("terminal_state_ref"):
+                require(subject, "failure.terminal_state_ref", failure["terminal_state_ref"], "state")
+                terminal = failure["terminal_state_ref"]
+                if action.get("entity_ref") and terminal in state_owner and state_owner[terminal] != action["entity_ref"]:
+                    add_violation(
+                        violations,
+                        "BUSINESS_STATE_ENTITY_MISMATCH",
+                        subject,
+                        field="failure.terminal_state_ref",
+                        state_ref=terminal,
+                        entity_ref=action["entity_ref"],
+                    )
+    return {
+        "actors": actors,
+        "entities": entities,
+        "components": components,
+        "boundaries": boundaries,
+        "resources": resources,
+        "rules": rules,
+        "actions": actions,
+        "state_owner": state_owner,
+        "state_terminal": state_terminal,
+    }
+
+
+def check_requirement_coverage(model: dict[str, Any], known: set[str], violations: list[dict[str, Any]]) -> None:
+    declared = set(model.get("requirement_refs", []))
+    covered: set[str] = set()
+    for action in model.get("actions", []):
+        covered.update(action.get("requirement_refs", []))
+        for ref in action.get("requirement_refs", []):
+            if ref not in known:
+                add_violation(violations, "BUSINESS_REQUIREMENT_REF_INVALID", action["id"], requirement_ref=ref)
+    for ref in declared:
+        if ref not in known:
+            add_violation(violations, "BUSINESS_REQUIREMENT_REF_INVALID", ref, requirement_ref=ref)
+        elif ref not in covered:
+            add_violation(violations, "BUSINESS_REQUIREMENT_UNCOVERED", ref, requirement_ref=ref, covering_actions=[])
+
+
+def check_provenance(model: dict[str, Any], known_sources: set[str], violations: list[dict[str, Any]]) -> None:
+    for subject, refs, path in all_sourced_facts(model):
+        missing = [ref for ref in refs if ref not in known_sources]
+        if missing:
+            add_violation(violations, "BUSINESS_PROVENANCE_SOURCE_INVALID", subject, path=path, missing_source_refs=missing)
+    for resource in model.get("resources", []):
+        origin = resource.get("origin", {})
+        code_source_ref = origin.get("code_source_ref") if origin.get("kind") == "preexisting_project" else None
+        if code_source_ref and code_source_ref not in known_sources:
+            add_violation(
+                violations,
+                "BUSINESS_PROVENANCE_SOURCE_INVALID",
+                resource["id"],
+                path="origin.code_source_ref",
+                missing_source_refs=[code_source_ref],
+            )
+
+
+def check_resources(model: dict[str, Any], violations: list[dict[str, Any]]) -> None:
+    producers: dict[str, list[str]] = {}
+    consumers: dict[str, list[str]] = {}
+    actions = {action["id"]: action for action in model.get("actions", [])}
+    for action in model.get("actions", []):
+        for ref in action.get("produces", []):
+            producers.setdefault(ref, []).append(action["id"])
+        for ref in action.get("consumes", []):
+            consumers.setdefault(ref, []).append(action["id"])
+    for resource in model.get("resources", []):
+        ref = resource["id"]
+        origin = resource["origin"]
+        kind = origin["kind"]
+        produced = producers.get(ref, [])
+        consumed = consumers.get(ref, [])
+        if kind == "produced_in_flow" and not produced:
+            add_violation(violations, "BUSINESS_RESOURCE_PRODUCER_MISSING", ref, consumers=consumed, producers=[])
+        if not consumed:
+            add_violation(violations, "BUSINESS_RESOURCE_CONSUMER_MISSING", ref, consumers=[], producers=produced)
+        if kind == "user_supplied":
+            intake = actions.get(origin.get("intake_action_ref"))
+            if not intake or ref not in intake.get("produces", []):
+                add_violation(violations, "BUSINESS_RESOURCE_INTAKE_INVALID", ref, intake_action_ref=origin.get("intake_action_ref"))
+        elif kind == "external_system":
+            receiver = actions.get(origin.get("receive_action_ref"))
+            if not receiver or ref not in receiver.get("consumes", []):
+                add_violation(violations, "BUSINESS_EXTERNAL_BOUNDARY_INVALID", ref, receive_action_ref=origin.get("receive_action_ref"))
+
+
+def check_rules(model: dict[str, Any], violations: list[dict[str, Any]]) -> None:
+    for rule in model.get("rules", []):
+        if rule.get("kind") != "decision":
+            continue
+        seen: dict[str, str] = {}
+        for branch in rule.get("branches", []):
+            if branch.get("default") is True:
+                continue
+            key = json.dumps(normalize(branch.get("when")), ensure_ascii=False, sort_keys=True, separators=(",", ":"))
+            if key in seen:
+                add_violation(
+                    violations,
+                    "BUSINESS_RULE_BRANCH_DUPLICATE_CONDITION",
+                    rule["id"],
+                    branch_ids=[seen[key], branch["id"]],
+                )
+            else:
+                seen[key] = branch["id"]
+
+
+def check_states(model: dict[str, Any], namespaces: dict[str, Any], violations: list[dict[str, Any]]) -> None:
+    outgoing: dict[str, list[str]] = {state: [] for state in namespaces["state_owner"]}
+    incoming: dict[str, list[str]] = {state: [] for state in namespaces["state_owner"]}
+    for action in model.get("actions", []):
+        source = action.get("from_state_ref")
+        target = action.get("to_state_ref")
+        if source in outgoing and target in incoming:
+            outgoing[source].append(target)
+            incoming[target].append(source)
+        if source in outgoing:
+            for failure in action.get("failure_modes", []):
+                terminal = failure.get("terminal_state_ref")
+                if terminal in incoming:
+                    outgoing[source].append(terminal)
+                    incoming[terminal].append(source)
+    for state, terminal in namespaces["state_terminal"].items():
+        if not terminal and not outgoing[state]:
+            add_violation(violations, "BUSINESS_STATE_OUTGOING_MISSING", state, outgoing=[])
+    if not outgoing:
+        return
+    starts = [state for state in outgoing if not incoming[state]]
+    if not starts:
+        add_violation(violations, "BUSINESS_STATE_START_MISSING", "STATE-MACHINE", states=sorted(outgoing))
+        return
+    reachable = set(starts)
+    queue = list(starts)
+    while queue:
+        state = queue.pop(0)
+        for target in outgoing[state]:
+            if target not in reachable:
+                reachable.add(target)
+                queue.append(target)
+    for state in outgoing:
+        if state not in reachable:
+            add_violation(violations, "BUSINESS_STATE_UNREACHABLE", state, start_states=starts)
+
+
+def flow_edges(model: dict[str, Any]) -> tuple[dict[str, list[str]], set[str]]:
+    rules = {rule["id"]: rule for rule in model.get("rules", [])}
+    edges = {action["id"]: [] for action in model.get("actions", [])}
+    terminals: set[str] = set()
+    for action in model.get("actions", []):
+        routing = action.get("routing", {})
+        if routing.get("terminal") is True:
+            terminals.add(action["id"])
+        edges[action["id"]].extend(routing.get("next_action_refs", []))
+        rule = rules.get(routing.get("decision_rule_ref"))
+        if rule:
+            for branch in rule.get("branches", []):
+                edges[action["id"]].extend(branch.get("next_action_refs", []))
+        for failure in action.get("failure_modes", []):
+            if failure.get("recovery_action_ref"):
+                edges[action["id"]].append(failure["recovery_action_ref"])
+    return edges, terminals
+
+
+def check_flow(model: dict[str, Any], violations: list[dict[str, Any]]) -> None:
+    edges, terminals = flow_edges(model)
+    if not edges:
+        return
+    incoming = {action: [] for action in edges}
+    for source, targets in edges.items():
+        for target in targets:
+            if target in incoming:
+                incoming[target].append(source)
+    starts = [action for action in edges if not incoming[action]]
+    if not starts:
+        add_violation(violations, "BUSINESS_FLOW_START_MISSING", "BUSINESS-FLOW", actions=sorted(edges))
+    reachable = set(starts)
+    queue = list(starts)
+    while queue:
+        action = queue.pop(0)
+        for target in edges[action]:
+            if target in edges and target not in reachable:
+                reachable.add(target)
+                queue.append(target)
+    for action in edges:
+        if action not in reachable:
+            add_violation(violations, "BUSINESS_FLOW_ACTION_UNREACHABLE", action, start_actions=starts)
+    reverse = {action: [] for action in edges}
+    for source, targets in edges.items():
+        for target in targets:
+            if target in reverse:
+                reverse[target].append(source)
+    can_finish = set(terminals)
+    queue = list(terminals)
+    while queue:
+        action = queue.pop(0)
+        for source in reverse[action]:
+            if source not in can_finish:
+                can_finish.add(source)
+                queue.append(source)
+    for action in edges:
+        if action not in can_finish:
+            add_violation(violations, "BUSINESS_FLOW_NO_TERMINAL_PATH", action, terminal_actions=sorted(terminals))
+
+
+def check_business_closure(model: dict[str, Any], root: Path) -> list[dict[str, Any]]:
+    violations: list[dict[str, Any]] = []
+    feature = model["feature"]
+    known_sources = resolve_sources(root, feature, model["source_registry_ref"], violations)
+    known_requirements = requirement_nodes(root, feature, violations)
+    namespaces = check_reference_closure(model, violations)
+    check_provenance(model, known_sources, violations)
+    check_requirement_coverage(model, known_requirements, violations)
+    check_resources(model, violations)
+    check_rules(model, violations)
+    check_states(model, namespaces, violations)
+    check_flow(model, violations)
+    for assumption in model.get("assumptions", []):
+        add_violation(violations, "BUSINESS_ASSUMPTION_UNRESOLVED", assumption["id"], affected_refs=assumption.get("affected_refs", []))
+    return violations
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--proposal", type=Path, required=True)
+    parser.add_argument("--schema", type=Path, default=DEFAULT_SCHEMA)
+    parser.add_argument("--canonical-out", type=Path)
+    parser.add_argument("--check-closure", action="store_true")
+    parser.add_argument("--root", type=Path)
+    args = parser.parse_args()
+    try:
+        schema = load_yaml(args.schema)
+        data = load_yaml(args.proposal)
+    except (OSError, ValueError, json.JSONDecodeError) as exc:
+        payload = {
+            "valid": False,
+            "verdict": "block_unsafe",
+            "errors": [{"code": "BUSINESS_YAML_INVALID", "path": "$", "message": str(exc)}],
+        }
+        print(json.dumps(payload, ensure_ascii=False))
+        return 1
+    errors = validate_model(data, schema)
+    if errors:
+        print(json.dumps({"valid": False, "verdict": "block_unsafe", "errors": errors}, ensure_ascii=False))
+        return 1
+    canonical, encoded, fingerprint = canonical_payload(data, schema)
+    violations: list[dict[str, Any]] = []
+    if args.check_closure:
+        if args.root is None:
+            violations = [{"code": "BUSINESS_CHECKER_CONFIGURATION_INVALID", "subject_ref": "BUSINESS-MODEL", "facts": {"message": "--root is required with --check-closure"}}]
+        else:
+            violations = check_business_closure(canonical, args.root.resolve())
+    if args.canonical_out:
+        args.canonical_out.parent.mkdir(parents=True, exist_ok=True)
+        args.canonical_out.write_bytes(encoded)
+    print(
+        json.dumps(
+            {
+                "valid": True,
+                "verdict": "allow",
+                "errors": [],
+                "closure_ok": not violations,
+                "violations": violations,
+                "canonical": canonical,
+                "canonical_fingerprint": fingerprint,
+            },
+            ensure_ascii=False,
+        )
+    )
+    return 0 if not violations else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())