Machine-readable RAES semantic diff and impact analysis (GOV-904)

[Brad-Edwards]

GOV-904 | FUNCTIONAL | SHOULD | Wave 3 | DRAFT

Requirements

• GOV-904

Statement

RAES shall publish machine-readable semantic diff and impact-analysis contracts and APIs over admitted RAES scenarios, modules, tasks, runs, evidence specifications, and studies, preserving canonical identity, provenance, uncertainty, and explicit semantic loss. Presentation and pack-aware orchestration belong to consuming repositories.

Current ownership boundary

• RAES owns the semantic comparison model, impact graph, portable result contract, and reference API.
• env-packs owns pack-aware file selection, migration orchestration, and CLI presentation.
• Hub owns browser/MCP presentation and user-facing comparison journeys.
• Adapters and backends contribute authoritative capability or realization facts; RAES does not infer them.

Required outcome

Define a source-neutral comparison request and result that distinguishes textual, structural, and semantic change and reports affected identities, downstream dependencies, uncertainty, and provenance.

Acceptance criteria

• Results distinguish added, removed, renamed, structurally changed, semantically changed, and unknown/indeterminate cases.
• Comparisons operate over canonical identities rather than file paths alone.
• Impact paths identify the rule or dependency that connects a change to an affected artifact.
• Unresolved references, lossy migrations, and incomparable versions remain explicit.
• The result is deterministic, versioned, machine-readable, and suitable for CLI, browser, and policy consumers.
• Fixtures cover scenarios, modules, tasks, evidence specifications, studies, and external concept bindings.
• No presentation layer is required to use the analysis API.

Non-goals

• Owning a pack-aware filesystem diff.
• Rendering a particular CLI or browser experience.
• Predicting backend behavior without capability or realization evidence.

---

Tracks Ground Control requirement GOV-904.

[Brad-Edwards]

🛠️ Picked up by /implement - driver codex, branch 110-semantic-diff-impact-analysis, 2026-08-01T21:03:56.908Z.

[Brad-Edwards]

gc workflow phase recorded: preflight (issue #110). Posted by the MCP server to enforce ordering between workflow steps (issue #794 MVP-2). Do not edit or delete — used by downstream tools to gate phase prerequisites.

[Brad-Edwards]

gc workflow phase recorded: plan (issue #110). Posted by the MCP server to enforce ordering between workflow steps (issue #794 MVP-2). Do not edit or delete — used by downstream tools to gate phase prerequisites.

Implementation plan

1. Drive the public contract with tests first. Add focused tests for a closed, versioned request/result family and pure processor API. Cover independent identity/textual/structural/semantic axes; added, removed, authoritative rename, changed, unknown, and incomparable outcomes; deterministic ordering and digests; bounded impact traversal; and explicit unresolved, lossy, and exhausted-bound results. Parameterized fixtures will exercise scenario, module, task, run, evidence specification, study, and external-concept-binding coordinates.
2. Publish the portable semantic-comparison contracts. Add raes_contracts.semantic_comparison models for artifact coordinates and owner-projected subjects, exact representation evidence, typed dependency edges, comparison limits/context, independent change relations, explainable impact paths, completeness, diagnostics, and source-neutral request/result envelopes. Reuse ContractModel, digest aliases, DiagnosticModel, RFC 8785 canonical digests, and existing ArtifactTransformationReportModel evidence; reject unknown fields and non-canonical ordering.
3. Implement one pure reference facade. Add raes_processor.semantic_comparison with a deterministic, cycle-safe comparison and reverse-dependency traversal over admitted projections supplied by callers. Renames will be accepted only from a successful digest-bound transformation report; absent/incompatible context will produce explicit typed outcomes. The facade will perform no filesystem, network, environment, subprocess, backend, persistence, logging, or presentation work.
4. Publish schemas and conformance evidence. Register request/result schemas in schema_bundle(), write the hand-governed schemas under contracts/schemas/semantic-comparison/, add valid and invalid conformance fixtures, and add sharded schema-publication ledger entries with content hashes. Keep generated-schema parity exact and expose the new public models/functions through the existing package facades.
5. Verify every issue criterion. Map each acceptance criterion to implementation and test lines, then run targeted tests followed by the configured completion/policy workflow. Required repository checks include tools/check_repo_policy.py, tools/check_requirement_governance.py, tools/verify_all.py, generated-schema parity, publication checks, and fixture conformance. Because the branch contains no UID and the issue has no formal Requirements section, repository gates will run with the issue-tracked GOV-904 identity where required.

Design review

• Security: bounded closed models reject extra fields, unsafe ambient dispatch, unbounded collections, and malformed digests; results contain only coordinates, digests, stable reason codes, bounded diagnostics, and rules—not raw operands, paths, secrets, evidence bodies, or exceptions. Existing artifact admission remains authoritative.
• Maintainability: reuse canonical contract bases, diagnostics, canonical JSON digests, transformation evidence, schema generation, fixtures, and policy tooling. No duplicate validator, registry, graph framework, serializer, error hierarchy, or workflow is introduced.
• Extensibility: artifact kind/profile/version plus owner-projected subjects and dependency rules form the explicit seam. A future artifact adapter or evidence-backed backend-impact profile can be added without changing the result envelope or weakening default source-only semantics.
• Whole-repo impact: changes are limited to raes_contracts, raes_processor, their tests/exports, normative schemas/fixtures/publication records, and the preflight design note. The implementation will preserve authority boundaries, package dependency direction, conformance corpus packaging, generated-schema parity, release ownership, and canonical nox/policy gates.

No new ADR is planned because the preflight found the existing authority, phase-identity, compatibility, and package-ownership decisions sufficient.

[Brad-Edwards]

gc workflow phase recorded: preflight (issue #110). Posted by the MCP server to enforce ordering between workflow steps (issue #794 MVP-2). Do not edit or delete — used by downstream tools to gate phase prerequisites.

[Brad-Edwards]

gc workflow phase recorded: plan (issue #110). Posted by the MCP server to enforce ordering between workflow steps (issue #794 MVP-2). Do not edit or delete — used by downstream tools to gate phase prerequisites.

Revised implementation plan

Bound requirement: GOV-904 (DRAFT, Wave 3).

The GOV-904 architecture preflight supersedes the earlier requirement-free design assumptions. The implementation will:

1. Publish versioned request/result JSON Schemas plus a governed contracts/profiles/semantic-comparison/reference-v1.json comparison profile.
2. Define a closed discriminated union of owner-specific coordinates for normalized scenarios, resolved modules, experiment tasks, runs, evidence capture specifications, studies, and external concept-binding sets. Wire schema version, owner version, lifecycle phase, canonicalization profile, and comparison-profile version remain distinct.
3. Expose trusted adapters over admitted typed RAES models only. Caller-authored generic projections, semantic digests, dependency edges, registries, filesystem paths, and dynamic import hooks are outside the public API.
4. Model identity, exact-representation/textual, structural, and semantic relations independently. Exact-representation evidence applies only to the subject it describes; absent evidence remains unknown.
5. Bind each request to a canonical two-sided impact scope with traversal roots, closure policy/status, artifact coordinates, and scope digest. Partial, redacted, unverified, unresolved, bounded, incomparable, or lossy evidence remains explicitly indeterminate.
6. Compare dependency facts side-by-side so added, removed, unchanged, and changed targets/resolution/provenance are retained, then emit deterministic bounded impact paths naming the authoritative rule and evidence side.
7. Admit raw request JSON only through the repository's bounded, duplicate-rejecting JSON ingress.
8. Cover every admitted owner family with real typed fixtures, verify schema/fixture parity and deterministic output, then run the full repository policy, review, and test-quality gates before publication.

[Brad-Edwards]

gc_codex_review — cycle 1 of 1 (pre-push) on issue #110 (branch 110-semantic-diff-impact-analysis)
Diff mode: inline — the complete diff was supplied in one prompt

Core review

Verdict: don't-ship

The portable request/result boundary, governed profile, digest-bound scope, and pure processor façade are shaped in the intended direction. However, the implementation does not realize the profile’s declared owner-specific structural and semantic projection seam: it substitutes generic canonical model/JSON digests, which collapses owner-defined meaning into serialization equality and forecloses the contract’s promised artifact-specific semantics.

Blocking findings (1):

1. [class] Replace generic digest equality with owner-specific semantic projections — implementations/python/packages/raes_processor/semantic_comparison.py:229
   The root semantic relation is computed from coordinate.canonical_digest, while nested scenario and mapping subjects use canonical digests of their raw serialized payloads. Consequently any serialized-field change is reported as semantic change, regardless of whether that field is semantic for the artifact family; conversely, the implementation has no way to apply owner-defined semantic exclusions or version-pair comparability rules. This conflicts with the published profile’s owner-semantic-projection/v1 and the preflight boundary that semantic comparison is artifact-kind/phase/version-pair specific. Implement trusted per-owner structural and semantic projections (including unsupported-version outcomes) behind the adapter seam before publishing this as a semantic comparator.

Security review

Verdict: ship

This change introduces a closed, digest-bound semantic-comparison contract family and a pure in-process analyzer seam. It keeps portable DTOs separate from artifact-specific projection and comparison logic, constrains caller-selected profiles and limits, and deliberately avoids filesystem, network, subprocess, persistence, and runtime-control-plane access. The design leaves room for new artifact adapters and governed profile versions without widening the trust boundary. I found no concrete, exploitable security regression in the supplied diff.

No blocking findings.

[Brad-Edwards]

gc_codex_review pre-push cycle 1 of 1 complete for issue #110 on branch '110-semantic-diff-impact-analysis'. Posted by the MCP server to enforce the pre-push hard-cap-1 contract (issues #796, #804, #906). Do not edit or delete — used by the next gc_codex_review (uncommitted) invocation to count cycles.

[Brad-Edwards]

Review decision record — codex cycle 1 (issue #110)

Reviewer: codex
Cycle: 1

Architectural read:

Core reviewer: The portable request/result boundary, governed profile, digest-bound scope, and pure processor façade are shaped in the intended direction. However, the implementation does not realize the profile’s declared owner-specific structural and semantic projection seam: it substitutes generic canonical model/JSON digests, which collapses owner-defined meaning into serialization equality and forecloses the contract’s promised artifact-specific semantics.

Security reviewer: This change introduces a closed, digest-bound semantic-comparison contract family and a pure in-process analyzer seam. It keeps portable DTOs separate from artifact-specific projection and comparison logic, constrains caller-selected profiles and limits, and deliberately avoids filesystem, network, subprocess, persistence, and runtime-control-plane access. The design leaves room for new artifact adapters and governed profile versions without widening the trust boundary. I found no concrete, exploitable security regression in the supplied diff.

Blocking findings: 1

Finding 1 — class (3 instances)

• ID: F1
• Title: [core] Replace generic digest equality with owner-specific semantic projections
• Location: implementations/python/packages/raes_processor/semantic_comparison.py:229
• Decision: fix
• Rationale: The root semantic relation is computed from coordinate.canonical_digest, while nested scenario and mapping subjects use canonical digests of their raw serialized payloads. Consequently any serialized-field change is reported as semantic …
• Instances:
  • implementations/python/packages/raes_processor/semantic_comparison.py:229
  • implementations/python/packages/raes_processor/semantic_comparison.py:268
  • implementations/python/packages/raes_processor/semantic_comparison.py:277

[Brad-Edwards]

gc_test_quality_review cycle 1 of 1 — issue #110

Reviewer: test-quality (claude-sonnet-5 via gc_test_quality_review)
Branch: 110-semantic-diff-impact-analysis
Cycle: 1 / 1
Findings: 1

Finding 1 — [critical] implementations/python/tests/test_semantic_comparison.py::test_published_schemas_and_fixtures_validate

Problem: The diff adds two invalid/ fixtures (contracts/fixtures/semantic-comparison/semantic-comparison-request-v1/invalid/filesystem-path-coordinate.json, proving canonical_identity rejects filesystem-path-shaped strings, and semantic-comparison-result-v1/invalid/path-without-edges.json, proving ImpactPathModel rejects a path with zero steps) but no test in the suite ever loads either file. test_published_schemas_and_fixtures_validate only globs the valid/ subdirectories of each fixture family; the invalid/ directories are never referenced anywhere in the repo outside the fixture files themselves.
Why it matters: If the identity pattern in semantic_comparison.py (_IDENTITY_PATTERN, which is what makes '/tmp/input.yaml'-style paths illegal) were loosened or dropped, or if ImpactPathModel's min_length=1 constraint on steps were removed, no test would fail — the fixtures built specifically to catch those regressions sit on disk unexercised, giving false confidence that this input-validation surface is covered.
Fix: Extend test_published_schemas_and_fixtures_validate (or add a sibling test) to also walk the invalid/ subdirectories and assert rejection, mirroring test_artifact_transformations.py::test_transformation_report_positive_and_negative_fixtures: for each fixture under semantic-comparison-request-v1/invalid and semantic-comparison-result-v1/invalid, assert the JSON-schema validator reports errors (e.g. assert Draft202012Validator(request_schema).is_valid(payload) is False) and, where the fixture is close enough to a real payload to reach model validation, that SemanticComparisonRequestModel/SemanticComparisonResultModel.model_validate raises. Note the two current fixtures are stale relative to the shipped contract shape (missing comparison_profile_digest/impact_scope on the request fixture, and using a field named 'edges' instead of the model's 'steps' on the result fixture) — those will need updating to the current wire shape before they can be wired in, otherwise they'll reject for the wrong (structural/extra-field) reasons rather than the identity-pattern/path-shape reason they're meant to prove.