target-supabase-sdk 0.2.13 → 0.2.15

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

@@ -1,8 +1,8 @@
-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 { Node } from "../node.interface";
 import type { ReadinessCheck, ReadinessReport } from "../readiness/readiness.types";
+import type { GuardRuntimeSlice } from "../runtime-state/service-runtime-state.types";
 
 /** Default TriggerManager runner key for {@link registerServiceGuardRunner}. */
 export const SERVICE_GUARD_RUNNER_KEY = "service-guard";
@@ -45,20 +45,45 @@ export interface RegisterServiceGuardRunnerOptions {
     onRegistryPatch: (
         patch: Pick<RegistrySlotRuntimeState, "slotOwned" | "lastSlotCheckAt" | "lastSlotCheckError">,
     ) => Promise<void>;
-    onGuardPatch: (patch: { nodeId: string; lastCheckAt: string; lastDecision?: string }) => Promise<void>;
+    onGuardPatch: (patch: Partial<GuardRuntimeSlice>) => Promise<void>;
     onDecision?: (decision: string) => Promise<void>;
 }
 
-export interface ServiceGuardNodeOptions extends TriggerNodeOptions {
+export interface ServiceGuardNodeOptions {
     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>;
+    guardRunner: Omit<RegisterServiceGuardRunnerOptions, "serviceValue" | "logTopic" | "runnerKey" | "spawnWorker">;
+    /**
+     * Idempotent spawn of all business nodes (scheduler + worker, etc.).
+     * Used at bootstrap, silent recovery, and healthy-mode TaskNode respawn.
+     */
+    spawnBusinessNodes: (reason: string) => Promise<void>;
+    /** Stop business nodes only (never the guard process). */
+    stopBusinessNodes: () => Promise<void>;
+    /** Local runtime gate: all business nodes registered and ready. */
+    isBusinessReady: () => Promise<boolean>;
+    /** Timeout for {@link isBusinessReady} during bootstrap and recovery. Default 180s. */
+    businessReadyTimeoutMs?: number;
+    /** Extra hook after the initial business spawn (cooldown is recorded automatically). */
     onWorkerSpawned?: () => void;
+    beforeProcessExit?: () => void | Promise<void>;
+}
+
+/** True when the guard slice is serving traffic (`mode` omitted = legacy healthy). */
+export function isGuardAvailable(guard: Pick<GuardRuntimeSlice, "mode">): boolean {
+    return guard.mode == null || guard.mode === "healthy";
+}
+
+/**
+ * Seconds for `Retry-After` when the guard is not serving traffic.
+ * `null` when {@link isGuardAvailable} is true.
+ */
+export function guardRetryAfterSec(guard: Pick<GuardRuntimeSlice, "mode" | "silentBackoffMs">): number | null {
+    if (isGuardAvailable(guard)) {
+        return null;
+    }
+    const backoffMs = guard.silentBackoffMs > 0 ? guard.silentBackoffMs : 15_000;
+    return Math.max(1, Math.ceil(backoffMs / 1000));
 }

package/src/node/service-host/claim-registry-slot.ts

@@ -0,0 +1,33 @@
+import { ServiceRegistryError } from "../../service/registry.service";
+import { claimServiceRegistrySlot, type ServiceRegistrySession } from "../../service/registry-lifecycle";
+import type { Service } from "../../service/service.interface";
+import type { LoggerWithScope } from "../../shared/log";
+
+export interface ClaimRegistrySlotOrExitInput {
+    serviceValue: string;
+    createInstance: () => Promise<Service>;
+    logger: LoggerWithScope;
+    logTopic: string;
+}
+
+/**
+ * Claim a registry slot, or `process.exit(1)` when no EMPTY slot remains.
+ * Other errors propagate.
+ */
+export async function claimRegistrySlotOrExit(input: ClaimRegistrySlotOrExitInput): Promise<ServiceRegistrySession> {
+    try {
+        return await claimServiceRegistrySlot({
+            serviceValue: input.serviceValue,
+            createInstance: input.createInstance,
+        });
+    } catch (error) {
+        if (error instanceof ServiceRegistryError && error.code === "SERVICE_SLOTS_FULL") {
+            input.logger.critical("No EMPTY registry slot — refusing to start", {
+                topic: input.logTopic,
+                data: { serviceValue: input.serviceValue, code: error.code },
+            });
+            process.exit(1);
+        }
+        throw error;
+    }
+}

package/src/node/service-host/create-l3-child-launcher.ts

@@ -0,0 +1,157 @@
+import type { ChildProcess } from "node:child_process";
+import type { ManagedChildProcesses } from "../process/managed-child-processes";
+import type {
+    GuardRuntimeSlice,
+    SchedulerRuntimeSlice,
+    WorkerRuntimeSlice,
+} from "../runtime-state/service-runtime-state.types";
+
+const WORKER_SCRIPT = "./dist/processes/worker.js";
+const GUARD_SCRIPT = "./dist/processes/guard.js";
+const SCHEDULER_SCRIPT = "./dist/processes/scheduler.js";
+
+export interface L3ChildLauncherRuntimeStore {
+    readRuntimeState(): Promise<{
+        worker: WorkerRuntimeSlice;
+        scheduler: SchedulerRuntimeSlice;
+        guard: GuardRuntimeSlice;
+    }>;
+    writeRuntimeState(patch: {
+        worker?: Partial<WorkerRuntimeSlice>;
+        scheduler?: Partial<SchedulerRuntimeSlice>;
+        guard?: Partial<GuardRuntimeSlice>;
+    }): Promise<unknown>;
+}
+
+export interface CreateL3ChildLauncherOptions {
+    childProcesses: ManagedChildProcesses;
+    readRuntimeState: L3ChildLauncherRuntimeStore["readRuntimeState"];
+    writeRuntimeState: L3ChildLauncherRuntimeStore["writeRuntimeState"];
+    /** Merged onto the child env. Default: `{ LOG_PERSIST_PROCESS: label }`. */
+    spawnEnv?: (label: string) => Record<string, string>;
+}
+
+export interface L3ChildLauncher {
+    spawnGuard: () => ChildProcess;
+    spawnTaskWorker: (reason: string) => Promise<ChildProcess>;
+    spawnScheduler: (reason: string) => Promise<ChildProcess>;
+    spawnBusinessNodes: (reason: string) => Promise<void>;
+    stopBusinessNodes: () => Promise<void>;
+    isBusinessReady: () => Promise<boolean>;
+    stopChildProcesses: () => Promise<void>;
+}
+
+function defaultSpawnEnv(label: string): Record<string, string> {
+    return { LOG_PERSIST_PROCESS: label };
+}
+
+/**
+ * Guard-owned scheduler + worker spawn/stop, plus main-owned Guard spawn.
+ * `stopBusinessNodes` must run in the Guard process (that instance's children only).
+ * `stopChildProcesses` is for main shutdown (`extraPids` for Guard-spawned PIDs).
+ */
+export function createL3ChildLauncher(options: CreateL3ChildLauncherOptions): L3ChildLauncher {
+    const { childProcesses, readRuntimeState, writeRuntimeState } = options;
+    const spawnEnv = options.spawnEnv ?? defaultSpawnEnv;
+
+    function nowIso(): string {
+        return new Date().toISOString();
+    }
+
+    async function spawnTaskWorker(reason: string): Promise<ChildProcess> {
+        const { child, created } = childProcesses.spawn("worker", WORKER_SCRIPT, {
+            env: spawnEnv("worker"),
+        });
+        if (!created) {
+            return child;
+        }
+
+        const current = await readRuntimeState();
+        await writeRuntimeState({
+            worker: {
+                pid: child.pid ?? null,
+                spawnedAt: nowIso(),
+                ready: false,
+                registeredTasks: [],
+                readyAt: null,
+            },
+            guard: {
+                lastSpawnAt: nowIso(),
+                lastDecision: reason,
+                spawnCount: current.guard.spawnCount + 1,
+            },
+        });
+
+        return child;
+    }
+
+    function spawnGuard(): ChildProcess {
+        return childProcesses.spawn("guard", GUARD_SCRIPT, { env: spawnEnv("guard") }).child;
+    }
+
+    async function spawnScheduler(reason: string): Promise<ChildProcess> {
+        const { child, created } = childProcesses.spawn("scheduler", SCHEDULER_SCRIPT, {
+            env: spawnEnv("scheduler"),
+        });
+        if (!created) {
+            return child;
+        }
+
+        await writeRuntimeState({
+            scheduler: {
+                pid: child.pid ?? null,
+                spawnedAt: nowIso(),
+                ready: false,
+                readyAt: null,
+            },
+            guard: {
+                lastDecision: reason,
+            },
+        });
+
+        return child;
+    }
+
+    async function spawnBusinessNodes(reason: string): Promise<void> {
+        await spawnScheduler(reason);
+        await spawnTaskWorker(reason);
+    }
+
+    async function stopBusinessNodes(): Promise<void> {
+        await childProcesses.stopAll();
+        await writeRuntimeState({
+            worker: {
+                pid: null,
+                ready: false,
+                readyAt: null,
+                registeredTasks: [],
+            },
+            scheduler: {
+                pid: null,
+                ready: false,
+                readyAt: null,
+            },
+        });
+    }
+
+    async function isBusinessReady(): Promise<boolean> {
+        const state = await readRuntimeState();
+        return state.worker.ready && state.scheduler.ready;
+    }
+
+    async function stopChildProcesses(): Promise<void> {
+        const state = await readRuntimeState();
+        const extraPids = [state.worker.pid, state.scheduler.pid].filter((pid): pid is number => pid != null);
+        await childProcesses.stopAll({ extraPids });
+    }
+
+    return {
+        spawnGuard,
+        spawnTaskWorker,
+        spawnScheduler,
+        spawnBusinessNodes,
+        stopBusinessNodes,
+        isBusinessReady,
+        stopChildProcesses,
+    };
+}

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

@@ -1,28 +1,9 @@
-export {
-    COLLECT_LOG_RUNNER_KEY,
-    registerCollectLogRunner,
-} from "../../shared/log/spool/register-collect-log-runner";
 export type {
-    RegisterServiceGuardRunnerOptions,
-    RunReadinessGateInput,
-    ServiceGuardNodeOptions,
-    ServiceGuardTickInput,
-    ServiceGuardTickResult,
-} from "../service-guard";
-export {
-    getWorkerSpawnCooldownLastAt,
-    markWorkerSpawned,
-    registerServiceGuardRunner,
-    runReadinessGate,
-    runServiceGuardTick,
-    SERVICE_GUARD_RUNNER_KEY,
-    ServiceGuardNode,
-} from "../service-guard";
-export type {
-    ApplyRegistrySlotGuardInput,
-    ApplyRegistrySlotGuardResult,
-} from "./registry-slot-guard-step";
-export { applyRegistrySlotGuardStep } from "./registry-slot-guard-step";
+    CreateL3ChildLauncherOptions,
+    L3ChildLauncher,
+    L3ChildLauncherRuntimeStore,
+} from "./create-l3-child-launcher";
+export { createL3ChildLauncher } from "./create-l3-child-launcher";
 export type {
     ServiceHost,
     ServiceHostClosable,

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

@@ -1,10 +1,12 @@
-import { createLogger, type Service, ServiceRegistryError } from "../../browser";
-import { claimServiceRegistrySlot, type ServiceRegistrySession } from "../../service/registry-lifecycle";
-import type { LoggerWithScope } from "../../shared/log";
+import { ServiceRegistryError } from "../../service/registry.service";
+import type { ServiceRegistrySession } from "../../service/registry-lifecycle";
+import type { Service } from "../../service/service.interface";
+import { createLogger, type LoggerWithScope } from "../../shared/log";
 import { LOG_SPOOL_SERVICE_ID_ENV } from "../../shared/log/spool/config";
 import { ensureLogSpoolFromEnv } from "../../shared/log/spool/enable";
 import { logSpoolEnabledFromEnv } from "../../shared/log/upload/env";
 import type { ManagedChildProcesses } from "../process/managed-child-processes";
+import { claimRegistrySlotOrExit } from "./claim-registry-slot";
 
 export interface ServiceHostClosable {
     close: () => Promise<void>;
@@ -112,21 +114,12 @@ export function createServiceHost(options: ServiceHostOptions): ServiceHost {
             await options.prepare();
         }
 
-        try {
-            session = await claimServiceRegistrySlot({
-                serviceValue: options.serviceValue,
-                createInstance: async () => unwrapService(await options.createInstance()),
-            });
-        } catch (error) {
-            if (error instanceof ServiceRegistryError && error.code === "SERVICE_SLOTS_FULL") {
-                logger.critical("No EMPTY registry slot — refusing to start", {
-                    topic: logTopic,
-                    data: { serviceValue: options.serviceValue, code: error.code },
-                });
-                process.exit(1);
-            }
-            throw error;
-        }
+        session = await claimRegistrySlotOrExit({
+            serviceValue: options.serviceValue,
+            createInstance: async () => unwrapService(await options.createInstance()),
+            logger,
+            logTopic,
+        });
 
         const hostCtx: ServiceHostContext = { service: session.service, session, serviceId: session.service.id };
 

package/src/node/service-host/single-process-service.ts

@@ -1,6 +1,7 @@
-import { createLogger, type Service, ServiceRegistryError } from "../../browser";
-import { claimServiceRegistrySlot, type ServiceRegistrySession } from "../../service/registry-lifecycle";
-import type { LoggerWithScope } from "../../shared/log";
+import type { ServiceRegistrySession } from "../../service/registry-lifecycle";
+import type { Service } from "../../service/service.interface";
+import { createLogger, type LoggerWithScope } from "../../shared/log";
+import { claimRegistrySlotOrExit } from "./claim-registry-slot";
 
 export interface SingleProcessServiceContext {
     service: Service;
@@ -29,23 +30,12 @@ export async function runSingleProcessService(options: SingleProcessServiceOptio
         await options.prepare();
     }
 
-    let session: ServiceRegistrySession | null = null;
-
-    try {
-        session = await claimServiceRegistrySlot({
-            serviceValue: options.serviceValue,
-            createInstance: options.createInstance,
-        });
-    } catch (error) {
-        if (error instanceof ServiceRegistryError && error.code === "SERVICE_SLOTS_FULL") {
-            logger.critical("No EMPTY registry slot — refusing to start", {
-                topic: logTopic,
-                data: { serviceValue: options.serviceValue, code: error.code },
-            });
-            process.exit(1);
-        }
-        throw error;
-    }
+    const session = await claimRegistrySlotOrExit({
+        serviceValue: options.serviceValue,
+        createInstance: options.createInstance,
+        logger,
+        logTopic,
+    });
 
     try {
         await options.run({ service: session.service, session });

package/src/node.ts

@@ -25,9 +25,6 @@ export {
     envProfileFromProcess,
     initSupabaseFromStandardEnv,
     loadEnvFiles,
-    parseEnvFile,
-    parseEnvLine,
-    pinEnvProfileFromArgv,
     publicBaseUrlFromEnv,
     readEnv,
     requireEnv,
@@ -77,6 +74,7 @@ export type {
     ReadinessCheckResult,
     ReadinessReport,
     RequiredEnvCheckOptions,
+    RunReadinessGateInput,
     ServiceReadyGate,
     ServiceReadySnapshot,
     SupabaseReachableCheckOptions,
@@ -88,6 +86,7 @@ export {
     createSupabaseReachableCheck,
     pollUntil,
     runReadinessChecks,
+    runReadinessGate,
     waitForServiceReady,
 } from "./node/readiness";
 export type {
@@ -109,31 +108,32 @@ export type {
     ApplyRegistrySlotGuardInput,
     ApplyRegistrySlotGuardResult,
     RegisterServiceGuardRunnerOptions,
-    RunReadinessGateInput,
     ServiceGuardNodeOptions,
     ServiceGuardTickInput,
     ServiceGuardTickResult,
-    ServiceHost,
-    ServiceHostClosable,
-    ServiceHostContext,
-    ServiceHostOptions,
-    SingleProcessServiceContext,
-    SingleProcessServiceOptions,
-} from "./node/service-host";
+} from "./node/service-guard";
 export {
     applyRegistrySlotGuardStep,
-    COLLECT_LOG_RUNNER_KEY,
-    createServiceHost,
-    getWorkerSpawnCooldownLastAt,
+    guardRetryAfterSec,
+    isGuardAvailable,
     markWorkerSpawned,
-    registerCollectLogRunner,
     registerServiceGuardRunner,
-    runReadinessGate,
     runServiceGuardTick,
-    runSingleProcessService,
     SERVICE_GUARD_RUNNER_KEY,
     ServiceGuardNode,
+} from "./node/service-guard";
+export type {
+    CreateL3ChildLauncherOptions,
+    L3ChildLauncher,
+    L3ChildLauncherRuntimeStore,
+    ServiceHost,
+    ServiceHostClosable,
+    ServiceHostContext,
+    ServiceHostOptions,
+    SingleProcessServiceContext,
+    SingleProcessServiceOptions,
 } from "./node/service-host";
+export { createL3ChildLauncher, createServiceHost, runSingleProcessService } from "./node/service-host";
 export { RepoManager } from "./repo/repo-manager";
 export { runCollectLogTick } from "./shared/log/spool/collector";
 export { LOG_SPOOL_SERVICE_ID_ENV } from "./shared/log/spool/config";
@@ -154,6 +154,10 @@ export type {
     LogSpoolWriterStats,
 } from "./shared/log/spool/interface";
 export { resolveLogSpoolRoot } from "./shared/log/spool/paths";
+export {
+    COLLECT_LOG_RUNNER_KEY,
+    registerCollectLogRunner,
+} from "./shared/log/spool/register-collect-log-runner";
 export {
     enableLogSpoolFromEnvInChild,
     getMainLogSpoolWriterStats,
@@ -177,7 +181,6 @@ export {
     resolvePathFromCwd,
     toFileImportHref,
 } from "./shared/utils/config-path.utils";
-export { getValueAtPath } from "./shared/utils/get-value-at-path";
 export type {
     BootstrapLocalTasksResult,
     BootstrapLocalTasksStatus,

package/src/shared/utils/postgrest.utils.ts

@@ -0,0 +1,28 @@
+/**
+ * PostgREST / Supabase JS client helpers for `target` table filters.
+ *
+ * @see `.cursor/skills/postgrest-query-filters/SKILL.md`
+ */
+
+/**
+ * Escape `%`, `_`, and `\` for PostgREST `ilike` patterns.
+ * Also strips commas — they break `.or()` filter strings when multiple columns are searched.
+ */
+export function escapeIlikePattern(raw: string): string {
+    return raw.replace(/\\/g, "\\\\").replace(/%/g, "\\%").replace(/_/g, "\\_").replace(/,/g, "");
+}
+
+/**
+ * Format a JS string array as a PostgreSQL `text[]` literal for PostgREST filter values.
+ *
+ * Required when tag values contain `:` or other special characters, and when using
+ * `.filter(column, "not.ov", literal)` — `.not("column", "ov", jsArray)` stringifies
+ * with `Array#toString()` and produces an invalid array literal.
+ *
+ * @example
+ * toPostgrestTextArrayLiteral(["stop-word:base", "small-word"])
+ * // → '{"stop-word:base","small-word"}'
+ */
+export function toPostgrestTextArrayLiteral(values: readonly string[]): string {
+    return `{${values.map((v) => `"${v.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`).join(",")}}`;
+}