target-supabase-sdk 0.2.2 → 0.2.4

package/src/node/node-runtime.base.ts

@@ -21,6 +21,16 @@ export interface NodeLoopContext {
     nodeId: string;
 }
 
+/** Shared options for {@link BaseNodeRuntime} and subclasses (e.g. TriggerNode). */
+export interface BaseNodeRuntimeOptions {
+    /**
+     * Called after node logout (or when the node was never registered),
+     * immediately before `process.exit`. Use for best-effort cleanup such as
+     * {@link unregisterServiceAtShutdown}. Errors are logged and ignored.
+     */
+    beforeProcessExit?: () => void | Promise<void>;
+}
+
 export const LOG_TOPIC_NODE = "node";
 const LOG_TOPIC_COMMAND = "command";
 const LOG_TOPIC_PROCESS = "process";
@@ -35,6 +45,7 @@ abstract class BaseNodeRuntime {
     private static readonly NODE_ID_PENDING_ASSIGNMENT = "pending-node-id";
 
     protected readonly runtimeModule: string;
+    private readonly beforeProcessExitHook: (() => void | Promise<void>) | null;
 
     private _localNodeId: string | null = null;
     private _isNodeIdLocked = false;
@@ -63,14 +74,34 @@ abstract class BaseNodeRuntime {
         this._isNodeIdLocked = true;
     }
 
-    protected constructor(runtimeModule: string) {
+    protected constructor(runtimeModule: string, options?: BaseNodeRuntimeOptions) {
         this.runtimeModule = runtimeModule;
+        this.beforeProcessExitHook = options?.beforeProcessExit ?? null;
         this.isRunning = false;
         this.loopCount = 0;
         this.startupTraceId = logManager.generateTraceId();
         this.startupScope = createScope({ module: runtimeModule, traceId: this.startupTraceId });
     }
 
+    private async runBeforeProcessExit(logger: LoggerWithScope): Promise<void> {
+        if (this.beforeProcessExitHook == null) {
+            return;
+        }
+        try {
+            await this.beforeProcessExitHook();
+        } catch (error) {
+            logger.warn("beforeProcessExit 钩子失败（best-effort）", {
+                topic: LOG_TOPIC_PROCESS,
+                data: { error: getErrorMessage(error) },
+            });
+        }
+    }
+
+    private async exitProcess(code: number, logger: LoggerWithScope): Promise<never> {
+        await this.runBeforeProcessExit(logger);
+        process.exit(code);
+    }
+
     /** Hook: task registration, trigger config load, etc. Throw to abort bootstrap. */
     protected abstract onBeforeRegisterNode(logger: LoggerWithScope): Promise<void>;
 
@@ -296,7 +327,7 @@ abstract class BaseNodeRuntime {
         }
 
         this.isRunning = false;
-        this.shutdownPromise = this.runShutdown(options?.trigger).catch((error) => {
+        this.shutdownPromise = this.runShutdown(options?.trigger).catch(async (error) => {
             const logger = createLogger({
                 scope: patchScope({ scope: this.startupScope, patch: { labels: { nodeId: this.getLogNodeId() } } }),
             });
@@ -307,7 +338,7 @@ abstract class BaseNodeRuntime {
                     error: getErrorMessage(error),
                 },
             });
-            process.exit(1);
+            await this.exitProcess(1, logger);
         });
         return this.shutdownPromise;
     }
@@ -324,7 +355,7 @@ abstract class BaseNodeRuntime {
 
         if (this.localNodeId == null) {
             logger.warn("本地節點未註冊，進程退出", { topic: LOG_TOPIC_NODE });
-            process.exit(0);
+            await this.exitProcess(0, logger);
             return;
         }
 
@@ -344,7 +375,7 @@ abstract class BaseNodeRuntime {
                 data: { error: getErrorMessage(error) },
             });
         } finally {
-            process.exit(0);
+            await this.exitProcess(0, logger);
         }
     }
 
@@ -391,7 +422,7 @@ abstract class BaseNodeRuntime {
         }
 
         this.consecutiveHeartbeatFailures = 0;
-        logger.success("心跳更新成功", {
+        logger.info("心跳更新成功", {
             topic: LOG_TOPIC_NODE,
             data: { lastHeartBeat: formatHeartbeat(lastHeartBeat) },
         });

package/src/node/preload/run-service-preload.ts

@@ -1,7 +1,7 @@
 import { resolve } from "node:path";
 import { validateLogPersistPreloadEnv } from "../../shared/log/enable-log-persist";
 import { logPersistEnabledFromEnv } from "../../shared/log/log-persist.config";
-import { loadEnvFiles } from "../env/load-env";
+import { loadEnvFiles, pinEnvProfileFromArgv } from "../env/load-env";
 import { resolveProjectRootByPackageName } from "../env/project-root";
 import type { ServicePreloadOptions } from "./service-preload.interface";
 
@@ -26,7 +26,7 @@ function applyServiceEnvDefaults(projectRoot: string, options: ServicePreloadOpt
  * Unified Node `--import` preload runner (sync only).
  *
  * Phase 1 — Resolve project root from service package name
- * Phase 2 — Load `.env.local` / `.env`
+ * Phase 2 — Load env files (`.env.local` / `.env`, or `.env.prod` when `--prod`)
  * Phase 3 — Apply SDK service env defaults + optional L3 hook
  * Phase 4 — Validate log-persist env when enabled
  * Phase 5 — Process diagnostics (TODO)
@@ -36,6 +36,7 @@ function applyServiceEnvDefaults(projectRoot: string, options: ServicePreloadOpt
 export function runServicePreload(options: ServicePreloadOptions): void {
     const projectRoot = resolveProjectRootByPackageName(options.callerImportMetaUrl, options.packageName);
 
+    pinEnvProfileFromArgv();
     loadEnvFiles(projectRoot, { afterLoad: options.afterLoadEnv });
 
     applyServiceEnvDefaults(projectRoot, options);

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

@@ -0,0 +1,27 @@
+import { createLogger } from "../../shared/log/create-logger";
+import type { ManagedChildProcessesOptions } from "./managed-child-processes";
+import { ManagedChildProcesses } from "./managed-child-processes";
+
+export type CreateManagedChildProcessesOptions = Pick<
+    ManagedChildProcessesOptions,
+    "projectRoot" | "preloadModules" | "useTsx" | "graceMs"
+> & {
+    /** Defaults to `createLogger({ module: "launcher" })`. */
+    logger?: ManagedChildProcessesOptions["logger"];
+};
+
+const DEFAULT_PRELOAD_MODULES = ["./scripts/preload.mjs"] as const;
+
+/**
+ * Standard L3 service child-process registry: node (not tsx), service preload, launcher logger.
+ * Each service keeps a singleton in `src/startup/child-processes.ts`.
+ */
+export function createManagedChildProcesses(options: CreateManagedChildProcessesOptions): ManagedChildProcesses {
+    return new ManagedChildProcesses({
+        projectRoot: options.projectRoot,
+        preloadModules: options.preloadModules ?? DEFAULT_PRELOAD_MODULES,
+        useTsx: options.useTsx ?? false,
+        graceMs: options.graceMs,
+        logger: options.logger ?? createLogger({ module: "launcher" }),
+    });
+}

package/src/node/process/index.ts

@@ -1,5 +1,9 @@
+export type { CreateManagedChildProcessesOptions } from "./create-managed-child-processes";
+export { createManagedChildProcesses } from "./create-managed-child-processes";
 export type {
+    CriticalExitHandler,
     ManagedChildProcessesOptions,
+    SpawnChildOptions,
     SpawnChildResult,
     StopAllChildrenOptions,
 } from "./managed-child-processes";

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;
+}