target-supabase-sdk 0.2.3 → 0.2.5

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

package/src/service/index.ts

@@ -1,9 +1,6 @@
-import { scanTargetList } from "../core.api";
-import { generateResponse, type SupabaseResponse } from "../core.interface";
-import { createLogger } from "../shared/log";
-import { ServiceLifecycleStatus } from "./base.interface";
-import { getService } from "./service.api";
-import { CategoryService, type Service } from "./service.interface";
+/**
+ * Service domain public API — curated re-exports only.
+ */
 
 export type {
     EnumMembers,
@@ -12,6 +9,63 @@ export type {
     ServiceLifecycle,
 } from "./base.interface";
 export { ServiceLifecycleStatus } from "./base.interface";
+export type {
+    GetConfigPayload,
+    PostSystemRegistryConfigPayload,
+    ResetSystemRegistryConfigPayload,
+    SystemRegistrySeedSlot,
+} from "./config.api";
+export {
+    buildEmptyServiceSlots,
+    buildSystemRegistryConfigDetails,
+    DEFAULT_SYSTEM_REGISTRY_SEED_SLOTS,
+    getConfig,
+    getConfigSchema,
+    postSystemRegistryConfig,
+    postSystemRegistryConfigSchema,
+    resetSystemRegistryConfig,
+    resetSystemRegistryConfigSchema,
+    systemRegistrySeedSlotSchema,
+} from "./config.api";
+export type { Config, ConfigDetails } from "./config.interface";
+export { CategoryConfig, TARGET_SYSTEM_REGISTRY_KEY } from "./config.interface";
+export type {
+    PatchServiceRuntimeInput,
+    RegisterServiceInput,
+    ReleasedRegistrySlot,
+    ReleaseSystemRegistrySlotsInput,
+    ReleaseSystemRegistrySlotsOutcome,
+    TargetSystemRegistrySlotView,
+    TargetSystemRegistryView,
+} from "./registry.service";
+export {
+    assertRegistrySlotAvailable,
+    assertRegistrySlotOwner,
+    getTargetSystemRegistry,
+    parseServiceSlot,
+    parseServiceSlots,
+    patchServiceRuntime,
+    registerService,
+    registerServiceAtStartup,
+    releaseSystemRegistrySlots,
+    resolveActiveRegistryServiceId,
+    ServiceRegistryError,
+    unregisterService,
+    unregisterServiceAtShutdown,
+} from "./registry.service";
+export type {
+    ClaimRegistrySlotInput,
+    RegistrySlotGuardResult,
+    RegistrySlotRuntimeState,
+    ServiceRegistrySession,
+} from "./registry-lifecycle";
+export {
+    claimServiceRegistrySlot,
+    createClaimedRegistrySlotRuntimeState,
+    EMPTY_REGISTRY_SLOT_RUNTIME_STATE,
+    registrySlotRuntimePatchFromGuardResult,
+    runRegistrySlotGuardCheck,
+} from "./registry-lifecycle";
 export type { GetApiPayload, GetServicePayload, PostApiPayload, PostServicePayload } from "./service.api";
 export {
     apiDetailsSchema,
@@ -27,147 +81,22 @@ export {
     schemaDefinitionSchema,
     serviceDetailsSchema,
     serviceLifecycleSchema,
+    serviceNodeSnapshotSchema,
+    serviceRuntimeSchema,
 } from "./service.api";
-export type { Api, ApiDetails, Service, ServiceDetails } from "./service.interface";
-export { ApiMethod, CategoryApi, CategoryService } from "./service.interface";
-
-export interface DiscoverServiceInput {
-    /** {@link Service.value} */
-    value: string;
-    traceId?: string;
-}
-
-const DISCOVER_LIFECYCLE_STATUS = ServiceLifecycleStatus.ACTIVE;
-const SERVICE_LIFECYCLE_STATUS_FIELD = "details->lifecycle->>status" as const;
-
-async function lookupServicePrimary(value: string): Promise<Service | null> {
-    const response = await getService({ value, lifecycleStatus: DISCOVER_LIFECYCLE_STATUS });
-    return response.data ?? null;
-}
-
-async function lookupServiceByScan(value: string): Promise<Service | null> {
-    const { data } = await scanTargetList<Service>({
-        category: CategoryService.SERVICE,
-        orderBy: { field: "value", ascending: true },
-        maxRows: 1,
-        filterList: [
-            { field: "value", operator: "eq", value },
-            {
-                field: SERVICE_LIFECYCLE_STATUS_FIELD,
-                operator: "eq",
-                value: DISCOVER_LIFECYCLE_STATUS,
-            },
-        ],
-    });
-
-    return data?.[0] ?? null;
-}
-
-async function resolveDiscoverFailureReason(value: string): Promise<"not-found" | "not-available"> {
-    const response = await getService({ value });
-    if (response.data == null) {
-        return "not-found";
-    }
-    return "not-available";
-}
-
-/**
- * Discover a single service by {@link Service.value}.
- * Only returns services with `lifecycle.status === ACTIVE` (filtered at query time).
- *
- * Lookup: primary `getService` → fallback `scanTargetList` by value.
- */
-export async function discoverService(input: DiscoverServiceInput): Promise<SupabaseResponse<Service>> {
-    const value = input.value.trim();
-    const logger = createLogger({
-        module: "discoverService",
-        traceId: input.traceId,
-        labels: { serviceValue: value },
-    });
-
-    if (value === "") {
-        const message = "discoverService: value must not be empty";
-        logger.warn(message, { topic: "service", data: { value: input.value } });
-        return generateResponse.error(message, undefined, "SERVICE_VALUE_REQUIRED") as SupabaseResponse<Service>;
-    }
-
-    try {
-        logger.info("开始发现服务", {
-            topic: "service",
-            data: { value, lifecycleStatus: DISCOVER_LIFECYCLE_STATUS },
-        });
-
-        let service = await lookupServicePrimary(value);
-        let source: "primary" | "scan" = "primary";
-
-        if (service == null) {
-            logger.warn("主路径未命中，尝试 catalog 扫描回退", {
-                topic: "service",
-                data: { value, step: "scan-fallback", lifecycleStatus: DISCOVER_LIFECYCLE_STATUS },
-            });
-            service = await lookupServiceByScan(value);
-            source = "scan";
-        }
-
-        if (service == null) {
-            const reason = await resolveDiscoverFailureReason(value);
-            if (reason === "not-available") {
-                const message = `Service ${value} is not available (lifecycle is not ACTIVE)`;
-                logger.warn("服务已注册但不可用", {
-                    topic: "service",
-                    data: { value, step: "not-available", lifecycleStatus: DISCOVER_LIFECYCLE_STATUS },
-                });
-                return generateResponse.error(message, undefined, "SERVICE_NOT_AVAILABLE") as SupabaseResponse<Service>;
-            }
-
-            const message = `Service not found: ${value}`;
-            logger.error("服务未发现", {
-                topic: "service",
-                data: { value, step: "not-found", tried: ["primary", "scan"] },
-            });
-            return generateResponse.error(message, undefined, "SERVICE_NOT_FOUND") as SupabaseResponse<Service>;
-        }
-
-        logger.info("服务发现成功", {
-            topic: "service",
-            data: {
-                value,
-                source,
-                serviceId: service.id,
-                lifecycleStatus: service.details.lifecycle.status,
-                apiKeyCount: service.details.apiKeys.length,
-                dependencyCount: service.details.dependencies.length,
-            },
-        });
-
-        return generateResponse.success(service);
-    } catch (error) {
-        const message = error instanceof Error ? error.message : String(error);
-        logger.error("服务发现失败", {
-            topic: "service",
-            data: { value, message },
-        });
-
-        let service: Service | null = null;
-        try {
-            service = await lookupServiceByScan(value);
-        } catch (fallbackError) {
-            const fallbackMessage = fallbackError instanceof Error ? fallbackError.message : String(fallbackError);
-            logger.error("扫描回退失败", {
-                topic: "service",
-                data: { value, message: fallbackMessage },
-            });
-            return generateResponse.error(message, undefined, "SERVICE_DISCOVER_FAILED") as SupabaseResponse<Service>;
-        }
-
-        if (service != null) {
-            logger.warn("主路径异常后扫描回退成功", {
-                topic: "service",
-                data: { value, serviceId: service.id, primaryError: message },
-            });
-            return generateResponse.success(service);
-        }
-
-        return generateResponse.error(message, undefined, "SERVICE_DISCOVER_FAILED") as SupabaseResponse<Service>;
-    }
-}
+export type {
+    Api,
+    ApiDetails,
+    Service,
+    ServiceDetails,
+    ServiceNodeSnapshot,
+    ServiceRuntime,
+    ServiceSlot,
+} from "./service.interface";
+export { ApiMethod, CategoryApi, CategoryService, ServiceSlotStatus } from "./service.interface";
+export type { PostServiceInstanceOptions, ServiceBootstrapResult } from "./service-bootstrap";
+export {
+    createActiveServiceLifecycle,
+    defaultL3ServiceDetails,
+    postServiceInstance,
+} from "./service-bootstrap";