feat(runtime): add Runtime 12 single-public-port embedded stack

[seakee]

Summary

Runtime 12 adds a stateless Go Ingress and one Embedded Compose stack whose only default host mapping is CPAMP :18317. It packages checksum-pinned CPA v7.3.3 behind the existing Runtime Supervisor while preserving typed lifecycle, readiness, recovery, process, secret, storage, and failure-domain boundaries.

The implementation is limited to Runtime 12 deployment wiring. It does not add Runtime 13 Manager mutation/reconcile, boot auto-start, dynamic controlBasePath, Full Web/Public API v2, updater, or native packaging.

Scope

• Frontend panel
• Manager Server
• CPA panel mode
• Full Docker mode
• Native packages / release
• Docs / Wiki
• CI / build / tooling

Changes

• Add the stdlib-only cpamp-ingress executable/image with a centralized transitional ControlMatcher: current proven Manager paths route to Manager and everything else routes directly to Gateway. Replacing that matcher with one effective controlBasePath matcher does not change proxy or Compose topology.
• Preserve transparent request/response streaming, SSE flushes, WebSocket upgrades, cancellation/backpressure, Host/Authorization/User-Agent/body semantics, and rebuild trusted forwarding headers after removing client-supplied forwarding metadata. Internal upstream transport ignores environment HTTP proxies.
• Add a unified three-service Compose stack. Only Ingress publishes ${CPAMP_PUBLIC_PORT:-18317}:18317; Manager 18317, Gateway 8317, and Supervisor 9081 remain internal.
• Add a dedicated Runtime image with Supervisor as PID 1 and checksum-pinned official CPA v7.3.3 artifacts. Entrypoint/Compose bootstrap internal state but never start CPA; only the existing typed durable Start operation can spawn it.
• Bootstrap a persistent high-entropy Runtime transport secret into a dedicated volume with mode 0600; Runtime has write access, Manager has read-only access for the Runtime 13 adapter seam, and Ingress receives no secret or data volume.
• Keep Manager data, Runtime Supervisor journal state, and Runtime Gateway config/auth/log/plugin state under separate ownership. The Gateway seed contains no Management Key, API key, provider credential, or sample secret.
• Extend PR classification and required CI with Ingress full/race/vet/stdlib/portability checks, Supervisor race coverage, two-architecture Runtime/Ingress image builds, fail-closed Compose architecture validation, and real single-public-port Docker smoke.
• Amend ADR-0001 with the accepted single-public-ingress and failure-domain facts. ADR-0004 is unchanged.

/healthz ownership: Ingress has no /healthz special case and this PR does not establish a public CPAMP /healthz contract. CPA /healthz remains the Supervisor's loopback readiness probe at 127.0.0.1:8317; public Data Plane smoke uses /v1/models. Unknown paths continue through the generic Gateway fallback, including any current Gateway path, without assigning long-term public ownership to /healthz.

Historical Asset Review

Reviewed feat/integrated-cpa-runtime only for package/network mechanics, architecture mapping, checksum fail-closed behavior, and image engineering history. This implementation rejects the historical Manager-owned runtime/model proxy, multiple public ports, dynamic updater, shared Manager state, and Docker-socket design. No material historical code was copied, so no additional attribution is required.

User Impact

The v2 Embedded Docker topology now has one public endpoint on port 18317 for both transitional Manager routes and Gateway/model traffic. This is foundation wiring for independent acceptance; Runtime 13 reconciliation and the final user installation/configuration flow remain intentionally absent.

Compatibility / Runtime Notes

• CPA panel mode: unchanged; standalone/CPA-hosted Panel Lite remains outside this Runtime 12 stack.
• Manager Server mode: the existing docker-compose.manager.yml remains valid and was revalidated. Transitional /, /management.html, /health, /status, /setup, /usage-service/*, and /v0/management/* routing is compatibility evidence only.
• Full Docker / native packages: root docker-compose.yml defines the new Embedded stack; native packages are unchanged. CPA child working directory is /runtime/gateway.
• Public/internal topology: public Ingress :18317; internal Manager :18317, Gateway :8317, Supervisor :9081.
• CPA artifacts: linux/amd64 SHA256 7af8c99cd08eee3ccc81d1596e8a31785674d3de6bd7ec61416d59493dd8fc01; linux/arm64 uses official aarch64 SHA256 5f320e3fae52af00f07b78201311e9d096b36e759441d948de48a10f49e71883.

Data / Security Notes

The Runtime transport token is generated from /dev/urandom, validated at a minimum of 32 bytes, atomically installed, persisted across restart/recreate, and fails closed if an explicit CI token conflicts with the existing source. The Compose validator rejects host networking, privileged services, and Docker socket mounts across every service. The token is separate from Manager /data, data.key, the Supervisor journal, Gateway state, CPA Management Key, and provider credentials.

Volumes remain narrowly owned: cpamp-manager-data:/data; cpamp-runtime-data:/runtime with /runtime/supervisor and /runtime/gateway; and cpamp-runtime-transport-secret:/run/cpamp/runtime-secret writable by Runtime and read-only to Manager. Ingress mounts no volume or secret.

Risk / Rollback

Risk level: Medium

Rollback notes: revert the two Runtime 12 commits to remove the new root Compose stack, Ingress, Runtime packaging, acceptance guards, and CI wiring. No database migration or user data rewrite is performed. Existing Manager-only Compose remains independent.

Verification

• Type check
• Lint
• Tests
• Build
• Manual UI check
• Docs/link check
• Not applicable, docs-only

Commands / evidence:

Ingress:
  go test ./...
  go test -race ./...
  go vet ./...
  CGO_ENABLED=0 GOOS=linux GOARCH={amd64,arm64} go build ./cmd/cpamp-ingress
  deterministic response/request streaming, SSE, WebSocket, cancellation,
  forwarding-header, decoded-route, and classifier replacement-seam tests passed

Runtime Supervisor:
  go test ./...
  go test -race ./...
  go vet ./...
  linux/amd64, linux/arm64, windows/amd64 portability builds passed
  runtime architecture-boundary test and validator passed

Manager/repository:
  Manager go test ./... and go vet ./... passed
  npm run test:repo: 11 files / 218 tests passed
  npm run type-check passed
  npm run lint passed with 5 pre-existing warnings and no errors
  PR classifier: 23 tests passed
  Prettier check and workflow YAML parse passed

Docker/Compose:
  Dockerfile.runtime built for amd64 and arm64; both official CPA checksums reported OK
  production Compose validator proved one host mapping, Ingress 18317:18317
  existing docker-compose.manager.yml parsed successfully
  fresh stack: offline / recovery inactive; stack and Runtime restart did not auto-start CPA
  generated secret remained unchanged across Runtime restart and force-recreate
  an edited existing Gateway config remained unchanged across force-recreate
  recreate remained offline / recovery inactive and did not auto-start CPA
  Supervisor was PID 1; CPA child cwd was /runtime/gateway
  typed Start -> ready kept runtimeGeneration unchanged and armed recovery
  public /v1/models -> typed Stop -> offline kept generation unchanged and disarmed recovery
  stopping Manager did not interrupt the running public Gateway route
  stopping Runtime/Gateway did not interrupt public Manager /health
  negative validator probes rejected Ingress host networking, privileged Manager,
  and Runtime Docker socket mounts

Final hygiene:
  git diff --cached --check / git show --check passed
  worktree clean after commit

The Docker registry briefly returned invalid character 'H' looking for beginning of value while resolving base-image metadata. Pulling the same pinned architecture base images and rerunning the unchanged build succeeded; all final builds and smoke checks passed.

Screenshots / Recordings

N/A — backend, proxy, packaging, architecture, and CI changes only; no visible UI implementation is included.

Docs

• README / README_CN updated for user-visible capabilities
• Matching docs manual and navigation updated
• Demo fixtures, screenshots, and deep links reviewed
• Release notes needed
• Not needed — explanation included below

Docs decision: ADR-0001 records the durable Runtime architecture facts. The 1.x user docs are not updated because Runtime 12 deliberately lacks Runtime 13 desired-state reconciliation and must not be advertised as the final installation flow.

Related

N/A