docs(server): design the compass gateway boot wiring (RIG-2862)

[rigel-mintaka]

Summary

Design record for the compass gateway boot wiring (RIG-2862, remainder). The fork's boot entrypoint still needs a broker, so the published image cannot serve under the stack. This record wires it to the Compass Server doors:

• Fork (compass-gateway): a VerifyAgentToken authorizer, a per-owner CompassAuthCredentialStore pool (lazy open, idle sweep, hasPendingWrites() pin, per-request leases), and a compass boot that calls startAuthGateway directly with a provider/id bundled catalog.
• Stack (compass-server): register the llm-gateway service bearer (service.token), pass the server URL and CA to the container, and start the gateway after the server is ready.
• Order: compass S0 → S1 → S2 → P1. Fork test(compass): SEA-1678 T6 end-to-end + Reload coverage for config passthrough #146 rebase → F1 → F2 → F3 → I1.

Open decisions

Do not merge until OQ1 (catalog) is ruled in RIG-5264. Matt is leaning B (per-owner catalog). B needs no parent amendment, because the stable-name routing record already ratified the resolveModel seam widening.

Resolved (Matt, 2026-10-12):

• OQ2: drop the inbound shared bearer.
• OQ7: A. The container reaches the server at host.containers.internal under pasta:--map-host-loopback on both OSes, with a DNS SAN. Probed on Linux and on a Mac (mattmini, podman 5.8.6 applehv).

Review

A design-critic pass ran before this PR. It found 10 findings, and all were folded in. The darwin network path was promoted to OQ7.

Ledger-impact: three DL rows are proposed in the record's Tasks. They are claimed with bun tools/dl-claim once RIG-5264 is ruled, in this PR, before merge.

Linear: RIG-2862, RIG-5264

[trunk-io]

Merging to main in this repository is managed by Trunk.

• To merge this pull request, check the box to the left or comment /trunk merge below.

After your PR is submitted to the merge queue, this comment will be automatically updated with its status. If the PR fails, failure details will also be posted here

[linear-code]

RIG-2862

[github-actions]

Compass engineering docs preview: https://compass-gateway-rig-2862-boo.compass-eng-docs.pages.dev

Deployed from compass-gateway/rig-2862-boot-wiring-design at 2a8d39a.

Changed pages:

• docs/designs/server/compass-gateway-boot-wiring.md

[rigel-mintaka]

Review result: clean at 552b2554

The review ran 3 rounds: first a single pass, then two fan-outs (correctness, security, design, style). It ended at 0 high, 0 medium, 0 low. Before the review, a design-critic pass made 10 findings; all were folded in, and the darwin network question became OQ7.

Round	Findings	Fixed in
1	Door listen host too broad; managed-plane pointer; missing quoted source	d850025e
2	Gateway dir not created before token ensure; F1 scope/dependency; stale token env name in errors; inbound TLS scope; two-owner isolation test; length	552b2554
3	none	—

Merge gate: OQ1, OQ2 and OQ7 are load-bearing and wait on RIG-5264. Their rulings get folded into the record and DL-rows get claimed before merge.

[rigel-mintaka]

Head is now 30c066b1. The only change since the clean review at 552b2554 is one interface line: CompassOwnerPool.withRequestLease is typed Promise<Response>, to match fork #151, which narrows routeScope the same way. Review stays clean at this head.

[rigel-mintaka]

Head is now fcfeca05.

• 654a86f5 records Matt's RIG-5264 rulings: OQ2 Drop, and OQ7 A, which uses host.containers.internal under pasta:--map-host-loopback with a DNS SAN. It adds the Linux and mattmini probe tables. On darwin, both outbound traffic and -p publish under pasta.
• 6f4060b7 folds in the round-4 fan-out:
  • OQ1-B is split into B1 and B2.
  • The S2 service-token mount moves and drainChildren is reordered.
  • Mount labels are set, the door-host citation and empty host are fixed, and the OQ2 paraphrase and ledger row 1 are qualified.
• fcfeca05 folds in round 5: B1's seam covers all 7 route handlers that call resolveModel.

Review: round 4 was a fan-out with 10 accepted findings; the two date findings were invalid. Round 5 verified those fixes and found 1 medium, which is fixed in fcfeca05. Open: 0 high, 0 medium. rumdl clean, design-ledger-gate OK.

Still blocked on OQ1 (A, or B1/B2) in RIG-5264. The DL rows get claimed when it is ruled.

[rigel-mintaka]

Head is now 2a8d39a1.

• 977ce3f9 adds a host floor for OQ7-A: passt 2024-08-21 or newer, because --map-host-loopback is not in Ubuntu 24.04's passt. It also adds an S2 network preflight, and I1 pins the runner to ubuntu-26.04.
• e12cf76c fixes round 6:
  • the preflight runs --entrypoint /usr/bin/tini <image> --version, because the image's tini entrypoint would otherwise swallow --version;
  • I1 names the compass release.yml and the pinned Go step (draft feat(gateway-image): smoke the broker-free Compass boot (RIG-2862) #2233).
• 2a8d39a1 adds links for the evidence (round 7, low).

Review:

Round	Found	Status
6	1 high, 1 medium, 1 low	fixed
7	1 low	fixed

Open: 0 high, 0 medium. A reviewer smoke-ran the preflight argv on the local gateway image, and it printed tini version 0.19.0. rumdl is clean and design-ledger-gate is OK.

Still waiting on OQ1 in RIG-5264.