feat(supervisor): stage gateway configuration snapshot delivery

[pimlock]

Summary

Add Stage 1 of gateway-pushed configuration over ConnectSupervisor. The gateway sends complete sandbox configuration and provider-environment snapshots; supervisors receive them while polling remains authoritative.

Configuration delivery flow

flowchart TD
    A[Configuration mutation] --> B[Commit authoritative state]
    B --> C[Notify scheduler of affected scope and component]
    C --> D[Coalesce notifications and build latest full snapshot]
    D --> E[Push snapshot over ConnectSupervisor]
    E --> F[Supervisor receives but ignores snapshot in Stage 1]
    B --> G[Existing polling path]
    G --> H[Supervisor applies configuration]

Loading

Related Issue

Part of #1731. Replaces #2967. Stage 2 will apply snapshots and acknowledge revisions; Stage 3 will add durable completion semantics and remove polling.

Changes

• Add bootstrap, snapshot, and acknowledgement contracts with gateway/supervisor protocol revision checks.
• Share read-only snapshot builders between polling and push delivery.
• Route committed updates through an async interface with ordered, coalesced delivery, bounded fanout, and payload limits. Remote-owner routing follows in feat(kubernetes): support HA gateway rebalancing #1868.
• Initialize policy history atomically without overwriting existing apply results.
• Update architecture, compatibility documentation, and generated bindings.

Testing

• Pre-commit and full local CI
• Go and TypeScript SDK CI
• Docker conformance and all four live-policy-update E2E tests

Postgres-specific concurrency coverage requires OPENSHELL_TEST_POSTGRES_URL and was not run.

Checklist

• Conventional Commits and DCO sign-off
• Architecture docs updated

[github-actions]

🌿 Preview your docs: https://nvidia-preview-pr-3244.docs.buildwithfern.com/openshell

[copy-pr-bot]

This pull request requires additional validation before any workflows can run on NVIDIA's runners.

Pull request vetters can view their responsibilities here.

Contributors can view more details about this message here.

[github-actions]

Label test:e2e applied for e7729ec. Open the existing run and click Re-run all jobs to execute with the label set. The run will execute the standard E2E suite after building the required gateway and supervisor images once. The matching required CI gate status on this PR will flip green automatically once the run finishes.

[github-actions]

All contributors have signed the DCO ✍️ ✅
_{Posted by the DCO Assistant Lite bot.}

[pimlock]

gator-agent

PR Review Status

I reconciled the current head against the full Gator feedback ledger and reviewed the author-only delta since bd9f91e5 in critical-only mode. The range-diff shows all ten PR-authored commits are patch-identical after the merge from main, the earlier fanout-bounding obligation remains resolved, and no new Critical defect was found. Current-head Branch Checks and E2E workflows are running.

Blocking findings:

• No blocking findings remain

Carried findings:

• None

Gator metadata

• Validation: Project-valid Stage 1 of accepted issue #1731; the effective PR patch remains within the reviewed gateway/supervisor configuration-delivery scope.
• Docs: Architecture and Fern gateway-reference documentation remain included for the current behavior.
• Checks: OpenShell Helm Lint and Trivy Changes are green; Branch Checks and E2E are pending on the current head.
• E2E: test:e2e and test:e2e-kubernetes are applied; the current-head Branch E2E Checks workflow is running.
• Head SHA: 8dfe13b575a931586a5bb26238230227bdc40d82
• Base SHA: fa0bfa490e42c87a74a70be6ebb40faee7fb8faa
• Merge base SHA: fa0bfa490e42c87a74a70be6ebb40faee7fb8faa
• Patch ID: ca184a2ffbb6b7e1d73cbd0fc2a97533eca331e3
• Gator payload: 9
• Review mode: critical_only
• Previous reviewed SHA: bd9f91e593c2096542599aebaad43a2c179426e9
• Review budget exhausted: yes
• Maintainer decision required: no
• Next state: gator:watch-pipeline