Skip to content

feat: port experiment contracts and trial compilation to Go - #2063

Merged
Brad-Edwards merged 9 commits into
go-cutoverfrom
1788-go-experiments-trials
Nov 16, 2026
Merged

Brad-Edwards merged 9 commits into
go-cutoverfrom
1788-go-experiments-trials

Conversation

@Brad-Edwards

@Brad-Edwards Brad-Edwards commented Nov 15, 2026 •

Copy link
Copy Markdown
Collaborator

Summary

Adds native Go experiment validation, deterministic trial compilation and realization, and experiment, study, and trial records for issue #1788. Reference cases check exact plan identities, integrity digests, random draws, replacement lineage, and record publication.

Runtime execution and storage use required shared-owner interfaces. The implementation declares the runtime-owned package for mechanical extraction by #1894; it does not introduce a second engine, store, backend, or worker.

Requirement UIDs

  • (none)

Related Issues

Closes #1788

ADR Impact

  • Preserves ADR-055, ADR-064, ADR-065, ADR-068, ADR-074, ADR-084, and ADR-094 behavior.
  • Applies ADR-021, ADR-117, ADR-121, and ADR-122 ownership and Go architecture checks.
  • FM3 classification and state transitions are recorded in docs/decisions/issue-1788-experiments-design.md.

Changes

  • Admit bounded experiment YAML, constructor projections, participant configuration, and scientific evidence through existing contract owners. Match explicit scalar/tag refusals, allocation control pins, and capture field selectors with recorded Python behavior.
  • Use fixed constructor and binary-path tables with fresh lookup results, named wire types, and shared diagnostic constants. The required single-method interfaces are ControlContextProvider and OwnerCaller.
  • Compile, seal, replay, realize, and replace trial plans with exact authority, apparatus, integrity, random-stream, and work-limit checks.
  • Preserve scoped execution results, interruption and retry recovery, deadline ownership, retirement, immutable publication, and original scientific accounting. Reject foreign journal records before calling their methods.
  • Reuse shared plaintext API snapshot fragments while retaining exact closure and duplicate checks.
  • Run trial and runtime tests in separate bounded Go CI groups, retaining full race and coverage checks and the existing 25-minute job limit. Extend the existing architecture-checksum scanner exception for one design-decision checksum, with regression coverage.
  • Keep published schemas, the Python implementation, and original golden expectations unchanged. Release-please owns changelog and version updates.

Test Plan

  • Targeted unit and reference tests pass
  • Integration tests pass if applicable
  • CI completion checks pass
  • Required coverage checks pass

Local verification passed:

  • 123 distinct targeted Go test functions pass across admission, trial compilation, runtime records, and native SDL. Two targeted shared API and consumer composition tests also pass.
  • Independent source comparisons cover 42 documents and 1,862 semantic refusals, 16 private records and 481 field refusals, 58 factory defaults, 62 binary-coercion inventories, and 73 YAML refusals. Failure tests cover malformed carriers, retained evidence and version conflicts, journal/archive outages, scoped retry proofs, and complete replacement recovery.
  • TestFullValidationGoldenCorpus: 110 selected experiment/trial cases passed. TestCorpus/mcp_experiment_validate: six unchanged command goldens passed, including all three experiment examples.
  • TestModelRulesMatchTheReferenceModels passes with ten additional Python-validated run-plan and capture-selector vectors; all 554 prior vectors are preserved.
  • Three targeted mutations were killed: result-value bounds, cleanup-obligation ownership, and draw-limit ordering before participant callbacks.
  • Changed-package golangci-lint run: zero issues. Actual archcheck: no findings. The nine changed documents and the updated verification note passed nox -s docs-prose -- <paths>. Three targeted Go workflow invariant cases passed. All 38 product packages occur exactly once across the six test groups.
  • pre-commit run, the file-local staged repository policy check, and targeted Ruff checks passed.

Final CI run passes on 9c6b2a9d19a2b94b7f3ef3ee692e137f72e2d104. The Go product coverage gate reports 90.0%. Sonar's quality gate passes with zero new issues, 83.4% new-code coverage, and 0.2% new-code duplication. All race groups and the public and container bootstrap checks pass.

Full test, integration, fuzz, coverage, and mutation suites run in CI only. This PR run did not request the opt-in exhaustive Go mutation sweep. The scanner regression test is marked integration and is left to CI. The source inventory, case mapping, owner-boundary limitations, and defect-case evidence are recorded in docs/decisions/issue-1788-experiments-verification.md and implementations/go/processor/trial/testdata/reference-case-map.json.

Ground Control Checks

  • Repository policy command passes
  • Pre-push code review and test-quality review completed

The automated pre-push review did not produce a verdict after two 20-minute timeouts. The user explicitly directed manual continuation without the Ground Control workflow. This PR makes no completed-review attestation.

Traceability

  • IMPLEMENTS: implementations/go/contract/admission, implementations/go/processor/trial, implementations/go/runtime/experiment, and implementations/tooling/go/arch/api_files.go.
  • TESTS: Native tests beside each owner, implementations/go/processor/trial/testdata/reference-case-map.json, and implementations/tooling/go/arch/api_files_test.go.
  • MOD-001 retains its existing status and statement; its implementation and test links include the exact shared-fragment loader checks.

Checklist

  • Code follows the project coding standards
  • FM level classified: FM3
  • Published contract schemas unchanged
  • PR title is a Conventional Commit
  • Architectural docs updated

Documentation

Updated the experiment design, preflight inventory, verification record, approved validator-key decision, architecture ownership and API declarations, Go architecture guide, and MOD-001 traceability. The verification note follows the repository guide and the doc-tools v0.1.0 documentation skill.

@Brad-Edwards
Brad-Edwards merged commit e039884 into go-cutover Nov 16, 2026
70 of 73 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant