From 3f72b9b96846fbc6f1a9551a56f563c85a0cbd2e Mon Sep 17 00:00:00 2001 From: Brad Edwards Date: Thu, 5 Nov 2026 04:53:01 +0100 Subject: [PATCH 1/2] chore: bootstrap runtime repository controls --- .gc/plan-rules.md | 11 + .github/CODEOWNERS | 1 + .github/workflows/ci.yml | 106 ++++++ .github/workflows/ground-control-phase-e.yml | 71 ++++ .gitignore | 3 + .ground-control.yaml | 44 +++ .mcp.json | 11 + .vale.ini | 10 + AGENTS.md | 12 + CONTRIBUTING.md | 27 ++ Makefile | 74 ++++ README.md | 14 +- THIRD_PARTY_NOTICES.md | 10 + docs/architecture.md | 58 ++++ .../adrs/adr-121-go-engineering-standards.md | 319 ++++++++++++++++++ .../adrs/adr-122-go-architecture-model.md | 232 +++++++++++++ .../issue-1891-runtime-repository-boundary.md | 258 ++++++++++++++ docs/source-manifest.json | 102 ++++++ implementations/.golangci.yml | 149 ++++++++ implementations/.gremlins.yaml | 10 + implementations/architecture.json | 47 +++ implementations/go/doc.go | 3 + implementations/go/go.mod | 3 + styles/RAES/AvoidDismissive.yml | 6 + styles/RAES/AvoidHype.yml | 6 + styles/RAES/HeadingCase.yml | 27 ++ styles/RAES/HeadingPunctuation.yml | 7 + styles/RAES/PlainWords.yml | 15 + styles/RAES/ReadingLevel.yml | 6 + styles/RAES/SentenceLength.yml | 6 + styles/config/vocabularies/RAES/accept.txt | 26 ++ tools/design-acceptance.sh | 31 ++ 32 files changed, 1704 insertions(+), 1 deletion(-) create mode 100644 .gc/plan-rules.md create mode 100644 .github/CODEOWNERS create mode 100644 .github/workflows/ci.yml create mode 100644 .github/workflows/ground-control-phase-e.yml create mode 100644 .ground-control.yaml create mode 100644 .mcp.json create mode 100644 .vale.ini create mode 100644 AGENTS.md create mode 100644 CONTRIBUTING.md create mode 100644 Makefile create mode 100644 THIRD_PARTY_NOTICES.md create mode 100644 docs/architecture.md create mode 100644 docs/decisions/adrs/adr-121-go-engineering-standards.md create mode 100644 docs/decisions/adrs/adr-122-go-architecture-model.md create mode 100644 docs/decisions/issue-1891-runtime-repository-boundary.md create mode 100644 docs/source-manifest.json create mode 100644 implementations/.golangci.yml create mode 100644 implementations/.gremlins.yaml create mode 100644 implementations/architecture.json create mode 100644 implementations/go/doc.go create mode 100644 implementations/go/go.mod create mode 100644 styles/RAES/AvoidDismissive.yml create mode 100644 styles/RAES/AvoidHype.yml create mode 100644 styles/RAES/HeadingCase.yml create mode 100644 styles/RAES/HeadingPunctuation.yml create mode 100644 styles/RAES/PlainWords.yml create mode 100644 styles/RAES/ReadingLevel.yml create mode 100644 styles/RAES/SentenceLength.yml create mode 100644 styles/config/vocabularies/RAES/accept.txt create mode 100644 tools/design-acceptance.sh diff --git a/.gc/plan-rules.md b/.gc/plan-rules.md new file mode 100644 index 0000000..3d8f14b --- /dev/null +++ b/.gc/plan-rules.md @@ -0,0 +1,11 @@ +# Runtime plan rules + +- Follow the existing RAE runtime split boundary and its public API commitments. Do not add features during extraction. +- Keep canonical SDL, processor, contract, backend and shared primitive authority in OpenRAE/rae. Runtime consumes its public APIs. +- Name the owning module and public interface for changed code. Update implementations/architecture.json before changing package boundaries. +- Keep requirement and source links against immutable OpenRAE/rae revisions. Do not copy the canonical requirements or published schemas. +- Run targeted tests locally with explicit PACKAGE and TEST selections. Full, integration, fuzz and mutation suites run in CI only. +- Preserve the Go engineering, architecture, security, regression and mutation checks of ADR-121 and ADR-122. +- Keep build/test jobs read-only and credential-free. Do not copy SDL publishing credentials, Ground Control project IDs or SonarCloud identities. +- Keep normal publication disabled until OpenRAE/rae#1804. Do not add services or publication destinations. +- Preserve source licences, notices, authorship and published evidence. Never rewrite or force-push source history. diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS new file mode 100644 index 0000000..4c5ff82 --- /dev/null +++ b/.github/CODEOWNERS @@ -0,0 +1 @@ +* @Brad-Edwards diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml new file mode 100644 index 0000000..041eb8b --- /dev/null +++ b/.github/workflows/ci.yml @@ -0,0 +1,106 @@ +name: CI + +on: + pull_request: + branches: [dev, main] + types: [opened, synchronize, reopened, edited] + push: + branches: [dev, main] + workflow_dispatch: + inputs: + mutations: + description: Run the existing mutation diagnostics + type: boolean + default: false + +permissions: + contents: read + +concurrency: + group: ci-${{ github.event.pull_request.number || github.ref }} + cancel-in-progress: true + +jobs: + verify: + runs-on: ubuntu-24.04 + timeout-minutes: 25 + steps: + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7 + with: + fetch-depth: 0 + persist-credentials: false + - name: Install the admitted Go toolchain + # Same version and archive digest as RAE's admitted artifact lock. + run: | + curl --fail --location --output "$RUNNER_TEMP/go.tar.gz" https://dl.google.com/go/go1.27.3.linux-amd64.tar.gz + echo "65efbc80fdc1fa2cd2631cad5b481777a68e8725f34e89f50fc6ac714e379b40 $RUNNER_TEMP/go.tar.gz" | sha256sum --check --strict + tar -xzf "$RUNNER_TEMP/go.tar.gz" -C "$RUNNER_TEMP" + echo "$RUNNER_TEMP/go/bin" >> "$GITHUB_PATH" + - name: Build pinned checks + run: make tools + - name: Install the admitted prose checker + run: | + curl --fail --location --output "$RUNNER_TEMP/vale.tar.gz" https://github.com/vale-cli/vale/releases/download/v3.15.2/vale_3.15.2_Linux_64-bit.tar.gz + echo "fc72e64454d6bd7af91905d4faebbf411bae3eec17bb572f4101311212bc0d9e $RUNNER_TEMP/vale.tar.gz" | sha256sum --check --strict + tar -xzf "$RUNNER_TEMP/vale.tar.gz" -C .tools/bin vale + - name: Compile, lint, and check architecture and source provenance + run: make check VALE=.tools/bin/vale + - name: Scan for secrets + run: .tools/bin/gitleaks git --redact --no-banner + - name: Run race tests and coverage + run: make test-ci + - name: Resolve the comparison base + id: base + env: + PR_BASE: ${{ github.event.pull_request.base.sha }} + PUSH_BASE: ${{ github.event.before }} + run: | + base="${PR_BASE:-$PUSH_BASE}" + if ! git cat-file -e "${base}^{commit}" 2>/dev/null; then + base=$(git rev-parse HEAD^) + fi + echo "sha=$(git merge-base "$base" HEAD)" >> "$GITHUB_OUTPUT" + - name: Check new regression tests against the base + env: + BASE: ${{ steps.base.outputs.sha }} + run: make regression + - name: Run each fuzz target for a bounded time + working-directory: implementations/go + run: | + set -o pipefail + go test -list '^Fuzz' ./... | + awk '/^Fuzz/ { targets[++n] = $1 } /^ok/ { for (i = 1; i <= n; i++) print $2, targets[i]; n = 0 }' | + while read -r package target; do + go test -run '^$' -fuzz "^${target}\$" -fuzztime 20s "$package" + done + - name: Run mutation diagnostics + if: ${{ github.event_name == 'workflow_dispatch' && inputs.mutations }} + env: + BASE: ${{ steps.base.outputs.sha }} + run: make mutation + + title-guard: + if: github.event_name == 'pull_request' + runs-on: ubuntu-24.04 + steps: + - name: Require a Conventional Commit title + env: + TITLE: ${{ github.event.pull_request.title }} + run: | + printf '%s\n' "$TITLE" | grep -Eq '^(feat|fix|perf|docs|chore|refactor|test|ci|build|style|revert)(\([[:alnum:]_./-]+\))?!?: .+' + if printf '%s\n' "$TITLE" | grep -Eiq '\[(codex|claude|openai)\]|generated.by|co.authored.by'; then + echo 'Use repository metadata without assistant attribution.' >&2 + exit 1 + fi + + body-guard: + if: github.event_name == 'pull_request' + runs-on: ubuntu-24.04 + steps: + - name: Require the issue, change and verification + env: + BODY: ${{ github.event.pull_request.body }} + run: | + printf '%s\n' "$BODY" | grep -Eq '(#[0-9]+|github.com/OpenRAE/(runtime|rae)/issues/[0-9]+)' + printf '%s\n' "$BODY" | grep -Eq '^## (Change|Summary)' + printf '%s\n' "$BODY" | grep -Eq '^## (Verification|Test plan)' diff --git a/.github/workflows/ground-control-phase-e.yml b/.github/workflows/ground-control-phase-e.yml new file mode 100644 index 0000000..4c823cd --- /dev/null +++ b/.github/workflows/ground-control-phase-e.yml @@ -0,0 +1,71 @@ +name: Ground Control Phase E +# Carries the pull request into the run record, so a dispatch run — which has no +# `pull_requests` association — is still bound to what it finalized (issue #1671). +run-name: Ground Control Phase E for PR ${{ github.event.pull_request.number || inputs.pr }} + +# A merged Ground Control delivery pull request finishes Phase E here, with no model or +# agent session. The agent records a trusted delivery-readiness handoff at Phase D and may +# then terminate permanently; this job is a trigger and a transport. +# +# It holds no `gh` logic, no marker parser, and no completion reconstruction. It passes the +# event's pull-request number to `grndctl finalize-merged-pr`, which resolves the issue from +# the trusted pointer and replays the recorded payload through the incumbent finalizer — so +# the merge gate, the immutable merged-revision requirement verification, the final-report +# marker, and the idempotent close all still apply, unchanged. +# +# It runs no tests, no policy suite, and no review, and it waits for no other post-merge job. +# +# Written by `grndctl init`. The pinned version below is the grndctl that wrote it; bump it +# deliberately rather than tracking a moving tag. + +on: + pull_request: + types: [closed] + branches: [main, dev] + workflow_dispatch: + inputs: + pr: + description: Pull request number to finalize (maintainer repair path) + required: true + type: string + +concurrency: + # Serialize per pull request so a replay cannot race itself. Never cancel: a cancelled + # finalization leaves neither a final report nor a failure record. + group: gc-phase-e-${{ github.event.pull_request.number || inputs.pr }} + cancel-in-progress: false + +permissions: + contents: read + pull-requests: read + # The close gate verifies this job's own run through the Actions API before it accepts an + # automation-authored final-report marker. + actions: read + issues: read + +jobs: + finalize: + if: ${{ github.event_name == 'workflow_dispatch' || github.event.pull_request.merged == true }} + runs-on: ubuntu-latest + permissions: + contents: read + pull-requests: read + actions: read + issues: write + steps: + # The immutable merge revision, never the pull-request head. Phase E reads requirement + # state from the merged tree and executes none of the delivered code; `fetch-depth: 0` + # brings every branch, so the merge commit is present on the dispatch path too. + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v4 + with: + ref: ${{ github.event.pull_request.merge_commit_sha || github.sha }} + fetch-depth: 0 + persist-credentials: false + - uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0 + with: + node-version: 22 + - name: Finalize the merged delivery + env: + GH_TOKEN: ${{ github.token }} + PR: ${{ github.event.pull_request.number || inputs.pr }} + run: npx --yes grndctl@1.8.1 finalize-merged-pr --pr "$PR" diff --git a/.gitignore b/.gitignore index a5bd233..a259c30 100644 --- a/.gitignore +++ b/.gitignore @@ -31,3 +31,6 @@ go.work.sum # Editor/IDE # .idea/ # .vscode/ + +# Local tools and build products +.tools/ diff --git a/.ground-control.yaml b/.ground-control.yaml new file mode 100644 index 0000000..80c4e1c --- /dev/null +++ b/.ground-control.yaml @@ -0,0 +1,44 @@ +schema_version: 2 +project: runtime +github_repo: OpenRAE/runtime +workflow: + base_branch: dev + test_command: make test + completion_command: make check + lint_command: make lint + format_command: make format + policy_command: make policy + precommit_command: make precommit + codex_review: + pre_push_cap: 1 + design: + compile_command: make build + structural_command: make architecture + wiring_command: make wiring + acceptance_command: bash tools/design-acceptance.sh +rules: + plan_rules: .gc/plan-rules.md +docs: + adr_dir: docs/decisions/adrs + architecture_overview: docs/architecture.md + coding_standards: docs/decisions/adrs/adr-121-go-engineering-standards.md + workflow_reference: CONTRIBUTING.md +example_paths: + source: implementations/go + test: implementations/go +architecture: + modules: + - path: . + implementations: + - Makefile + - implementations/architecture.json + adrs: + - docs/decisions/adrs/adr-121-go-engineering-standards.md + - docs/decisions/adrs/adr-122-go-architecture-model.md + - path: implementations/go + implementations: + - implementations/go/doc.go + - implementations/go/go.mod + adrs: + - docs/decisions/adrs/adr-121-go-engineering-standards.md + - docs/decisions/adrs/adr-122-go-architecture-model.md diff --git a/.mcp.json b/.mcp.json new file mode 100644 index 0000000..5a6aa31 --- /dev/null +++ b/.mcp.json @@ -0,0 +1,11 @@ +{ + "mcpServers": { + "ground-control": { + "type": "stdio", + "command": "grndctl", + "args": [ + "mcp" + ] + } + } +} diff --git a/.vale.ini b/.vale.ini new file mode 100644 index 0000000..b13ce89 --- /dev/null +++ b/.vale.ini @@ -0,0 +1,10 @@ +StylesPath = styles +MinAlertLevel = error +Vocab = RAES + +[*.{md,rst}] +BasedOnStyles = RAES +Vale.Spelling = NO +Vale.Terms = NO +Vale.Avoid = NO +Vale.Repetition = error diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..dc91470 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,12 @@ +# Runtime agent rules + +Use `.ground-control.yaml` through `gc_get_repo_ground_control_context` before implementation. +The Ground Control project is `runtime`; this repository is `OpenRAE/runtime`. +Start the agent and `grndctl mcp` from this checkout, so repository authorization matches. + +Read `CONTRIBUTING.md`, `docs/architecture.md`, and `.gc/plan-rules.md`. +The accepted split documents govern the design. Do not add to the design during repository setup or extraction. +Run targeted tests locally. Full, integration, fuzz and mutation suites run in CI only. +Keep secrets in ignored local configuration. Never copy credentials from the SDL repository. +Do not publish runtime artifacts before OpenRAE/rae#1804. +Use native issue/feature branch names and Conventional Commit PR titles. Merge requires maintainer approval. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..45ca0f3 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,27 @@ +# Contribute + +Use Go 1.27.3, the toolchain admitted by OpenRAE/rae. +Pull requests target the protected `dev` integration branch. +Link each pull request to its issue and the applicable canonical RAE requirements. +Use a Conventional Commit title and explain the change and verification. +`@Brad-Edwards` owns repository and security decisions. + +Install Vale 3.15.2 for the existing prose rules. +Run `make tools` once to build the pinned checks. +Run `make check` for compilation, lint, architecture and module checks. +Run selected tests with `make test PACKAGE=./path/to/package TEST=TestName`. +The bootstrap has no runtime implementation or behavior tests yet. +CI owns the full race, coverage, regression, fuzz and mutation runs. +The 90% statement coverage floor applies when executable statements exist. + +Follow the unchanged [Go standards](docs/decisions/adrs/adr-121-go-engineering-standards.md) +and [architecture rules](docs/decisions/adrs/adr-122-go-architecture-model.md). +Runtime consumes public RAE APIs; it does not copy their semantic implementation. +The existing split is described in [the architecture reference](docs/architecture.md). + +Run `grndctl doctor` from this checkout to check Ground Control setup. +`.mcp.json` starts the installed `grndctl mcp` here. +Credentials stay in ignored `.env`; the bootstrap needs no publishing credentials. +SonarCloud must use a runtime-specific project before runtime source is imported. +No SDL project or token is copied by this bootstrap. +Normal publication remains disabled until OpenRAE/rae#1804. diff --git a/Makefile b/Makefile new file mode 100644 index 0000000..ed0a7bb --- /dev/null +++ b/Makefile @@ -0,0 +1,74 @@ +# Reuse the existing RAE checks at an immutable source revision. +GO ?= go +VALE ?= vale +RAE_VERSION := v0.0.0-20261104214245-9b3146bf4d8a +RAE_TOOLS := github.com/OpenRAE/rae/implementations/tooling/go +TOOLS_BIN := $(CURDIR)/.tools/bin +export GOTOOLCHAIN := local +export GOWORK := off +export GOFLAGS := -mod=readonly + +.PHONY: tools check build lint format architecture wiring policy precommit test test-ci regression mutation design-acceptance docs + +tools: + mkdir -p "$(TOOLS_BIN)" + $(GO) mod download -json $(RAE_TOOLS)@$(RAE_VERSION) > .tools/rae-module.json + $(GO) -C "$$(jq -er .Dir .tools/rae-module.json)" build -o "$(TOOLS_BIN)/" ./cmd/archcheck ./cmd/raesvet ./cmd/regressiontest github.com/golangci/golangci-lint/v2/cmd/golangci-lint + GOBIN="$(TOOLS_BIN)" $(GO) install github.com/zricethezav/gitleaks/v8@v8.30.1 + +build: + $(GO) -C implementations/go build ./... + +lint: + cd implementations/go && "$(TOOLS_BIN)/golangci-lint" run ./... + $(GO) -C implementations/go vet -vettool="$(TOOLS_BIN)/raesvet" ./... + +format: + cd implementations/go && "$(TOOLS_BIN)/golangci-lint" fmt ./... + +architecture: + "$(TOOLS_BIN)/archcheck" + +wiring: + "$(TOOLS_BIN)/archcheck" -view + +policy: architecture + git diff --check + jq -r '.files[] | "\(.sha256) \(.destination_path)"' docs/source-manifest.json | sha256sum --check --strict + +docs: + $(VALE) README.md AGENTS.md CONTRIBUTING.md THIRD_PARTY_NOTICES.md .gc/plan-rules.md docs/architecture.md + +check: build lint policy docs + $(GO) -C implementations/go mod tidy -diff + $(GO) -C implementations/go mod verify + +precommit: policy + "$(TOOLS_BIN)/gitleaks" git --staged --redact --no-banner + +# Local test runs always name the relevant package and case. +test: + @test -n "$(PACKAGE)" -a -n "$(TEST)" || { echo 'Set PACKAGE and TEST for a targeted test run.' >&2; exit 2; } + $(GO) -C implementations/go test -race -run '$(TEST)' '$(PACKAGE)' + +# CI only: preserve race detection and the existing 90% statement floor. +test-ci: + @test "$$CI" = true || { echo 'Full tests run in CI only.' >&2; exit 2; } + mkdir -p .tools + $(GO) -C implementations/go test -race -covermode=atomic -coverprofile="$(CURDIR)/.tools/cover.out" ./... + @if test "$$(wc -l < .tools/cover.out)" -gt 1; then \ + $(GO) tool cover -func=.tools/cover.out | awk '/^total:/ { sub(/%/, "", $$3); found=1; if ($$3 < 90) exit 1 } END { if (!found) exit 1 }'; \ + else echo 'No executable statements in the bootstrap package.'; fi + +regression: + @test -n "$(BASE)" || { echo 'Set BASE to the comparison commit.' >&2; exit 2; } + cd implementations/go && "$(TOOLS_BIN)/regressiontest" -base "$(BASE)" + +mutation: + @test "$$CI" = true || { echo 'Mutation runs are CI only.' >&2; exit 2; } + @test -n "$(BASE)" || { echo 'Set BASE to the comparison commit.' >&2; exit 2; } + $(GO) -C "$$(jq -er .Dir .tools/rae-module.json)" build -o "$(TOOLS_BIN)/gremlins" github.com/go-gremlins/gremlins/cmd/gremlins + cd implementations/go && "$(TOOLS_BIN)/gremlins" unleash --workers 2 --config ../.gremlins.yaml --diff "$(BASE)" + +design-acceptance: + @bash tools/design-acceptance.sh diff --git a/README.md b/README.md index 9b4fa41..cf8d533 100644 --- a/README.md +++ b/README.md @@ -1,2 +1,14 @@ -# runtime +# Runtime + Conformant reference runtime for controlling OpenRÆ scenarios and backends. + +This repository will receive the existing Go runtime. +It will own execution, the control plane and HTTP API, stores, workers, and the combined `raes` executable. +SDL, processor, contract and portable backend APIs stay in [OpenRAE/rae](https://github.com/OpenRAE/rae). +The split keeps the same behavior. + +See [the architecture reference](docs/architecture.md), [contribution guide](CONTRIBUTING.md), +and [bootstrap issue](https://github.com/OpenRAE/rae/issues/1893). +The Go module is `github.com/OpenRAE/runtime/implementations/go`. +No runtime implementation is imported yet. +Releases stay off until the [coordinated Go launch](https://github.com/OpenRAE/rae/issues/1804). diff --git a/THIRD_PARTY_NOTICES.md b/THIRD_PARTY_NOTICES.md new file mode 100644 index 0000000..3824ff6 --- /dev/null +++ b/THIRD_PARTY_NOTICES.md @@ -0,0 +1,10 @@ +# Third-party notices + +This setup has no runtime code or third-party product dependency. +Copied RAE files are listed in `docs/source-manifest.json`. +They come from OpenRAE/rae under its MIT licence. +`LICENSE` keeps copyright (c) 2026 OpenRÆ. +Development tools keep their upstream licences. +They are not shipped as runtime artifacts. +The source import must retain its licence, notices and author records. +Its manifest must name each source path and commit. diff --git a/docs/architecture.md b/docs/architecture.md new file mode 100644 index 0000000..d7092b1 --- /dev/null +++ b/docs/architecture.md @@ -0,0 +1,58 @@ +# Runtime architecture reference + +The existing [runtime split decision](decisions/issue-1891-runtime-repository-boundary.md) +is the design authority for this repository. +The working name was `OpenRAE/rae-runtime`. +The existing public repository is `OpenRAE/runtime`. +The imported decision and ADRs are unchanged snapshots from RAE commit `9b3146bf4d8a478db3c6b273b1ed90952a239752`. +Their relative links refer to RAE. +Read linked files at that commit in OpenRAE/rae. +SDL and contract authority stay in RAE. + +The bootstrap declares only the Go module and an empty package. +It adds no runtime feature or public API. +Schema, storage and security behavior stay the same. +Runtime may consume the released public SDL, processor, contract and portable backend APIs. +RAE product modules must not depend on runtime. +The [public API issue](https://github.com/OpenRAE/rae/issues/1825) owns the exact import and composition interfaces. +The existing checker checks `implementations/architecture.json` against the code and these docs. +Build and test jobs can only read the repository. +They have no publishing credentials. + +The [bootstrap source manifest](source-manifest.json) pins reused setup artifacts. +[Issue #1894](https://github.com/OpenRAE/rae/issues/1894) owns the completed runtime import and its source manifest. +Before the move, freeze the completed Go commit. +List each source path and blob in a new manifest. +Use the accepted split decision's local rehearsal and transfer procedure. +Keep the original extraction inventory and published evidence immutable in RAE. +Import the original bytes first. +Record module and import edits in a separate commit. +Keep the licence, notices and author records. +Never rewrite the source history. +Normal publication stays disabled until OpenRAE/rae#1804. + + + + + +| Layer | Status | Allowed dependencies | +| --- | --- | --- | +| `runtime` | implemented packages | | + +```mermaid +flowchart BT + L0["runtime"] +``` + +| Package owner | Layer | Cross-layer visibility | Consumer importable | Actual dependencies | +| --- | --- | --- | --- | --- | +| `implementations/go` | runtime | false | true | | + +| Trust-view evidence | SHA-256 | +| --- | --- | +| `docs/decisions/adrs/adr-121-go-engineering-standards.md` | `49217f20d43a33c553797580f6cbc16fb4784e4f0ad207507c7f5dafafcaaae1` | +| `docs/decisions/adrs/adr-122-go-architecture-model.md` | `bb34edd9eb80bb56645ef57f4f48eb3113ac02e95b7af696f32de3bdb8d11fa6` | +| `docs/decisions/issue-1891-runtime-repository-boundary.md` | `e8233ecdf836dbbad4dda9ef373572dd466f1cf59ad0eeb4ab01cc9fd476e406` | + + + diff --git a/docs/decisions/adrs/adr-121-go-engineering-standards.md b/docs/decisions/adrs/adr-121-go-engineering-standards.md new file mode 100644 index 0000000..49e79e2 --- /dev/null +++ b/docs/decisions/adrs/adr-121-go-engineering-standards.md @@ -0,0 +1,319 @@ +# ADR-121: Go Engineering Standards + +## Status + +accepted + +## Date + +2026-10-31 + +## Classification + +Classification: FM0 +Required artifacts: unit tests (the analyzers under `implementations/tooling/go/lint` and the command `implementations/tooling/go/cmd/regressiontest`), CI lanes (`.github/workflows/canonical-verification.yml` job `go`) +Waivers: none + +The decision sets code standards and their checks. It adds no SDL, contract, or +runtime semantics. + +## Context + +Milestone 74 ports the codebase to Go and replaces the Python implementation in +one hard cutover. The Go code must follow the Google Go Style Guide to the +extent that a tool can check it deterministically. It must also pass strict +linting and mutation testing, and meet the repository standards that do not +depend on Python. + +Google publishes its Go style guide as three documents. The +[Style Guide](https://google.github.io/styleguide/go/guide) and +[Style Decisions](https://google.github.io/styleguide/go/decisions) are +normative. [Best Practices](https://google.github.io/styleguide/go/best-practices) +is advisory. + +These current standards are specific to Python: + +- ruff; +- the ADR-015 cap on file length; +- the ADR-117 ratchets; +- Coverage.py under ADR-103; +- the ADR-116 exception classes; +- the nox graph of ADR-014. + +ADR-106 admits the Go toolchain and the Go tool module (issue #1773 amendment). + +## Decision + +### 1. Scope + +These standards apply to each Go module under `implementations/`. Today that is +the Go tool module `implementations/tooling/go`. Each new Go module joins the +CI matrix of the `go` job. + +### 2. Formatting and strict linting + +`gofmt` and `goimports` format all Go code. golangci-lint runs with +`implementations/.golangci.yml`, which enables all linters except a listed set. +Each disabled linter has a stated reason: it conflicts with Google Go style or +with a published contract, or an enabled check covers it. Any finding fails CI. + +A `//nolint` directive must name the linter and state why the finding is false. +`nolintlint` checks the form. Review checks that the finding is false. An +exclusion in the configuration needs the same reason. + +### 3. Google Go style + +The [rule map](#appendix-google-go-style-rule-map) lists each rule of the three +documents. For each rule, it names the check that enforces the rule, or it +states why no deterministic check is possible. Such rules are review rules. + +A published contract takes precedence over a style rule. For example, the +command and flag names of `raes` keep their published form. + +### 4. Repository analyzers + +Three `go/analysis` analyzers in `implementations/tooling/go/lint` check the +deterministic rules that no golangci-lint linter checks: + +- `gotwant`: a test failure message prints the actual value before the wanted value. +- `getprefix`: a function or method name does not start with a Get prefix. +- `wrapverb`: `fmt.Errorf` places `%w` at the start or the end of the format. + +`raesvet` combines them. CI runs `go vet -vettool=raesvet` on each module. + +### 5. Contract-based development + +The Go code uses these idiomatic forms of contract-based development: + +1. The published schemas stay the authority. Go types for a published contract + follow from its schema. +2. A type with invariants keeps its fields unexported. Its constructor checks + the invariants and returns an error. Its methods rely on the invariants. +3. Input from outside the process is checked once, at the boundary where it + enters. Validated types then carry it. +4. Interfaces are small, and their consumers define them. When an interface has + more than one implementation, its owner provides an exported test suite that + each implementation passes, as `testing/fstest.TestFS` does. +5. A function returns an error for bad input. It panics only when an internal + invariant is broken. +6. Fuzz tests check the round trips and invariants of parsers and encoders. + +### 6. Errors, logging, time, and randomness + +- An error is the last result. Error strings start in lower case and have no + final punctuation. +- A caller classifies a failure with `errors.Is` or `errors.As`. The six + ADR-116 categories stay: invalid input, conflict, not found, authorization, + operational, and evidence integrity. +- Code logs with `log/slog`. Library code never configures logging. Messages + are constant, and records carry no input values. +- The behavior of ADR-116 that consumers see stays. The `raes` command exits + with status 70 after an unexpected failure. An MCP tool result never contains + the text of an unexpected error. +- Code reads the time from an injected clock (ADR-118), so `time.Now` is + forbidden outside the clock owner. Randomness comes from `crypto/rand` or from + the governed random streams, so `math/rand` is forbidden. + +### 7. Tests + +- Tests sit beside the code in `_test.go` files. They use the `testing` package, + and `github.com/google/go-cmp` for comparisons. Assertion libraries are not + allowed. +- CI runs the tests with the race detector. +- The statement coverage of each module is at least 90%, the ADR-103 floor. +- Exhaustive mutation testing runs separately from normal PR admission. The + scheduled workflow and automatic failure issues are delivered by issue #1898. + The canonical graph keeps an explicit, default-off mutation diagnostic input; + normal PR and protected-push CI do not enable it. Normal Go jobs have a + 25-minute limit and retain tests, race detection, coverage, lint, analyzers, + contract checks and regression checks. A timeout is a failure. +- Each tested mutant must be killed or time out, so test efficacy and mutant + coverage remain 100%. `implementations/.gremlins.yaml` holds the thresholds, + because gremlins ignores a threshold flag of its command line. Incomplete + mutation runs do not establish a passing result. Mutation testing runs in CI + only, except for targeted replay of specific captured findings. +- A condition goes in an `if` statement, not in the expression of a `case` + clause. The coverage profile records no block for a `case` expression, so + gremlins cannot test its mutants. +- A regression test is a test function whose name starts with `TestRegression`, + in a file whose name ends with `_regression_test.go`. That file holds the + helpers that its tests need, and its fixtures are in testdata. Each new + regression test must build and fail at the merge base, and the + `regressiontest` command checks it. In the base run, the package keeps none of + its base test files or testdata. It gets the regression test files and the + testdata of the head commit. +- Full test, mutation, and fuzz suites run in CI only. Local runs stay targeted. + +### 8. Dependencies + +Code uses the standard library first. The ADR-122 architecture model lists the +external import paths that each layer may import, each with a reason. The +golangci-lint `depguard` rule denies the standard library packages that section +6 replaces. ADR-106 governs how the module digests are admitted. + +### 9. Standards that change and standards that stay + +| Python standard | Go standard | +| --- | --- | +| ruff format and check | `gofmt`, `goimports`, golangci-lint, and the repository analyzers | +| ADR-015 cap on file length | No cap. `gocognit` limits complexity to 15, and ADR-122 governs structure. | +| ADR-117 ratchets | ADR-122 architecture model and the Go compiler rules | +| ADR-103 coverage with Coverage.py | 90% statement coverage of each Go module | +| ADR-116 exception classes | Section 6 | +| ADR-014 nox lanes | The `go` job of the canonical graph until issue #1801 | + +These standards stay and apply to the Go code: + +- the documentation style guide, Vale, and ASD-STE100 prose; +- ADRs and their pins; +- requirement traceability; +- contract governance under ADR-009 and ADR-061; +- pull request title and body guards; +- secret, vulnerability, and code scanning; +- artifact admission under ADR-106 and ADR-107; +- the SonarCloud quality gate; +- the assurance levels of ADR-007 and ADR-018. + +## Alternatives Considered + +- **go-mutesting for mutation testing.** It has no mode for changed lines. + Gremlins has one. +- **A golangci-lint plugin for the repository analyzers.** A plugin needs a + custom golangci-lint build. `go vet -vettool` is the standard Go mechanism. +- **Enable only a selected set of linters.** New linters would then stay off. + Enabling all linters and disabling each one with a reason is stricter. +- **A cap on Go file length.** Google Go style sets no length limit. Complexity + limits and the architecture model control structure. + +## Consequences + +- Each Go module meets the same checks from its first line of code. +- A style rule that a tool cannot check stays a review rule, and the rule map + says so. +- Mutation testing and tool builds add CI time. + +## Appendix: Google Go style rule map + +"Review" means that no deterministic check is possible, because the rule needs +judgment about meaning or context. + +### Style Guide + +| Rule | Check | +| --- | --- | +| Style principles: clarity, simplicity, least mechanism, concision, maintainability, consistency | Review | +| Formatting | `gofmt` | +| MixedCaps | revive `var-naming`, staticcheck ST1003 | +| Line length | No limit; `lll` is disabled | +| Naming | revive `exported` (stutter); otherwise review | +| Local consistency | Review | + +### Style Decisions + +| Rule | Check | +| --- | --- | +| Underscores | revive `var-naming`, staticcheck ST1003 | +| Package names | revive `package-naming`, `var-naming` | +| Receiver names | revive `receiver-naming`, staticcheck ST1016 | +| Constant names | revive `var-naming` | +| Initialisms | revive `var-naming`, staticcheck ST1003 | +| Getters | `getprefix` | +| Variable names | Review | +| Repetition | revive `exported`; otherwise review | +| Comment line length | Review | +| Doc comments | revive `exported`, `godot` | +| Comment sentences | `godot` | +| Examples | `testableexamples` | +| Named result parameters | `nakedret`; otherwise review | +| Package comments | revive `package-comments`, staticcheck ST1000 | +| Import renaming | revive `redundant-import-alias`; otherwise review | +| Import grouping | `goimports` | +| Import "blank" | revive `blank-imports` | +| Import "dot" | revive `dot-imports`, staticcheck ST1001 | +| Returning errors | revive `error-return`, staticcheck ST1008 | +| Error strings | revive `error-strings`, staticcheck ST1005 | +| Handle errors | `errcheck` | +| In-band errors | Review | +| Indent error flow | revive `indent-error-flow`, `early-return`, `superfluous-else` | +| Literal formatting | `gofmt`, govet `composites` | +| Nil slices | Review | +| Indentation confusion | `gofmt`; otherwise review | +| Function formatting | `gofmt`; otherwise review | +| Conditionals and loops | `gofmt`; otherwise review | +| Copying | govet `copylocks` | +| Don't panic | `forcetypeassert`, `errcheck` type assertions; otherwise review | +| Must functions | Review | +| Goroutine lifetimes | govet `lostcancel`, `contextcheck`; otherwise review | +| Interfaces | `ireturn`, `iface`, `interfacebloat`; otherwise review | +| Generics | Review | +| Pass values | Review | +| Receiver type | `recvcheck` | +| switch and break | revive `unnecessary-stmt` | +| Synchronous functions | Review | +| Type aliases | Review | +| Use %q | gocritic `sprintfQuotedString` | +| Use any | revive `use-any`, `modernize` | +| Flags | Review; the published `raes` command contract takes precedence | +| Logging | `sloglint`, `depguard` denies `log`; otherwise review | +| Contexts | revive `context-as-argument`, `containedctx`, `contextcheck`, `noctx` | +| crypto/rand | gosec G404, `depguard` denies `math/rand` | +| Assertion libraries | `archcheck` ARCH-008 (ADR-122) | +| Identify the function | Review | +| Identify the input | Review | +| Got before want | `gotwant` | +| Full structure comparisons | Review | +| Compare stable results | Review | +| Keep going | Review | +| Equality comparison and diffs | `forbidigo` denies `reflect.DeepEqual`; otherwise review | +| Level of detail | Review | + +### Best Practices + +| Rule | Check | +| --- | --- | +| Function and method names: avoid repetition | revive `exported`; otherwise review | +| Naming conventions | `getprefix`; otherwise review | +| Test double and helper packages | Review | +| Shadowing | govet `shadow` | +| Util packages | revive `package-naming` | +| Package size | Review | +| Protocol Buffer messages and stubs | No protocol buffers are used | +| Import ordering | `goimports` | +| Error structure | `errorlint`, `errname`; otherwise review | +| Adding information to errors | Review | +| Placement of %w in errors | `wrapverb` | +| Logging errors | Review | +| Program initialization | `gochecknoinits`; otherwise review | +| Program checks and panics | Review | +| When to panic | Review | +| Documentation conventions: parameters, contexts, concurrency, cleanup, errors | Review | +| Preview | Review | +| Godoc formatting | `gofmt` | +| Signal boosting | Review | +| Variable initialization and zero values | revive `var-declaration`; otherwise review | +| Composite literals | Review | +| Size hints | Review | +| Channel direction | Review | +| Function argument lists: option structure, variadic options | Review | +| Complex command-line interfaces | Review | +| Leave testing to the Test function | Review | +| Designing extensible validation APIs and acceptance testing | Review; section 5 item 4 | +| Use real transports | Review | +| t.Error vs. t.Fatal | Review | +| Error handling in test helpers | `thelper` | +| Don't call t.Fatal from separate goroutines | govet `testinggoroutine` | +| Use field names in struct literals | govet `composites` | +| Keep setup code scoped to specific tests | Review | +| When to use a custom TestMain entrypoint | Review | +| Amortizing common test setup | Review | +| String concatenation | `perfsprint`; otherwise review | +| Constant strings | Review | +| Global state | `gochecknoglobals`; otherwise review | +| Interfaces: avoid unnecessary interfaces, ownership, design | `iface`, `interfacebloat`, `ireturn`; otherwise review | + +## Amendments + +| Date | Commit/PR | Summary | +| --- | --- | --- | +| 2026-10-31 | #1775 | Section 8 and the rule map: the ADR-122 architecture model lists the permitted external import paths. depguard keeps only its denials. | +| 2026-11-04 | #1882 | Separate exhaustive mutation testing from normal PR admission; keep the other Go gates and bound normal Go jobs to 25 minutes. | diff --git a/docs/decisions/adrs/adr-122-go-architecture-model.md b/docs/decisions/adrs/adr-122-go-architecture-model.md new file mode 100644 index 0000000..2a41ebc --- /dev/null +++ b/docs/decisions/adrs/adr-122-go-architecture-model.md @@ -0,0 +1,232 @@ +# ADR-122: Go architecture model + +## Status + +accepted + +## Date + +2026-10-31 + +## Classification + +Classification: FM0 +Required artifacts: unit tests (`implementations/tooling/go/arch` and the command `implementations/tooling/go/cmd/archcheck`), CI lanes (`.github/workflows/canonical-verification.yml` job `go-architecture`) +Waivers: none + +The decision sets the structure of the Go code and its checks. It adds no SDL, +contract, or runtime semantics. + +## Context + +Milestone 74 ports the codebase to Go. Issue #1775 requires one +machine-readable architecture model for the repository. Checks compiled from +the model must run on the whole repository, and each failure must state its fix. +Each change must also pass a check of its design against the model before code +exists. + +ADR-036 gives each Python package one area. The Python packages do not keep +these boundaries: 703 import statements import 1,361 private names from other +modules. ADR-117 added ratchets with baselines for these problems. MOD-001 +states its layering rules in Python terms. + +The Go compiler enforces some structure. It rejects import cycles. It permits +an import of an `internal` package only from the tree of its parent directory. +Only exported identifiers are visible outside a package. The compiler does not +know layers, permitted dependencies, or the packages that a design declares. + +## Decision + +### 1. One model for the repository + +`implementations/architecture.json` is the only architecture model, with the +schema `raes-go-architecture/v2`. All its directories are relative to the +repository root. The model declares these items: + +| Item | Content | +| --- | --- | +| Module | The directory of a `go.mod` file and the module path that it states | +| Layer | A name, a directory, a description, the layers whose packages it may import (`uses`), and the permitted external import paths, each with a reason (`external`) | +| Package | A directory in its layer, a description, a `public` flag, first-party imports, owning design and exact typed API | + +A package can import a package of its own layer. It can also import a public +package of a layer that its layer uses. The `uses` relation has no cycle. An +external path permits the import paths below it. + +Large typed snapshots may use ordered `api_files` under `implementations/architecture-api/`. +Each file contains declarations for its build configuration. +Loading expands these bounded files before the same exact API comparison and design commitment. +The model retains its 4 MiB limit; files have a 500 KiB limit and share a 16 MiB read budget. +A package can reference at most 64 files and cannot also declare an inline API. + +### 2. Layers + +The layers follow the contract families and the areas of ADR-036 and ADR-115. +They do not copy the Python package structure. + +| Layer | Directory | Uses | Content | +| --- | --- | --- | --- | +| `base` | `implementations/go/internal/base` | none | Shared primitives: canonical JSON, digests, random streams, input limits, errors, logging, and the clock | +| `contract` | `implementations/go/internal/contract` | `base` | Bindings and validation of the published contracts, concept authority, vocabularies, and profiles | +| `sdl` | `implementations/go/internal/sdl` | `contract`, `base` | Source loading, the document model, semantic validation, instantiation, and composition | +| `processor` | `implementations/go/internal/processor` | `sdl`, `contract`, `base` | Compilation, planning, trial compilation, and the analysis services | +| `backend` | `implementations/go/internal/backend` | `contract`, `base` | The interfaces that the runtime needs from a backend, backend manifests, and the backend test doubles | +| `runtime` | `implementations/go/internal/runtime` | `backend`, `processor`, `sdl`, `contract`, `base` | The control plane, its stores, distributed execution, and participant control | +| `conformance` | `implementations/go/internal/conformance` | `runtime`, `backend`, `processor`, `sdl`, `contract`, `base` | Processor and backend conformance checks | +| `app` | `implementations/go/internal/app` | `conformance`, `runtime`, `backend`, `processor`, `sdl`, `contract`, `base` | Services that the command line, the MCP server, and the HTTP API share | +| `adapter` | `implementations/go/internal/adapter` | `app`, `runtime`, `contract`, `base` | Thin adapters for the `raes` command, the `raes-mcp` server, and the control-plane HTTP API | +| `command` | `implementations/go/cmd` | `adapter`, `base` | The main packages of the `raes` and `raes-mcp` binaries | +| `parity` | `implementations/go/internal/parity` | none | The checker of the Go implementation against the golden corpus of the Python implementation (issue #1778) | +| `tooling` | `implementations/tooling/go` | none | Development tools: the repository analyzers, the architecture check, and CI checks | + +The current product layers are below `implementations/go/internal`. Thus the compiler +permits imports of them only from `implementations/go`. No layer uses +`parity` or `tooling`. + +### 3. Rules and their checks + +Each rule has exactly one check. `archcheck` is the command in +`implementations/tooling/go/cmd/archcheck`. `go build` is the Go compiler, +which each build and test runs. + +| Rule | Statement | Check | +| --- | --- | --- | +| ARCH-001 | The model declares each Go module of the repository once, with the directory and the module path of its `go.mod`. | `archcheck` | +| ARCH-002 | Each layer has a unique name, a directory, and a description. It uses only other declared layers, and the uses have no cycle. | `archcheck` | +| ARCH-003 | Each package has a unique directory in its layer and in a declared module, and a description. | `archcheck` | +| ARCH-004 | Each import in the model names a declared package in the same layer, or a public package of a layer that the importer's layer uses. | `archcheck` | +| ARCH-005 | The model declares each Go package, and each declared package has code. | `archcheck` | +| ARCH-006 | The non-test files of each package import exactly the first-party packages that the model declares for it. | `archcheck` | +| ARCH-007 | The test files of each package import only first-party packages that ARCH-004 permits for it. | `archcheck` | +| ARCH-008 | Each external entry has a reason and is in use. A package imports an external path only when its layer lists it. | `archcheck` | +| ARCH-009 | This table states each rule that a check enforces, with that check. | `archcheck` | +| ARCH-010 | The declared package dependency graph has no cycle, including same-layer cycles. | `archcheck` | +| ARCH-011 | Only code in the tree of the parent of an `internal` directory imports the packages below it. | `go build` | +| ARCH-012 | Code outside a package uses only its exported identifiers. These identifiers are the public interface of the package. | `go build` | +| ARCH-013 | Every package has intended typed interfaces per build configuration and a matching owning-design commitment. Actual APIs match those interfaces. | `archcheck` | +| ARCH-014 | The current system view matches model components, dependencies and content-bound design evidence. | `archcheck` | + +An external path is an import path outside the standard library and the +declared modules. A standard library path has no dot in its first element. + +### 4. The check command + +`archcheck` runs from the repository root. It reads the model and checks the +rules that need only the model: ARCH-001 to ARCH-004 and the entries of +ARCH-008. With `-design`, it also checks declared package cycles, API metadata, design commitments and current-view evidence. It does not read proposed product code. Without `-design`, it also +checks the rule table of this ADR and the code. It reads the imports of each Go +file of each declared module with `go/build`, test files included. It ignores +build constraints, so the code of each platform and build tag meets the model. + +Each finding names the rule and the location, and it states the change that +fixes it. For example: + +```text +archcheck: ARCH-005 implementations/tooling/go/newtool: the model does not declare this package. Fix: declare the package, its layer, and its imports in the model through the design step. +``` + +The command exits with status 1 on a finding. The `go-architecture` job of the +canonical graph runs it, and the `gate` job requires that job. + +### 5. The design step + +Before a change writes Go code, it does these steps: + +1. Declare each new or changed module, layer, package, import, and external + entry in the model. +2. Record each package's intended typed API per declared build configuration. + Link its owning design and record the API digest in that design. +3. Run `archcheck -design` on the changed model. + +The change writes the code after the design check passes. In CI, `archcheck` +fails when the code and the model do not agree. Thus the model changes before +the code that needs the change. The plan rules in `.gc/plan-rules.md` require the +design check before implementation starts. + +### 5.1 Typed interfaces and current system views + +The [current overview](../../develop/go-architecture.md) distinguishes implemented and planned components. +Issue #1825 owns downstream consumer API design. Internal visibility does not grant downstream importability. + +The model records explicit GOOS, GOARCH and tag configurations. Each package records `design` and `api`. +The API contains sorted standard Go type/object strings, exact constants, reachable private types and method sets. +The owning design commits to SHA-256 of encoding/json.Marshal bytes for the API map. +This encoding sorts keys and applies its default HTML escaping. +Private implementation changes do not update the interface. +`archcheck -api` prints actual interfaces for review; it never updates intent. +Uncovered production source files fail visibly. +API loading uses the admitted Go loader offline, with read-only module resolution and no proposed-code execution. + +The model names the current `overview` and SHA-256 commitments for its evidence `sources`. +`archcheck -view` prints a deterministic component, ownership and dependency section. +The normal check and pre-code check reject stale generated content or changed evidence. +Rooted filesystem reads contain design and evidence references within the repository. +These checks prove artifact consistency, not semantic equivalence or human approval. + +### 6. Dependencies + +The model is the only list of permitted dependencies. ARCH-006 governs the +first-party imports, and ARCH-008 governs the external imports of each layer. +The golangci-lint `depguard` rule keeps only its denials of standard library +packages (ADR-121). ADR-106 governs the admission of module digests. + +### 7. No baseline + +The Go code starts with no findings. No check has a baseline or an allowlist. + +## Alternatives considered + +- **go-arch-lint.** Version 1.19.1 checks the dependencies between components, + the vendor packages of each component, and the files that no component + matches. Its `self-inspect` command validates the configuration. Components + match packages by directory globs, so a new package or a new import between + permitted components changes no model. Thus a design cannot record them + before the code. It also has no package visibility, and its messages state no + fix. +- **depguard rules for each layer.** depguard denies imports by file glob. It + does not classify packages, record package imports, or report unused + permissions. +- **Bazel visibility rules.** Bazel would replace the go command, the module + files, and the CI lanes for the whole repository. + +## Consequences + +- Each new Go package or import needs a model change. The change shows the + design in review before the code. +- A package that the model does not classify fails CI. +- The model lists each external dependency with its reason. depguard no longer + holds an allow list. +- `archcheck` is a small program on the standard Go package loader. The + repository maintains it and its tests. + +## Repository ownership at the Go cutover + +The [ownership map](../issue-1891-runtime-repository-boundary.md) fixes the planned repository boundary for the common #1804 Go launch. +The existing model still owns the current modules, packages, typed APIs and imports. +Layer descriptions name their next owners. +Source digests bind the split plan and its full source inventory to the current view. +Do not claim that an absent module or package has moved. +Keep schema version 2 and ARCH-001 through ARCH-014. + +Runtime imports only released public SDL, processor, contract and backend APIs from `OpenRAE/rae`. +No `rae` product module or `raes-mcp` imports runtime. +Pure conformance and authoring services stay in `rae`. +Live conformance, execution services and HTTP belong to runtime. +Only runtime publishes the combined `raes` executable. + +#1825 fixes the exact external packages and command-composition API. +#1892 makes the required primitive moves. +Go still checks `internal` visibility. +The model's `public` flag cannot grant an internal import to the other repository. +Keep current module paths unless a named split dependency requires a change. +Update this same model, API pins and views before moving code. +Do not add a second model or copy semantic code. + +## Amendments + +| Date | Commit/PR | Summary | +| --- | --- | --- | +| 2026-10-31 | #1778 | Section 2: the `parity` layer holds the checker of the Go implementation against the golden corpus. | +| 2026-11-02 | #1859 | Version 2 binds typed package interfaces to designs, checks package cycles before code, and verifies current system views. | +| 2026-11-03 | #1780 | Bounded API snapshot files retain exact generated binding declarations without enlarging the model bound. | +| 2026-11-04 | #1891 | Recorded the planned runtime repository owner and one-way public dependencies at the common Go cutover; preserved behavioral decisions. | diff --git a/docs/decisions/issue-1891-runtime-repository-boundary.md b/docs/decisions/issue-1891-runtime-repository-boundary.md new file mode 100644 index 0000000..b78323a --- /dev/null +++ b/docs/decisions/issue-1891-runtime-repository-boundary.md @@ -0,0 +1,258 @@ +# Runtime repository boundary and extraction inventory + +Issue [#1891](https://github.com/OpenRAE/rae/issues/1891) records the repository split for the Go hard cutover. +The common user-facing release gate is [#1804](https://github.com/OpenRAE/rae/issues/1804). +This plan records who owns each part. +It does not change product code. +It transfers no source, creates no repository and changes no installed behavior. + +The working destination name is `OpenRAE/rae-runtime`. +It is not an approved destination or visibility choice. +Name the final repository first. +Record its access settings and approval before any move. +Only one owner edits each part during the move. + +## Authority and dependency direction + +| Continuing owner | Responsibility | +| --- | --- | +| `OpenRAE/rae` | SDL syntax, models, bounded loading, validation, authoring, inventory descriptions, instantiation, compiler, planner, trial compilation, analysis and language services | +| `OpenRAE/rae` | Normative specifications, published schemas and IDs, profiles, fixtures, bindings, contract validation, concept authority, portable backend interfaces, portable stubs and pure conformance checks. | +| Runtime repository | Execution engine, control plane, HTTP API, stores, Temporal workers, backend registry and invocation, participant execution/control, injects, experiment/run lifecycle, operational archives and execution-dependent conformance runners. | +| Existing external backends | Concrete realization, native resources and credentials; this split moves none of those implementations. | + +Runtime imports released public SDL, processor, contract and backend APIs from `rae`. +`rae` product libraries, released modules and `raes-mcp` must not import runtime. +A build may check both repositories. +That does not grant a product import. +There is no third contracts repository, network compiler, plugin system or copied semantic implementation. + +```mermaid +flowchart LR + subgraph RAE[OpenRAE/rae - canonical language and contract authority] + Authoring[SDL and authoring services] + Processor[Compiler / planner / trial compiler] + Contracts[Published contracts / bindings / validation] + Backend[Portable backend interfaces and stubs] + MCP[raes-mcp publisher] + Commands[Public authoring command composition - issue 1825] + end + subgraph Runtime[Runtime repository - planned] + Engine[Engine / control plane / stores / workers] + HTTP[Existing HTTP adapter] + CLI[Combined raes publisher] + Live[Live conformance and operational archives] + end + Engine -->|released public imports| Processor + Engine -->|canonical admission and type identity| Contracts + Engine -->|injected portable interfaces| Backend + CLI -->|public command composition| Commands + MCP --> Authoring + Commands --> Processor + HTTP --> Engine + Live --> Engine + Engine -->|existing protocol invocation| External[Existing external backends] +``` + +An arrow means that one part uses another. +It does not add a service call. +Authentication, authorization, store scope, leases, retry permission, uncertain-effect handling, evidence and secret boundaries stay as ADR-104, ADR-113 and ADR-115 define them. +P3 remains unavailable. +Splitting repositories grants no runtime capability. + +## Mixed responsibilities and public seams + +Paths below start at the source root. +They name roles. +A mixed file can have more than one role. +Do not copy the whole file on that basis. +Python stays the reference for behavior until the Go launch. +Continue the existing Go port once; do not extract Python or port it again. + +| Existing area | Retained in `rae` | Runtime responsibility / necessary adjustment | +| --- | --- | --- | +| `implementations/python/packages/raes/`, including `runtime_*`, participant and experiment models | All language vocabulary, runtime inventory descriptions and semantic admission | None moves merely because its name contains runtime, participant or experiment | +| `raes_processor/compiler`, `planner`, `trial_compiler`, `trial_realization`, `models` | Compilation, planning, admitted trial identities, allocation, artifacts and analysis | Live experiment/trial execution consumes the admitted artifacts through public processor APIs. | +| `raes_processor/trial_scheduler.py` | `ScheduledEntry`, `BatchSchedule`, `plan_batch_schedule` and schedule meaning | `dispatch_batch_schedule` invokes effects; live dispatch and execution-receipt production belong with runtime. Preserve schedule identity and behavior. | +| `raes_contracts/` | All published DTOs, defaults, validation, normalized round trips, schema/vocabulary authority and shared type identity | Runtime consumes these released bindings, including snapshots and archive records; it does not redefine them. | +| `raes_backend_protocols/`, `raes_backend_stubs/` | Portable interfaces, manifest/profile admission and inert test doubles | Backend registry, invocation and runtime-specific adapters move; concrete backends stay external. | +| `raes_backend_stubs/stubs.py` | `StubProvisioner`, `StubOrchestrator`, `StubEvaluator`, `StubParticipantRuntime` and pure evaluation helpers | `create_stub_components` and `create_stub_target` assemble runtime targets. Move those factories with `RuntimeTarget`, `RuntimeTargetComponents`, `ReferenceTimeRuntime` and `backend_selection_observation_runtime` dependencies. Runtime imports the portable stubs; the stubs must not import runtime. | +| `raes_backend_stubs/manifest.py` and `raes_runtime/registry_scenario.py` | `create_stub_manifest` stays portable. The pure `scenario_component_options` selector belongs with processor compilation: it only compiles/reads a scenario model and returns existing feature flags | Expose that single selector through the public processor API in #1825. A retained authoring/app wrapper keeps scenario-aware manifest behavior: call the selector, then pass its flags to the pure stub manifest. The backend layer imports neither processor nor runtime. Runtime composition uses the same selector. Preserve all five flags, error checks and defaults. Keep `participant_temporal_probe_manager` in runtime; do not copy the selector or move the whole mixed file. | +| `raes_runtime/` | Canonical contracts it consumes stay with their existing authority | All live engine, operation, store, HTTP, worker, participant, inject and experiment/run behavior. | +| `raes_operations/run_artifacts.py` | `MaterializationArchiveRecord`, materialization submission types and semantic admission remain contract code | `RunMaterializationArchive` publication, protected filesystem readback and operational archive lifecycle. | +| `raes_conformance/conformance/` | `fixture_suite`, `processor`, pure validators, profiles, reports and diagnostics | Live target/probe/control runners move. The current dependency closure is too broad: pure checks reach `raes_runtime.result_contracts` through `snapshot_semantics`, and reports reach live probe types. Keep pure admission with its contract owner and separate live runner types. Split the facade; a current import is not a reason to move pure checks. | +| `conformance/modular_control_report.py` and `modular_control_types.py` | `validate_modular_report`, `ModularControlEvidence`, `ModularOwnerObservation` and the pure obligation/operation vocabulary | Keep pure report admission in `rae`. Move `ModularControlStep`, `ModularControlCase` and `ModularControlHarness` with the live runner. The report carrier must not retain control-plane or target imports. | +| `conformance/mixed_backend_types.py`, `participant_opacity_types.py`, `participant_policy_types.py` | Portable report bindings, coordinates, transcripts, observation carriers, pure serialization and validation | Separate runtime-bound case/configuration and harness types that need `RuntimeTarget` or control-plane callbacks. Live harnesses import shared carriers from `rae`. Pure report validation must not import a live harness to obtain its data types. | +| `raes_cli/processor.py`, `sdl.py`, `semantic.py` | Existing authoring, plan, reconciliation demonstration, normalization and inspection implementations | An admitted `RuntimeSnapshot` argument is data, not a live execution dependency. | +| `raes_cli/conformance.py` | Processor and pure fixture command implementations | Execution-dependent backend conformance composition; preserve both command groups. | +| `raes_cli/main.py`, `entrypoint.py`, `runtime.py` | Publicly composable authoring command implementations | Combined `raes` executable and public offline store-maintenance commands. | +| `raes_mcp/`, including `tools/operations.py` | Existing authoring, experiment-authoring, inspection and portable operation tools | No runtime import, renamed tool, forwarding service or second semantic implementation. | +| `implementations/go/internal/base/` | Every existing primitive keeps its authority | Expose only consumer-required types under #1825/#1892. Runtime-only helpers stay with runtime; do not copy shared primitives. | +| `implementations/python/tests/` and shared fixtures | Historical migration evidence; pure language/processor/contract/stub assertions continue in `rae` Go tests | Port existing effect, engine/store/HTTP/Temporal, participant, inject and archive assertions into runtime Go tests. Split mixed tests by assertions and fixture dependencies. | + +Issue [#1825](https://github.com/OpenRAE/rae/issues/1825) owns exact public package/type/function names, command composition and compatibility commitments. +Issue [#1892](https://github.com/OpenRAE/rae/issues/1892) performs necessary moves of already ported primitives. +This plan fixes their owners and import direction. +It does not design a second API. + +| Required external interface | Authority / reason it must cross the repository boundary | +| --- | --- | +| Bounded SDL loading, validation, authoring and diagnostics | `rae`; runtime and authoring consumers must reuse the existing semantic implementation | +| Compiler, planner and trial compiler inputs/results | `rae`; runtime needs admitted execution artifacts without importing processor internals. | +| Published contract bindings and admission | `rae`; preserve type identity, defaults, normalization, serialization, IDs and validation. | +| Backend protocols, manifests, profiles and portable stubs | `rae`; runtime invokes injected backends through the existing portable contracts. | +| Required clock/error/digest/domain/value types | Current `rae` primitive authority; expose only types reachable from required consumer interfaces. | +| Authoring command registration/composition | `rae`; runtime publishes the existing combined `raes` tree without a reverse dependency. | +| Engine/control-plane and store/lease/clock provider seams | Runtime; Coldlight embeds this shared runtime. Environment packs and LilRAE select the relevant released `rae` APIs and, only where needed, runtime APIs. | + +Go still checks each `internal` import. +The model's `public` flag cannot grant that access. +A package needed by the other repository must be made public. +#1825 and #1892 own those moves. +Keep `github.com/OpenRAE/rae/implementations/go`. +Change a module path only when a named import requires it. +Do not move unrelated internals or expose every helper. +Approve the new repository before fixing its module path. +At the move, update imports and module files together. +Update the model, API pins and tests in that same change. +Release candidates must use exact released module versions. +A local workspace is not enough. + +## Executable and installation ownership + +The runtime repository is the sole publisher of the combined `raes` executable. +It imports authoring commands from released `rae` APIs. +It adds its own runtime commands to that tree. +Keep `sdl`, `processor`, `conformance`, `semantic` and `runtime`. +Keep their subcommands, flags, results and exit behavior. +The HTTP adapter keeps the same behavior under runtime. + +`rae` retains authoring services and is the sole publisher of `raes-mcp`. +Preserve all existing MCP tool names, inputs, outputs and diagnostics. +Neither its binary nor its released library imports runtime. +No `rae` release artifact installs another `raes` binary after cutover. +Install both release candidates as a pair. +Check that each binary has one owner. +Check the whole command tree. +#1825 fixes the exact API and install artifact names. + +## Complete source inventory + +The [inventory](issue-1891-runtime-extraction-inventory.json) pins source commit `31cc63844f63027f4517307b0cd287eea55946dd`. +It covers all 53,364 tracked paths. +This includes tests, fixtures, examples, CI and release inputs. +It also covers docs, requirements and research/proof producers. +The source tree ID pins every path, mode and blob. +SHA-256 binds the full path manifest. +Each rule has a path count and digest for its records. +The old path and new prefix give the new path. +Git keeps each blob ID. +The manifest need not list those 53,364 paths a second time. + +Use the longest matching `old_prefix`. +It must equal the full path or one of its parent directories. +Rules are not globs. +A partial file name does not match. +The most specific rule wins exactly once. +The owner takes the named role after cutover. +This does not grant a right to copy the Python reference. + +| Disposition | Meaning | +| --- | --- | +| `retained` | Current artifact and its authority remain in `rae` | +| `moved` | The continuing operational artifact moves to runtime at the coordinated cutover; old public URLs keep a migration pointer. | +| `consumed-by-version` | The canonical artifact remains in `rae`; runtime consumes an immutable released bundle with identity and provenance. | +| `migration-only` | Port/reference material is used until #1804, then retired from active delivery; historical evidence remains in `rae`. It has no source-transfer destination. | + +Go has base primitives and the parity harness at this source commit. +The other product layers are still planned. +The inventory's `planned_go_areas` records their eventual split without pretending that absent code has been extracted. +Keep this baseline immutable. +Freeze the completed Go source SHA before the move. +Create a new manifest for that SHA. +Check each new, changed or removed path against this map. +Review each mixed file with its tests and fixtures. +Do this before selecting it for the move. +The frozen manifest must name approved module paths and the #1825 public API map. +Do not move code while an entry is unresolved. +Do not treat this early baseline as the final completed-runtime transfer list. + +## Governance, documentation, evidence and delivery artifacts + +| Asset / current path | Continuing ownership and delivery rule | +| --- | --- | +| `specs/`, `contracts/`, `docs/requirements/`, `docs/governance/` | `rae` retains normative authority, requirement IDs, traceability records and canonical fixtures. Runtime records implementation/test links against exact released IDs and bundles; it does not fork the requirements or schemas | +| `docs/decisions/`, ADR pins and historical design/preflight records | Retain in `rae`; runtime references immutable revisions. New runtime implementation decisions live with runtime and cannot silently amend canonical language or contract decisions. | +| `docs/explain/`, `docs/public/`, `docs/migration/` | Keep language/contract/processor documentation in `rae`. The inventory names operational guides whose continuing owner moves to runtime. Mixed CLI/install and runtime-architecture pages retain canonical explanations in `rae` and link to the version-matched runtime operations guide. | +| `examples/` and contract fixtures | Canonical SDL examples and portable fixture bytes remain in `rae`; runtime consumes named versions for execution examples. Operational harness code and run outputs belong with runtime, while canonical input copies remain identified by digest. | +| `implementations/formal/`, `specs/formal/` | Canonical formal models and pure proof producers remain in `rae`; runtime supplies implementation-specific witnesses against exact model/source identities. | +| `docs/research/` | Published evidence, capture retention, source pins, protocol decisions and historical producer scripts remain immutable in `rae`. They are historical evidence, not runtime installation instructions. | +| `tools/` canonical checks | Specification/schema/requirement/proof-bundle admission stays `rae`-owned. Runtime consumes immutable results and owns new execution-dependent evidence producers. Preserve existing source-bound capture and numbered-publication rules. | +| Current runtime research producers | `docs/research/execution-architecture/experiments/`, runtime-control-plane, execution-recovery and participant-control research keep their old evidence/producers in `rae`. Future runtime Go producers get new source/path identities in the frozen transfer manifest; do not rewrite old captures or perform a Python extraction. | +| `.github/workflows/canonical-verification.yml` | `rae` keeps the current workflow. Keep canonical `proof-archive`, `model-check`, `checks`, `proof`, `go-architecture`, language/processor tests and documentation checks. Runtime adapts existing Go, integration, regression, security, traceability, mutation, coverage, Sonar and required-check controls to its own code. | +| `parity-inputs`, `parity-corpus` and `internal/parity` | Migration lanes until the common Go launch. Freeze golden evidence in `rae`; preserve digest/source provenance when runtime consumes relevant vectors. Do not create a second mutable corpus authority. | +| Remaining workflow files and tooling modules | Current files remain in `rae`; runtime adapts existing applicable title/body, bootstrap, policy, docs, release, security, scorecard and completion controls before its paired candidate is accepted. | +| Release Please configuration, version files, packaging inputs, wheel/sdist history | Existing Python release inputs are migration-only where they deliver Python. Retain historical releases and notices. `rae` publishes the SDL/processor/contract modules and `raes-mcp`; runtime publishes its library, combined `raes` and existing HTTP/worker artifacts. Each artifact has one publisher. | +| `LICENSE`, `THIRD_PARTY_NOTICES.md`, module digests, security/governance/contact files | Preserve source license/notices and imported dependency provenance. `rae` keeps its canonical files; the authorized destination must carry the applicable notices and operational/security ownership before source import. | + +This plan approves no new host, service or access change. +It adds no publication site or supply-chain dependency. +Keep the existing design and code checks. +Keep the security, traceability, regression and mutation gates. +Do not weaken them for the split. +Full, integration, fuzz and mutation suites stay in CI; local verification stays targeted. + +## Reproducible transfer and provenance + +The baseline inventory records Git object IDs for `LICENSE`, `THIRD_PARTY_NOTICES.md`, `implementations/go/go.mod` and `go.sum`. +Preserve file license headers and the applicable dependency notices in the destination. +The final transfer receipt records both repository identities, approved access, source commit/tree, selected old/new paths, modes, blob IDs, required transformations and destination import commit. +Keep any import-path edits separate from the byte-preserving import so review can distinguish copied bytes from necessary wiring changes. + +Rehearse entirely locally before an authorized transfer: + +1. Read the pinned commit with `git ls-tree -r -z --full-tree` and verify the source tree and manifest digest. +2. Resolve every path through the inventory rules, checking effective counts/digests, destination containment and collisions. +3. At the completed-Go freeze, regenerate the concrete extraction selection and compare changes from the baseline. Include tests, fixtures, producer paths, licenses and build/release inputs; reject unresolved mixed ownership. +4. Materialize only selected regular blobs and intended contained links from the frozen commit. Preserve modes and verify every extracted blob against its source ID. Do not follow checkout symlinks or copy ignored files, credentials or local state. +5. After destination/access approval, import that selection into a new destination commit with the source manifest and license/notice provenance. Keep the source repository's history intact; never reset, filter or force-push it for extraction. +6. Apply only necessary module/import/build wiring. Record transformed path/blob pairs and prove unchanged behavior with existing regression, conformance and mutation gates in CI. + +The inventory structural test performs steps 1 and 2 against the complete pinned Git tree without copying source. +A local rehearsal grants no right to upload or publish its output. + +## Delivery sequence and release gate + +1. Complete #1825's public consumer and command-composition commitments, then #1892's required primitive moves. +2. Continue the existing Go port on `go-cutover`, applying this ownership map to each existing slice. Keep one behavior implementation per responsibility. +3. Approve the destination and access settings. Freeze the completed-Go source inventory, prepare the destination and import its runtime with tests and existing CI/release controls. Reconcile later Go changes explicitly; only one repository actively edits each implementation. +4. Prepare the SDL-only build, paired cross-repository verification and documentation, exact module versions and paired release candidates. Record source SHAs, module digests, canonical bundle identities and artifact publishers for both candidates. +5. Rehearse, then execute #1804 as one coordinated breaking launch. Remove runtime implementation from `rae` in that cutover PR. No separate user-facing runtime release precedes this common gate. + +After that launch, the repositories release independently against explicit compatible versions. +Before launch, a source import is not a runtime release. +A green build alone is not a release either. +Tie rollback and rehearsal evidence to the paired candidates. +Keep the same store and security behavior. + +## Model and verification + +`implementations/architecture.json` remains the sole Go architecture model. +Its layer descriptions declare the planned repository owners and mixed-layer split. +Its `sources` bind this decision, including the inventory commitment below, to the current system view. +The current graph still shows the modules, packages, imports and APIs in this checkout. +Do not invent destination modules for absent code or bypass Go `internal` visibility. +Later package moves update that same model through #1825 and existing Go design gates. + +Targeted checks cover complete inventory ownership, source/provenance identities, collision/containment checks, product dependency direction, executable publishers and release-gate data. +The existing Go architecture-tool test lane owns these structural checks. +It already fetches full history without persisting checkout credentials. +The product Python test tree and frozen parity corpus stay unchanged. +Native `archcheck -design` and `archcheck` validate model, typed APIs and source-bound views. +ADR-059 checks amendment records and canonical pins. +Changed-document Vale checks apply the repository's writing rules. +These checks prove that the artifacts agree. +Reviewers must still check the role of each part. +They must check that behavior stays the same. + + diff --git a/docs/source-manifest.json b/docs/source-manifest.json new file mode 100644 index 0000000..73e7ff0 --- /dev/null +++ b/docs/source-manifest.json @@ -0,0 +1,102 @@ +{ + "source_repository": "https://github.com/OpenRAE/rae", + "source_commit": "9b3146bf4d8a478db3c6b273b1ed90952a239752", + "destination_repository": "https://github.com/OpenRAE/runtime", + "purpose": "Bootstrap configuration and unchanged governing documents only; not the completed-runtime extraction manifest.", + "files": [ + { + "source_path": "implementations/.golangci.yml", + "destination_path": "implementations/.golangci.yml", + "source_blob": "3bbad57b854fae3289dadbac9c2ed100172da180", + "sha256": "fe7fcba028fccfff88bd5b565f26f67ccbb1f69f6f5d6ad6a45b8792a013eb52", + "source_sha256": "a3bd25dd5aaf72450ccd06ba7ce0df70bbd0f6c9dbf164e6cc513c23f4b34445", + "transformation": "Add the runtime module to the formatter local import prefixes; keep all lint rules unchanged." + }, + { + "source_path": "implementations/.gremlins.yaml", + "destination_path": "implementations/.gremlins.yaml", + "source_blob": "504200c5b6a15ac9cf3d5da7f1cd79913e26703c", + "sha256": "75cc3cd1cb951c838d6f2685405347c82c0b425c18e09537f563a3dd85fe81c8" + }, + { + "source_path": "docs/decisions/adrs/adr-121-go-engineering-standards.md", + "destination_path": "docs/decisions/adrs/adr-121-go-engineering-standards.md", + "source_blob": "49e79e217553d5484bd2fa1ebf8f6c0443f9489b", + "sha256": "49217f20d43a33c553797580f6cbc16fb4784e4f0ad207507c7f5dafafcaaae1" + }, + { + "source_path": "docs/decisions/adrs/adr-122-go-architecture-model.md", + "destination_path": "docs/decisions/adrs/adr-122-go-architecture-model.md", + "source_blob": "2a41ebc7e6f43098f66e3061bc973c7c158bb164", + "sha256": "bb34edd9eb80bb56645ef57f4f48eb3113ac02e95b7af696f32de3bdb8d11fa6" + }, + { + "source_path": "docs/decisions/issue-1891-runtime-repository-boundary.md", + "destination_path": "docs/decisions/issue-1891-runtime-repository-boundary.md", + "source_blob": "b78323a5402cda83b4401bd4347b4fb32b3f7731", + "sha256": "e8233ecdf836dbbad4dda9ef373572dd466f1cf59ad0eeb4ab01cc9fd476e406" + }, + { + "source_path": ".vale.ini", + "destination_path": ".vale.ini", + "source_blob": "b13ce89fe30def8d5d1c51c8b50912ac06d35961", + "sha256": "fa16a15b5bca25e971c34eeb005b1d70954b0284ac4427c24154435766599d7c" + }, + { + "source_path": "styles/RAES/AvoidDismissive.yml", + "destination_path": "styles/RAES/AvoidDismissive.yml", + "source_blob": "bb57baf45a3915e246f8c0d4c60c271bbef2ada9", + "sha256": "14d9b2d8aefdfe99a5bf4e753c60877222e6988a7a880e8710a1c9b3bd684800" + }, + { + "source_path": "styles/RAES/AvoidHype.yml", + "destination_path": "styles/RAES/AvoidHype.yml", + "source_blob": "fb9fd70647a1c983ced431a3a38c843cc8f0286e", + "sha256": "2641519f19e1e3a145650a55e3c25b5085e5d3ba814adf5e90efe451429ddb1f" + }, + { + "source_path": "styles/RAES/HeadingCase.yml", + "destination_path": "styles/RAES/HeadingCase.yml", + "source_blob": "f538bf30a5bd8e71ea4b12fddf8fc8c93dda6d5f", + "sha256": "5a794f4864b6edd540b7deeb69ca59705f598589ac63b6da959682675863523c" + }, + { + "source_path": "styles/RAES/HeadingPunctuation.yml", + "destination_path": "styles/RAES/HeadingPunctuation.yml", + "source_blob": "02e14d97082d4f476e53ce24a7c92a6b214ffed4", + "sha256": "022486315654dc7e7873a6a3647534a4f9a2cb948e2745c00c04004426982d4f" + }, + { + "source_path": "styles/RAES/PlainWords.yml", + "destination_path": "styles/RAES/PlainWords.yml", + "source_blob": "a8888f1c2c9bdf56051e5442147dae250605d54a", + "sha256": "44efc05c81ce07a2cb843fba96984b55255b22c2d5c7735677f89b27411de9c2" + }, + { + "source_path": "styles/RAES/ReadingLevel.yml", + "destination_path": "styles/RAES/ReadingLevel.yml", + "source_blob": "a81c02647c1f98ba5583353b5b442e85b4f76891", + "sha256": "943e6960e2ebe35985faca8bba1194a7ffeb873a9a7b3119b6b55af90c2a5cb7" + }, + { + "source_path": "styles/RAES/SentenceLength.yml", + "destination_path": "styles/RAES/SentenceLength.yml", + "source_blob": "62df04b3b22c70d22926399f66657296c99be1b0", + "sha256": "7b5e718997af724d072a732e19ccfe290d61ae994730251410917ccd815064ea" + }, + { + "source_path": "styles/config/vocabularies/RAES/accept.txt", + "destination_path": "styles/config/vocabularies/RAES/accept.txt", + "source_blob": "8c6e8195cdce294101d94f4681f951c49d0467ed", + "sha256": "f9d4805876464cd7e4454989d86bfc3a6cc35ceadc0f94d15f97255f0115f69b" + }, + { + "source_path": ".github/workflows/ground-control-phase-e.yml", + "destination_path": ".github/workflows/ground-control-phase-e.yml", + "source_blob": "531a311c3dab4aa8c2dde24803cd7fe60f5fcbc7", + "sha256": "95a6af7d680585e7593118c9707f82eabb0334d654902430534c44c44a1775d0", + "source_sha256": "9387dfd281f73f1b074e1d86a7124bacc474c7ed4db5c9ced7de303a4630ccc3", + "transformation": "Use runtime branches and the installed schema-v2-capable Ground Control version; keep the existing finalization flow." + } + ] +} diff --git a/implementations/.golangci.yml b/implementations/.golangci.yml new file mode 100644 index 0000000..724e9ff --- /dev/null +++ b/implementations/.golangci.yml @@ -0,0 +1,149 @@ +# Strict lint configuration for all Go code in this repository (ADR-121). +# golangci-lint finds this file from each Go module below this directory. +version: "2" + +run: + # A module must already match its reviewed go.sum (ADR-106). + modules-download-mode: readonly + +linters: + default: all + disable: + # Each disabled linter conflicts with the Google Go style guide or with a + # published contract, or an enabled check already covers it. + - cyclop # gocognit carries the complexity limit, as SonarCloud does. + - err113 # Google style permits fmt.Errorf; callers test sentinel errors where they need to. + - exhaustruct # Google style relies on zero values. + - funcorder # Not a Google style rule. + - funlen # Google style sets no length limit; gocognit limits complexity. + - gocyclo # gocognit carries the complexity limit. + - godox # Google style permits TODO comments that give context. + - gomodguard # Deprecated; gomodguard_v2 replaces it. + - lll # Google style sets no line length limit. + - maintidx # gocognit carries the complexity limit. + - mnd # Google style does not require a named constant for each number. + - nlreturn # Not a Google style rule. + - noinlineerr # Google style uses `if err := f(); err != nil`. + - nonamedreturns # Google style permits named results that document a function. + - paralleltest # Google style does not require parallel tests. + - prealloc # Google style asks for size hints only when the size is known. + - tagliatelle # JSON field names follow the published contracts. + - testpackage # Google style permits tests in the package under test. + - tparallel # Google style does not require parallel tests. + - varnamelen # Google style prefers short names in short scopes. + - wrapcheck # Google style adds context to an error only where it helps the reader. + - wsl # Not a Google style rule. + - wsl_v5 # Not a Google style rule. + - exhaustruct_v5 # Google style relies on zero values. + settings: + depguard: + rules: + dependencies: + # The architecture model lists the external packages that each layer + # may import (ADR-122). depguard denies the standard library packages + # that the standards replace (ADR-121). + list-mode: lax + deny: + - pkg: math/rand + desc: use crypto/rand, or the governed random streams for reproducible values + - pkg: log$ + desc: use log/slog with value-free records (ADR-116) + errcheck: + check-type-assertions: true + exhaustive: + default-signifies-exhaustive: false + forbidigo: + analyze-types: true + forbid: + - pattern: ^reflect\.DeepEqual$ + msg: compare with cmp.Equal or cmp.Diff (Google Go style decisions) + - pattern: ^fmt\.Print(f|ln)?$ + msg: write to an explicit io.Writer + - pattern: ^time\.Now$ + msg: read the time from an injected clock (ADR-118) + gocognit: + # The SonarCloud cognitive complexity limit. + min-complexity: 15 + gocritic: + enabled-checks: + # Google Go style decisions: "Use %q". + - sprintfQuotedString + govet: + enable-all: true + disable: + - fieldalignment # Google style favors readable field order over struct packing. + nolintlint: + require-explanation: true + require-specific: true + revive: + rules: + - name: blank-imports + - name: context-as-argument + - name: context-keys-type + - name: dot-imports + - name: early-return + - name: empty-block + - name: error-naming + - name: error-return + - name: error-strings + - name: errorf + - name: exported + - name: identical-branches + - name: increment-decrement + - name: indent-error-flow + - name: package-comments + # Google Go style best practices: no util, common, helpers, or models packages. + - name: package-naming + arguments: + - checkExtraBadName: true + - name: range + - name: receiver-naming + - name: redefines-builtin-id + - name: redundant-import-alias + - name: superfluous-else + - name: time-naming + - name: unexported-return + - name: unnecessary-stmt + - name: unreachable-code + - name: unused-parameter + - name: use-any + - name: var-declaration + - name: var-naming + sloglint: + attr-only: true + static-msg: true + key-naming-case: snake + staticcheck: + checks: ["all"] + exclusions: + generated: strict + rules: + # ADR-118 permits exactly the system clock owner to read wall time. + - path: 'go/internal/base/clock/clock\.go$' + linters: [forbidigo] + source: '^func System\(' + # The go/analysis API requires each analyzer to be a package-level variable. + - path: tooling/go/lint/ + linters: [gochecknoglobals] + text: "^Analyzer is a global variable$" + # The go/analysis API requires a nil result from an analyzer that declares no result type. + - path: tooling/go/lint/ + linters: [nilnil] + source: "return nil, nil" + # Repeated literals keep each test case readable on its own. + - path: _test\.go$ + linters: [goconst] + +formatters: + enable: + - gofmt + - goimports + settings: + goimports: + local-prefixes: + - github.com/OpenRAE/runtime + - github.com/OpenRAE/rae + +issues: + max-issues-per-linter: 0 + max-same-issues: 0 diff --git a/implementations/.gremlins.yaml b/implementations/.gremlins.yaml new file mode 100644 index 0000000..504200c --- /dev/null +++ b/implementations/.gremlins.yaml @@ -0,0 +1,10 @@ +# Mutation testing thresholds of the Go modules (ADR-121). +# +# Gremlins v0.6.0 reads a threshold flag of its command line as text and then +# ignores it. This file gives each threshold as a number. Gremlins fails when a +# value is equal to or less than its threshold. Thus 99.99 fails a change of up +# to 10,000 mutants when one mutant lives or no test covers it. +unleash: + threshold: + efficacy: 99.99 + mutant-coverage: 99.99 diff --git a/implementations/architecture.json b/implementations/architecture.json new file mode 100644 index 0000000..e996140 --- /dev/null +++ b/implementations/architecture.json @@ -0,0 +1,47 @@ +{ + "schema": "raes-go-architecture/v2", + "configurations": [ + { + "id": "linux-amd64", + "goos": "linux", + "goarch": "amd64", + "tags": [] + } + ], + "overview": "docs/architecture.md", + "sources": { + "docs/decisions/adrs/adr-121-go-engineering-standards.md": "49217f20d43a33c553797580f6cbc16fb4784e4f0ad207507c7f5dafafcaaae1", + "docs/decisions/adrs/adr-122-go-architecture-model.md": "bb34edd9eb80bb56645ef57f4f48eb3113ac02e95b7af696f32de3bdb8d11fa6", + "docs/decisions/issue-1891-runtime-repository-boundary.md": "e8233ecdf836dbbad4dda9ef373572dd466f1cf59ad0eeb4ab01cc9fd476e406" + }, + "modules": [ + { + "dir": "implementations/go", + "path": "github.com/OpenRAE/runtime/implementations/go" + } + ], + "layers": [ + { + "name": "runtime", + "dir": "implementations/go", + "doc": "The runtime responsibility defined by the accepted RAE split; only an empty bootstrap package exists. Runtime consumes public RAE APIs; RAE product modules never import runtime.", + "uses": [], + "external": [] + } + ], + "packages": [ + { + "design": "docs/architecture.md", + "api": { + "linux-amd64": [ + "package raesruntime" + ] + }, + "dir": "implementations/go", + "layer": "runtime", + "public": false, + "doc": "Empty bootstrap package; no runtime implementation or exported API.", + "imports": [] + } + ] +} diff --git a/implementations/go/doc.go b/implementations/go/doc.go new file mode 100644 index 0000000..7e5974e --- /dev/null +++ b/implementations/go/doc.go @@ -0,0 +1,3 @@ +// Package raesruntime is reserved for the existing Go runtime extraction. +// Runtime behavior and public APIs are supplied by the coordinated split. +package raesruntime diff --git a/implementations/go/go.mod b/implementations/go/go.mod new file mode 100644 index 0000000..6fd3a31 --- /dev/null +++ b/implementations/go/go.mod @@ -0,0 +1,3 @@ +module github.com/OpenRAE/runtime/implementations/go + +go 1.27.3 diff --git a/styles/RAES/AvoidDismissive.yml b/styles/RAES/AvoidDismissive.yml new file mode 100644 index 0000000..bb57baf --- /dev/null +++ b/styles/RAES/AvoidDismissive.yml @@ -0,0 +1,6 @@ +extends: existence +message: "Remove dismissive wording ('%s') and state the action directly." +level: error +ignorecase: true +tokens: + - '\b(?:simply|just|obviously|trivial(?:ly)?|easily|easy|straightforward)\b' diff --git a/styles/RAES/AvoidHype.yml b/styles/RAES/AvoidHype.yml new file mode 100644 index 0000000..fb9fd70 --- /dev/null +++ b/styles/RAES/AvoidHype.yml @@ -0,0 +1,6 @@ +extends: existence +message: "Replace promotional wording ('%s') with a measurable current-state claim." +level: error +ignorecase: true +tokens: + - '\b(?:powerful|seamless|world-class|production-ready|comprehensive|state[- ]of[- ]the[- ]art)\b' diff --git a/styles/RAES/HeadingCase.yml b/styles/RAES/HeadingCase.yml new file mode 100644 index 0000000..f538bf3 --- /dev/null +++ b/styles/RAES/HeadingCase.yml @@ -0,0 +1,27 @@ +extends: capitalization +message: "Use sentence case for headings: found '%s'; expected '%s'." +level: error +scope: heading +match: $sentence +exceptions: + - Go + - ADR-122 + - MOD-001 + - GOV-928 + - API + # The vocabulary lists lowercase 'backend', so a heading's first word needs this exception. + - Backend + - CLI + - Conformance + - GitHub + - MCP + - OpenSSF + - PyPI + - Python + - RAES + - Reproducible Agentic Environments System + - Release + - Please + - SDL + - SARIF + - Vale diff --git a/styles/RAES/HeadingPunctuation.yml b/styles/RAES/HeadingPunctuation.yml new file mode 100644 index 0000000..02e14d9 --- /dev/null +++ b/styles/RAES/HeadingPunctuation.yml @@ -0,0 +1,7 @@ +extends: existence +message: "Do not end a heading with punctuation." +level: error +scope: heading +nonword: true +tokens: + - '[.!?:;]$' diff --git a/styles/RAES/PlainWords.yml b/styles/RAES/PlainWords.yml new file mode 100644 index 0000000..a8888f1 --- /dev/null +++ b/styles/RAES/PlainWords.yml @@ -0,0 +1,15 @@ +extends: substitution +message: "Use '%s' instead of '%s'." +level: error +ignorecase: true +swap: + '\bin order to\b': to + '\bprior to\b': before + '\bsubsequent to\b': after + '\butili[sz]e\b': use + '\butili[sz]es\b': uses + '\butili[sz]ing\b': using + '\bfacilitate\b': help + '\bleverage\b': use + '\bcommence\b': start + '\bterminate\b': stop diff --git a/styles/RAES/ReadingLevel.yml b/styles/RAES/ReadingLevel.yml new file mode 100644 index 0000000..a81c026 --- /dev/null +++ b/styles/RAES/ReadingLevel.yml @@ -0,0 +1,6 @@ +extends: metric +message: "Keep the Flesch-Kincaid grade level at 11 or below (found %s)." +level: error +formula: | + (0.39 * (words / sentences)) + (11.8 * (syllables / words)) - 15.59 +condition: "> 11.0" diff --git a/styles/RAES/SentenceLength.yml b/styles/RAES/SentenceLength.yml new file mode 100644 index 0000000..62df04b --- /dev/null +++ b/styles/RAES/SentenceLength.yml @@ -0,0 +1,6 @@ +extends: occurrence +message: "Keep sentences to 32 words or fewer (found %s)." +level: error +scope: sentence +max: 32 +token: '\b[\p{L}\p{N}_''-]+\b' diff --git a/styles/config/vocabularies/RAES/accept.txt b/styles/config/vocabularies/RAES/accept.txt new file mode 100644 index 0000000..8c6e819 --- /dev/null +++ b/styles/config/vocabularies/RAES/accept.txt @@ -0,0 +1,26 @@ +autodoc +backend +backends +bestpractices +conformance +Flesch +GitGuardian +intersphinx +libvirt +MyST +nox +OpenSSF +provenance +PyPI +quickstart +Read the Docs +release-please +reStructuredText +SARIF +Scorecard +SDL +Sphinx +toctree +Typer +uv +Vale diff --git a/tools/design-acceptance.sh b/tools/design-acceptance.sh new file mode 100644 index 0000000..3368b0c --- /dev/null +++ b/tools/design-acceptance.sh @@ -0,0 +1,31 @@ +#!/usr/bin/env bash +# Ground Control's exact-case adapter for the native Go JSON test runner. +set -euo pipefail +selection=$(cat) +file=$(jq -er '.test_file | select(type == "string")' <<<"$selection") +name=$(jq -er '.test_name | select(type == "string")' <<<"$selection") +if [[ ! "$name" =~ ^Test[A-Za-z0-9_]+$ || "$file" != implementations/go/*_test.go || "$file" == *..* || ! -f "$file" ]]; then + echo 'Select an existing Go test file and one top-level TestName.' >&2 + exit 2 +fi +resolved=$(realpath "$file") +if [[ "$resolved" != "$(pwd)/implementations/go/"* ]]; then + echo 'The selected test must stay inside the runtime module.' >&2 + exit 2 +fi +log=$(mktemp) +errors=$(mktemp) +trap 'rm -f "$log" "$errors"' EXIT +status=0 +go -C "$(dirname "$file")" test -json -count=1 -run "^${name}$" . >"$log" 2>"$errors" || status=$? +cat "$log" "$errors" >&2 +jq -s --arg name "$name" --argjson exit_code "$status" ' + [.[] | select(.Test == $name and (.Action == "pass" or .Action == "fail" or .Action == "skip"))] as $cases | + {test_name: $name, matches: ($cases | length), + status: (if ($cases | length) == 0 then (if $exit_code == 0 then "missing" else "broken" end) + elif ($cases | length) != 1 then "broken" + elif $cases[0].Action == "skip" then "skipped" + elif $cases[0].Action == "fail" then "failed" + elif $exit_code != 0 then "broken" else "passed" end), + message: ([.[] | select(.Test == $name) | .Output // empty] | join("") | .[:6000])} +' "$log" From 1afb0a4fb12e03a1c31d6bbb8e1e74bb663d2958 Mon Sep 17 00:00:00 2001 From: Brad Edwards Date: Thu, 5 Nov 2026 04:57:00 +0100 Subject: [PATCH 2/2] chore: keep finalization on supported local tooling --- .github/workflows/ground-control-phase-e.yml | 71 -------------------- docs/source-manifest.json | 8 --- 2 files changed, 79 deletions(-) delete mode 100644 .github/workflows/ground-control-phase-e.yml diff --git a/.github/workflows/ground-control-phase-e.yml b/.github/workflows/ground-control-phase-e.yml deleted file mode 100644 index 4c823cd..0000000 --- a/.github/workflows/ground-control-phase-e.yml +++ /dev/null @@ -1,71 +0,0 @@ -name: Ground Control Phase E -# Carries the pull request into the run record, so a dispatch run — which has no -# `pull_requests` association — is still bound to what it finalized (issue #1671). -run-name: Ground Control Phase E for PR ${{ github.event.pull_request.number || inputs.pr }} - -# A merged Ground Control delivery pull request finishes Phase E here, with no model or -# agent session. The agent records a trusted delivery-readiness handoff at Phase D and may -# then terminate permanently; this job is a trigger and a transport. -# -# It holds no `gh` logic, no marker parser, and no completion reconstruction. It passes the -# event's pull-request number to `grndctl finalize-merged-pr`, which resolves the issue from -# the trusted pointer and replays the recorded payload through the incumbent finalizer — so -# the merge gate, the immutable merged-revision requirement verification, the final-report -# marker, and the idempotent close all still apply, unchanged. -# -# It runs no tests, no policy suite, and no review, and it waits for no other post-merge job. -# -# Written by `grndctl init`. The pinned version below is the grndctl that wrote it; bump it -# deliberately rather than tracking a moving tag. - -on: - pull_request: - types: [closed] - branches: [main, dev] - workflow_dispatch: - inputs: - pr: - description: Pull request number to finalize (maintainer repair path) - required: true - type: string - -concurrency: - # Serialize per pull request so a replay cannot race itself. Never cancel: a cancelled - # finalization leaves neither a final report nor a failure record. - group: gc-phase-e-${{ github.event.pull_request.number || inputs.pr }} - cancel-in-progress: false - -permissions: - contents: read - pull-requests: read - # The close gate verifies this job's own run through the Actions API before it accepts an - # automation-authored final-report marker. - actions: read - issues: read - -jobs: - finalize: - if: ${{ github.event_name == 'workflow_dispatch' || github.event.pull_request.merged == true }} - runs-on: ubuntu-latest - permissions: - contents: read - pull-requests: read - actions: read - issues: write - steps: - # The immutable merge revision, never the pull-request head. Phase E reads requirement - # state from the merged tree and executes none of the delivered code; `fetch-depth: 0` - # brings every branch, so the merge commit is present on the dispatch path too. - - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v4 - with: - ref: ${{ github.event.pull_request.merge_commit_sha || github.sha }} - fetch-depth: 0 - persist-credentials: false - - uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0 - with: - node-version: 22 - - name: Finalize the merged delivery - env: - GH_TOKEN: ${{ github.token }} - PR: ${{ github.event.pull_request.number || inputs.pr }} - run: npx --yes grndctl@1.8.1 finalize-merged-pr --pr "$PR" diff --git a/docs/source-manifest.json b/docs/source-manifest.json index 73e7ff0..ed94e41 100644 --- a/docs/source-manifest.json +++ b/docs/source-manifest.json @@ -89,14 +89,6 @@ "destination_path": "styles/config/vocabularies/RAES/accept.txt", "source_blob": "8c6e8195cdce294101d94f4681f951c49d0467ed", "sha256": "f9d4805876464cd7e4454989d86bfc3a6cc35ceadc0f94d15f97255f0115f69b" - }, - { - "source_path": ".github/workflows/ground-control-phase-e.yml", - "destination_path": ".github/workflows/ground-control-phase-e.yml", - "source_blob": "531a311c3dab4aa8c2dde24803cd7fe60f5fcbc7", - "sha256": "95a6af7d680585e7593118c9707f82eabb0334d654902430534c44c44a1775d0", - "source_sha256": "9387dfd281f73f1b074e1d86a7124bacc474c7ed4db5c9ced7de303a4630ccc3", - "transformation": "Use runtime branches and the installed schema-v2-capable Ground Control version; keep the existing finalization flow." } ] }