TASK-034: build CEG contract compiler validator

[cryptoxdog]

Generated under L9 controlled autonomy.

Task: TASK-034
Program: sha256:9cd1a79f948dac419913c134396e58359e4df82862bb3901bdd327684a37cb52
Contract: sha256:996d0a1bf4919ee1af07ce521f99a1f87874d27e516ff34612519bb9a41efda7
Verification: sha256:a5b42a3479a3a810f978af8989c28fbeeceda66987b347704fe94263e7715e8e

This PR is draft only. The controller cannot mark ready, approve, merge, tag, release, or deploy.

[github-actions]

⚠️ Large PR Warning
Reviewable lines changed: 433
Warning threshold: 300 lines
Consider splitting for easier review

📋 Best Practices for Large Changes

1. Refactoring + Features: Separate into 2 PRs
2. Multiple Features: One PR per feature
3. Database + Code: Separate migration from logic
4. Generated Code: Exclude it from reviewable-size accounting

---

✅ This PR passes the blocking limit but is larger than recommended.

[github-actions]

L9 Audit Harness Report

• Generated: 2026-08-02T12:30:14.007398+00:00
• Repo root: /home/runner/work/Cognitive.Engine.Graphs/Cognitive.Engine.Graphs
• Overall result: ✅ PASSED
• Exit code: 0

Step Results

Step	Status	Exit Code	Notes
Architecture Audit	✅ Passed	0
Spec Coverage	✅ Passed	0
Contract Wiring	✅ Passed	0

Architecture Audit Findings

Severity	Count
🔴 CRITICAL	0
🟠 HIGH	0
🟡 MEDIUM	25
🔵 LOW	0

See artifacts/audit_report.md for full details.

Spec Coverage

• ✅ Implemented: 37
• ⚠️ Partial: 9
• ❌ Missing: 0
• Total features: 46

Category	Implemented	Partial	Missing	Total
gates	10	0	0	10
scoring	7	0	0	7
v1.1_node	2	0	0	2
v1.1_edge	2	0	0	2
v1.1_action	0	2	0	2
v1.1_scoring	1	1	0	2
action_handler	0	6	0	6
gds_algorithm	5	0	0	5
research_pattern	10	0	0	10

See artifacts/coverage_report.md for full details.

Next Steps

All checks passed. Safe to merge.

[Copilot]

Pull request overview

Adds a repo-scoped “payload contract compiler validator” tool to validate contracts/payloads JSON Schemas and example fixtures against native engine.models.payloads Pydantic models, and to confirm DomainPackLoader remains the authority for the PlasticOS domain pack. This is wired into the existing make agent-check / agent-check-unit gates and documented via ADR-109 and the payload contracts README.

Changes:

• Added tools/payload_contract_compiler.py to validate payload schemas/fixtures and emit a deterministic digest report (or stdout-only digest).
• Added unit tests covering the compiler report generation and CLI behavior.
• Integrated the validator into make agent-check / agent-check-unit, and documented usage (ADR + README).

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
tools/payload_contract_compiler.py	New validator that checks JSON Schema validity, model fixture validation, and PlasticOS domain authority; emits digest/report.
tests/unit/test_payload_contract_compiler.py	Unit tests for report generation, CLI exit code, and presence of expected payload schemas.
Makefile	Adds the validator as a new step in agent-check and agent-check-unit.
docs/adr/ADR-109-ceg-contract-compiler-validator.md	ADR documenting intent/scope and non-goals for the validator.
contracts/payloads/README.md	Documents how to run the validator locally.

[Copilot]

Pull request overview

Copilot reviewed 5 out of 5 changed files in this pull request and generated no new comments.

Suppressed comments (1)

tools/payload_contract_compiler.py:194

• validate_domain_authority() instantiates DomainPackLoader() without an explicit config_path, so the base directory depends on the current working directory and/or DOMAIN_SPECS_PATH. That makes the validator non-deterministic and can cause false FAILs when executed outside the repo root (or in CI with a different env).

    from engine.config.loader import DomainPackLoader

    loader = DomainPackLoader()
    domain = loader.load_domain("plasticos")

[cryptoxdog]

Addressed review: validate_domain_authority() now pins DomainPackLoader(config_path=<repo>/domains) so DOMAIN_SPECS_PATH cannot redirect authority away from in-repo plasticos.

[Copilot]

Pull request overview

Copilot reviewed 5 out of 5 changed files in this pull request and generated no new comments.

Suppressed comments (3)

tools/payload_contract_compiler.py:215

• DomainPackLoader defaults to resolving the "domains" base path relative to the current working directory, while the rest of this tool uses ROOT-relative paths. This can make the validator (and its unit test) fail when invoked from a non-repo-root working directory (common in CI wrappers or ad-hoc invocations). Pass an explicit config_path rooted at this repo to make domain loading deterministic.

    from engine.config.loader import DomainPackLoader

    # Pin to repo domains/ so DOMAIN_SPECS_PATH cannot redirect authority.
    domains_path = ROOT / "domains"

tools/payload_contract_compiler.py:124

• When jsonschema is available, the report only includes check_schema_backend on PASS, but not on FAIL. That makes downstream consumers interpret failures ambiguously (they can’t tell whether the backend was jsonschema vs structural). Set check_schema_backend before the try/except so it’s always present for this path.

        if Draft202012Validator is not None:
            try:
                Draft202012Validator.check_schema(schema)
                entry["check_schema"] = "PASS"
                entry["check_schema_backend"] = "jsonschema"

tools/payload_contract_compiler.py:145

• FORBIDDEN_TRANSPORT_FIELDS is already a frozenset, so converting it to a set on every schema file adds unnecessary work. You can intersect the props set with the frozenset directly.

        transport_hits = sorted(props & set(FORBIDDEN_TRANSPORT_FIELDS))

[Copilot]

Pull request overview

Copilot reviewed 5 out of 5 changed files in this pull request and generated no new comments.

Suppressed comments (3)

Makefile:244

• agent-check is documented as mirroring CI's blocking set, but it now runs the payload contract compiler validator too. This can cause confusion when local make agent-check fails but CI is still green (the current .github/workflows/contracts.yml doesn't run this validator).

agent-check:	## Agent completion gate: CI's blocking set + audit harness, run locally

Makefile:268

• Same as agent-check: agent-check-unit now runs the payload contract compiler validator but the target description still only mentions CI blocking set + audit harness. Keeping these descriptions accurate helps avoid local/CI mismatch confusion.

agent-check-unit:	## Local agent gate (skips Docker integration/perf): CI's blocking set + audit harness, run locally

tools/payload_contract_compiler.py:165

• Deriving the fixture stem via path.name.replace(".json", "") will remove all occurrences of .json in the filename, not just the suffix. Using Path.stem is safer and avoids accidental schema-name mismatches if a fixture name ever contains .json earlier in the string.

    entry["transport_property_hits"] = transport_hits
    entry["status"] = "PASS" if entry["check_schema"] == "PASS" and not hits and not transport_hits else "FAIL"
    return entry

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[Copilot]

Pull request overview

Copilot reviewed 5 out of 5 changed files in this pull request and generated no new comments.

Suppressed comments (2)

tools/payload_contract_compiler.py:145

• ADR-109 describes this tool as performing Draft 2020-12 schema validation, but when jsonschema is unavailable the code falls back to a minimal structural check and still reports check_schema=PASS. That can allow invalid schemas to pass make agent-check silently in environments missing jsonschema, weakening this gate.

def _apply_schema_check(entry: dict[str, Any], schema: dict[str, Any], path: Path) -> None:
    if Draft202012Validator is not None:
        try:
            Draft202012Validator.check_schema(schema)
            entry["check_schema"] = "PASS"
            entry["check_schema_backend"] = "jsonschema"
        except Exception as exc:
            entry["check_schema"] = "FAIL"
            entry["error"] = str(exc)
        return
    errors = _structural_schema_errors(schema, path)
    if errors:
        entry["check_schema"] = "FAIL"
        entry["error"] = "; ".join(errors)
        return
    entry["check_schema"] = "PASS"
    entry["check_schema_backend"] = "structural"

tests/unit/test_payload_contract_compiler.py:45

• This test writes to a fixed path under artifacts/, which can collide if the test suite is executed concurrently (e.g., via pytest-xdist or multiple CI jobs sharing the workspace). Making the filename unique per process avoids intermittent failures.

    report_path = ROOT / "artifacts" / "payload-contract-compiler-cli-test.json"
    try: