target-supabase-sdk 0.2.3 → 0.2.4

package/src/node/process/managed-child-processes.ts

@@ -8,7 +8,13 @@ export interface ManagedChildProcessesOptions {
     preloadModules?: readonly string[];
     /** SIGTERM -> wait -> SIGKILL delay (default 5000 ms). */
     graceMs?: number;
-    logger?: Pick<LoggerWithScope, "info" | "warn" | "error">;
+    logger?: Pick<LoggerWithScope, "info" | "warn" | "error" | "critical">;
+    useTsx?: boolean;
+}
+
+export interface SpawnChildOptions {
+    env?: Record<string, string>;
+    useTsx?: boolean;
 }
 
 export interface SpawnChildResult {
@@ -22,6 +28,11 @@ export interface StopAllChildrenOptions {
     extraPids?: readonly number[];
 }
 
+export interface CriticalExitHandler {
+    labels: readonly string[];
+    onCriticalExit: (label: string, code: number | null, signal: NodeJS.Signals | null) => void;
+}
+
 /**
  * Process-local registry for tsx child processes (supervisor, worker, etc.).
  * Each OS process has its own instance - do not expect cross-process PID tracking.
@@ -30,16 +41,24 @@ export class ManagedChildProcesses {
     private readonly projectRoot: string;
     private readonly preloadModules: readonly string[];
     private readonly graceMs: number;
-    private readonly logger?: Pick<LoggerWithScope, "info" | "warn" | "error">;
+    private readonly defaultUseTsx: boolean;
+    private readonly logger?: Pick<LoggerWithScope, "info" | "warn" | "error" | "critical">;
     private readonly byLabel = new Map<string, ChildProcess>();
+    private criticalExitHandler: CriticalExitHandler | null = null;
+    private suppressCriticalExit = false;
 
     constructor(options: ManagedChildProcessesOptions) {
         this.projectRoot = options.projectRoot;
         this.preloadModules = options.preloadModules ?? [];
         this.graceMs = options.graceMs ?? 5_000;
+        this.defaultUseTsx = options.useTsx ?? true;
         this.logger = options.logger;
     }
 
+    setCriticalExitHandler(handler: CriticalExitHandler): void {
+        this.criticalExitHandler = handler;
+    }
+
     get(label: string): ChildProcess | null {
         return this.byLabel.get(label) ?? null;
     }
@@ -55,7 +74,7 @@ export class ManagedChildProcesses {
             .map(([label]) => label);
     }
 
-    spawn(label: string, entryScript: string): SpawnChildResult {
+    spawn(label: string, entryScript: string, spawnOptions?: SpawnChildOptions): SpawnChildResult {
         const existing = this.getRunning(label);
         if (existing != null) {
             return { child: existing, created: false };
@@ -65,14 +84,23 @@ export class ManagedChildProcesses {
             projectRoot: this.projectRoot,
             entryScript,
             preloadModules: this.preloadModules,
+            useTsx: spawnOptions?.useTsx ?? this.defaultUseTsx,
+            env: spawnOptions?.env != null ? { ...process.env, ...spawnOptions.env } : process.env,
         });
 
-        child.on("exit", (code, signal) => {
+        child.on("exit", (code: number | null, signal: NodeJS.Signals | null) => {
             this.logger?.info("child exited", { topic: "process", data: { label, code, signal } });
             const current = this.byLabel.get(label);
             if (current === child) {
                 this.byLabel.delete(label);
             }
+            if (
+                !this.suppressCriticalExit &&
+                this.criticalExitHandler != null &&
+                this.criticalExitHandler.labels.includes(label)
+            ) {
+                this.criticalExitHandler.onCriticalExit(label, code, signal);
+            }
         });
 
         this.byLabel.set(label, child);
@@ -90,20 +118,25 @@ export class ManagedChildProcesses {
     }
 
     async stopAll(options?: StopAllChildrenOptions): Promise<void> {
-        const tracked = [...this.byLabel.values()].filter((child) => isChildProcessRunning(child));
+        this.suppressCriticalExit = true;
+        try {
+            const tracked = [...this.byLabel.values()].filter((child) => isChildProcessRunning(child));
 
-        await Promise.all(tracked.map((child) => this.stopChild(child)));
+            await Promise.all(tracked.map((child) => this.stopChild(child)));
 
-        const extraPids = options?.extraPids ?? [];
-        for (const pid of extraPids) {
-            if (pid == null || tracked.some((child) => child.pid === pid)) {
-                continue;
-            }
-            try {
-                process.kill(pid, "SIGTERM");
-            } catch {
-                // already exited
+            const extraPids = options?.extraPids ?? [];
+            for (const pid of extraPids) {
+                if (pid == null || tracked.some((child) => child.pid === pid)) {
+                    continue;
+                }
+                try {
+                    process.kill(pid, "SIGTERM");
+                } catch {
+                    // already exited
+                }
             }
+        } finally {
+            this.suppressCriticalExit = false;
         }
     }
 

package/src/node/runtime-state/create-service-runtime-state-store.ts

@@ -0,0 +1,125 @@
+import { EMPTY_REGISTRY_SLOT_RUNTIME_STATE } from "../../service/registry-lifecycle";
+import { createJsonFileStateStore, type JsonFileStateStore, type JsonStatePatch } from "../fs/json-state-store";
+import type {
+    DefaultExtraRuntimeSlices,
+    GuardRuntimeSlice,
+    ReadinessRuntimeSlice,
+    SchedulerRuntimeSlice,
+    ServiceRuntimeExtraSlicePatch,
+    ServiceRuntimeNestedKeys,
+    ServiceRuntimeState,
+    WorkerRuntimeSlice,
+} from "./service-runtime-state.types";
+
+const EPOCH_ISO = new Date(0).toISOString();
+
+export interface CreateServiceRuntimeStateStoreOptions<
+    TExtraSlices extends Record<string, object> = DefaultExtraRuntimeSlices,
+> {
+    filePath: string;
+    /** Default values for service-specific top-level nested slices. */
+    extraDefaults?: TExtraSlices;
+}
+
+export interface FinishRunnerTickOptions<TExtraSlices extends Record<string, object> = DefaultExtraRuntimeSlices> {
+    nowMs: number;
+    lastFired: Record<string, string>;
+    postedCount?: number;
+    /** Patch extra slices in the same atomic write as the scheduler tick. */
+    extra?: ServiceRuntimeExtraSlicePatch<TExtraSlices>;
+}
+
+export interface ServiceRuntimeStateStore<TExtraSlices extends Record<string, object> = DefaultExtraRuntimeSlices> {
+    readRuntimeState(): Promise<ServiceRuntimeState<TExtraSlices>>;
+    writeRuntimeState(
+        patch: JsonStatePatch<ServiceRuntimeState<TExtraSlices>, ServiceRuntimeNestedKeys<TExtraSlices>>,
+    ): Promise<ServiceRuntimeState<TExtraSlices>>;
+    resetRuntimeStateForStartup(): Promise<ServiceRuntimeState<TExtraSlices>>;
+    finishRunnerTick(options: FinishRunnerTickOptions<TExtraSlices>): Promise<void>;
+}
+
+function createDefaultServiceRuntimeState<TExtraSlices extends Record<string, object>>(options: {
+    extraDefaults?: TExtraSlices;
+}): ServiceRuntimeState<TExtraSlices> {
+    const readiness: ReadinessRuntimeSlice = {
+        status: "pending",
+        checkedAt: null,
+        message: null,
+        checks: [],
+    };
+    const guard: GuardRuntimeSlice = {
+        nodeId: null,
+        lastCheckAt: null,
+        lastDecision: null,
+        lastSpawnAt: null,
+        spawnCount: 0,
+    };
+    const scheduler: SchedulerRuntimeSlice = {
+        lastTickAt: null,
+        lastPostedCount: 0,
+        lastFired: {},
+    };
+    const worker: WorkerRuntimeSlice = {
+        pid: null,
+        spawnedAt: null,
+        ready: false,
+        registeredTasks: [],
+        readyAt: null,
+    };
+
+    return {
+        updatedAt: EPOCH_ISO,
+        readiness,
+        guard,
+        scheduler,
+        worker,
+        registry: { ...EMPTY_REGISTRY_SLOT_RUNTIME_STATE },
+        ...(options.extraDefaults ?? ({} as TExtraSlices)),
+    };
+}
+
+/** JSON file-backed service runtime state (L3 blueprint) with typed core slices and extensions. */
+export function createServiceRuntimeStateStore<TExtraSlices extends Record<string, object> = DefaultExtraRuntimeSlices>(
+    options: CreateServiceRuntimeStateStoreOptions<TExtraSlices>,
+): ServiceRuntimeStateStore<TExtraSlices> {
+    type State = ServiceRuntimeState<TExtraSlices>;
+    type NK = ServiceRuntimeNestedKeys<TExtraSlices>;
+
+    const defaultState = createDefaultServiceRuntimeState(options);
+    const nestedKeys = [
+        "readiness",
+        "guard",
+        "scheduler",
+        "worker",
+        "registry",
+        ...(Object.keys(options.extraDefaults ?? {}) as (keyof TExtraSlices & string)[]),
+    ] as NK[];
+
+    let store: JsonFileStateStore<State, NK> | undefined;
+
+    function instance(): JsonFileStateStore<State, NK> {
+        store ??= createJsonFileStateStore<State, NK>({
+            filePath: options.filePath,
+            defaultState,
+            nestedKeys,
+            updatedAtKey: "updatedAt",
+        });
+        return store;
+    }
+
+    return {
+        readRuntimeState: () => instance().read(),
+        writeRuntimeState: (patch) => instance().write(patch),
+        resetRuntimeStateForStartup: () => instance().reset(),
+        finishRunnerTick: async ({ nowMs, lastFired, postedCount, extra }) => {
+            await instance().write({
+                scheduler: {
+                    lastTickAt: new Date(nowMs).toISOString(),
+                    lastFired,
+                    ...(postedCount != null ? { lastPostedCount: postedCount } : {}),
+                },
+                ...extra,
+            } as JsonStatePatch<State, NK>);
+        },
+    };
+}

package/src/node/runtime-state/index.ts

@@ -0,0 +1,17 @@
+export type {
+    CreateServiceRuntimeStateStoreOptions,
+    FinishRunnerTickOptions,
+    ServiceRuntimeStateStore,
+} from "./create-service-runtime-state-store";
+export { createServiceRuntimeStateStore } from "./create-service-runtime-state-store";
+export type {
+    GuardRuntimeSlice,
+    ReadinessRuntimeSlice,
+    ReadinessStatus,
+    SchedulerRuntimeSlice,
+    ServiceRuntimeCoreNestedKey,
+    ServiceRuntimeExtraSlicePatch,
+    ServiceRuntimeNestedKeys,
+    ServiceRuntimeState,
+    WorkerRuntimeSlice,
+} from "./service-runtime-state.types";

package/src/node/runtime-state/service-runtime-state.types.ts

@@ -0,0 +1,64 @@
+import type { RegistrySlotRuntimeState } from "../../service/registry-lifecycle";
+
+export type ReadinessStatus = "pending" | "passed" | "failed";
+
+export interface ReadinessRuntimeSlice {
+    status: ReadinessStatus;
+    checkedAt: string | null;
+    message: string | null;
+    checks: { name: string; ok: boolean; detail?: string }[];
+}
+
+export interface GuardRuntimeSlice {
+    nodeId: string | null;
+    lastCheckAt: string | null;
+    lastDecision: string | null;
+    lastSpawnAt: string | null;
+    spawnCount: number;
+}
+
+export interface SchedulerRuntimeSlice {
+    lastTickAt: string | null;
+    lastPostedCount: number;
+    lastFired: Record<string, string>;
+}
+
+export interface WorkerRuntimeSlice {
+    pid: number | null;
+    spawnedAt: string | null;
+    ready: boolean;
+    registeredTasks: string[];
+    readyAt: string | null;
+}
+
+/**
+ * Default when an L3 service has no service-specific runtime state slices.
+ * Use an empty object type (not `Record<string, never>`) so intersecting with core
+ * slices does not add a string index signature that collapses property types to `never`.
+ */
+export type DefaultExtraRuntimeSlices = Record<never, never>;
+
+/**
+ * Cross-process service runtime state persisted to `state.json`.
+ * L3 blueprint: readiness + guard + scheduler + worker + registry.
+ * Extend via extra top-level slices only.
+ */
+export type ServiceRuntimeState<TExtraSlices extends Record<string, object> = DefaultExtraRuntimeSlices> = {
+    updatedAt: string;
+    readiness: ReadinessRuntimeSlice;
+    guard: GuardRuntimeSlice;
+    scheduler: SchedulerRuntimeSlice;
+    worker: WorkerRuntimeSlice;
+    registry: RegistrySlotRuntimeState;
+} & TExtraSlices;
+
+export type ServiceRuntimeCoreNestedKey = "readiness" | "guard" | "scheduler" | "worker" | "registry";
+
+export type ServiceRuntimeNestedKeys<TExtraSlices extends Record<string, object>> =
+    | ServiceRuntimeCoreNestedKey
+    | (keyof TExtraSlices & string);
+
+/** Patch shape for extra top-level slices (one level deep). */
+export type ServiceRuntimeExtraSlicePatch<TExtraSlices extends Record<string, object>> = {
+    [K in keyof TExtraSlices]?: TExtraSlices[K] extends object ? Partial<TExtraSlices[K]> : TExtraSlices[K];
+};

package/src/node/service-guard/index.ts

@@ -0,0 +1,17 @@
+export { registerServiceGuardRunner } from "./register-service-guard-runner";
+export type { RunReadinessGateInput } from "./run-readiness-gate";
+export { runReadinessGate } from "./run-readiness-gate";
+export { runServiceGuardTick } from "./run-service-guard-tick";
+export type {
+    RegisterServiceGuardRunnerOptions,
+    ServiceGuardNodeOptions,
+    ServiceGuardTickInput,
+    ServiceGuardTickResult,
+} from "./service-guard.interface";
+export { SERVICE_GUARD_RUNNER_KEY } from "./service-guard.interface";
+export { ServiceGuardNode } from "./service-guard-node";
+export {
+    getWorkerSpawnCooldownLastAt,
+    markWorkerSpawned,
+    resetWorkerSpawnCooldownForTests,
+} from "./worker-spawn-cooldown";

package/src/node/service-guard/register-service-guard-runner.ts

@@ -0,0 +1,64 @@
+import type { TriggerRunnerContext } from "../../trigger/trigger.interface";
+import { TriggerManager } from "../../trigger/trigger-manager";
+import { runServiceGuardTick } from "./run-service-guard-tick";
+import { type RegisterServiceGuardRunnerOptions, SERVICE_GUARD_RUNNER_KEY } from "./service-guard.interface";
+
+async function runServiceGuardRunner(
+    ctx: TriggerRunnerContext,
+    options: RegisterServiceGuardRunnerOptionsWithClock,
+): Promise<void> {
+    const { loopTraceId, nodeId, logger } = ctx;
+    const nowMs = options.now?.() ?? Date.now();
+    const checkedAt = new Date(nowMs).toISOString();
+    const serviceId = await options.getServiceId();
+
+    const result = await runServiceGuardTick({
+        serviceValue: options.serviceValue,
+        serviceId,
+        nodeId,
+        loopTraceId,
+        logger,
+        logTopic: options.logTopic,
+        checkedAt,
+        nowMs,
+        taskNodeStaleMs: options.taskNodeStaleMs,
+        workerSpawnCooldownMs: options.workerSpawnCooldownMs,
+        maxNodes: options.maxNodes,
+        spawnWorker: options.spawnWorker,
+    });
+
+    if (result.registryPatch != null) {
+        await options.onRegistryPatch(result.registryPatch);
+    }
+
+    if (!result.continueTick) {
+        return;
+    }
+
+    await options.onGuardPatch({
+        nodeId,
+        lastCheckAt: checkedAt,
+        lastDecision: result.decision,
+    });
+
+    if (options.onDecision != null) {
+        await options.onDecision(result.decision);
+    }
+}
+
+export interface RegisterServiceGuardRunnerOptionsWithClock extends RegisterServiceGuardRunnerOptions {
+    /** Test hook — defaults to Date.now(). */
+    now?: () => number;
+}
+
+/** Register the standard L3 guard runner (registry slot + TaskNode + Service runtime). */
+export function registerServiceGuardRunner(options: RegisterServiceGuardRunnerOptionsWithClock): void {
+    TriggerManager.registerRunner({
+        key: options.runnerKey ?? SERVICE_GUARD_RUNNER_KEY,
+        intervalMs: options.intervalMs,
+        initialDelayMs: options.initialDelayMs,
+        fn: (ctx) => runServiceGuardRunner(ctx, options),
+    });
+}
+
+export { SERVICE_GUARD_RUNNER_KEY };

package/src/node/service-guard/run-readiness-gate.ts

@@ -0,0 +1,34 @@
+import type { LoggerWithScope } from "../../shared/log";
+import type { ReadinessCheck, ReadinessReport } from "../readiness/readiness.types";
+import { runReadinessChecks } from "../readiness/run-readiness-checks";
+
+export interface RunReadinessGateInput {
+    checks: ReadinessCheck[];
+    onReport: (report: ReadinessReport) => Promise<void>;
+    logger: LoggerWithScope;
+    logTopic?: string;
+}
+
+/** Run readiness checks, persist report via callback, fail-fast when not ok. */
+export async function runReadinessGate(input: RunReadinessGateInput): Promise<ReadinessReport> {
+    const { checks, onReport, logger, logTopic = "guard" } = input;
+
+    logger.info("Running readiness checks", { topic: logTopic });
+    const report = await runReadinessChecks(checks);
+    await onReport(report);
+
+    if (!report.ok) {
+        logger.error("Readiness checks failed", {
+            topic: logTopic,
+            data: { message: report.message, checks: report.checks },
+        });
+        throw new Error(report.message ?? "Readiness checks failed");
+    }
+
+    logger.debug("Readiness checks passed", {
+        topic: logTopic,
+        data: { checks: report.checks.map((check) => check.name) },
+    });
+
+    return report;
+}

package/src/node/service-guard/run-service-guard-tick.ts

@@ -0,0 +1,106 @@
+import { CategoryNode, evaluateBusyNodeLiveness, type Node, patchServiceRuntime, scanTargetList } from "../../browser";
+import { applyRegistrySlotGuardStep } from "../service-host/registry-slot-guard-step";
+import type { ServiceGuardTickInput, ServiceGuardTickResult } from "./service-guard.interface";
+import { getWorkerSpawnCooldownLastAt, markWorkerSpawned } from "./worker-spawn-cooldown";
+
+/**
+ * One guard-runner tick: registry slot check, TaskNode liveness, optional worker
+ * respawn, Service runtime heartbeat rollup.
+ */
+export async function runServiceGuardTick(input: ServiceGuardTickInput): Promise<ServiceGuardTickResult> {
+    const {
+        serviceValue,
+        serviceId,
+        nodeId,
+        loopTraceId,
+        logger,
+        logTopic = "guard",
+        checkedAt,
+        nowMs,
+        taskNodeStaleMs,
+        workerSpawnCooldownMs,
+        maxNodes = 200,
+        spawnWorker,
+        getLastWorkerSpawnAt = getWorkerSpawnCooldownLastAt,
+        markWorkerSpawned: markWorkerSpawnedAt = markWorkerSpawned,
+    } = input;
+
+    const continueTick = true;
+    let registryPatch: ServiceGuardTickResult["registryPatch"];
+    let decision = "idle";
+
+    if (serviceId != null) {
+        const guard = await applyRegistrySlotGuardStep({
+            serviceValue,
+            serviceId,
+            checkedAt,
+            logger,
+            logTopic,
+            traceId: loopTraceId,
+        });
+        registryPatch = guard.registryPatch;
+        if (!guard.continueTick) {
+            return { continueTick: false, decision: "slot_lost", nodes: [], registryPatch };
+        }
+        decision = "slot_ok";
+    }
+
+    const { data: nodes = [] } = await scanTargetList<Node>({
+        category: CategoryNode.NODE,
+        maxRows: maxNodes,
+    });
+
+    const liveness = evaluateBusyNodeLiveness(nodes, {
+        staleMs: taskNodeStaleMs,
+        now: nowMs,
+        excludeNodeId: nodeId,
+        onlyFreshCandidates: true,
+    });
+
+    const ageMs = liveness.freshest?.ageMs ?? Number.POSITIVE_INFINITY;
+
+    if (liveness.healthy) {
+        decision = "healthy";
+    } else if (nowMs - getLastWorkerSpawnAt() < workerSpawnCooldownMs) {
+        decision = "spawn_cooldown";
+        logger.warn("TaskNode unavailable but spawn cooldown active", {
+            topic: logTopic,
+            data: {
+                traceId: loopTraceId,
+                ageMs,
+                staleMs: taskNodeStaleMs,
+                cooldownMs: workerSpawnCooldownMs,
+            },
+        });
+    } else {
+        decision = "spawn_worker";
+        logger.warn("TaskNode stale — restarting worker", {
+            topic: logTopic,
+            data: {
+                traceId: loopTraceId,
+                peerWorkerCount: liveness.busyWorkerCount,
+                freshPeerCount: liveness.freshWorkerCount,
+                staleMs: taskNodeStaleMs,
+            },
+        });
+        await spawnWorker("guard:restart-unhealthy-tasknode");
+        markWorkerSpawnedAt(nowMs);
+    }
+
+    try {
+        await patchServiceRuntime({
+            serviceValue,
+            serviceId: serviceId ?? undefined,
+            nodes,
+            lastHeartBeat: nowMs,
+        });
+    } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        logger.warn("Failed to patch Service runtime rollup", {
+            topic: logTopic,
+            data: { traceId: loopTraceId, message },
+        });
+    }
+
+    return { continueTick, decision, nodes, registryPatch };
+}

package/src/node/service-guard/service-guard-node.ts

@@ -0,0 +1,52 @@
+import type { LoggerWithScope } from "../../shared/log";
+import { TriggerNode } from "../../trigger/trigger-node";
+import { registerServiceGuardRunner } from "./register-service-guard-runner";
+import { runReadinessGate } from "./run-readiness-gate";
+import type { ServiceGuardNodeOptions } from "./service-guard.interface";
+
+/**
+ * L3 guard process TriggerNode: readiness gate, TaskNode worker spawn owner,
+ * and {@link registerServiceGuardRunner} tick (registry slot + liveness + runtime).
+ *
+ * Use {@link ServiceGuardNode.create} so the guard runner is registered before `start()`.
+ */
+class ServiceGuardNode extends TriggerNode {
+    private readonly options: ServiceGuardNodeOptions;
+
+    private constructor(options: ServiceGuardNodeOptions) {
+        super({
+            requireRunners: true,
+            beforeProcessExit: options.beforeProcessExit,
+        });
+        this.options = options;
+    }
+
+    /** Register the guard runner and return a ready-to-start node. */
+    static create(options: ServiceGuardNodeOptions): ServiceGuardNode {
+        registerServiceGuardRunner({
+            serviceValue: options.serviceValue,
+            logTopic: options.logTopic,
+            ...options.guardRunner,
+        });
+        return new ServiceGuardNode(options);
+    }
+
+    protected async onBeforeRegisterNode(nodeLogger: LoggerWithScope): Promise<void> {
+        await runReadinessGate({
+            checks: this.options.readinessChecks,
+            onReport: this.options.onReadinessReport,
+            logger: nodeLogger,
+            logTopic: this.options.logTopic,
+        });
+
+        await super.onBeforeRegisterNode(nodeLogger);
+
+        nodeLogger.info("Spawning TaskNode worker (single spawn owner)", {
+            topic: this.options.logTopic ?? "guard",
+        });
+        await this.options.spawnWorker("guard:readiness-passed");
+        this.options.onWorkerSpawned?.();
+    }
+}
+
+export { ServiceGuardNode };

package/src/node/service-guard/service-guard.interface.ts

@@ -0,0 +1,64 @@
+import type { Node } from "../../node/node.interface";
+import type { RegistrySlotRuntimeState } from "../../service/registry-lifecycle";
+import type { LoggerWithScope } from "../../shared/log";
+import type { TriggerNodeOptions } from "../../trigger/trigger.interface";
+import type { ReadinessCheck, ReadinessReport } from "../readiness/readiness.types";
+
+/** Default TriggerManager runner key for {@link registerServiceGuardRunner}. */
+export const SERVICE_GUARD_RUNNER_KEY = "service-guard";
+
+export interface ServiceGuardTickInput {
+    serviceValue: string;
+    serviceId: string | null;
+    nodeId: string;
+    loopTraceId: string;
+    logger: LoggerWithScope;
+    logTopic?: string;
+    checkedAt: string;
+    nowMs: number;
+    taskNodeStaleMs: number;
+    workerSpawnCooldownMs: number;
+    maxNodes?: number;
+    spawnWorker: (reason: string) => Promise<void>;
+    getLastWorkerSpawnAt?: () => number;
+    markWorkerSpawned?: (at: number) => void;
+}
+
+export interface ServiceGuardTickResult {
+    continueTick: boolean;
+    decision: string;
+    nodes: Node[];
+    registryPatch?: Pick<RegistrySlotRuntimeState, "slotOwned" | "lastSlotCheckAt" | "lastSlotCheckError">;
+}
+
+export interface RegisterServiceGuardRunnerOptions {
+    serviceValue: string;
+    getServiceId: () => Promise<string | null>;
+    logTopic?: string;
+    runnerKey?: string;
+    intervalMs: number;
+    initialDelayMs?: number;
+    taskNodeStaleMs: number;
+    workerSpawnCooldownMs: number;
+    maxNodes?: number;
+    spawnWorker: (reason: string) => Promise<void>;
+    onRegistryPatch: (
+        patch: Pick<RegistrySlotRuntimeState, "slotOwned" | "lastSlotCheckAt" | "lastSlotCheckError">,
+    ) => Promise<void>;
+    onGuardPatch: (patch: { nodeId: string; lastCheckAt: string; lastDecision?: string }) => Promise<void>;
+    onDecision?: (decision: string) => Promise<void>;
+}
+
+export interface ServiceGuardNodeOptions extends TriggerNodeOptions {
+    serviceValue: string;
+    logTopic?: string;
+    readinessChecks: ReadinessCheck[];
+    onReadinessReport: (report: ReadinessReport) => Promise<void>;
+    guardRunner: Omit<
+        RegisterServiceGuardRunnerOptions,
+        "serviceValue" | "logTopic" | "runnerKey" | "intervalMs" | "initialDelayMs"
+    > &
+        Pick<RegisterServiceGuardRunnerOptions, "intervalMs" | "initialDelayMs">;
+    spawnWorker: (reason: string) => Promise<void>;
+    onWorkerSpawned?: () => void;
+}

package/src/node/service-guard/worker-spawn-cooldown.ts

@@ -0,0 +1,13 @@
+let lastWorkerSpawnAt = 0;
+
+export function getWorkerSpawnCooldownLastAt(): number {
+    return lastWorkerSpawnAt;
+}
+
+export function markWorkerSpawned(at = Date.now()): void {
+    lastWorkerSpawnAt = at;
+}
+
+export function resetWorkerSpawnCooldownForTests(): void {
+    lastWorkerSpawnAt = 0;
+}