Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 11 additions & 0 deletions .gc/plan-rules.md
Original file line number Diff line number Diff line change
@@ -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.
1 change: 1 addition & 0 deletions .github/CODEOWNERS
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
* @Brad-Edwards
106 changes: 106 additions & 0 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
@@ -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)'
3 changes: 3 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -31,3 +31,6 @@ go.work.sum
# Editor/IDE
# .idea/
# .vscode/

# Local tools and build products
.tools/
44 changes: 44 additions & 0 deletions .ground-control.yaml
Original file line number Diff line number Diff line change
@@ -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
11 changes: 11 additions & 0 deletions .mcp.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
{
"mcpServers": {
"ground-control": {
"type": "stdio",
"command": "grndctl",
"args": [
"mcp"
]
}
}
}
10 changes: 10 additions & 0 deletions .vale.ini
Original file line number Diff line number Diff line change
@@ -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
12 changes: 12 additions & 0 deletions AGENTS.md
Original file line number Diff line number Diff line change
@@ -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.
27 changes: 27 additions & 0 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
@@ -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.
74 changes: 74 additions & 0 deletions Makefile
Original file line number Diff line number Diff line change
@@ -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
14 changes: 13 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
@@ -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).
10 changes: 10 additions & 0 deletions THIRD_PARTY_NOTICES.md
Original file line number Diff line number Diff line change
@@ -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.
58 changes: 58 additions & 0 deletions docs/architecture.md
Original file line number Diff line number Diff line change
@@ -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.

<!-- go-api implementations/go a236139039bc9e8534511663c21517cf76d3d13a00b1843ad5e92aa072688666 -->

<!-- go-view -->

| 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` |
<!-- go-component runtime 3573009f51627c9651e859af77206fbcbaff12ce92a6dd4be61dcfc98b3645d3 -->

<!-- /go-view -->
Loading
Loading