target-supabase-sdk 0.2.12 → 0.2.14

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

@@ -1,6 +1,7 @@
-import { createLogger, type Service, ServiceRegistryError } from "../../browser";
-import { claimServiceRegistrySlot, type ServiceRegistrySession } from "../../service/registry-lifecycle";
-import type { LoggerWithScope } from "../../shared/log";
+import type { ServiceRegistrySession } from "../../service/registry-lifecycle";
+import type { Service } from "../../service/service.interface";
+import { createLogger, type LoggerWithScope } from "../../shared/log";
+import { claimRegistrySlotOrExit } from "./claim-registry-slot";
 
 export interface SingleProcessServiceContext {
     service: Service;
@@ -29,23 +30,12 @@ export async function runSingleProcessService(options: SingleProcessServiceOptio
         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;
-    }
+    const session = await claimRegistrySlotOrExit({
+        serviceValue: options.serviceValue,
+        createInstance: options.createInstance,
+        logger,
+        logTopic,
+    });
 
     try {
         await options.run({ service: session.service, session });

package/src/node.ts

@@ -25,9 +25,6 @@ export {
     envProfileFromProcess,
     initSupabaseFromStandardEnv,
     loadEnvFiles,
-    parseEnvFile,
-    parseEnvLine,
-    pinEnvProfileFromArgv,
     publicBaseUrlFromEnv,
     readEnv,
     requireEnv,
@@ -77,6 +74,7 @@ export type {
     ReadinessCheckResult,
     ReadinessReport,
     RequiredEnvCheckOptions,
+    RunReadinessGateInput,
     ServiceReadyGate,
     ServiceReadySnapshot,
     SupabaseReachableCheckOptions,
@@ -88,6 +86,7 @@ export {
     createSupabaseReachableCheck,
     pollUntil,
     runReadinessChecks,
+    runReadinessGate,
     waitForServiceReady,
 } from "./node/readiness";
 export type {
@@ -109,51 +108,63 @@ export type {
     ApplyRegistrySlotGuardInput,
     ApplyRegistrySlotGuardResult,
     RegisterServiceGuardRunnerOptions,
-    RunReadinessGateInput,
     ServiceGuardNodeOptions,
     ServiceGuardTickInput,
     ServiceGuardTickResult,
-    ServiceHost,
-    ServiceHostClosable,
-    ServiceHostContext,
-    ServiceHostOptions,
-    SingleProcessServiceContext,
-    SingleProcessServiceOptions,
-} from "./node/service-host";
+} from "./node/service-guard";
 export {
     applyRegistrySlotGuardStep,
-    createServiceHost,
-    getWorkerSpawnCooldownLastAt,
+    guardRetryAfterSec,
+    isGuardAvailable,
     markWorkerSpawned,
     registerServiceGuardRunner,
-    runReadinessGate,
     runServiceGuardTick,
-    runSingleProcessService,
     SERVICE_GUARD_RUNNER_KEY,
     ServiceGuardNode,
+} from "./node/service-guard";
+export type {
+    CreateL3ChildLauncherOptions,
+    L3ChildLauncher,
+    L3ChildLauncherRuntimeStore,
+    ServiceHost,
+    ServiceHostClosable,
+    ServiceHostContext,
+    ServiceHostOptions,
+    SingleProcessServiceContext,
+    SingleProcessServiceOptions,
 } from "./node/service-host";
+export { createL3ChildLauncher, createServiceHost, runSingleProcessService } 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 {
+    COLLECT_LOG_RUNNER_KEY,
+    registerCollectLogRunner,
+} from "./shared/log/spool/register-collect-log-runner";
+export {
+    enableLogSpoolFromEnvInChild,
+    getMainLogSpoolWriterStats,
+    isLogSpoolEnabled,
+    shutdownLogSpool,
+} from "./shared/log/spool/service-lifecycle";
+export type { LogBatchMeta, LogPersistLane } from "./shared/log/upload/interface";
 export type {
     ConfigSchema,
     LoadCachedJsConfigOptions,
@@ -170,7 +181,6 @@ export {
     resolvePathFromCwd,
     toFileImportHref,
 } from "./shared/utils/config-path.utils";
-export { getValueAtPath } from "./shared/utils/get-value-at-path";
 export type {
     BootstrapLocalTasksResult,
     BootstrapLocalTasksStatus,

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

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/{log-min-level.ts → core/log-min-level.ts}

@@ -1,4 +1,4 @@
-import { isDevEnvironment } from "../../core.utils";
+import { isDevEnvironment } from "../../../core.utils";
 import { LogLevel } from "./log-manager";
 
 /** Env key for global {@link LogManager} min level (console + log-persist when enabled). */

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,19 +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 { ResolveLogMinLevelOptions } from "./log-min-level";
-// log-min-level
+} 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 "./log-min-level";
-export type { LogBatchMeta, LogPersistLane } from "./log-persist.interface";
-export { LOG_BATCH_LOADER_KEY, LOG_PERSIST_LOADER_KEY } from "./log-persist.interface";
+} from "./core/log-min-level";
 export type {
     CreateScopeInput,
     LoggerResetScopePatch,
@@ -39,8 +33,7 @@ export type {
     LogScopeInput,
     LogScopePatch,
     PatchScopeInput,
-} from "./log-scope";
-// log-scope
+} from "./core/log-scope";
 export {
     createScope,
     formatScopeLabels,
@@ -48,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";