@checkstack/satellite-backend 0.3.6 → 0.5.0

package/src/heartbeat-monitor.ts

@@ -1,70 +1,141 @@
 import type { Logger } from "@checkstack/backend-api";
 import type { SignalService } from "@checkstack/signal-common";
 import type { SatelliteService } from "./service";
-import {
-  SATELLITE_STATUS_CHANGED,
-  OFFLINE_THRESHOLD_MS,
-} from "@checkstack/satellite-common";
+import type { SatelliteConnectionEvent } from "./entity";
+import { computeStatus } from "./status";
+import { SATELLITE_STATUS_CHANGED } from "@checkstack/satellite-common";
 
 /**
- * Monitors satellite heartbeats and broadcasts status change signals.
- * Tracks previous state in-memory to detect transitions (online → offline, offline → online).
+ * Plug-point for driving the heartbeat-lost (`online` → `offline`) edge into
+ * the reactive `satellite-connection` entity (reactive automation engine
+ * §10.6). Bound from `afterPluginsReady`; when not provided, no entity state is
+ * mirrored.
+ *
+ * The monitor flips ONLY `lastConnectionEvent` to `"heartbeat_lost"` (leaving
+ * the already-aged `lastHeartbeatAt` untouched, since it is what made the
+ * computed status `offline` in the first place). The change-deriver re-fires
+ * `satellite.heartbeat_lost`. The opposite edge (offline→online) is mirrored as
+ * `connected` by the WS handler on reconnect, so the monitor leaves it alone.
+ */
+export interface SatelliteHeartbeatEntitySink {
+  mirror: (satelliteId: string) => Promise<void>;
+}
+
+/**
+ * Monitors satellite heartbeats and detects the online→offline transition from
+ * DURABLE state alone — no pod-local baseline.
+ *
+ * ## Horizontal-scale correctness
+ *
+ * The heartbeat-check job runs under ONE consumer group claimed by a VARYING
+ * pod. A process-local "previous status" map is therefore wrong: a pod with an
+ * empty map never sees the online→offline edge, so `connectionStatus` could get
+ * stuck `online` forever after a pod crash. This monitor instead reads every
+ * satellite's durable `(lastHeartbeatAt, lastConnectionEvent)`, computes status
+ * via {@link computeStatus} (the same wall-clock liveness rule the entity read
+ * uses), and detects the heartbeat-lost edge purely from durable state:
+ *
+ *   computed status is `offline` AND `lastConnectionEvent === "connected"`
+ *     ⇒ this satellite just lost its heartbeat (it was last marked connected,
+ *       but its heartbeat has now aged past the offline threshold).
+ *
+ * The mutate that flips `lastConnectionEvent` to `"heartbeat_lost"` is
+ * IDEMPOTENT across pods and redelivery: once it is `"heartbeat_lost"`, the
+ * predicate above is false, so re-runs (on any pod) are no-ops, and the entity
+ * handle's diff-on-unchanged suppresses any duplicate transition/event. Any pod
+ * can therefore drive the edge correctly, regardless of which pod (if any) ever
+ * observed the satellite online in memory.
  */
 export class HeartbeatMonitor {
   /**
-   * In-memory tracking of each satellite's last known status.
-   * Used to detect transitions and avoid redundant signal broadcasts.
+   * Pod-local broadcast-dedup ONLY (never the source of truth). The durable
+   * `lastConnectionEvent` flip is what makes detection idempotent; this set
+   * merely avoids re-broadcasting the same status-change signal from this pod on
+   * back-to-back checks. A fresh pod with an empty set still detects + mirrors
+   * the edge from durable state — it just also broadcasts once, which is benign.
    */
-  private previousStatuses = new Map<string, "online" | "offline">();
+  private broadcastedOffline = new Set<string>();
 
   constructor(
     private service: SatelliteService,
     private signalService: SignalService,
     private logger: Logger,
+    private entitySink?: SatelliteHeartbeatEntitySink,
   ) {}
 
   /**
-   * Check all satellites and broadcast status change signals for any transitions.
-   * Called periodically by a recurring queue job.
+   * Check all satellites and drive the heartbeat-lost edge for any that have
+   * aged out while still marked connected. Called periodically by a recurring
+   * queue job; safe to run on any pod and to redeliver.
    */
   async checkHeartbeats(): Promise<void> {
-    const allSatellites = await this.service.listSatellites();
+    const rows = await this.service.listConnectionLiveness();
+    const liveIds = new Set(rows.map((r) => r.id));
 
-    for (const satellite of allSatellites) {
-      const previousStatus = this.previousStatuses.get(satellite.id);
-      const currentStatus = satellite.status;
+    for (const row of rows) {
+      const status = computeStatus(row.lastHeartbeatAt);
+      const lostHeartbeat = this.hasLostHeartbeat({
+        status,
+        lastConnectionEvent: row.lastConnectionEvent,
+      });
 
-      // Detect transition
-      if (previousStatus !== undefined && previousStatus !== currentStatus) {
-        this.logger.info(
-          `Satellite ${satellite.name} (${satellite.region}) status: ${previousStatus} → ${currentStatus}`,
-        );
+      if (!lostHeartbeat) {
+        // Still online (or already past the lost edge / never connected):
+        // nothing to detect. Clear the broadcast-dedup marker once a satellite
+        // is no longer in the lost state so a future lost edge re-broadcasts.
+        if (status === "online") this.broadcastedOffline.delete(row.id);
+        continue;
+      }
+
+      // Durable heartbeat-lost edge: computed offline while still marked
+      // `connected`. Detected from durable state, so this fires correctly from
+      // ANY pod with no prior in-memory knowledge of the satellite.
+      this.logger.info(
+        `Satellite ${row.name} (${row.region}) lost heartbeat (online → offline)`,
+      );
 
+      // Broadcast the status-change signal once per offline edge from this pod.
+      if (!this.broadcastedOffline.has(row.id)) {
+        this.broadcastedOffline.add(row.id);
         await this.signalService.broadcast(SATELLITE_STATUS_CHANGED, {
-          satelliteId: satellite.id,
-          status: currentStatus,
-          name: satellite.name,
-          region: satellite.region,
+          satelliteId: row.id,
+          status: "offline",
+          name: row.name,
+          region: row.region,
         });
       }
 
-      this.previousStatuses.set(satellite.id, currentStatus);
+      // Drive the entity edge. The mutate is idempotent: it flips
+      // `lastConnectionEvent` to `"heartbeat_lost"`, after which this branch is
+      // never re-entered for the same satellite (re-runs are no-ops).
+      if (this.entitySink) {
+        try {
+          await this.entitySink.mirror(row.id);
+        } catch (error) {
+          this.logger.error(
+            `Failed to mirror satellite-connection (heartbeat_lost) for ${row.name}:`,
+            error,
+          );
+        }
+      }
     }
 
-    // Clean up tracked satellites that no longer exist
-    const currentIds = new Set(allSatellites.map((s) => s.id));
-    for (const trackedId of this.previousStatuses.keys()) {
-      if (!currentIds.has(trackedId)) {
-        this.previousStatuses.delete(trackedId);
-      }
+    // Drop broadcast-dedup markers for satellites that no longer exist.
+    for (const id of this.broadcastedOffline) {
+      if (!liveIds.has(id)) this.broadcastedOffline.delete(id);
     }
   }
 
   /**
-   * Get the offline threshold in milliseconds.
-   * Exposed for testing.
+   * Pure predicate: a satellite has just lost its heartbeat when its computed
+   * status is `offline` but its last recorded lifecycle edge still says it was
+   * `connected`. Once the edge is mirrored (`lastConnectionEvent` becomes
+   * `"heartbeat_lost"`), this returns false — the idempotency guarantee.
    */
-  static get OFFLINE_THRESHOLD_MS(): number {
-    return OFFLINE_THRESHOLD_MS;
+  private hasLostHeartbeat(props: {
+    status: "online" | "offline";
+    lastConnectionEvent: SatelliteConnectionEvent | null;
+  }): boolean {
+    return props.status === "offline" && props.lastConnectionEvent === "connected";
   }
 }

package/src/hooks.ts

@@ -2,8 +2,15 @@ import { createHook } from "@checkstack/backend-api";
 
 /**
  * Satellite hooks for cross-plugin communication.
- * Other plugins (e.g., healthcheck-backend) can subscribe to clean up
- * when a satellite is removed.
+ *
+ * The connection-lifecycle hooks (`satellite.connected` / `.disconnected` /
+ * `.heartbeat_lost`) were removed in Phase 4 (reactive automation engine
+ * §10.6): satellite connection state is now the reactive
+ * `satellite-connection` entity (see `./entity.ts`), and the equivalent
+ * trigger events are derived from its changes.
+ *
+ * `satellite.removed` stays — it is a deletion/cleanup signal (consumed by
+ * healthcheck-backend to scrub the satellite's id), not entity state.
  */
 export const satelliteHooks = {
   /**

package/src/index.ts

@@ -9,6 +9,10 @@ import {
 } from "@checkstack/satellite-common";
 import { HealthCheckApi } from "@checkstack/healthcheck-common";
 import { healthCheckHooks } from "@checkstack/healthcheck-backend";
+import { ScriptPackagesApi } from "@checkstack/script-packages-common";
+import { scriptPackagesChangedHook } from "@checkstack/script-packages-backend";
+import { secretResolverRef } from "@checkstack/secrets-backend";
+import { resolveSatelliteRunSecrets } from "./run-secret-resolver";
 import { SatelliteService } from "./service";
 import { createSatelliteRouter } from "./router";
 import { HeartbeatMonitor } from "./heartbeat-monitor";
@@ -16,6 +20,21 @@ import { SatelliteWsHandler } from "./satellite-ws-handler";
 import { ConfigRelay } from "./config-relay";
 import { entityKindExtensionPoint } from "@checkstack/gitops-backend";
 import { registerSatelliteGitOpsKinds } from "./satellite-gitops-kinds";
+import {
+  automationTriggerExtensionPoint,
+  entityExtensionPoint,
+  withEntityWrite,
+  type EntityHandle,
+} from "@checkstack/automation-backend";
+import {
+  SATELLITE_CONNECTION_ENTITY_KIND,
+  createSatelliteConnectionRead,
+  deriveSatelliteConnectionEvents,
+  satelliteChangeToPayload,
+  satelliteConnectionStateSchema,
+  type SatelliteConnectionState,
+} from "./entity";
+import { satelliteTriggers } from "./automations";
 
 // Queue and job constants
 const HEARTBEAT_QUEUE = "satellite-heartbeat";
@@ -27,6 +46,50 @@ export default createBackendPlugin({
   register(env) {
     env.registerAccessRules(satelliteAccessRules);
 
+    // ─── Automation Platform: reactive connection entity ─────────────
+    // Satellite connection state is the `satellite-connection` entity
+    // (reactive automation engine §10.6, §9.1), PLUGIN-BACKED (Model B) and
+    // COMPUTE-ON-READ: its `status` is DERIVED on read from the DURABLE, shared
+    // `satellites.lastHeartbeatAt` column (the single liveness source of truth,
+    // same as the admin list), and `lastConnectionEvent` is the only extra
+    // durable column (the deriver's event discriminator). There is NO stored
+    // status copy and NO framework `entity_state` mirror, so EVERY pod computes
+    // the same state AND a stale row self-heals to offline once the heartbeat
+    // ages out (this fixes the horizontal-scaling bug twice: the old in-memory
+    // map made pod A's satellite invisible to pod B, and the prior fix's stored
+    // status got stuck `online` after a pod crash because the heartbeat-lost
+    // EDGE was detected pod-locally). The three lifecycle sites (connect /
+    // disconnect / heartbeat-lost) write the liveness inputs through
+    // `handle.mutate`, and the framework records full transition HISTORY in
+    // `entity_transitions`.
+    //
+    // The `satellite.connected` / `.disconnected` / `.heartbeat_lost` trigger
+    // events are DERIVED from its changes (no hook-backed triggers). The
+    // ENTITY-DRIVEN triggers below stay registered so they remain in the
+    // editor's trigger catalog + payload-introspectable, and a `toPayload`
+    // mapper makes the runtime `trigger.payload` match their `payloadSchema`
+    // (mirroring incident / catalog / dependency / healthcheck).
+    const automationTriggers = env.getExtensionPoint(
+      automationTriggerExtensionPoint,
+    );
+    for (const trigger of satelliteTriggers) {
+      automationTriggers.registerTrigger(trigger, pluginMetadata);
+    }
+
+    const entity = env.getExtensionPoint(entityExtensionPoint);
+    entity.registerChangeDeriver({
+      kind: SATELLITE_CONNECTION_ENTITY_KIND,
+      derive: deriveSatelliteConnectionEvents,
+      toPayload: satelliteChangeToPayload,
+    });
+    entity.declareNonReactiveState({
+      table: "satellites",
+      reason: "bookkeeping",
+      note: "lastHeartbeatAt is the raw liveness timestamp; the satellite-connection entity's reactive status is computed from it on read.",
+    });
+    // Created once in init; reused by the WS handler + heartbeat monitor.
+    let satelliteEntityHandle: EntityHandle<SatelliteConnectionState>;
+
     // ─── GitOps Entity Kind Registration ─────────────────────────────
     let gitopsService: SatelliteService | undefined;
     const kindRegistry = env.getExtensionPoint(entityKindExtensionPoint);
@@ -47,6 +110,7 @@ export default createBackendPlugin({
         signalService: coreServices.signalService,
         queueManager: coreServices.queueManager,
         wsRegistry: coreServices.wsRegistry,
+        secretResolver: secretResolverRef,
       },
       init: async ({ logger, database, rpc, signalService }) => {
         logger.debug("🛰️ Initializing Satellite Backend...");
@@ -56,6 +120,20 @@ export default createBackendPlugin({
         );
         gitopsService = service;
 
+        // Declare the reactive `satellite-connection` entity once. PLUGIN-
+        // BACKED, COMPUTE-ON-READ: `read` computes status from the durable
+        // `satellites.lastHeartbeatAt` (+ reads `lastConnectionEvent`) via the
+        // service (the source of truth — no stored status copy, no
+        // `entity_state` mirror, globally consistent from any pod). The handle
+        // is the only typed path that drives connection-state changes (reactive
+        // automation engine §4.2); it is reused by the WS handler + heartbeat
+        // monitor wired in afterPluginsReady.
+        satelliteEntityHandle = entity.defineEntity({
+          kind: SATELLITE_CONNECTION_ENTITY_KIND,
+          state: satelliteConnectionStateSchema,
+          read: createSatelliteConnectionRead(service),
+        });
+
         const router = createSatelliteRouter({
           service,
           signalService,
@@ -72,6 +150,7 @@ export default createBackendPlugin({
         signalService,
         wsRegistry,
         rpcClient,
+        secretResolver,
         onHook,
       }) => {
         const service = new SatelliteService(
@@ -112,6 +191,71 @@ export default createBackendPlugin({
             },
           },
           logger,
+          {
+            // Drive connect/disconnect through `handle.mutate` (Model B):
+            // `apply` UPDATEs the satellite row's durable liveness columns
+            // (`lastHeartbeatAt` + `lastConnectionEvent`) — the globally-
+            // readable source of truth — and returns the view (status COMPUTED
+            // from `lastHeartbeatAt`). The framework snapshots `prev` via
+            // `read`, records the transition (durable history), and emits the
+            // change; the deriver re-fires the equivalent trigger events.
+            mirror: async ({ satelliteId, lastEvent, lastHeartbeatAt }) => {
+              await withEntityWrite({
+                handle: satelliteEntityHandle,
+                id: satelliteId,
+                apply: () =>
+                  service.applyConnectionState({
+                    satelliteId,
+                    lastEvent,
+                    lastHeartbeatAt,
+                  }),
+              });
+            },
+          },
+          {
+            // Script-package distribution: carry the desired lockfile hash in
+            // assignment payloads + persist per-satellite reconcile state.
+            // Satellites pull blobs from CORE (getManifest/downloadBlob),
+            // never the registry.
+            getDesiredLockfileHash: async () => {
+              const spClient = rpcClient.forPlugin(ScriptPackagesApi);
+              const state = await spClient.getInstallState();
+              return state.lockfileHash;
+            },
+            reportSyncState: async (input) => {
+              const spClient = rpcClient.forPlugin(ScriptPackagesApi);
+              await spClient.reportSatelliteSyncState(input);
+            },
+            getManifest: async ({ lockfileHash }) => {
+              const spClient = rpcClient.forPlugin(ScriptPackagesApi);
+              const res = await spClient.getManifest({ lockfileHash });
+              return res.entries;
+            },
+            getBlobBase64: async ({ integrity }) => {
+              const spClient = rpcClient.forPlugin(ScriptPackagesApi);
+              try {
+                const res = await spClient.downloadBlob({ integrity });
+                return res.data;
+              } catch {
+                return null;
+              }
+            },
+          },
+          {
+            // JIT secret delivery: resolve a collector's declared secretEnv
+            // (read from the satellite's own assignment) via the central
+            // resolver. Values are returned over the WS channel per-run and
+            // never persisted.
+            resolveRunSecrets: async ({ satelliteId, configId, collectorId }) =>
+              resolveSatelliteRunSecrets({
+                satelliteId,
+                configId,
+                collectorId,
+                getAssignmentsForSatellite: (id) =>
+                  configRelay.getAssignmentsForSatellite(id),
+                resolver: secretResolver,
+              }),
+          },
         );
 
         // Register satellite WebSocket endpoint via the scoped WS registry
@@ -124,6 +268,30 @@ export default createBackendPlugin({
           service,
           signalService,
           logger,
+          {
+            // Drive the online → offline (heartbeat-lost) edge through
+            // `handle.mutate`. `apply` flips ONLY `lastConnectionEvent` to
+            // `"heartbeat_lost"` (the aged `lastHeartbeatAt` is left untouched —
+            // it is what made the computed status `offline`). The framework
+            // records the transition (durable history) and the deriver re-fires
+            // `satellite.heartbeat_lost`. The mutate is idempotent: once
+            // `lastConnectionEvent === "heartbeat_lost"`, the monitor's
+            // predicate is false and re-runs (on any pod) are no-ops. This is
+            // the durable, any-pod offline-on-timeout backstop: a pod that dies
+            // without flipping its satellites to offline leaves a stale state
+            // only until ANY pod's monitor observes the heartbeat timeout.
+            mirror: async (satelliteId) => {
+              await withEntityWrite({
+                handle: satelliteEntityHandle,
+                id: satelliteId,
+                apply: () =>
+                  service.applyConnectionState({
+                    satelliteId,
+                    lastEvent: "heartbeat_lost",
+                  }),
+              });
+            },
+          },
         );
 
         const queue = queueManager.getQueue<Record<string, never>>(
@@ -163,6 +331,18 @@ export default createBackendPlugin({
           },
         );
 
+        // Fan the script-packages.changed broadcast out to THIS instance's
+        // connected satellites. Every core instance subscribes in broadcast
+        // mode, so each pushes to its own satellites; offline satellites
+        // converge via the assignment-carried lockfile hash on reconnect.
+        onHook(
+          scriptPackagesChangedHook,
+          async ({ lockfileHash }) => {
+            wsHandler.pushRefreshScriptPackagesToAll(lockfileHash);
+          },
+          { mode: "broadcast" },
+        );
+
         logger.debug("✅ Satellite Backend afterPluginsReady complete.");
       },
     });

package/src/run-secret-resolver.test.ts

@@ -0,0 +1,121 @@
+import { describe, it, expect } from "bun:test";
+import type { SatelliteAssignment } from "@checkstack/satellite-common";
+import type { SecretResolverService } from "@checkstack/secrets-backend";
+import { resolveSatelliteRunSecrets } from "./run-secret-resolver";
+
+// A resolver that resolves from a fixed name->value map (mirrors the real
+// resolveForRun: substitute ${{ secrets.NAME }} per declared env entry).
+function fakeResolver(values: Record<string, string>): SecretResolverService {
+  const TEMPLATE_RE = /\$\{\{\s*secrets\.([a-zA-Z0-9_-]+)\s*\}\}/g;
+  return {
+    resolveSecret: async ({ name }) => {
+      if (!(name in values)) throw new Error(`Secret not found: ${name}`);
+      return values[name];
+    },
+    resolveBySchema: async ({ value }) => ({ resolved: value, warnings: [] }),
+    resolveForRun: async ({ secretEnv }) => {
+      const env: Record<string, string> = {};
+      for (const [envName, template] of Object.entries(secretEnv)) {
+        TEMPLATE_RE.lastIndex = 0;
+        env[envName] = template.replaceAll(TEMPLATE_RE, (_m, name: string) => {
+          if (!(name in values)) throw new Error(`Secret not found: ${name}`);
+          return values[name];
+        });
+      }
+      return {
+        env,
+        masking: {
+          size: 0,
+          maskText: (t) => t,
+          maskDeep: (v) => v,
+        },
+      };
+    },
+  };
+}
+
+function assignment(
+  configId: string,
+  collectors: SatelliteAssignment["collectors"],
+): SatelliteAssignment {
+  return {
+    configId,
+    systemId: "sys-1",
+    strategyId: "script",
+    config: {},
+    collectors,
+    intervalSeconds: 60,
+  };
+}
+
+describe("resolveSatelliteRunSecrets", () => {
+  it("resolves ONLY the collector's declared secretEnv from the assignment", async () => {
+    const assignments = [
+      assignment("config-1", [
+        {
+          id: "col-1",
+          collectorId: "inline-script",
+          config: { secretEnv: { API_TOKEN: "${{ secrets.jira_token }}" } },
+        },
+      ]),
+    ];
+    const env = await resolveSatelliteRunSecrets({
+      satelliteId: "sat-1",
+      configId: "config-1",
+      collectorId: "col-1",
+      getAssignmentsForSatellite: async () => assignments,
+      resolver: fakeResolver({ jira_token: "real-value", other: "nope" }),
+    });
+    expect(env).toEqual({ API_TOKEN: "real-value" });
+  });
+
+  it("throws when the assignment is not assigned to this satellite", async () => {
+    await expect(
+      resolveSatelliteRunSecrets({
+        satelliteId: "sat-1",
+        configId: "missing",
+        collectorId: "col-1",
+        getAssignmentsForSatellite: async () => [],
+        resolver: fakeResolver({}),
+      }),
+    ).rejects.toThrow(/No assignment/);
+  });
+
+  it("throws when the collector declares no secretEnv (least-privilege)", async () => {
+    const assignments = [
+      assignment("config-1", [
+        { id: "col-1", collectorId: "inline-script", config: {} },
+      ]),
+    ];
+    await expect(
+      resolveSatelliteRunSecrets({
+        satelliteId: "sat-1",
+        configId: "config-1",
+        collectorId: "col-1",
+        getAssignmentsForSatellite: async () => assignments,
+        resolver: fakeResolver({}),
+      }),
+    ).rejects.toThrow(/no secretEnv/);
+  });
+
+  it("propagates a clear error when a required secret cannot resolve", async () => {
+    const assignments = [
+      assignment("config-1", [
+        {
+          id: "col-1",
+          collectorId: "inline-script",
+          config: { secretEnv: { TOKEN: "${{ secrets.absent }}" } },
+        },
+      ]),
+    ];
+    await expect(
+      resolveSatelliteRunSecrets({
+        satelliteId: "sat-1",
+        configId: "config-1",
+        collectorId: "col-1",
+        getAssignmentsForSatellite: async () => assignments,
+        resolver: fakeResolver({}),
+      }),
+    ).rejects.toThrow(/Secret not found: absent/);
+  });
+});

package/src/run-secret-resolver.ts

@@ -0,0 +1,66 @@
+import { secretEnvMappingSchema } from "@checkstack/secrets-common";
+import type { SecretResolverService } from "@checkstack/secrets-backend";
+import type { SatelliteAssignment } from "@checkstack/satellite-common";
+
+/**
+ * Resolve a satellite collector run's secrets just-in-time.
+ *
+ * Security model (least-privilege, decision 5): the satellite asks by
+ * `configId` + `collectorId` only. Core reads the `secretEnv` mapping from
+ * the satellite's OWN persisted assignment for that collector — the
+ * satellite does not get to choose which secrets — and resolves ONLY those
+ * refs via the central resolver. So a compromised satellite cannot request
+ * arbitrary secrets; it can only obtain what its assignment already
+ * declares it needs.
+ *
+ * Returns the resolved env map. Throws a clear error when the collector
+ * isn't in the satellite's assignments, when the collector declares no
+ * `secretEnv` (nothing to resolve — caller should not have asked), or when
+ * a referenced secret can't be resolved. The values are never persisted.
+ */
+export async function resolveSatelliteRunSecrets({
+  satelliteId,
+  configId,
+  collectorId,
+  getAssignmentsForSatellite,
+  resolver,
+}: {
+  satelliteId: string;
+  configId: string;
+  collectorId: string;
+  getAssignmentsForSatellite: (
+    satelliteId: string,
+  ) => Promise<SatelliteAssignment[]>;
+  resolver: SecretResolverService;
+}): Promise<Record<string, string>> {
+  const assignments = await getAssignmentsForSatellite(satelliteId);
+  const assignment = assignments.find((a) => a.configId === configId);
+  if (!assignment) {
+    throw new Error(
+      `No assignment "${configId}" for this satellite; cannot deliver secrets.`,
+    );
+  }
+
+  const collector = (assignment.collectors ?? []).find(
+    (c) => c.id === collectorId || c.collectorId === collectorId,
+  );
+  if (!collector) {
+    throw new Error(
+      `Collector "${collectorId}" not found in assignment "${configId}".`,
+    );
+  }
+
+  // The declared mapping lives inside the collector's config. Validate it so
+  // a malformed config can't smuggle non-template values through.
+  const parsed = secretEnvMappingSchema.safeParse(
+    (collector.config as { secretEnv?: unknown }).secretEnv,
+  );
+  if (!parsed.success || Object.keys(parsed.data).length === 0) {
+    throw new Error(
+      `Collector "${collectorId}" declares no secretEnv; nothing to resolve.`,
+    );
+  }
+
+  const { env } = await resolver.resolveForRun({ secretEnv: parsed.data });
+  return env;
+}