target-supabase-sdk 0.2.3 → 0.2.4

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

@@ -0,0 +1,30 @@
+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";
+export type {
+    ServiceHost,
+    ServiceHostClosable,
+    ServiceHostContext,
+    ServiceHostOptions,
+} from "./service-host";
+export { createServiceHost } from "./service-host";
+export type { SingleProcessServiceContext, SingleProcessServiceOptions } from "./single-process-service";
+export { runSingleProcessService } from "./single-process-service";

package/src/node/service-host/registry-slot-guard-step.ts

@@ -0,0 +1,57 @@
+import { registrySlotRuntimePatchFromGuardResult, runRegistrySlotGuardCheck } from "../../service/registry-lifecycle";
+import type { LoggerWithScope } from "../../shared/log";
+
+export interface ApplyRegistrySlotGuardInput {
+    serviceValue: string;
+    serviceId: string;
+    checkedAt: string;
+    logger: Pick<LoggerWithScope, "critical" | "warn">;
+    logTopic?: string;
+    traceId?: string;
+}
+
+export interface ApplyRegistrySlotGuardResult {
+    /** When false, caller should abort the supervisor tick (slot lost shutdown initiated). */
+    continueTick: boolean;
+    registryPatch: ReturnType<typeof registrySlotRuntimePatchFromGuardResult>;
+}
+
+/**
+ * Run registry slot ownership check and optionally SIGTERM the parent main process.
+ * Used by guard / supervisor TriggerNode runners across L3 services.
+ */
+export async function applyRegistrySlotGuardStep(
+    input: ApplyRegistrySlotGuardInput,
+): Promise<ApplyRegistrySlotGuardResult> {
+    const result = await runRegistrySlotGuardCheck({
+        serviceValue: input.serviceValue,
+        serviceId: input.serviceId,
+    });
+    const registryPatch = registrySlotRuntimePatchFromGuardResult(result, input.checkedAt);
+
+    if (result.shouldShutdown) {
+        input.logger.critical("Registry slot lost — shutting down service", {
+            topic: input.logTopic ?? "guard",
+            data: {
+                traceId: input.traceId,
+                serviceId: input.serviceId,
+                serviceValue: input.serviceValue,
+            },
+        });
+        process.kill(process.ppid, "SIGTERM");
+        return { continueTick: false, registryPatch };
+    }
+
+    if (result.error != null) {
+        input.logger.warn("Registry slot check failed (transient) — skipping enforcement this tick", {
+            topic: input.logTopic ?? "guard",
+            data: {
+                traceId: input.traceId,
+                serviceId: input.serviceId,
+                message: result.error,
+            },
+        });
+    }
+
+    return { continueTick: true, registryPatch };
+}

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

@@ -0,0 +1,168 @@
+import { createLogger, type Service, ServiceRegistryError } from "../../browser";
+import { claimServiceRegistrySlot, type ServiceRegistrySession } from "../../service/registry-lifecycle";
+import type { LoggerWithScope } from "../../shared/log";
+import type { ManagedChildProcesses } from "../process/managed-child-processes";
+
+export interface ServiceHostClosable {
+    close: () => Promise<void>;
+}
+
+export interface ServiceHostContext {
+    service: Service;
+    session: ServiceRegistrySession;
+}
+
+export interface ServiceHostOptions {
+    serviceValue: string;
+    logger?: LoggerWithScope;
+    logTopic?: string;
+    childProcesses?: ManagedChildProcesses;
+    /** Labels that trigger host shutdown when the child exits unexpectedly. */
+    criticalSupervisors?: readonly string[];
+
+    prepare?: () => Promise<void>;
+    createInstance: () => Promise<Service | { service: Service; baseUrl?: string }>;
+    onRegistryClaimed?: (ctx: ServiceHostContext) => Promise<void>;
+    startSupervisors?: () => void | Promise<void>;
+    waitUntilReady?: () => Promise<void>;
+    startServer?: () => Promise<ServiceHostClosable>;
+    /** Stop child processes and other local resources (not registry release). */
+    onShutdown?: (signal: string) => Promise<void>;
+}
+
+const DEFAULT_CRITICAL_SUPERVISORS = ["guard", "supervisor"] as const;
+
+export interface ServiceHost {
+    run: () => Promise<void>;
+    requestShutdown: (signal: string, exitCode?: number) => void;
+}
+
+function unwrapService(created: Service | { service: Service; baseUrl?: string }): Service {
+    return typeof created === "object" && created != null && "service" in created ? created.service : created;
+}
+
+export function createServiceHost(options: ServiceHostOptions): ServiceHost {
+    const logger = options.logger ?? createLogger({ module: "service-host" });
+    const logTopic = options.logTopic ?? "startup";
+    const criticalSupervisors = options.criticalSupervisors ?? DEFAULT_CRITICAL_SUPERVISORS;
+
+    let session: ServiceRegistrySession | null = null;
+    let httpServer: ServiceHostClosable | null = null;
+    let shuttingDown = false;
+
+    async function shutdown(signal: string, exitCode = 0): Promise<void> {
+        if (shuttingDown) {
+            return;
+        }
+        shuttingDown = true;
+
+        logger.info("shutting down", { topic: logTopic, data: { signal, exitCode } });
+
+        if (httpServer != null) {
+            await httpServer.close().catch(() => undefined);
+            httpServer = null;
+        }
+
+        if (options.onShutdown != null) {
+            await options.onShutdown(signal).catch(() => undefined);
+        }
+
+        if (session != null) {
+            await session.release();
+            session = null;
+        }
+
+        process.exit(exitCode);
+    }
+
+    function requestShutdown(signal: string, exitCode = 0): void {
+        void shutdown(signal, exitCode);
+    }
+
+    function installProcessHandlers(): void {
+        process.on("SIGINT", () => void shutdown("SIGINT"));
+        process.on("SIGTERM", () => void shutdown("SIGTERM"));
+
+        options.childProcesses?.setCriticalExitHandler({
+            labels: criticalSupervisors,
+            onCriticalExit: (label, code, signal) => {
+                if (shuttingDown) {
+                    return;
+                }
+                logger.critical("Critical supervisor exited — shutting down service", {
+                    topic: logTopic,
+                    data: { label, code, signal },
+                });
+                void shutdown("supervisor-exit", 1);
+            },
+        });
+    }
+
+    async function run(): Promise<void> {
+        installProcessHandlers();
+
+        if (options.prepare != null) {
+            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;
+        }
+
+        if (options.onRegistryClaimed != null) {
+            await options.onRegistryClaimed({ service: session.service, session });
+        }
+
+        if (options.startSupervisors != null) {
+            await options.startSupervisors();
+        }
+
+        if (options.waitUntilReady != null) {
+            await options.waitUntilReady();
+        }
+
+        if (options.startServer != null) {
+            httpServer = await options.startServer();
+        }
+    }
+
+    async function runWithFatalHandling(): Promise<void> {
+        try {
+            await run();
+        } catch (error: unknown) {
+            const message = error instanceof Error ? error.message : String(error);
+            const code = error instanceof ServiceRegistryError ? error.code : undefined;
+            logger.error("fatal", { topic: logTopic, data: { message, code } });
+
+            if (httpServer != null) {
+                await httpServer.close().catch(() => undefined);
+                httpServer = null;
+            }
+
+            if (options.onShutdown != null) {
+                await options.onShutdown("fatal").catch(() => undefined);
+            }
+
+            if (session != null) {
+                await session.release().catch(() => undefined);
+                session = null;
+            }
+
+            process.exit(1);
+        }
+    }
+
+    return { run: runWithFatalHandling, requestShutdown };
+}

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

@@ -0,0 +1,58 @@
+import { createLogger, type Service, ServiceRegistryError } from "../../browser";
+import { claimServiceRegistrySlot, type ServiceRegistrySession } from "../../service/registry-lifecycle";
+import type { LoggerWithScope } from "../../shared/log";
+
+export interface SingleProcessServiceContext {
+    service: Service;
+    session: ServiceRegistrySession;
+}
+
+export interface SingleProcessServiceOptions {
+    serviceValue: string;
+    logger?: LoggerWithScope;
+    logTopic?: string;
+
+    prepare?: () => Promise<void>;
+    createInstance: () => Promise<Service>;
+    run: (ctx: SingleProcessServiceContext) => Promise<void>;
+}
+
+/**
+ * Single-process L3 entry (e.g. log-service): claim registry slot then run the service body.
+ * Registry release is the caller's responsibility inside `run` (e.g. TriggerNode `beforeProcessExit`).
+ */
+export async function runSingleProcessService(options: SingleProcessServiceOptions): Promise<void> {
+    const logger = options.logger ?? createLogger({ module: "single-process-service" });
+    const logTopic = options.logTopic ?? "startup";
+
+    if (options.prepare != null) {
+        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;
+    }
+
+    try {
+        await options.run({ service: session.service, session });
+    } catch (error: unknown) {
+        const message = error instanceof Error ? error.message : String(error);
+        logger.error("fatal", { topic: logTopic, data: { message } });
+        await session.release().catch(() => undefined);
+        process.exit(1);
+    }
+}

package/src/node.ts

@@ -51,16 +51,21 @@ export {
     nodeBufferToArrayBuffer,
     readAndVerifySourceFile,
 } from "./node/fs/read-source-file";
+export type { BaseNodeRuntimeOptions, NodeLoopContext } from "./node/node-runtime.base";
 export { BaseNodeRuntime } from "./node/node-runtime.base";
 export type {
     BuildNodeImportArgsInput,
+    CreateManagedChildProcessesOptions,
+    CriticalExitHandler,
     ManagedChildProcessesOptions,
+    SpawnChildOptions,
     SpawnChildResult,
     SpawnTsxChildOptions,
     StopAllChildrenOptions,
 } from "./node/process";
 export {
     buildNodeImportArgs,
+    createManagedChildProcesses,
     isChildProcessRunning,
     ManagedChildProcesses,
     spawnTsxChild,
@@ -85,6 +90,48 @@ export {
     runReadinessChecks,
     waitForServiceReady,
 } from "./node/readiness";
+export type {
+    CreateServiceRuntimeStateStoreOptions,
+    FinishRunnerTickOptions,
+    GuardRuntimeSlice,
+    ReadinessRuntimeSlice,
+    ReadinessStatus,
+    SchedulerRuntimeSlice,
+    ServiceRuntimeCoreNestedKey,
+    ServiceRuntimeExtraSlicePatch,
+    ServiceRuntimeNestedKeys,
+    ServiceRuntimeState,
+    ServiceRuntimeStateStore,
+    WorkerRuntimeSlice,
+} from "./node/runtime-state";
+export { createServiceRuntimeStateStore } from "./node/runtime-state";
+export type {
+    ApplyRegistrySlotGuardInput,
+    ApplyRegistrySlotGuardResult,
+    RegisterServiceGuardRunnerOptions,
+    RunReadinessGateInput,
+    ServiceGuardNodeOptions,
+    ServiceGuardTickInput,
+    ServiceGuardTickResult,
+    ServiceHost,
+    ServiceHostClosable,
+    ServiceHostContext,
+    ServiceHostOptions,
+    SingleProcessServiceContext,
+    SingleProcessServiceOptions,
+} from "./node/service-host";
+export {
+    applyRegistrySlotGuardStep,
+    createServiceHost,
+    getWorkerSpawnCooldownLastAt,
+    markWorkerSpawned,
+    registerServiceGuardRunner,
+    runReadinessGate,
+    runServiceGuardTick,
+    runSingleProcessService,
+    SERVICE_GUARD_RUNNER_KEY,
+    ServiceGuardNode,
+} from "./node/service-host";
 export { RepoManager } from "./repo/repo-manager";
 export {
     disableLogPersist,
@@ -105,6 +152,25 @@ export type {
     LogPersistStats,
     WaitForLogPersistReadyOptions,
 } from "./shared/log/log-persist.interface";
+export type { LogPersistCoordinator, LogPersistCoordinatorOptions } from "./shared/log/log-persist-coordinator";
+export { createLogPersistCoordinator } from "./shared/log/log-persist-coordinator";
+export type {
+    ConfigSchema,
+    LoadCachedJsConfigOptions,
+    ResolveFirstExistingPathOptions,
+} from "./shared/utils/config-path.utils";
+export {
+    getConfigFileDir,
+    importJsConfigModule,
+    loadCachedJsConfigModule,
+    pathExists,
+    resolveFirstExistingPath,
+    resolvePathFromBaseDir,
+    resolvePathFromConfigFile,
+    resolvePathFromCwd,
+    toFileImportHref,
+} from "./shared/utils/config-path.utils";
+export { getValueAtPath } from "./shared/utils/get-value-at-path";
 export type {
     BootstrapLocalTasksResult,
     BootstrapLocalTasksStatus,
@@ -132,6 +198,9 @@ export {
 } from "./task/task-manager";
 export { TaskNode } from "./task/task-node";
 export type { PostTaskPayload } from "./task/task-post.api";
+export { postTask, postTaskSchema } from "./task/task-post.api";
+export type { PostTaskWithRetryOptions, PostTaskWithRetryResult } from "./task/task-post-retry.api";
+export { POST_TASK_DEFAULT_MAX_ATTEMPTS, postTaskWithRetry } from "./task/task-post-retry.api";
 export { postTaskWithValidation } from "./task/task-post-validated.api";
 export type {
     TaskRepoValidationFailureReason,

package/src/service/config.api.ts

@@ -0,0 +1,224 @@
+import { z } from "zod";
+import {
+    createTarget,
+    getPossibleTarget,
+    getTarget,
+    isOptimisticLockError,
+    type QueryFilter,
+    updateTargetDetails,
+    validateWithSchema,
+} from "../core.api";
+import { generateResponse } from "../core.interface";
+import { CategoryConfig, type Config, type ConfigDetails, TARGET_SYSTEM_REGISTRY_KEY } from "./config.interface";
+import { type ServiceSlot, ServiceSlotStatus } from "./service.interface";
+
+const targetIdSchema = z.string().trim().min(1);
+
+export const getConfigSchema = z
+    .object({
+        id: targetIdSchema.optional(),
+        value: z.string().trim().min(1).optional(),
+    })
+    .refine(
+        (payload) => {
+            const hasId = payload.id != null && payload.id !== "";
+            const hasValue = payload.value != null && payload.value !== "";
+            return hasId !== hasValue;
+        },
+        { message: "Provide exactly one of id or value" },
+    );
+
+export type GetConfigPayload = z.infer<typeof getConfigSchema>;
+
+/** One declarative EMPTY slot entry for seeding the system registry. */
+export const systemRegistrySeedSlotSchema = z.object({
+    serviceValue: z.string().trim().min(1),
+});
+
+export type SystemRegistrySeedSlot = z.infer<typeof systemRegistrySeedSlotSchema>;
+
+export const postSystemRegistryConfigSchema = z.object({
+    /** When omitted, {@link DEFAULT_SYSTEM_REGISTRY_SEED_SLOTS} is used. */
+    slots: z.array(systemRegistrySeedSlotSchema).min(1).optional(),
+    tagList: z.array(z.string()).optional().default([]),
+});
+
+export type PostSystemRegistryConfigPayload = z.infer<typeof postSystemRegistryConfigSchema>;
+
+/** Same payload shape as {@link postSystemRegistryConfig} — replaces slots with fresh EMPTY rows. */
+export const resetSystemRegistryConfigSchema = postSystemRegistryConfigSchema;
+
+export type ResetSystemRegistryConfigPayload = PostSystemRegistryConfigPayload;
+
+const DEFAULT_RESET_RETRY_ATTEMPTS = 5;
+const RESET_RETRY_DELAY_MS = 50;
+
+/** Default one EMPTY slot per known L3 service (override via payload or seed file). */
+export const DEFAULT_SYSTEM_REGISTRY_SEED_SLOTS: readonly SystemRegistrySeedSlot[] = [
+    { serviceValue: "log-service" },
+    { serviceValue: "watch-service" },
+    { serviceValue: "download-service" },
+    { serviceValue: "storage-service" },
+] as const;
+
+const configCategoryFilter: QueryFilter = {
+    field: "category",
+    operator: "eq",
+    value: CategoryConfig.CONFIG,
+};
+
+function buildConfigLookupFilters(payload: GetConfigPayload): QueryFilter[] {
+    const filters: QueryFilter[] = [configCategoryFilter];
+
+    if (payload.id == null || payload.id === "") {
+        filters.push({ field: "value", operator: "eq", value: payload.value! });
+    }
+
+    return filters;
+}
+
+/** Build EMPTY {@link ServiceSlot} rows from seed entries (one slot per array item). */
+export function buildEmptyServiceSlots(seedSlots: readonly SystemRegistrySeedSlot[]): ServiceSlot[] {
+    return seedSlots.map(({ serviceValue }) => ({
+        serviceValue,
+        serviceId: null,
+        status: ServiceSlotStatus.EMPTY,
+    }));
+}
+
+function parseRegistryRevision(rawMeta: unknown): number {
+    const source = typeof rawMeta === "object" && rawMeta !== null ? (rawMeta as Record<string, unknown>) : null;
+    const revision = source?.revision;
+    return typeof revision === "number" && Number.isFinite(revision) ? revision : 0;
+}
+
+function lockOnRegistryRevision(revision: number): QueryFilter[] {
+    return [{ field: "details->meta->>revision", operator: "eq", value: String(revision) }];
+}
+
+function sleep(ms: number): Promise<void> {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/** Build `ConfigDetails` for the globally unique system registry row. */
+export function buildSystemRegistryConfigDetails(slots: readonly ServiceSlot[]): ConfigDetails {
+    return {
+        manifestVersion: 0,
+        loaderKey: TARGET_SYSTEM_REGISTRY_KEY,
+        meta: { revision: 0 },
+        objects: [...slots],
+    };
+}
+
+/** Fetch a Config by id or by {@link Config.value} key (`category=config`). */
+export const getConfig = validateWithSchema(
+    getConfigSchema,
+    "getConfigSchema",
+)(async (payload) => {
+    const filterList = buildConfigLookupFilters(payload);
+
+    if (payload.id != null && payload.id !== "") {
+        const result = await getTarget({
+            id: payload.id,
+            filterList,
+        });
+        return {
+            ...result,
+            data: result.data as Config,
+        };
+    }
+
+    const result = await getPossibleTarget({
+        filterList,
+    });
+
+    if (result.data == null) {
+        return {
+            ...result,
+            data: undefined,
+        };
+    }
+
+    return {
+        ...result,
+        data: result.data as Config,
+    };
+});
+
+/**
+ * Insert the globally unique system registry Config (`category=config`,
+ * `value=target-system-registry`). Rejects duplicates via `checkRedundancyFilterList`.
+ */
+export const postSystemRegistryConfig = validateWithSchema(
+    postSystemRegistryConfigSchema,
+    "postSystemRegistryConfigSchema",
+)(async ({ slots, tagList }) => {
+    const seedSlots = [...(slots ?? DEFAULT_SYSTEM_REGISTRY_SEED_SLOTS)];
+    const serviceSlots = buildEmptyServiceSlots(seedSlots);
+    const details = buildSystemRegistryConfigDetails(serviceSlots);
+
+    return createTarget<Config, PostSystemRegistryConfigPayload>({
+        payload: { slots: seedSlots, tagList },
+        checkRedundancyFilterList: [
+            configCategoryFilter,
+            { field: "value", operator: "eq", value: TARGET_SYSTEM_REGISTRY_KEY },
+        ],
+        createFn: () => ({
+            name: TARGET_SYSTEM_REGISTRY_KEY,
+            value: TARGET_SYSTEM_REGISTRY_KEY,
+            category: CategoryConfig.CONFIG,
+            tagList,
+            details,
+        }),
+    });
+});
+
+/**
+ * Replace the system registry slot layout with fresh EMPTY rows.
+ * Creates the row when missing (same as {@link postSystemRegistryConfig}).
+ * Clears ACTIVE slot bindings — use for dev recovery after crashes or layout changes.
+ */
+export const resetSystemRegistryConfig = validateWithSchema(
+    resetSystemRegistryConfigSchema,
+    "resetSystemRegistryConfigSchema",
+)(async ({ slots, tagList }) => {
+    const seedSlots = [...(slots ?? DEFAULT_SYSTEM_REGISTRY_SEED_SLOTS)];
+    const serviceSlots = buildEmptyServiceSlots(seedSlots);
+
+    const existing = await getConfig({ value: TARGET_SYSTEM_REGISTRY_KEY });
+    if (existing.data == null) {
+        return postSystemRegistryConfig({ slots: seedSlots, tagList });
+    }
+
+    const configId = existing.data.id;
+
+    for (let attempt = 1; attempt <= DEFAULT_RESET_RETRY_ATTEMPTS; attempt += 1) {
+        try {
+            const fresh = await getConfig({ id: configId });
+            if (fresh.data == null) {
+                throw new Error(`System registry config disappeared during reset (id=${configId})`);
+            }
+
+            const revision = parseRegistryRevision(fresh.data.details.meta);
+            const updated = await updateTargetDetails<Config, ConfigDetails>({
+                id: configId,
+                optimisticLockFilterList: lockOnRegistryRevision(revision),
+                updateFn: (details) => ({
+                    ...details,
+                    meta: { revision: revision + 1 },
+                    objects: serviceSlots,
+                }),
+            });
+
+            return generateResponse.success<Config>(updated);
+        } catch (error) {
+            if (isOptimisticLockError(error) && attempt < DEFAULT_RESET_RETRY_ATTEMPTS) {
+                await sleep(RESET_RETRY_DELAY_MS * attempt);
+                continue;
+            }
+            throw error;
+        }
+    }
+
+    throw new Error("[resetSystemRegistryConfig] Optimistic lock retries exhausted");
+});

package/src/service/config.interface.ts

@@ -0,0 +1,25 @@
+import type { Target } from "../core.interface";
+
+export interface Config extends Target {
+    /** Human readable name */
+    name: string;
+    /** Unique key, like TARGET_SYSTEM_REGISTRY_KEY */
+    value: string;
+    category: CategoryConfig;
+    details: ConfigDetails;
+}
+
+export enum CategoryConfig {
+    CONFIG = "config",
+}
+
+/** Globally unique Config key for the declarative system service registry. */
+export const TARGET_SYSTEM_REGISTRY_KEY = "target-system-registry";
+
+export interface ConfigDetails {
+    manifestVersion: number;
+    /** How to resolve the Config */
+    loaderKey: string;
+    meta: unknown;
+    objects: Array<unknown>;
+}