Mesh Propagation — Artifact Distribution

This document covers the three-tier artifact source resolution strategy and mesh-based artifact propagation for fleet rollouts.

Overview

Artifacts (OCI images, lock files, policy bundles) needed for rollout activation are resolved through a three-tier strategy:

  1. Verified local cache — instant, no network

  2. Reachable mesh peer — LAN relay, lower latency

  3. Registry fallback — WAN, always available

Critical invariant: mesh propagation distributes bytes only. It never grants activation permission. Verification is always local and mandatory after peer or registry fetch, before any activation can proceed.

Source Resolution

SourceResolver (runtime/source_resolver.go) implements the strategy:

Tier 1: Local Cache

If a LocalCacheChecker is configured and HasVerifiedArtifact(ref) returns true, the artifact is used immediately. No network access needed.

Tier 2: Mesh Peer Relay

If PeerFetcher is configured and MeshHints include peer relay nodes:

  1. Filter peers through PeerReachable probe

  2. For each reachable peer, call FetchFromPeer(ctx, peer, ref)

  3. On fetch success, verify locally using the configured Verifier

  4. Emit artifact_source_peer telemetry event

If a peer-fetched artifact fails verification, try the next peer.

Tier 3: Registry Fallback

If all peers fail (or none are configured):

  1. Call RegistryFetcher.FetchFromRegistry(ctx, ref)

  2. Verify locally using the configured Verifier

  3. Emit artifact_source_registry telemetry event

Fail-Closed Verification

If any fetch source is configured (peer or registry) but Verifier or PubKeyPath is missing, the resolver returns an error immediately. Fetched artifacts are never used without verification.

Configuration

SourceResolverConfig fields:

Field

Type

Required

Description

LocalCache

LocalCacheChecker

No

Checks for verified local copy

PeerFetcher

PeerFetcher

No

Fetches from mesh peers

RegistryFetcher

RegistryFetcher

No

Fetches from OCI registry

Verifier

Verifier

Yes*

Verifies fetched artifacts

PubKeyPath

string

Yes*

Cosign public key path

PeerReachable

func(string) bool

No

Probes peer reachability

*Required when PeerFetcher or RegistryFetcher is configured.

Mesh Hints

MeshHints are delivered alongside rollout poll responses from the control plane. They include:

  • PeerRelayNodes — list of peer node IDs that have the artifact available

  • RegistryRef — the canonical OCI registry reference

Peer selection uses SelectReachablePeers() which filters the hints through the PeerReachable probe.

Edge Relay Configuration

The edge relay subsystem (edge/config/config.go) controls outbound multi-peer relay behavior:

Field

Type

Description

SuccessCondition

string

"one_peer" (default) or "all_peers"

EvictOnRelay

bool

Evict segment immediately on relay success

WorkerCount

int

Concurrent relay executor goroutines

DialTimeoutSeconds

int

Max dial time for outbound relay

AckTimeoutSeconds

int

Max wait for peer ACK after send

Artifact Availability Tracking

The control plane tracks artifact availability per-node in the artifact_availability table:

CREATE TABLE IF NOT EXISTS artifact_availability (
    plan_id              TEXT    NOT NULL,
    artifact_fingerprint TEXT    NOT NULL,
    node_id              TEXT    NOT NULL,
    locally_available    INTEGER NOT NULL DEFAULT 0,
    peer_available       INTEGER NOT NULL DEFAULT 0,
    relay_status         TEXT    NOT NULL DEFAULT 'not_started',
    last_seen_peer_id    TEXT,
    peer_count           INTEGER NOT NULL DEFAULT 0,
    updated_at           TEXT    NOT NULL,
    PRIMARY KEY (plan_id, node_id)
);

This data is advisory (read-only observability surface). It does not affect activation eligibility.

Telemetry Events

Artifact distribution events are emitted as EventKindRollout with attrs["phase"] set to the phase constant:

Phase Constant

Value

When

RolloutPhaseArtifactSourcePeer

artifact_source_peer

Artifact fetched from mesh peer

RolloutPhaseArtifactSourceRegistry

artifact_source_registry

Artifact fetched from registry

RolloutPhaseArtifactDiscoveredPeer

artifact_discovered_peer

Peer identified as source

RolloutPhaseArtifactFetchStarted

artifact_fetch_started

Fetch initiated

RolloutPhaseArtifactFetchSucceeded

artifact_fetch_succeeded

Artifact received and verified

RolloutPhaseArtifactFetchFailed

artifact_fetch_failed

Fetch attempt failed

RolloutPhaseArtifactFallbackRegistry

artifact_fallback_registry

Falling back from peer to registry

RolloutPhaseArtifactRelayDeadlettered

artifact_relay_deadlettered

Relay retries exhausted

Additional attributes on source events:

  • artifact_ref — the OCI artifact reference

  • source — "mesh_peer" or "registry"

  • peer_node_id — the peer’s node ID (peer source only)