target-supabase-sdk 0.2.11 → 0.2.13

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`.

package/src/shared/log/README.md

@@ -0,0 +1,206 @@
+# Log module (`src/shared/log`)
+
+Structured logging, optional file-backed persistence, and Supabase `LogBatch` upload for L3 services.
+
+## Layout
+
+```text
+src/shared/log/
+  README.md
+  index.ts                 # browser-safe public API (re-exports core + upload types)
+
+  core/                    # in-process logging (browser + Node)
+    log-manager.ts         # LogManager singleton, LogEntry, levels
+    create-logger.ts       # createLogger({ module, scope, … })
+    log-scope.ts           # traceId / labels / patchScope
+    log-min-level.ts       # LOG_MIN_LEVEL env
+    log-batch.ts           # decode persisted LogBatch Lists (read side)
+
+  upload/                  # shared Supabase upload pipeline (Node)
+    env.ts                 # LOG_PERSIST_ENABLED, SERVICE, PROCESS, runtime dir
+    interface.ts           # LogBatch meta, loader keys, lane type
+    batch-id.ts            # computeLogBatchIdempotencyKey
+    flush.ts               # buildLogListDraft, postLogBatch
+    hook.ts                # LogManager → spool writer offer bridge
+    logger.ts              # internal pipeline loggers (no feedback loop)
+
+  spool/                   # file-backed persistence (Node only)
+    enable.ts              # ensureLogSpoolFromEnv, spawn env helpers
+    service-lifecycle.ts   # isLogSpoolEnabled, enableLogSpoolFromEnvInChild, shutdownLogSpool
+    writer.ts              # per-process memory buffer → .tmp files
+    collector.ts           # guard: upload .tmp, rename .json, periodic GC
+    paths.ts               # {RUNTIME_DATA_DIR}/log-spool/{serviceId}/…
+    file.ts                # batch filename parse/build
+    process-roles.ts       # main|guard|scheduler|worker + extras
+    config.ts              # writer / GC / collect interval env
+    coordinator.ts         # createLogSpoolCoordinator facade
+    register-collect-log-runner.ts
+```
+
+**Package exports**
+
+| Entry | Scope |
+|-------|--------|
+| `target-supabase-sdk` / `index.ts` | `core/` + decode types from `upload/interface` |
+| `target-supabase-sdk/node` | spool + upload symbols used by L3 services |
+
+Node-only code must not be imported from the browser bundle. Spool files use `node:fs`.
+
+---
+
+## Data flow
+
+```text
+App code
+  → createLogger / logManager
+  → offerToLogPersist (when spool enabled)
+  → LogSpoolWriter (memory buffer)
+  → {spoolRoot}/{serviceId}/{role}/*.tmp
+
+Guard collect-log runner (1 min tick)
+  → read *.tmp → postLogBatch → rename *.json
+  → GC old tmp/json (once per day; 7 d retention)
+
+log-service (downstream)
+  → decodeLogBatch / LogTrace merge by traceId
+```
+
+**One-line rule:** producers flush `LogEntry[]` to `.tmp`; only the guard uploads `LogBatch` and renames to `.json`.
+
+---
+
+## Environment
+
+| Key | Role |
+|-----|------|
+| `LOG_PERSIST_ENABLED` | Master switch (`true` → file spool) |
+| `LOG_PERSIST_SERVICE` | Logical service value in List meta (e.g. `watch-service`) |
+| `LOG_PERSIST_PROCESS` | This process role: `main` \| `guard` \| `scheduler` \| `worker` or extra |
+| `LOG_SPOOL_SERVICE_ID` | Instance id — set by main after registry claim |
+| `LOG_SPOOL_EXTRA_PROCESS_ROLES` | Comma-separated extras (e.g. `chrome-sidecar`) |
+| `RUNTIME_DATA_DIR` | Runtime root; spool lives at `{dir}/log-spool/` |
+| `LOG_SPOOL_DIR` | Optional override for spool root parent |
+
+### Writer tuning
+
+| Key | Default |
+|-----|---------|
+| `LOG_SPOOL_MAX_ENTRIES` | 2000 |
+| `LOG_SPOOL_MAX_BYTES` | 2 MB |
+| `LOG_SPOOL_FLUSH_DEBOUNCE_MS` | 3 s (after count/byte threshold) |
+| `LOG_SPOOL_MAX_AGE_MS` | 60 s (flush buffered logs even when below threshold) |
+| `LOG_PERSIST_POST_TIMEOUT_MS` | 30 s |
+
+### Collector / GC
+
+| Key | Default |
+|-----|---------|
+| `LOG_SPOOL_COLLECT_INTERVAL_MS` | 60 s |
+| `LOG_SPOOL_GC_INTERVAL_MS` | 24 h (how often guard runs tmp/json GC) |
+| `LOG_SPOOL_SYNCED_RETENTION_MS` | 7 d (delete `.json` when mtime older than this) |
+| `LOG_SPOOL_TMP_RETENTION_MS` | 7 d (delete stale `.tmp` by filename timestamp) |
+
+---
+
+## On-disk layout
+
+```text
+{RUNTIME_DATA_DIR}/log-spool/{serviceId}/
+  main/main.{YYYYMMDDHHmmss}.{hash8}.tmp   → .json after upload
+  guard/…
+  scheduler/…
+  worker/…
+  {extra}/…
+```
+
+Upload state: `.tmp` = pending, `.json` = uploaded (no central index file).
+
+Batch file JSON: `{ entries: LogEntry[], meta?: { serviceId, processRole, serviceValue } }`.
+
+Uploaded List meta:
+
+- `meta.process` = `{serviceId}:{processRole}` (e.g. `abc123:worker`)
+- `meta.service` = logical value (`watch-service`)
+- `meta.lane` = `"slow"` (legacy transport field; required for decode today)
+
+---
+
+## L3 integration
+
+### Preload (`runServicePreload`)
+
+Sync phases set `LOG_PERSIST_SERVICE`, `RUNTIME_DATA_DIR`, validate env, merge `logSpoolExtraProcessRoles`.  
+**Do not** call `ensureLogSpoolFromEnv` in preload — it is async and needs `LOG_SPOOL_SERVICE_ID`.
+
+### Main (`createServiceHost`)
+
+After registry claim, main sets `LOG_SPOOL_SERVICE_ID` and calls `ensureLogSpoolFromEnv({ processRole: "main", … })`.
+
+### Child processes
+
+Guard / scheduler / worker `main()`:
+
+```typescript
+import { enableLogSpoolFromEnvInChild } from "target-supabase-sdk/node";
+
+await enableLogSpoolFromEnvInChild();
+```
+
+### Shutdown
+
+```typescript
+import { shutdownLogSpool } from "target-supabase-sdk/node";
+
+await shutdownLogSpool();
+```
+
+Flushes remaining memory buffer to `.tmp`.
+
+### Extra process roles (e.g. download-service `chrome-sidecar`)
+
+```javascript
+// scripts/preload.mjs
+runServicePreload({
+  // …
+  logSpoolExtraProcessRoles: ["chrome-sidecar"],
+});
+```
+
+---
+
+## Public Node API (curated)
+
+| Symbol | Role |
+|--------|------|
+| `ensureLogSpoolFromEnv` | Enable writer in current process |
+| `enableLogSpoolFromEnvInChild` | Child entry: no-op when disabled, else `ensureLogSpoolFromEnv` |
+| `isLogSpoolEnabled` | Read master switch (`LOG_PERSIST_ENABLED`) |
+| `getMainLogSpoolWriterStats` | Writer stats or `null` when disabled (main observability) |
+| `shutdownLogSpool` | No-op when disabled, else flush + disable |
+| `shutdownLogSpoolFromEnv` | Flush buffer + disable (unconditional) |
+| `getLogSpoolStats` | Writer buffer stats |
+| `buildLogSpoolSpawnEnv` | Manual child env (usually unnecessary) |
+| `validateLogSpoolPreloadEnv` | Preload validation |
+| `logSpoolEnabledFromEnv` | Read master switch |
+| `createLogSpoolCoordinator` | Service-bound lifecycle facade |
+| `registerCollectLogRunner` | Guard TriggerNode runner (via `ServiceGuardNode`) |
+| `runCollectLogTick` | Manual / tests |
+| `resolveLogSpoolRoot` | Spool directory path |
+
+Internal helpers (`resolveLogSpoolSpawnEnvForLabel`, `resolveAllLogSpoolProcessRoles`, etc.) are not exported from `node` — use preload `logSpoolExtraProcessRoles` or env instead.
+
+---
+
+## Concurrency (Windows)
+
+- One writer per `.tmp` file — producers only create new files.
+- Guard renames after successful upload; does not RMW batch contents.
+- GC scans directories; no shared JSON index file.
+
+---
+
+## Related skills
+
+- [log-spool](../../../.cursor/skills/log-spool/SKILL.md) — agent quick reference
+- [service-preload](../../../.cursor/skills/service-preload/SKILL.md) — preload protocol
+- [l3-service-host](../../../.cursor/skills/l3-service-host/SKILL.md) — `createServiceHost` integration

package/src/shared/log/{log-batch.ts → core/log-batch.ts}

@@ -1,12 +1,12 @@
 /**
  * Read side of the log-persist pipeline: decode persisted `LogBatch` Lists into
  * structured batches and flat entries. Pure and defensive — malformed rows are
- * skipped rather than thrown. Mirrors the write side in `log-persist-flush.ts`.
+ * skipped rather than thrown. Mirrors the write side in `upload/flush.ts`.
  */
 
-import type { List } from "../../list/list.interface";
-import type { LogEntry } from "./log-manager";
-import { LOG_PERSIST_LOADER_KEY, type LogBatchMeta, type LogPersistLane } from "./log-persist.interface";
+import type { List } from "../../../list/list.interface";
+import type { LogEntry } from "../core/log-manager";
+import { LOG_PERSIST_LOADER_KEY, type LogBatchMeta, type LogPersistLane } from "../upload/interface";
 
 const LANES: ReadonlySet<string> = new Set<LogPersistLane>(["fast", "medium", "slow"]);
 

package/src/shared/log/{log-manager.ts → core/log-manager.ts}

@@ -1,6 +1,6 @@
-import { isDevEnvironment } from "../../core.utils";
-import { generateUniqueId } from "../utils/id.utils";
-import { offerToLogPersist } from "./log-persist-hook";
+import { isDevEnvironment } from "../../../core.utils";
+import { generateUniqueId } from "../../utils/id.utils";
+import { offerToLogPersist } from "../upload/hook";
 import { formatScopeLabels, type LoggerResetScopePatch, type LogScope, patchScope, resolveLogData } from "./log-scope";
 
 /**

package/src/shared/log/core/log-min-level.ts

@@ -0,0 +1,46 @@
+import { isDevEnvironment } from "../../../core.utils";
+import { LogLevel } from "./log-manager";
+
+/** Env key for global {@link LogManager} min level (console + log-persist when enabled). */
+export const LOG_MIN_LEVEL_ENV_KEY = "LOG_MIN_LEVEL";
+
+const LOG_LEVEL_BY_NAME: Record<string, LogLevel> = {
+    DEBUG: LogLevel.DEBUG,
+    INFO: LogLevel.INFO,
+    SUCCESS: LogLevel.SUCCESS,
+    WARN: LogLevel.WARN,
+    ERROR: LogLevel.ERROR,
+    CRITICAL: LogLevel.CRITICAL,
+};
+
+export interface ResolveLogMinLevelOptions {
+    env?: NodeJS.ProcessEnv;
+    /** When {@link LOG_MIN_LEVEL_ENV_KEY} unset; defaults to LogManager convention (DEBUG in dev, INFO in prod). */
+    defaultLevel?: LogLevel;
+}
+
+function sdkDefaultLogMinLevel(): LogLevel {
+    return isDevEnvironment() ? LogLevel.DEBUG : LogLevel.INFO;
+}
+
+/**
+ * Parse `LOG_MIN_LEVEL` after `.env` load. Invalid values throw (same style as `envInt`).
+ */
+export function resolveLogMinLevel(options?: ResolveLogMinLevelOptions): LogLevel {
+    const env = options?.env ?? process.env;
+    const raw = env[LOG_MIN_LEVEL_ENV_KEY]?.trim().toUpperCase();
+    if (raw == null || raw === "") {
+        return options?.defaultLevel ?? sdkDefaultLogMinLevel();
+    }
+
+    const level = LOG_LEVEL_BY_NAME[raw];
+    if (level == null) {
+        throw new Error(`Invalid ${LOG_MIN_LEVEL_ENV_KEY}: ${raw}`);
+    }
+    return level;
+}
+
+/** Alias for {@link resolveLogMinLevel}. */
+export function logMinLevelFromEnv(options?: ResolveLogMinLevelOptions): LogLevel {
+    return resolveLogMinLevel(options);
+}

package/src/shared/log/{log-scope.ts → core/log-scope.ts}

@@ -1,4 +1,4 @@
-import { generateUniqueId } from "../utils/id.utils";
+import { generateUniqueId } from "../../utils/id.utils";
 
 /** Logger-bound scope: module + trace chain + optional labels. */
 export interface LogScope {

package/src/shared/log/index.ts

@@ -1,16 +1,14 @@
 /**
- * Log domain public API — curated re-exports only.
+ * Log domain public API — curated re-exports only (browser-safe).
  */
 
 export type {
     CreateLoggerFromModuleInput,
     CreateLoggerFromScopeInput,
     CreateLoggerInput,
-} from "./create-logger";
-// create-logger
-export { createLogger } from "./create-logger";
-export type { DecodedLogBatch, FlatLogEntry } from "./log-batch";
-// log-batch (persisted LogBatch decode — read side of log-persist)
+} from "./core/create-logger";
+export { createLogger } from "./core/create-logger";
+export type { DecodedLogBatch, FlatLogEntry } from "./core/log-batch";
 export {
     decodeLogBatch,
     decodeLogBatchList,
@@ -19,12 +17,15 @@ export {
     isLogBatchList,
     isLogEntry,
     parseLogBatchMeta,
-} from "./log-batch";
-export type { LogEntry, LoggerWithScope, LogOptions, LogRestParams, WithScopeOptions } from "./log-manager";
-// log-manager
-export { LogLevel, LogManager, logManager } from "./log-manager";
-export type { LogBatchMeta, LogPersistLane } from "./log-persist.interface";
-export { LOG_BATCH_LOADER_KEY, LOG_PERSIST_LOADER_KEY } from "./log-persist.interface";
+} from "./core/log-batch";
+export type { LogEntry, LoggerWithScope, LogOptions, LogRestParams, WithScopeOptions } from "./core/log-manager";
+export { LogLevel, LogManager, logManager } from "./core/log-manager";
+export type { ResolveLogMinLevelOptions } from "./core/log-min-level";
+export {
+    LOG_MIN_LEVEL_ENV_KEY,
+    logMinLevelFromEnv,
+    resolveLogMinLevel,
+} from "./core/log-min-level";
 export type {
     CreateScopeInput,
     LoggerResetScopePatch,
@@ -32,8 +33,7 @@ export type {
     LogScopeInput,
     LogScopePatch,
     PatchScopeInput,
-} from "./log-scope";
-// log-scope
+} from "./core/log-scope";
 export {
     createScope,
     formatScopeLabels,
@@ -41,4 +41,6 @@ export {
     patchScope,
     resolveLogData,
     withModule,
-} from "./log-scope";
+} from "./core/log-scope";
+export type { LogBatchMeta, LogPersistLane } from "./upload/interface";
+export { LOG_BATCH_LOADER_KEY, LOG_PERSIST_LOADER_KEY } from "./upload/interface";