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 8bf93ead in critical-only mode. The earlier fanout-bounding obligation remains resolved, the new delta only updates the repairable invalid-policy snapshot test after upstream integration, and no new Critical defect was found. Required current-head checks, including E2E, are green.

Action required: a maintainer must review and approve the PR.

Blocking findings:

• No blocking findings remain

Carried findings:

• None

Gator metadata

• Validation: Project-valid Stage 1 of accepted issue #1731; the current implementation remains within the reviewed gateway/supervisor configuration-delivery scope.
• Docs: Architecture, gateway reference, and troubleshooting guidance are updated for the current behavior.
• Checks: OpenShell Branch Checks, Helm Lint, Trivy Changes, DCO, and E2E are green for the current head.
• E2E: test:e2e is applied and the current-head E2E suite completed successfully.
• Head SHA: bd9f91e593c2096542599aebaad43a2c179426e9
• Base SHA: d91b1999a0f26c07b652652fcc3475bf3388d2c6
• Merge base SHA: d91b1999a0f26c07b652652fcc3475bf3388d2c6
• Patch ID: 07916ac6bfc22b10c3571859fce1a82996b3149b
• Gator payload: 9
• Review mode: critical_only
• Previous reviewed SHA: 8bf93eadd823357a2adaed5621b63dca63e6dc91
• Review budget exhausted: yes
• Maintainer decision required: no
• Next state: gator:approval-needed