target-supabase-sdk 0.2.12 → 0.2.13

package/dist/shared/log/upload/interface.d.ts

@@ -0,0 +1,33 @@
+import type { TargetDraft } from "../../../core.interface";
+import type { List } from "../../../list/list.interface";
+import type { LogEntry } from "../core/log-manager";
+/**
+ * `ListDetails.loaderKey` stamped on every persisted log batch (write + read side).
+ * Business type: **LogBatch** (transport flush). Pairs with log-service **LogTrace**
+ * (`LogTrace.0`) after rekeying by `traceId`.
+ */
+export declare const LOG_PERSIST_LOADER_KEY = "LogBatch.0";
+/** Alias for {@link LOG_PERSIST_LOADER_KEY} — preferred when contrasting with LogTrace. */
+export declare const LOG_BATCH_LOADER_KEY = "LogBatch.0";
+/** Legacy transport metadata — fixed `"slow"` for spool uploads; required for downstream decode today. */
+export type LogPersistLane = "fast" | "medium" | "slow";
+export interface LogBatchMeta {
+    service: string;
+    process: string;
+    pid: number;
+    lane: LogPersistLane;
+    count: number;
+    from: number | null;
+    to: number | null;
+    flushedAt: number;
+    idempotencyKey: string;
+}
+export interface BuildLogListDraftInput {
+    service: string;
+    process: string;
+    lane: LogPersistLane;
+    idempotencyKey: string;
+    entries: LogEntry[];
+}
+export type LogListDraft = TargetDraft<List>;
+//# sourceMappingURL=interface.d.ts.map

package/dist/shared/log/upload/interface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"interface.d.ts","sourceRoot":"","sources":["../../../../src/shared/log/upload/interface.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAC3D,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,8BAA8B,CAAC;AACzD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAEpD;;;;GAIG;AACH,eAAO,MAAM,sBAAsB,eAAe,CAAC;AAEnD,2FAA2F;AAC3F,eAAO,MAAM,oBAAoB,eAAyB,CAAC;AAE3D,0GAA0G;AAC1G,MAAM,MAAM,cAAc,GAAG,MAAM,GAAG,QAAQ,GAAG,MAAM,CAAC;AAExD,MAAM,WAAW,YAAY;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,cAAc,CAAC;IACrB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,EAAE,EAAE,MAAM,GAAG,IAAI,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,sBAAsB;IACnC,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,cAAc,CAAC;IACrB,cAAc,EAAE,MAAM,CAAC;IACvB,OAAO,EAAE,QAAQ,EAAE,CAAC;CACvB;AAED,MAAM,MAAM,YAAY,GAAG,WAAW,CAAC,IAAI,CAAC,CAAC"}

package/dist/shared/log/upload/logger.d.ts

@@ -0,0 +1,22 @@
+/** User-facing / lifecycle logs — may be persisted like normal app logs. */
+export declare const LOG_PERSIST_TOPIC = "log-persist";
+/** Operational logs from the persist pipeline — never re-offered to avoid feedback loops. */
+export declare const LOG_PERSIST_INTERNAL_TOPIC = "log-persist-internal";
+type PipelineLogData = Record<string, unknown>;
+/** Supabase upload path (`postLogBatch`). */
+export declare const persistLogger: {
+    debug: (message: string, data?: PipelineLogData) => void;
+    info: (message: string, data?: PipelineLogData) => void;
+    warn: (message: string, data?: PipelineLogData) => void;
+    error: (message: string, data?: PipelineLogData) => void;
+};
+/** File spool writer + collector. */
+export declare const spoolLogger: {
+    debug: (message: string, data?: PipelineLogData) => void;
+    info: (message: string, data?: PipelineLogData) => void;
+    warn: (message: string, data?: PipelineLogData) => void;
+    error: (message: string, data?: PipelineLogData) => void;
+};
+export declare function isLogPersistInternalTopic(topic: string | undefined): boolean;
+export {};
+//# sourceMappingURL=logger.d.ts.map

package/dist/shared/log/upload/logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../../../src/shared/log/upload/logger.ts"],"names":[],"mappings":"AAEA,4EAA4E;AAC5E,eAAO,MAAM,iBAAiB,gBAAgB,CAAC;AAE/C,6FAA6F;AAC7F,eAAO,MAAM,0BAA0B,yBAAyB,CAAC;AAEjE,KAAK,eAAe,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAoB/C,6CAA6C;AAC7C,eAAO,MAAM,aAAa;qBARD,MAAM,SAAS,eAAe;oBAC/B,MAAM,SAAS,eAAe;oBAC9B,MAAM,SAAS,eAAe;qBAC7B,MAAM,SAAS,eAAe;CAKQ,CAAC;AAEhE,qCAAqC;AACrC,eAAO,MAAM,WAAW;qBAXC,MAAM,SAAS,eAAe;oBAC/B,MAAM,SAAS,eAAe;oBAC9B,MAAM,SAAS,eAAe;qBAC7B,MAAM,SAAS,eAAe;CAQK,CAAC;AAE7D,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAE5E"}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "target-supabase-sdk",
-    "version": "0.2.12",
+    "version": "0.2.13",
     "description": "Supabase client initializer and data access APIs",
     "license": "MIT",
     "author": "KyLoc20",

package/src/browser.ts

@@ -171,6 +171,7 @@ export {
     registerServiceAtStartup,
     registrySlotRuntimePatchFromGuardResult,
     releaseSystemRegistrySlots,
+    releaseSystemRegistrySlotsByServiceId,
     resetSystemRegistryConfig,
     resetSystemRegistryConfigSchema,
     resolveActiveRegistryServiceId,

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

@@ -1,14 +1,15 @@
 import { resolve } from "node:path";
-import { validateLogPersistPreloadEnv } from "../../shared/log/enable-log-persist";
-import { logManager } from "../../shared/log/log-manager";
-import { resolveLogMinLevel } from "../../shared/log/log-min-level";
-import { logPersistEnabledFromEnv } from "../../shared/log/log-persist.config";
+import { logManager } from "../../shared/log/core/log-manager";
+import { resolveLogMinLevel } from "../../shared/log/core/log-min-level";
+import { validateLogSpoolPreloadEnv } from "../../shared/log/spool/enable";
+import { mergeLogSpoolExtraProcessRolesEnv } from "../../shared/log/spool/process-roles";
+import { logSpoolEnabledFromEnv } from "../../shared/log/upload/env";
 import { loadEnvFiles, pinEnvProfileFromArgv } from "../env/load-env";
 import { resolveProjectRootByPackageName } from "../env/project-root";
 import type { ServicePreloadOptions } from "./service-preload.interface";
 
 function applyServiceEnvDefaults(projectRoot: string, options: ServicePreloadOptions): void {
-    if (!logPersistEnabledFromEnv()) {
+    if (!logSpoolEnabledFromEnv()) {
         return;
     }
 
@@ -22,6 +23,10 @@ function applyServiceEnvDefaults(projectRoot: string, options: ServicePreloadOpt
         const relative = options.runtimeDataDirRelative ?? "data/runtime";
         process.env.RUNTIME_DATA_DIR = resolve(projectRoot, relative);
     }
+
+    if (options.logSpoolExtraProcessRoles != null && options.logSpoolExtraProcessRoles.length > 0) {
+        mergeLogSpoolExtraProcessRolesEnv(process.env, options.logSpoolExtraProcessRoles);
+    }
 }
 
 function applyLogMinLevelFromEnv(options: ServicePreloadOptions): void {
@@ -56,7 +61,7 @@ export function runServicePreload(options: ServicePreloadOptions): void {
 
     applyLogMinLevelFromEnv(options);
 
-    validateLogPersistPreloadEnv();
+    validateLogSpoolPreloadEnv();
 
     // TODO: Phase 5 — optional unhandledRejection / uncaughtException formatters
     // (formerly watch-service preload-diagnostics.mjs)

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

@@ -1,4 +1,4 @@
-import type { LogLevel } from "../../shared/log/log-manager";
+import type { LogLevel } from "../../shared/log/core/log-manager";
 
 export interface ServicePreloadOptions {
     /** `import.meta.url` from the service `scripts/preload.mjs`. */
@@ -17,4 +17,6 @@ export interface ServicePreloadOptions {
     defaultLogMinLevel?: LogLevel;
     /** Apply `logManager.setOptions({ minLevel })` from env (default true). */
     applyLogMinLevel?: boolean;
+    /** Extra spool roles beyond main|guard|scheduler|worker (e.g. `chrome-sidecar`). Merged into `LOG_SPOOL_EXTRA_PROCESS_ROLES`. */
+    logSpoolExtraProcessRoles?: readonly string[];
 }

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

@@ -1,4 +1,4 @@
-import { createLogger } from "../../shared/log/create-logger";
+import { createLogger } from "../../shared/log/core/create-logger";
 import type { ManagedChildProcessesOptions } from "./managed-child-processes";
 import { ManagedChildProcesses } from "./managed-child-processes";
 

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

@@ -1,6 +1,7 @@
 import type { ChildProcess } from "node:child_process";
 import { resolve } from "node:path";
 import type { LoggerWithScope } from "../../shared/log";
+import { resolveLogSpoolSpawnEnvForLabel } from "../../shared/log/spool/enable";
 import { isChildProcessRunning, spawnTsxChild } from "./process-spawn";
 
 export interface ManagedChildProcessesOptions {
@@ -80,12 +81,18 @@ export class ManagedChildProcesses {
             return { child: existing, created: false };
         }
 
+        const logSpoolEnv = resolveLogSpoolSpawnEnvForLabel(label);
+        const childEnv =
+            spawnOptions?.env != null
+                ? { ...process.env, ...logSpoolEnv, ...spawnOptions.env }
+                : { ...process.env, ...logSpoolEnv };
+
         const child = spawnTsxChild({
             projectRoot: this.projectRoot,
             entryScript,
             preloadModules: this.preloadModules,
             useTsx: spawnOptions?.useTsx ?? this.defaultUseTsx,
-            env: spawnOptions?.env != null ? { ...process.env, ...spawnOptions.env } : process.env,
+            env: childEnv,
         });
 
         child.on("exit", (code: number | null, signal: NodeJS.Signals | null) => {

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

@@ -1,4 +1,5 @@
 import type { LoggerWithScope } from "../../shared/log";
+import { registerCollectLogRunner } from "../../shared/log/spool/register-collect-log-runner";
 import { TriggerNode } from "../../trigger/trigger-node";
 import { registerServiceGuardRunner } from "./register-service-guard-runner";
 import { runReadinessGate } from "./run-readiness-gate";
@@ -28,6 +29,10 @@ class ServiceGuardNode extends TriggerNode {
             logTopic: options.logTopic,
             ...options.guardRunner,
         });
+        registerCollectLogRunner({
+            serviceValue: options.serviceValue,
+            getServiceId: options.guardRunner.getServiceId,
+        });
         return new ServiceGuardNode(options);
     }
 

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

@@ -1,3 +1,7 @@
+export {
+    COLLECT_LOG_RUNNER_KEY,
+    registerCollectLogRunner,
+} from "../../shared/log/spool/register-collect-log-runner";
 export type {
     RegisterServiceGuardRunnerOptions,
     RunReadinessGateInput,

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

@@ -1,6 +1,9 @@
 import { createLogger, type Service, ServiceRegistryError } from "../../browser";
 import { claimServiceRegistrySlot, type ServiceRegistrySession } from "../../service/registry-lifecycle";
 import 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";
 
 export interface ServiceHostClosable {
@@ -10,6 +13,8 @@ export interface ServiceHostClosable {
 export interface ServiceHostContext {
     service: Service;
     session: ServiceRegistrySession;
+    /** Registry instance id — same as `service.id`; children inherit via spawn env injection. */
+    serviceId: string;
 }
 
 export interface ServiceHostOptions {
@@ -23,9 +28,11 @@ export interface ServiceHostOptions {
     prepare?: () => Promise<void>;
     createInstance: () => Promise<Service | { service: Service; baseUrl?: string }>;
     onRegistryClaimed?: (ctx: ServiceHostContext) => Promise<void>;
-    startSupervisors?: () => void | Promise<void>;
+    startSupervisors?: (ctx: ServiceHostContext) => void | Promise<void>;
     waitUntilReady?: () => Promise<void>;
     startServer?: () => Promise<ServiceHostClosable>;
+    /** When true (default), enable file log spool for main after registry claim. */
+    enableLogSpoolAfterClaim?: boolean;
     /** Stop child processes and other local resources (not registry release). */
     onShutdown?: (signal: string) => Promise<void>;
 }
@@ -121,12 +128,24 @@ export function createServiceHost(options: ServiceHostOptions): ServiceHost {
             throw error;
         }
 
+        const hostCtx: ServiceHostContext = { service: session.service, session, serviceId: session.service.id };
+
         if (options.onRegistryClaimed != null) {
-            await options.onRegistryClaimed({ service: session.service, session });
+            await options.onRegistryClaimed(hostCtx);
+        }
+
+        const enableSpool = options.enableLogSpoolAfterClaim ?? true;
+        if (enableSpool && logSpoolEnabledFromEnv()) {
+            process.env[LOG_SPOOL_SERVICE_ID_ENV] = session.service.id;
+            await ensureLogSpoolFromEnv({
+                serviceId: session.service.id,
+                serviceValue: options.serviceValue,
+                processRole: "main",
+            });
         }
 
         if (options.startSupervisors != null) {
-            await options.startSupervisors();
+            await options.startSupervisors(hostCtx);
         }
 
         if (options.waitUntilReady != null) {

package/src/node.ts

@@ -122,9 +122,11 @@ export type {
 } from "./node/service-host";
 export {
     applyRegistrySlotGuardStep,
+    COLLECT_LOG_RUNNER_KEY,
     createServiceHost,
     getWorkerSpawnCooldownLastAt,
     markWorkerSpawned,
+    registerCollectLogRunner,
     registerServiceGuardRunner,
     runReadinessGate,
     runServiceGuardTick,
@@ -133,27 +135,32 @@ export {
     ServiceGuardNode,
 } 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";
+export type { LogSpoolCoordinator, LogSpoolCoordinatorOptions } from "./shared/log/spool/coordinator";
+export { createLogSpoolCoordinator } from "./shared/log/spool/coordinator";
 export {
-    disableLogPersist,
-    enableLogPersist,
-    ensureLogPersistFromEnv,
-    getLogPersistStats,
-    logPersistEnabledFromEnv,
-    resolveLogPersistRegistryPath,
-    snapshotLogPersistReady,
-    validateLogPersistPreloadEnv,
-    waitForLogPersistReady,
-} from "./shared/log/enable-log-persist";
+    buildLogSpoolSpawnEnv,
+    ensureLogSpoolFromEnv,
+    getLogSpoolStats,
+    logSpoolEnabledFromEnv,
+    shutdownLogSpoolFromEnv,
+    validateLogSpoolPreloadEnv,
+} from "./shared/log/spool/enable";
 export type {
-    EnableLogPersistOptions,
-    EnsureLogPersistFromEnvOptions,
-    LogPersistLane,
-    LogPersistReadySnapshot,
-    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";
+    EnableLogSpoolOptions,
+    LogSpoolCoreProcessRole,
+    LogSpoolProcessRole,
+    LogSpoolWriterStats,
+} from "./shared/log/spool/interface";
+export { resolveLogSpoolRoot } from "./shared/log/spool/paths";
+export {
+    enableLogSpoolFromEnvInChild,
+    getMainLogSpoolWriterStats,
+    isLogSpoolEnabled,
+    shutdownLogSpool,
+} from "./shared/log/spool/service-lifecycle";
+export type { LogBatchMeta, LogPersistLane } from "./shared/log/upload/interface";
 export type {
     ConfigSchema,
     LoadCachedJsConfigOptions,

package/src/service/index.ts

@@ -35,6 +35,8 @@ export type {
     PatchServiceRuntimeInput,
     RegisterServiceInput,
     ReleasedRegistrySlot,
+    ReleaseSystemRegistrySlotsByServiceIdInput,
+    ReleaseSystemRegistrySlotsByServiceIdOutcome,
     ReleaseSystemRegistrySlotsInput,
     ReleaseSystemRegistrySlotsOutcome,
     TargetSystemRegistrySlotView,
@@ -51,6 +53,7 @@ export {
     registerService,
     registerServiceAtStartup,
     releaseSystemRegistrySlots,
+    releaseSystemRegistrySlotsByServiceId,
     resolveActiveRegistryServiceId,
     ServiceRegistryError,
     unregisterService,

package/src/service/registry.service.ts

@@ -58,6 +58,13 @@ export interface ReleaseSystemRegistrySlotsInput {
     maxAttempts?: number;
 }
 
+export interface ReleaseSystemRegistrySlotsByServiceIdInput {
+    /** Runtime Service row ids bound to ACTIVE slots (one slot per id). */
+    serviceIds: string[];
+    traceId?: string;
+    maxAttempts?: number;
+}
+
 export interface ReleasedRegistrySlot {
     serviceValue: string;
     serviceId: string;
@@ -71,6 +78,13 @@ export interface ReleaseSystemRegistrySlotsOutcome {
     unchangedServiceValues: string[];
 }
 
+export interface ReleaseSystemRegistrySlotsByServiceIdOutcome {
+    config: Config;
+    released: ReleasedRegistrySlot[];
+    /** Requested `serviceIds` with no ACTIVE slot released (unknown id, already EMPTY, or never bound). */
+    unchangedServiceIds: string[];
+}
+
 export interface AppendSystemRegistrySlotsInput {
     /** Logical service keys to declare with one new EMPTY slot each when missing. */
     serviceValues: string[];
@@ -365,6 +379,34 @@ function releaseActiveSlotsForServiceValues(
     return { nextSlots, released };
 }
 
+function releaseActiveSlotsForServiceIds(
+    slots: ServiceSlot[],
+    serviceIdSet: ReadonlySet<string>,
+): { nextSlots: ServiceSlot[]; released: ReleasedRegistrySlot[] } {
+    const nextSlots = [...slots];
+    const released: ReleasedRegistrySlot[] = [];
+
+    for (let slotIndex = 0; slotIndex < nextSlots.length; slotIndex += 1) {
+        const slot = nextSlots[slotIndex];
+        if (slot.serviceId == null || !serviceIdSet.has(slot.serviceId) || slot.status !== ServiceSlotStatus.ACTIVE) {
+            continue;
+        }
+
+        released.push({
+            serviceValue: slot.serviceValue,
+            serviceId: slot.serviceId,
+            slotIndex,
+        });
+        nextSlots[slotIndex] = {
+            ...slot,
+            serviceId: null,
+            status: ServiceSlotStatus.EMPTY,
+        };
+    }
+
+    return { nextSlots, released };
+}
+
 /**
  * Force-release ACTIVE registry slots for the given logical service keys (`ACTIVE → EMPTY`).
  * Ops/dev recovery when a process crashed without {@link unregisterService}.
@@ -475,6 +517,106 @@ export async function releaseSystemRegistrySlots(
     );
 }
 
+/**
+ * Force-release ACTIVE registry slots for the given runtime Service row ids (`ACTIVE → EMPTY`).
+ * Targets one slot per `serviceId` — use when multiple slots share the same `serviceValue`.
+ * Ops/dev recovery when a process crashed without {@link unregisterService}.
+ * Does not delete Service rows or mutate `details.runtime`.
+ */
+export async function releaseSystemRegistrySlotsByServiceId(
+    input: ReleaseSystemRegistrySlotsByServiceIdInput,
+): Promise<ReleaseSystemRegistrySlotsByServiceIdOutcome> {
+    const serviceIds = [...new Set(input.serviceIds.map((value) => value.trim()).filter((value) => value !== ""))];
+    if (serviceIds.length === 0) {
+        throw new Error("[releaseSystemRegistrySlotsByServiceId] serviceIds must not be empty");
+    }
+
+    const serviceIdSet = new Set(serviceIds);
+    const maxAttempts = input.maxAttempts ?? DEFAULT_REGISTER_RETRY_ATTEMPTS;
+    const logger = createLogger({
+        module: "releaseSystemRegistrySlotsByServiceId",
+        traceId: input.traceId,
+        labels: { serviceIds: serviceIds.join(",") },
+    });
+
+    logger.info("开始按 serviceId 强制释放 registry 槽位", {
+        topic: LOG_TOPIC_REGISTRY,
+        data: { serviceIds },
+    });
+
+    for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
+        try {
+            const config = await loadSystemRegistryConfig();
+            const revision = parseRegistryRevision(config.details.meta);
+            const slots = parseServiceSlots(config);
+
+            const { nextSlots, released } = releaseActiveSlotsForServiceIds(slots, serviceIdSet);
+            const releasedIdSet = new Set(released.map((entry) => entry.serviceId));
+            const unchangedServiceIds = serviceIds.filter((serviceId) => !releasedIdSet.has(serviceId));
+
+            if (released.length === 0) {
+                logger.info("无 ACTIVE 槽位需要释放", {
+                    topic: LOG_TOPIC_REGISTRY,
+                    data: { serviceIds, attempt },
+                });
+                return { config, released, unchangedServiceIds: serviceIds };
+            }
+
+            await persistSlotClaim({
+                configId: config.id,
+                revision,
+                slots: nextSlots,
+            });
+
+            const updated = await loadSystemRegistryConfig();
+            logger.info("槽位强制释放成功", {
+                topic: LOG_TOPIC_REGISTRY,
+                data: {
+                    released,
+                    unchangedServiceIds,
+                    attempt,
+                    revision: revision + 1,
+                },
+            });
+
+            return {
+                config: updated,
+                released,
+                unchangedServiceIds,
+            };
+        } catch (error) {
+            if (error instanceof ServiceRegistryError) {
+                logger.error("槽位强制释放被拒绝", {
+                    topic: LOG_TOPIC_REGISTRY,
+                    data: { serviceIds, code: error.code, message: error.message },
+                });
+                throw error;
+            }
+
+            if (isOptimisticLockError(error) && attempt < maxAttempts) {
+                logger.warn("registry 乐观锁冲突，重试", {
+                    topic: LOG_TOPIC_REGISTRY,
+                    data: { serviceIds, attempt, maxAttempts },
+                });
+                await sleep(50 * attempt);
+                continue;
+            }
+
+            const message = error instanceof Error ? error.message : String(error);
+            logger.error("槽位强制释放失败", {
+                topic: LOG_TOPIC_REGISTRY,
+                data: { serviceIds, attempt, message },
+            });
+            throw new ServiceRegistryError(message, "REGISTRY_UPDATE_FAILED");
+        }
+    }
+
+    throw new ServiceRegistryError(
+        "[releaseSystemRegistrySlotsByServiceId] Optimistic lock retries exhausted",
+        "REGISTRY_UPDATE_FAILED",
+    );
+}
+
 /**
  * Append EMPTY {@link ServiceSlot} rows for logical service keys not yet declared.
  * Idempotent — skips keys that already appear in `details.objects`.