Repository navigation
docs: Define the Galactic Worker contract and host ownership - #1445
Merged
Merged
Conversation
Galactic has no node-local API for service agents, and many processes write shared host state through their own locks, or none. Epic #1430 replaces that with one Worker per node, and every later Task builds against a written contract. The new docs/worker pages record: - the claim API: request, observe, update and release, keyed by caller, node, VPC and attachment UID, with generations, separate desired, programmed and observed state, five worked transitions, and the approved transport, identity and access model - one mutation authority per class of host state: the owner of the scope's fence in internal/edge/ownership where several processes write, or the only writer otherwise, with today's writers and the step that moves each one; CNI writes with Exclusive so workload attach still works while Worker is down - galactic-edge as the provider connector, behind a Worker-backed agent.Datapath, instead of a new binary - the integration branch workflow, including why the branch starts from an empty commit: a branch push at the main SHA would overwrite main's multi-architecture v0.0.0-<sha> images with amd64-only ones - the qualification platform, comparison method and confirmed limits Two existing writers bypass any shared lock: the galactic-vrf sidecar's BGPVRFInstance write, and five processes writing egress_route_table. Both are listed as transfer steps. Fixes: #1431 Co-Authored-By: Claude <claude@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Galactic has no node-local API for service agents, and shared host state is written by many processes with separate locks or none.
This adds the Worker design pages that every Task of epic #1430 implements against. They cover the claim API with five worked transitions, one mutation authority per class of host state, the connector decision, the branch workflow and the qualification plan.
Transport, socket access, NIC and numeric limits were confirmed on 2026-11-18, and the remaining contract details are open to review here.
Branch evidence
The integration branch starts from a signed empty commit on top of the planning baseline, so its image tags never collide with tags main already published.
The publish run for that push published only the two integration-branch tags and the start commit's own tag, with no release and nothing tagged for main: https://github.com/datum-cloud/galactic/actions/runs/44399031276
Test plan
Fixes #1431