feat(control-plane): add runtime operations and shared workspaces

.dockerignore

@@ -4,11 +4,15 @@
 .githooks/
 .agents/
 .codex/
+.local/
+.playwright-cli/
 
 # Local runtime state and credentials must never enter the build context.
 .colossus/
 **/.env
 **/.env.*
+**/development-credentials/
+**/.authority-key.env
 **/.aws/
 **/.ssh/
 **/.git-credentials

.github/workflows/control-plane-image.yml

@@ -0,0 +1,110 @@
+name: Publish Control Plane image
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: Published stable or preview release tag
+        required: true
+        type: string
+  pull_request:
+    paths:
+      - .github/workflows/control-plane-image.yml
+      - scripts/ci/*control-plane*.mjs
+      - scripts/ci/publish-control-plane-image.sh
+
+permissions: {}
+
+concurrency:
+  group: control-plane-image-${{ github.event.release.tag_name || inputs.tag || github.event.pull_request.number }}
+  cancel-in-progress: false
+
+jobs:
+  publisher-revision:
+    name: Resolve the protected main publisher
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    permissions:
+      contents: read
+    outputs:
+      revision: ${{ steps.publisher.outputs.revision }}
+    steps:
+      - name: Use proposed code for tests or protected main for publication
+        id: publisher
+        env:
+          GH_TOKEN: ${{ github.token }}
+          EVENT_NAME: ${{ github.event_name }}
+        shell: bash
+        run: |
+          set -euo pipefail
+          if [[ "$EVENT_NAME" == pull_request ]]; then
+            revision="$GITHUB_SHA"
+          else
+            revision=$(gh api repos/obscuritylabs/Colossus/git/ref/heads/main --jq .object.sha)
+          fi
+          [[ "$revision" =~ ^[0-9a-f]{40}$ ]]
+          printf 'revision=%s\n' "$revision" >> "$GITHUB_OUTPUT"
+
+  contracts:
+    needs: publisher-revision
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          ref: ${{ needs.publisher-revision.outputs.revision }}
+          persist-credentials: false
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
+        with:
+          node-version: 22.18.0
+      - run: node --test scripts/ci/control-plane-assets.test.mjs
+      - run: bash -n scripts/ci/publish-control-plane-image.sh
+
+  publish:
+    name: Publish the exact tested multi-platform server
+    needs: [publisher-revision, contracts]
+    if: >-
+      github.repository == 'obscuritylabs/Colossus' &&
+      ((github.event_name == 'release' && github.event.release.draft == false) ||
+       (github.event_name == 'workflow_dispatch' && github.ref == 'refs/heads/main'))
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    permissions:
+      actions: read
+      contents: read
+      packages: write
+    steps:
+      - name: Use the same protected publisher revision that passed contracts
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          ref: ${{ needs.publisher-revision.outputs.revision }}
+          fetch-depth: 0
+          persist-credentials: false
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
+        with:
+          node-version: 22.18.0
+      - name: Authenticate with a job-scoped registry token
+        env:
+          GHCR_TOKEN: ${{ github.token }}
+          GHCR_USER: ${{ github.actor }}
+        run: printf '%s' "$GHCR_TOKEN" | docker login ghcr.io --username "$GHCR_USER" --password-stdin
+      - name: Verify release bytes against trusted tag artifacts and publish
+        env:
+          GH_TOKEN: ${{ github.token }}
+          RELEASE_TAG: ${{ github.event.release.tag_name || inputs.tag }}
+        run: bash scripts/ci/publish-control-plane-image.sh
+      - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: colossus-control-plane-publication
+          path: |
+            ${{ runner.temp }}/control-plane-image/publication.json
+            ${{ runner.temp }}/control-plane-image/assets.json
+          if-no-files-found: error
+          retention-days: 30
+      - name: Remove the job-scoped registry session
+        if: always()
+        run: docker logout ghcr.io

.github/workflows/documentation-candidate.yml

@@ -0,0 +1,123 @@
+name: Documentation image candidate
+
+on:
+  push:
+    tags: ["v*"]
+  pull_request:
+    paths:
+      - .github/workflows/documentation-candidate.yml
+      - .github/workflows/documentation-image.yml
+      - .dockerignore
+      - deploy/documentation/**
+      - docs/**
+      - documentation/legacy-routes.tsv
+      - scripts/docs-site
+      - scripts/generate-doc-redirects
+      - scripts/ci/documentation-*.mjs
+      - scripts/ci/publish-documentation-image.sh
+      - scripts/ci/verify-control-plane-assets.mjs
+      - zensical.toml
+
+permissions: {}
+
+concurrency:
+  group: documentation-candidate-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  source:
+    name: Verify documentation candidate source
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    permissions:
+      contents: read
+    outputs:
+      tag: ${{ steps.source.outputs.tag }}
+      commit: ${{ steps.source.outputs.commit }}
+      epoch: ${{ steps.source.outputs.epoch }}
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
+        with:
+          node-version: 22.18.0
+      - name: Bind the annotated release tag to protected main
+        id: source
+        env:
+          EVENT_NAME: ${{ github.event_name }}
+          SOURCE_TAG: ${{ github.ref_name }}
+        shell: bash
+        run: |
+          set -euo pipefail
+          commit=$(git rev-parse HEAD)
+          tag=v0.0.0-preview.1
+          if [[ "$EVENT_NAME" == push ]]; then
+            tag="$SOURCE_TAG"
+            node --input-type=module - "$tag" "$commit" <<'JS'
+          import { validateRequest } from './scripts/ci/verify-control-plane-assets.mjs';
+          validateRequest(process.argv[2], process.argv[3]);
+          JS
+            git fetch origin refs/heads/main:refs/remotes/origin/main "refs/tags/$tag:refs/tags/$tag"
+            test "$(git cat-file -t "$tag")" = tag
+            test "$(git rev-parse "$tag^{commit}")" = "$commit"
+            git merge-base --is-ancestor "$commit" origin/main
+          fi
+          printf 'tag=%s\ncommit=%s\nepoch=%s\n' "$tag" "$commit" "$(git show -s --format=%ct "$commit")" >> "$GITHUB_OUTPUT"
+      - run: node --test scripts/ci/documentation-candidate.test.mjs
+      - run: bash -n scripts/ci/publish-documentation-image.sh
+
+  candidate:
+    name: Build and smoke linux/${{ matrix.arch }} documentation
+    needs: source
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - arch: amd64
+            runner: ubuntu-24.04
+          - arch: arm64
+            runner: ubuntu-24.04-arm
+    runs-on: ${{ matrix.runner }}
+    timeout-minutes: 20
+    permissions:
+      contents: read
+    env:
+      SOURCE_TAG: ${{ needs.source.outputs.tag }}
+      SOURCE_COMMIT: ${{ needs.source.outputs.commit }}
+      SOURCE_DATE_EPOCH: ${{ needs.source.outputs.epoch }}
+      IMAGE_ARCH: ${{ matrix.arch }}
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          ref: ${{ needs.source.outputs.commit }}
+          persist-credentials: false
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
+        with:
+          node-version: 22.18.0
+      - name: Build exact-source documentation without registry credentials
+        run: |
+          docker build --platform "linux/$IMAGE_ARCH" \
+            --build-arg "COLOSSUS_VERSION=$SOURCE_TAG" \
+            --build-arg "COLOSSUS_REVISION=$SOURCE_COMMIT" \
+            --build-arg "SOURCE_DATE_EPOCH=$SOURCE_DATE_EPOCH" \
+            --tag colossus-documentation:candidate \
+            --file deploy/documentation/Dockerfile .
+      - name: Test browse, search, portable links, and hardened runtime
+        run: node deploy/documentation/smoke.mjs colossus-documentation:candidate
+      - name: Retain only the actual tested image and source-bound candidate
+        shell: bash
+        run: |
+          set -euo pipefail
+          candidate_output="$RUNNER_TEMP/documentation-candidate"
+          mkdir -p "$candidate_output"
+          docker save colossus-documentation:candidate | gzip -n > "$candidate_output/Colossus-Documentation-${SOURCE_TAG}-linux-${IMAGE_ARCH}.docker.tar.gz"
+          node scripts/ci/documentation-candidate.mjs create "$candidate_output" "$SOURCE_TAG" "$SOURCE_COMMIT" "$IMAGE_ARCH"
+      - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        if: github.event_name == 'push'
+        with:
+          name: colossus-documentation-${{ matrix.arch }}
+          path: ${{ runner.temp }}/documentation-candidate/*
+          if-no-files-found: error
+          retention-days: 30

.github/workflows/documentation-image.yml

@@ -0,0 +1,112 @@
+name: Publish Documentation image
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: Published stable or preview release tag
+        required: true
+        type: string
+  pull_request:
+    paths:
+      - .github/workflows/documentation-image.yml
+      - scripts/ci/documentation-*.mjs
+      - scripts/ci/publish-documentation-image.sh
+
+permissions: {}
+
+concurrency:
+  group: documentation-image-${{ github.event.release.tag_name || inputs.tag || github.event.pull_request.number }}
+  cancel-in-progress: false
+
+jobs:
+  publisher-revision:
+    name: Resolve the protected main publisher
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    permissions:
+      contents: read
+    outputs:
+      revision: ${{ steps.publisher.outputs.revision }}
+    steps:
+      - name: Use proposed code for tests or protected main for publication
+        id: publisher
+        env:
+          GH_TOKEN: ${{ github.token }}
+          EVENT_NAME: ${{ github.event_name }}
+        shell: bash
+        run: |
+          set -euo pipefail
+          if [[ "$EVENT_NAME" == pull_request ]]; then
+            revision="$GITHUB_SHA"
+          else
+            revision=$(gh api repos/obscuritylabs/Colossus/git/ref/heads/main --jq .object.sha)
+          fi
+          [[ "$revision" =~ ^[0-9a-f]{40}$ ]]
+          printf 'revision=%s\n' "$revision" >> "$GITHUB_OUTPUT"
+
+  contracts:
+    name: Verify immutable documentation publication contracts
+    needs: publisher-revision
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          ref: ${{ needs.publisher-revision.outputs.revision }}
+          persist-credentials: false
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
+        with:
+          node-version: 22.18.0
+      - run: node --test scripts/ci/documentation-candidate.test.mjs
+      - run: bash -n scripts/ci/publish-documentation-image.sh
+
+  publish:
+    name: Publish the tested documentation platform index
+    needs: [publisher-revision, contracts]
+    if: >-
+      github.repository == 'obscuritylabs/Colossus' &&
+      ((github.event_name == 'release' && github.event.release.draft == false) ||
+       (github.event_name == 'workflow_dispatch' && github.ref == 'refs/heads/main'))
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    permissions:
+      actions: read
+      contents: read
+      packages: write
+    steps:
+      - name: Use the same protected publisher revision that passed contracts
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          ref: ${{ needs.publisher-revision.outputs.revision }}
+          fetch-depth: 0
+          persist-credentials: false
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
+        with:
+          node-version: 22.18.0
+      - name: Authenticate with a job-scoped package token
+        env:
+          GHCR_TOKEN: ${{ github.token }}
+          GHCR_USER: ${{ github.actor }}
+        run: printf '%s' "$GHCR_TOKEN" | docker login ghcr.io --username "$GHCR_USER" --password-stdin
+      - name: Verify release provenance, retained tested candidates, and immutable publication
+        env:
+          GH_TOKEN: ${{ github.token }}
+          RELEASE_TAG: ${{ github.event.release.tag_name || inputs.tag }}
+        run: bash scripts/ci/publish-documentation-image.sh
+      - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: colossus-documentation-publication-${{ github.event.release.tag_name || inputs.tag }}
+          path: |
+            ${{ runner.temp }}/documentation-image/publication.json
+            ${{ runner.temp }}/documentation-image/provenance.json
+            ${{ runner.temp }}/documentation-image/trusted/*.json
+          if-no-files-found: error
+          retention-days: 30
+      - name: Remove the job-scoped registry session
+        if: always()
+        run: docker logout ghcr.io