target-supabase-sdk 0.2.4 → 0.2.5

package/dist/preload.js

@@ -1,5 +1,5 @@
 import { resolve } from 'node:path';
-import { r as resolveProjectRootByPackageName, p as pinEnvProfileFromArgv, l as loadEnvFiles, v as validateLogPersistPreloadEnv, a as logPersistEnabledFromEnv } from './chunks/enable-log-persist-B8rg_wXG.js';
+import { r as resolveProjectRootByPackageName, p as pinEnvProfileFromArgv, l as loadEnvFiles, v as validateLogPersistPreloadEnv, a as logPersistEnabledFromEnv } from './chunks/enable-log-persist-BL2FaGQp.js';
 import 'node:fs';
 import 'node:url';
 import 'node:fs/promises';

package/dist/service/index.d.ts

@@ -7,8 +7,8 @@ export type { GetConfigPayload, PostSystemRegistryConfigPayload, ResetSystemRegi
 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, TargetSystemRegistrySlotView, TargetSystemRegistryView, } from "./registry.service";
-export { assertRegistrySlotAvailable, assertRegistrySlotOwner, getTargetSystemRegistry, parseServiceSlot, parseServiceSlots, patchServiceRuntime, registerService, registerServiceAtStartup, resolveActiveRegistryServiceId, ServiceRegistryError, unregisterService, unregisterServiceAtShutdown, } from "./registry.service";
+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";

package/dist/service/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/service/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,YAAY,EACR,WAAW,EACX,eAAe,EACf,gBAAgB,EAChB,gBAAgB,GACnB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,sBAAsB,EAAE,MAAM,kBAAkB,CAAC;AAC1D,YAAY,EACR,gBAAgB,EAChB,+BAA+B,EAC/B,gCAAgC,EAChC,sBAAsB,GACzB,MAAM,cAAc,CAAC;AACtB,OAAO,EACH,sBAAsB,EACtB,gCAAgC,EAChC,kCAAkC,EAClC,SAAS,EACT,eAAe,EACf,wBAAwB,EACxB,8BAA8B,EAC9B,yBAAyB,EACzB,+BAA+B,EAC/B,4BAA4B,GAC/B,MAAM,cAAc,CAAC;AACtB,YAAY,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAChE,OAAO,EAAE,cAAc,EAAE,0BAA0B,EAAE,MAAM,oBAAoB,CAAC;AAChF,YAAY,EACR,wBAAwB,EACxB,oBAAoB,EACpB,4BAA4B,EAC5B,wBAAwB,GAC3B,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EACH,2BAA2B,EAC3B,uBAAuB,EACvB,uBAAuB,EACvB,gBAAgB,EAChB,iBAAiB,EACjB,mBAAmB,EACnB,eAAe,EACf,wBAAwB,EACxB,8BAA8B,EAC9B,oBAAoB,EACpB,iBAAiB,EACjB,2BAA2B,GAC9B,MAAM,oBAAoB,CAAC;AAC5B,YAAY,EACR,sBAAsB,EACtB,uBAAuB,EACvB,wBAAwB,EACxB,sBAAsB,GACzB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EACH,wBAAwB,EACxB,qCAAqC,EACrC,iCAAiC,EACjC,uCAAuC,EACvC,yBAAyB,GAC5B,MAAM,sBAAsB,CAAC;AAC9B,YAAY,EAAE,aAAa,EAAE,iBAAiB,EAAE,cAAc,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AAC1G,OAAO,EACH,gBAAgB,EAChB,qBAAqB,EACrB,MAAM,EACN,YAAY,EACZ,UAAU,EACV,gBAAgB,EAChB,OAAO,EACP,aAAa,EACb,WAAW,EACX,iBAAiB,EACjB,sBAAsB,EACtB,oBAAoB,EACpB,sBAAsB,EACtB,yBAAyB,EACzB,oBAAoB,GACvB,MAAM,eAAe,CAAC;AACvB,YAAY,EACR,GAAG,EACH,UAAU,EACV,OAAO,EACP,cAAc,EACd,mBAAmB,EACnB,cAAc,EACd,WAAW,GACd,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AACjG,YAAY,EAAE,0BAA0B,EAAE,sBAAsB,EAAE,MAAM,qBAAqB,CAAC;AAC9F,OAAO,EACH,4BAA4B,EAC5B,uBAAuB,EACvB,mBAAmB,GACtB,MAAM,qBAAqB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/service/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,YAAY,EACR,WAAW,EACX,eAAe,EACf,gBAAgB,EAChB,gBAAgB,GACnB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,sBAAsB,EAAE,MAAM,kBAAkB,CAAC;AAC1D,YAAY,EACR,gBAAgB,EAChB,+BAA+B,EAC/B,gCAAgC,EAChC,sBAAsB,GACzB,MAAM,cAAc,CAAC;AACtB,OAAO,EACH,sBAAsB,EACtB,gCAAgC,EAChC,kCAAkC,EAClC,SAAS,EACT,eAAe,EACf,wBAAwB,EACxB,8BAA8B,EAC9B,yBAAyB,EACzB,+BAA+B,EAC/B,4BAA4B,GAC/B,MAAM,cAAc,CAAC;AACtB,YAAY,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAChE,OAAO,EAAE,cAAc,EAAE,0BAA0B,EAAE,MAAM,oBAAoB,CAAC;AAChF,YAAY,EACR,wBAAwB,EACxB,oBAAoB,EACpB,oBAAoB,EACpB,+BAA+B,EAC/B,iCAAiC,EACjC,4BAA4B,EAC5B,wBAAwB,GAC3B,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EACH,2BAA2B,EAC3B,uBAAuB,EACvB,uBAAuB,EACvB,gBAAgB,EAChB,iBAAiB,EACjB,mBAAmB,EACnB,eAAe,EACf,wBAAwB,EACxB,0BAA0B,EAC1B,8BAA8B,EAC9B,oBAAoB,EACpB,iBAAiB,EACjB,2BAA2B,GAC9B,MAAM,oBAAoB,CAAC;AAC5B,YAAY,EACR,sBAAsB,EACtB,uBAAuB,EACvB,wBAAwB,EACxB,sBAAsB,GACzB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EACH,wBAAwB,EACxB,qCAAqC,EACrC,iCAAiC,EACjC,uCAAuC,EACvC,yBAAyB,GAC5B,MAAM,sBAAsB,CAAC;AAC9B,YAAY,EAAE,aAAa,EAAE,iBAAiB,EAAE,cAAc,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AAC1G,OAAO,EACH,gBAAgB,EAChB,qBAAqB,EACrB,MAAM,EACN,YAAY,EACZ,UAAU,EACV,gBAAgB,EAChB,OAAO,EACP,aAAa,EACb,WAAW,EACX,iBAAiB,EACjB,sBAAsB,EACtB,oBAAoB,EACpB,sBAAsB,EACtB,yBAAyB,EACzB,oBAAoB,GACvB,MAAM,eAAe,CAAC;AACvB,YAAY,EACR,GAAG,EACH,UAAU,EACV,OAAO,EACP,cAAc,EACd,mBAAmB,EACnB,cAAc,EACd,WAAW,GACd,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AACjG,YAAY,EAAE,0BAA0B,EAAE,sBAAsB,EAAE,MAAM,qBAAqB,CAAC;AAC9F,OAAO,EACH,4BAA4B,EAC5B,uBAAuB,EACvB,mBAAmB,GACtB,MAAM,qBAAqB,CAAC"}

package/dist/service/registry.service.d.ts

@@ -27,6 +27,23 @@ export interface RegisterServiceInput {
     traceId?: string;
     maxAttempts?: number;
 }
+export interface ReleaseSystemRegistrySlotsInput {
+    /** Logical service keys whose ACTIVE slots should be forced to EMPTY (e.g. `watch-service`). */
+    serviceValues: string[];
+    traceId?: string;
+    maxAttempts?: number;
+}
+export interface ReleasedRegistrySlot {
+    serviceValue: string;
+    serviceId: string;
+    slotIndex: number;
+}
+export interface ReleaseSystemRegistrySlotsOutcome {
+    config: Config;
+    released: ReleasedRegistrySlot[];
+    /** Requested `serviceValues` with no ACTIVE slot released (already EMPTY or never bound). */
+    unchangedServiceValues: string[];
+}
 export declare class ServiceRegistryError extends Error {
     readonly code: "REGISTRY_CONFIG_NOT_FOUND" | "SERVICE_NOT_DECLARED" | "SERVICE_SLOTS_FULL" | "REGISTRY_SLOT_LOST" | "REGISTRY_UPDATE_FAILED";
     constructor(message: string, code: "REGISTRY_CONFIG_NOT_FOUND" | "SERVICE_NOT_DECLARED" | "SERVICE_SLOTS_FULL" | "REGISTRY_SLOT_LOST" | "REGISTRY_UPDATE_FAILED");
@@ -53,6 +70,12 @@ export declare function assertRegistrySlotOwner(input: {
     serviceValue: string;
     serviceId: string;
 }): Promise<void>;
+/**
+ * Force-release ACTIVE registry slots for the given logical service keys (`ACTIVE → EMPTY`).
+ * Ops/dev recovery when a process crashed without {@link unregisterService}.
+ * Does not delete Service rows or mutate `details.runtime`.
+ */
+export declare function releaseSystemRegistrySlots(input: ReleaseSystemRegistrySlotsInput): Promise<ReleaseSystemRegistrySlotsOutcome>;
 /**
  * Claim one EMPTY slot for a running Service instance (`EMPTY → ACTIVE` only).
  *

package/dist/service/registry.service.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"registry.service.d.ts","sourceRoot":"","sources":["../../src/service/registry.service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,wBAAwB,CAAC;AAGnD,OAAO,EAAE,KAAK,MAAM,EAAkD,MAAM,oBAAoB,CAAC;AAEjG,OAAO,EACH,KAAK,OAAO,EAGZ,KAAK,WAAW,EAEnB,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EAAE,0BAA0B,EAAE,MAAM,oBAAoB,CAAC;AAUhE,MAAM,WAAW,4BAA4B;IACzC,IAAI,EAAE,WAAW,CAAC;IAClB,mEAAmE;IACnE,OAAO,EAAE,OAAO,GAAG,IAAI,CAAC;CAC3B;AAED,MAAM,WAAW,wBAAwB;IACrC,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,4BAA4B,EAAE,CAAC;CACzC;AAED,MAAM,WAAW,oBAAoB;IACjC,2DAA2D;IAC3D,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,qBAAa,oBAAqB,SAAQ,KAAK;IAGvC,QAAQ,CAAC,IAAI,EACP,2BAA2B,GAC3B,sBAAsB,GACtB,oBAAoB,GACpB,oBAAoB,GACpB,wBAAwB;gBAN9B,OAAO,EAAE,MAAM,EACN,IAAI,EACP,2BAA2B,GAC3B,sBAAsB,GACtB,oBAAoB,GACpB,oBAAoB,GACpB,wBAAwB;CAKrC;AAcD,iFAAiF;AACjF,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,WAAW,GAAG,IAAI,CA2BnE;AAED,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,WAAW,EAAE,CAS/D;AAqCD;;;GAGG;AACH,wBAAsB,uBAAuB,IAAI,OAAO,CAAC,wBAAwB,CAAC,CAejF;AA2BD;;;GAGG;AACH,wBAAsB,2BAA2B,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAkBrF;AAED;;;;GAIG;AACH,wBAAsB,uBAAuB,CAAC,KAAK,EAAE;IAAE,YAAY,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAsB/G;AA+CD;;;;;;;;;GASG;AACH,wBAAsB,eAAe,CAAC,KAAK,EAAE,oBAAoB,GAAG,OAAO,CAAC,IAAI,CAAC,CAqFhF;AAED,yEAAyE;AACzE,wBAAsB,8BAA8B,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAQjG;AAUD,MAAM,WAAW,wBAAwB;IACrC,YAAY,EAAE,MAAM,CAAC;IACrB,uFAAuF;IACvF,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,SAAS,IAAI,EAAE,CAAC;IACvB,aAAa,EAAE,MAAM,CAAC;CACzB;AAED,iFAAiF;AACjF,wBAAsB,mBAAmB,CAAC,KAAK,EAAE,wBAAwB,GAAG,OAAO,CAAC,IAAI,CAAC,CAkBxF;AAED;;GAEG;AACH,wBAAsB,wBAAwB,CAAC,KAAK,EAAE,oBAAoB,GAAG,OAAO,CAAC,IAAI,CAAC,CAEzF;AAED;;;;;;GAMG;AACH,wBAAsB,iBAAiB,CAAC,KAAK,EAAE,oBAAoB,GAAG,OAAO,CAAC,IAAI,CAAC,CA6ElF;AAED;;GAEG;AACH,wBAAsB,2BAA2B,CAAC,KAAK,EAAE,oBAAoB,GAAG,OAAO,CAAC,IAAI,CAAC,CAsB5F"}
+{"version":3,"file":"registry.service.d.ts","sourceRoot":"","sources":["../../src/service/registry.service.ts"],"names":[],"mappings":"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"}

package/package.json

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

package/src/browser.ts

@@ -118,6 +118,9 @@ export type {
     RegisterServiceInput,
     RegistrySlotGuardResult,
     RegistrySlotRuntimeState,
+    ReleasedRegistrySlot,
+    ReleaseSystemRegistrySlotsInput,
+    ReleaseSystemRegistrySlotsOutcome,
     ResetSystemRegistryConfigPayload,
     Service,
     ServiceBootstrapResult,
@@ -166,6 +169,7 @@ export {
     registerService,
     registerServiceAtStartup,
     registrySlotRuntimePatchFromGuardResult,
+    releaseSystemRegistrySlots,
     resetSystemRegistryConfig,
     resetSystemRegistryConfigSchema,
     resolveActiveRegistryServiceId,

package/src/node/fs/json-state-store.ts

@@ -76,8 +76,11 @@ export function createJsonFileStateStore<T extends object, NK extends keyof T =
                 const raw = await readFile(filePath, "utf8");
                 const parsed = JSON.parse(raw) as Partial<T>;
                 return mergeWithNested(defaultState, parsed, {}, nestedKeys);
-            } catch {
-                return { ...defaultState };
+            } catch (error) {
+                if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+                    return mergeWithNested(defaultState, {}, {}, nestedKeys);
+                }
+                throw error;
             }
         },
 

package/src/node/fs/runtime-state-path.ts

@@ -0,0 +1,35 @@
+import { dirname, join } from "node:path";
+
+const RUNTIME_STATE_SHARD_DIR = "runtime-state";
+
+export interface ResolvedRuntimeStatePaths {
+    /** Directory holding one JSON file per top-level slice. */
+    stateDir: string;
+    /** Legacy monolithic `state.json` — migrated on read/reset when present. */
+    legacyFilePath: string | null;
+}
+
+/**
+ * Resolve sharded runtime state layout from {@link CreateServiceRuntimeStateStoreOptions.filePath}.
+ *
+ * | `filePath`              | Shard dir                         | Legacy        |
+ * |-------------------------|-----------------------------------|---------------|
+ * | `.../state.json`        | `.../runtime-state/`              | `state.json`  |
+ * | `.../runtime-state/`    | same directory                    | none          |
+ */
+export function resolveRuntimeStatePaths(filePath: string): ResolvedRuntimeStatePaths {
+    if (filePath.endsWith(".json")) {
+        return {
+            stateDir: join(dirname(filePath), RUNTIME_STATE_SHARD_DIR),
+            legacyFilePath: filePath,
+        };
+    }
+    return {
+        stateDir: filePath,
+        legacyFilePath: null,
+    };
+}
+
+export function runtimeStateShardPath(stateDir: string, sliceKey: string): string {
+    return join(stateDir, `${sliceKey}.json`);
+}

package/src/node/fs/sharded-json-state-store.ts

@@ -0,0 +1,157 @@
+import { mkdir, readFile, stat, unlink } from "node:fs/promises";
+import { createJsonFileStateStore, type JsonStatePatch } from "./json-state-store";
+import { resolveRuntimeStatePaths, runtimeStateShardPath } from "./runtime-state-path";
+
+export interface CreateShardedJsonFileStateStoreOptions<T extends object, NK extends keyof T> {
+    /** Monolithic legacy path or shard directory root (see {@link resolveRuntimeStatePaths}). */
+    filePath: string;
+    defaultState: T;
+    /** Top-level keys persisted as separate shard files. */
+    nestedKeys: NK[];
+    updatedAtKey?: keyof T;
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+    return value != null && typeof value === "object" && !Array.isArray(value);
+}
+
+function mergeSlice<T extends object>(defaults: T, key: keyof T, patchValue: unknown): T[keyof T] {
+    const base = defaults[key];
+    if (isPlainObject(base) && isPlainObject(patchValue)) {
+        return { ...base, ...patchValue } as T[keyof T];
+    }
+    return patchValue as T[keyof T];
+}
+
+/**
+ * JSON runtime state with **one file per top-level slice** (log-persist registry pattern).
+ * Eliminates cross-slice lost updates when guard/scheduler/worker write concurrently.
+ */
+export function createShardedJsonFileStateStore<T extends object, NK extends keyof T>(
+    options: CreateShardedJsonFileStateStoreOptions<T, NK>,
+): {
+    read(): Promise<T>;
+    write(patch: JsonStatePatch<T, NK>): Promise<T>;
+    reset(): Promise<T>;
+} {
+    const { defaultState, nestedKeys, updatedAtKey } = options;
+    const { stateDir, legacyFilePath } = resolveRuntimeStatePaths(options.filePath);
+
+    type ShardStore = ReturnType<typeof createJsonFileStateStore<object>>;
+    const shardStores = new Map<string, ShardStore>();
+
+    function shardStore(sliceKey: NK): ShardStore {
+        const key = String(sliceKey);
+        let store = shardStores.get(key);
+        if (store == null) {
+            store = createJsonFileStateStore({
+                filePath: runtimeStateShardPath(stateDir, key),
+                defaultState: defaultState[sliceKey] as object,
+            });
+            shardStores.set(key, store);
+        }
+        return store;
+    }
+
+    async function readUpdatedAtFromShardMtimes(): Promise<string> {
+        let maxMtimeMs = 0;
+        for (const sliceKey of nestedKeys) {
+            try {
+                const shardStat = await stat(runtimeStateShardPath(stateDir, String(sliceKey)));
+                maxMtimeMs = Math.max(maxMtimeMs, shardStat.mtimeMs);
+            } catch (error) {
+                if ((error as NodeJS.ErrnoException).code !== "ENOENT") {
+                    throw error;
+                }
+            }
+        }
+        if (maxMtimeMs <= 0) {
+            return defaultState[updatedAtKey as keyof T] as string;
+        }
+        return new Date(maxMtimeMs).toISOString();
+    }
+
+    async function migrateLegacyMonolithicIfPresent(): Promise<void> {
+        if (legacyFilePath == null) {
+            return;
+        }
+
+        let raw: string;
+        try {
+            raw = await readFile(legacyFilePath, "utf8");
+        } catch (error) {
+            if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+                return;
+            }
+            throw error;
+        }
+
+        let parsed: Partial<T>;
+        try {
+            parsed = JSON.parse(raw) as Partial<T>;
+        } catch {
+            await unlink(legacyFilePath).catch(() => undefined);
+            return;
+        }
+
+        await mkdir(stateDir, { recursive: true });
+        for (const sliceKey of nestedKeys) {
+            const slice = parsed[sliceKey];
+            if (slice != null) {
+                await shardStore(sliceKey).write(slice as object);
+            }
+        }
+
+        await unlink(legacyFilePath).catch(() => undefined);
+    }
+
+    return {
+        async read(): Promise<T> {
+            await mkdir(stateDir, { recursive: true });
+            await migrateLegacyMonolithicIfPresent();
+
+            const merged = { ...defaultState } as T;
+            for (const sliceKey of nestedKeys) {
+                merged[sliceKey] = (await shardStore(sliceKey).read()) as T[NK];
+            }
+            if (updatedAtKey != null) {
+                merged[updatedAtKey] = (await readUpdatedAtFromShardMtimes()) as T[keyof T];
+            }
+            return merged;
+        },
+
+        async write(patch: JsonStatePatch<T, NK>): Promise<T> {
+            await mkdir(stateDir, { recursive: true });
+            await migrateLegacyMonolithicIfPresent();
+
+            for (const sliceKey of nestedKeys) {
+                const patchSlice = patch[sliceKey];
+                if (patchSlice == null) {
+                    continue;
+                }
+                const current = await shardStore(sliceKey).read();
+                const nextSlice = mergeSlice(defaultState, sliceKey, {
+                    ...(current as object),
+                    ...(patchSlice as object),
+                });
+                await shardStore(sliceKey).write(nextSlice as object);
+            }
+
+            return this.read();
+        },
+
+        async reset(): Promise<T> {
+            await mkdir(stateDir, { recursive: true });
+
+            for (const sliceKey of nestedKeys) {
+                await shardStore(sliceKey).reset();
+            }
+
+            if (legacyFilePath != null) {
+                await unlink(legacyFilePath).catch(() => undefined);
+            }
+
+            return this.read();
+        },
+    };
+}

package/src/node/runtime-state/create-service-runtime-state-store.ts

@@ -1,5 +1,6 @@
 import { EMPTY_REGISTRY_SLOT_RUNTIME_STATE } from "../../service/registry-lifecycle";
-import { createJsonFileStateStore, type JsonFileStateStore, type JsonStatePatch } from "../fs/json-state-store";
+import type { JsonStatePatch } from "../fs/json-state-store";
+import { createShardedJsonFileStateStore } from "../fs/sharded-json-state-store";
 import type {
     DefaultExtraRuntimeSlices,
     GuardRuntimeSlice,
@@ -16,6 +17,10 @@ const EPOCH_ISO = new Date(0).toISOString();
 export interface CreateServiceRuntimeStateStoreOptions<
     TExtraSlices extends Record<string, object> = DefaultExtraRuntimeSlices,
 > {
+    /**
+     * Monolithic legacy path (`…/state.json`) or shard directory (`…/runtime-state/`).
+     * Legacy files migrate automatically to `dirname/state.json → runtime-state/*.json`.
+     */
     filePath: string;
     /** Default values for service-specific top-level nested slices. */
     extraDefaults?: TExtraSlices;
@@ -78,7 +83,7 @@ function createDefaultServiceRuntimeState<TExtraSlices extends Record<string, ob
     };
 }
 
-/** JSON file-backed service runtime state (L3 blueprint) with typed core slices and extensions. */
+/** Sharded JSON runtime state (L3 blueprint) — one file per slice under `runtime-state/`. */
 export function createServiceRuntimeStateStore<TExtraSlices extends Record<string, object> = DefaultExtraRuntimeSlices>(
     options: CreateServiceRuntimeStateStoreOptions<TExtraSlices>,
 ): ServiceRuntimeStateStore<TExtraSlices> {
@@ -95,24 +100,19 @@ export function createServiceRuntimeStateStore<TExtraSlices extends Record<strin
         ...(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;
-    }
+    const store = createShardedJsonFileStateStore<State, NK>({
+        filePath: options.filePath,
+        defaultState,
+        nestedKeys,
+        updatedAtKey: "updatedAt",
+    });
 
     return {
-        readRuntimeState: () => instance().read(),
-        writeRuntimeState: (patch) => instance().write(patch),
-        resetRuntimeStateForStartup: () => instance().reset(),
+        readRuntimeState: () => store.read(),
+        writeRuntimeState: (patch) => store.write(patch),
+        resetRuntimeStateForStartup: () => store.reset(),
         finishRunnerTick: async ({ nowMs, lastFired, postedCount, extra }) => {
-            await instance().write({
+            await store.write({
                 scheduler: {
                     lastTickAt: new Date(nowMs).toISOString(),
                     lastFired,

package/src/service/index.ts

@@ -32,6 +32,9 @@ export { CategoryConfig, TARGET_SYSTEM_REGISTRY_KEY } from "./config.interface";
 export type {
     PatchServiceRuntimeInput,
     RegisterServiceInput,
+    ReleasedRegistrySlot,
+    ReleaseSystemRegistrySlotsInput,
+    ReleaseSystemRegistrySlotsOutcome,
     TargetSystemRegistrySlotView,
     TargetSystemRegistryView,
 } from "./registry.service";
@@ -44,6 +47,7 @@ export {
     patchServiceRuntime,
     registerService,
     registerServiceAtStartup,
+    releaseSystemRegistrySlots,
     resolveActiveRegistryServiceId,
     ServiceRegistryError,
     unregisterService,

package/src/service/registry.service.ts

@@ -51,6 +51,26 @@ export interface RegisterServiceInput {
     maxAttempts?: number;
 }
 
+export interface ReleaseSystemRegistrySlotsInput {
+    /** Logical service keys whose ACTIVE slots should be forced to EMPTY (e.g. `watch-service`). */
+    serviceValues: string[];
+    traceId?: string;
+    maxAttempts?: number;
+}
+
+export interface ReleasedRegistrySlot {
+    serviceValue: string;
+    serviceId: string;
+    slotIndex: number;
+}
+
+export interface ReleaseSystemRegistrySlotsOutcome {
+    config: Config;
+    released: ReleasedRegistrySlot[];
+    /** Requested `serviceValues` with no ACTIVE slot released (already EMPTY or never bound). */
+    unchangedServiceValues: string[];
+}
+
 export class ServiceRegistryError extends Error {
     constructor(
         message: string,
@@ -298,6 +318,148 @@ function releaseOwnedSlot(slots: ServiceSlot[], serviceId: string): ServiceSlot[
     return next;
 }
 
+function releaseActiveSlotsForServiceValues(
+    slots: ServiceSlot[],
+    serviceValueSet: 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 (
+            !serviceValueSet.has(slot.serviceValue) ||
+            slot.status !== ServiceSlotStatus.ACTIVE ||
+            slot.serviceId == null
+        ) {
+            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}.
+ * Does not delete Service rows or mutate `details.runtime`.
+ */
+export async function releaseSystemRegistrySlots(
+    input: ReleaseSystemRegistrySlotsInput,
+): Promise<ReleaseSystemRegistrySlotsOutcome> {
+    const serviceValues = [
+        ...new Set(input.serviceValues.map((value) => value.trim()).filter((value) => value !== "")),
+    ];
+    if (serviceValues.length === 0) {
+        throw new Error("[releaseSystemRegistrySlots] serviceValues must not be empty");
+    }
+
+    const serviceValueSet = new Set(serviceValues);
+    const maxAttempts = input.maxAttempts ?? DEFAULT_REGISTER_RETRY_ATTEMPTS;
+    const logger = createLogger({
+        module: "releaseSystemRegistrySlots",
+        traceId: input.traceId,
+        labels: { serviceValues: serviceValues.join(",") },
+    });
+
+    logger.info("开始强制释放 registry 槽位", {
+        topic: LOG_TOPIC_REGISTRY,
+        data: { serviceValues },
+    });
+
+    for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
+        try {
+            const config = await loadSystemRegistryConfig();
+            const revision = parseRegistryRevision(config.details.meta);
+            const slots = parseServiceSlots(config);
+
+            for (const serviceValue of serviceValues) {
+                if (!isServiceValueDeclared(slots, serviceValue)) {
+                    throw new ServiceRegistryError(
+                        `Service ${serviceValue} is not declared in system registry config`,
+                        "SERVICE_NOT_DECLARED",
+                    );
+                }
+            }
+
+            const { nextSlots, released } = releaseActiveSlotsForServiceValues(slots, serviceValueSet);
+            const releasedValueSet = new Set(released.map((entry) => entry.serviceValue));
+            const unchangedServiceValues = serviceValues.filter((serviceValue) => !releasedValueSet.has(serviceValue));
+
+            if (released.length === 0) {
+                logger.info("无 ACTIVE 槽位需要释放", {
+                    topic: LOG_TOPIC_REGISTRY,
+                    data: { serviceValues, attempt },
+                });
+                return { config, released, unchangedServiceValues: serviceValues };
+            }
+
+            await persistSlotClaim({
+                configId: config.id,
+                revision,
+                slots: nextSlots,
+            });
+
+            const updated = await loadSystemRegistryConfig();
+            logger.info("槽位强制释放成功", {
+                topic: LOG_TOPIC_REGISTRY,
+                data: {
+                    released,
+                    unchangedServiceValues,
+                    attempt,
+                    revision: revision + 1,
+                },
+            });
+
+            return {
+                config: updated,
+                released,
+                unchangedServiceValues,
+            };
+        } catch (error) {
+            if (error instanceof ServiceRegistryError) {
+                logger.error("槽位强制释放被拒绝", {
+                    topic: LOG_TOPIC_REGISTRY,
+                    data: { serviceValues, code: error.code, message: error.message },
+                });
+                throw error;
+            }
+
+            if (isOptimisticLockError(error) && attempt < maxAttempts) {
+                logger.warn("registry 乐观锁冲突，重试", {
+                    topic: LOG_TOPIC_REGISTRY,
+                    data: { serviceValues, attempt, maxAttempts },
+                });
+                await sleep(50 * attempt);
+                continue;
+            }
+
+            const message = error instanceof Error ? error.message : String(error);
+            logger.error("槽位强制释放失败", {
+                topic: LOG_TOPIC_REGISTRY,
+                data: { serviceValues, attempt, message },
+            });
+            throw new ServiceRegistryError(message, "REGISTRY_UPDATE_FAILED");
+        }
+    }
+
+    throw new ServiceRegistryError(
+        "[releaseSystemRegistrySlots] Optimistic lock retries exhausted",
+        "REGISTRY_UPDATE_FAILED",
+    );
+}
+
 /**
  * Claim one EMPTY slot for a running Service instance (`EMPTY → ACTIVE` only).
  *