target-supabase-sdk 0.1.9 → 0.2.1

package/src/shared/log/enable-log-persist.ts

@@ -0,0 +1,225 @@
+import { resolve } from "node:path";
+import { envBool } from "../../node/env/env-parsers";
+import { readEnv, requireEnv } from "../../node/env/require-env";
+import { pollUntil } from "../../node/readiness";
+import { createLogger } from "./create-logger";
+import { LogPersist } from "./log-persist";
+import {
+    logPersistConfigFromEnv,
+    logPersistEnabledFromEnv,
+    logPersistProcessFromEnv,
+    logPersistRegistryDirFromEnv,
+    logPersistServiceFromEnv,
+    resolveLogPersistConfig,
+} from "./log-persist.config";
+import type {
+    EnableLogPersistOptions,
+    EnsureLogPersistFromEnvOptions,
+    LogPersistReadySnapshot,
+    LogPersistStats,
+    WaitForLogPersistReadyOptions,
+} from "./log-persist.interface";
+import { registerLogPersistOffer } from "./log-persist-hook";
+import { LOG_PERSIST_TOPIC, persistLogger } from "./log-persist-logger";
+import { defaultLogPersistRegistryPath, readLogPersistRegistry } from "./log-persist-registry";
+
+export { logPersistEnabledFromEnv };
+
+function resolveRegistryFilePath(explicit?: string): string {
+    if (explicit != null && explicit.trim() !== "") {
+        return resolve(explicit);
+    }
+    const dir = logPersistRegistryDirFromEnv();
+    if (dir == null) {
+        throw new Error(
+            "[LogPersist] registry path required: set registryFilePath option or LOG_PERSIST_REGISTRY_DIR / RUNTIME_DATA_DIR",
+        );
+    }
+    return defaultLogPersistRegistryPath(resolve(dir));
+}
+
+export async function enableLogPersist(options: EnableLogPersistOptions): Promise<void> {
+    const registryFilePath = options.registryFilePath != null ? resolve(options.registryFilePath) : undefined;
+    const resolvedRegistry = registryFilePath ?? resolveRegistryFilePath();
+
+    const envConfig = logPersistConfigFromEnv();
+    await LogPersist.getInstance().enable({
+        ...options,
+        registryFilePath: resolvedRegistry,
+        config: resolveLogPersistConfig({
+            fast: { ...envConfig.fast, ...options.config?.fast },
+            medium: { ...envConfig.medium, ...options.config?.medium },
+            slow: { ...envConfig.slow, ...options.config?.slow },
+            postTimeoutMs: options.config?.postTimeoutMs ?? envConfig.postTimeoutMs,
+            shutdownDrainTimeoutMs: options.config?.shutdownDrainTimeoutMs ?? envConfig.shutdownDrainTimeoutMs,
+        }),
+    });
+}
+
+export async function disableLogPersist(): Promise<void> {
+    await LogPersist.getInstance().disable();
+}
+
+export function getLogPersistStats(): LogPersistStats {
+    return LogPersist.getInstance().getStats();
+}
+
+/**
+ * Enable log persistence when LOG_PERSIST_ENABLED=true.
+ * `process` / `service` can be passed explicitly or via LOG_PERSIST_PROCESS / LOG_PERSIST_SERVICE.
+ */
+export async function ensureLogPersistFromEnv(options: EnsureLogPersistFromEnvOptions = {}): Promise<boolean> {
+    if (!logPersistEnabledFromEnv()) {
+        registerLogPersistOffer(null);
+        return false;
+    }
+
+    const service = options.service ?? logPersistServiceFromEnv();
+    const processName = options.process ?? logPersistProcessFromEnv();
+    if (service == null || service === "") {
+        throw new Error("[LogPersist] LOG_PERSIST_SERVICE is required when LOG_PERSIST_ENABLED=true");
+    }
+    if (processName == null || processName === "") {
+        throw new Error(
+            "[LogPersist] LOG_PERSIST_PROCESS is required when LOG_PERSIST_ENABLED=true (or pass process option)",
+        );
+    }
+
+    const registryFilePath =
+        options.registryFilePath != null ? resolve(options.registryFilePath) : resolveRegistryFilePath();
+
+    await enableLogPersist({
+        service,
+        process: processName,
+        registryFilePath,
+        config: options.config,
+    });
+
+    const lifecycleLogger = createLogger({ module: "log-persist" });
+    lifecycleLogger.info("log persist enabled from env", {
+        topic: LOG_PERSIST_TOPIC,
+        data: { service, process: processName, registryFilePath },
+    });
+
+    return true;
+}
+
+/**
+ * Preload guard: when persistence is enabled, required env must be present before app code runs.
+ */
+export function validateLogPersistPreloadEnv(env: NodeJS.ProcessEnv = process.env): void {
+    if (!envBool("LOG_PERSIST_ENABLED", false, env)) {
+        return;
+    }
+
+    const missing: string[] = [];
+    if (readEnv("LOG_PERSIST_SERVICE", env) == null) {
+        missing.push("LOG_PERSIST_SERVICE");
+    }
+    const registryDir = logPersistRegistryDirFromEnv(env);
+    if (registryDir == null) {
+        missing.push("LOG_PERSIST_REGISTRY_DIR or RUNTIME_DATA_DIR");
+    }
+
+    if (missing.length > 0) {
+        throw new Error(`[LogPersist] preload env incomplete: ${missing.join(", ")}`);
+    }
+}
+
+function evaluateLogPersistReady(
+    state: Awaited<ReturnType<typeof readLogPersistRegistry>>,
+    expectedProcesses: string[],
+    staleMs: number,
+    now: number,
+): LogPersistReadySnapshot {
+    const missing: string[] = [];
+    const stale: string[] = [];
+    const registered: string[] = [];
+
+    for (const processName of expectedProcesses) {
+        const record = state.processes[processName];
+        if (record == null) {
+            missing.push(processName);
+            continue;
+        }
+
+        const heartbeatAt = Date.parse(record.lastHeartbeatAt);
+        if (!Number.isFinite(heartbeatAt) || now - heartbeatAt > staleMs) {
+            stale.push(processName);
+            continue;
+        }
+
+        registered.push(processName);
+    }
+
+    return {
+        ok: missing.length === 0 && stale.length === 0,
+        missing,
+        stale,
+        registered,
+    };
+}
+
+/**
+ * Wait until every expected process has registered in the shared registry with a fresh heartbeat.
+ * Call from the service main process after spawning children.
+ */
+export async function waitForLogPersistReady(options: WaitForLogPersistReadyOptions): Promise<LogPersistReadySnapshot> {
+    const timeoutMs = options.timeoutMs ?? 60_000;
+    const pollIntervalMs = options.pollIntervalMs ?? 500;
+    const staleMs = options.staleMs ?? 90_000;
+
+    let last: LogPersistReadySnapshot = {
+        ok: false,
+        missing: [...options.expectedProcesses],
+        stale: [],
+        registered: [],
+    };
+
+    try {
+        await pollUntil({
+            intervalMs: pollIntervalMs,
+            timeoutMs,
+            until: async () => {
+                const state = await readLogPersistRegistry(options.registryFilePath);
+                if (state.service !== options.service) {
+                    last = {
+                        ok: false,
+                        missing: options.expectedProcesses,
+                        stale: [],
+                        registered: [],
+                    };
+                    return false;
+                }
+                last = evaluateLogPersistReady(state, options.expectedProcesses, staleMs, Date.now());
+                return last.ok;
+            },
+        });
+    } catch {
+        persistLogger.warn("waitForLogPersistReady timed out", {
+            timeoutMs,
+            expectedProcesses: options.expectedProcesses,
+            ...last,
+        });
+    }
+
+    return last;
+}
+
+export async function snapshotLogPersistReady(options: {
+    registryFilePath: string;
+    service: string;
+    expectedProcesses: string[];
+    staleMs?: number;
+}): Promise<LogPersistReadySnapshot> {
+    const state = await readLogPersistRegistry(options.registryFilePath);
+    return evaluateLogPersistReady(state, options.expectedProcesses, options.staleMs ?? 90_000, Date.now());
+}
+
+export function resolveLogPersistRegistryPath(registryDir?: string): string {
+    const dir = registryDir ?? logPersistRegistryDirFromEnv();
+    if (dir == null) {
+        requireEnv("LOG_PERSIST_REGISTRY_DIR");
+    }
+    return defaultLogPersistRegistryPath(resolve(dir ?? ""));
+}

package/src/shared/log/index.ts

@@ -0,0 +1,31 @@
+/**
+ * Log domain public API — curated re-exports only.
+ */
+
+export type {
+    CreateLoggerFromModuleInput,
+    CreateLoggerFromScopeInput,
+    CreateLoggerInput,
+} from "./create-logger";
+// create-logger
+export { createLogger } from "./create-logger";
+export type { LogEntry, LoggerWithScope, LogOptions, LogRestParams, WithScopeOptions } from "./log-manager";
+// log-manager
+export { LogLevel, LogManager, logManager } from "./log-manager";
+export type {
+    CreateScopeInput,
+    LoggerResetScopePatch,
+    LogScope,
+    LogScopeInput,
+    LogScopePatch,
+    PatchScopeInput,
+} from "./log-scope";
+// log-scope
+export {
+    createScope,
+    formatScopeLabels,
+    normalizeScope,
+    patchScope,
+    resolveLogData,
+    withModule,
+} from "./log-scope";

package/src/shared/log/log-manager.ts

@@ -1,5 +1,7 @@
 import { isDevEnvironment } from "../../core.utils";
 import { generateUniqueId } from "../utils/id.utils";
+import { offerToLogPersist } from "./log-persist-hook";
+import { formatScopeLabels, type LoggerResetScopePatch, type LogScope, patchScope, resolveLogData } from "./log-scope";
 
 /**
  * Log severity and semantics (low → high). `minLevel` filters by {@link LOG_LEVEL_RANK}.
@@ -31,86 +33,70 @@ const LOG_LEVEL_RANK: Record<LogLevel, number> = {
     [LogLevel.CRITICAL]: 5,
 };
 
-interface LogEntry {
+interface LogEntry extends LogScope {
     timestamp: number;
     level: LogLevel;
-    /** Tell people what happened, but more structured */
     message: string;
-    /** Category of a kind of log */
-    topic: string | null;
-    /** Where the log comes from */
-    module: string;
-    /** Specific process — correlates one logical chain (loop, request). */
-    traceId: string;
-    /** Worker node id when the log is node-scoped; omit for scheduler / admin / API-only paths. */
-    nodeId?: string;
+    topic: string;
     extra?: string;
-    context?: unknown;
+    /** Per-line structured business payload. */
+    data?: unknown;
 }
 
-interface LogContext {
-    module: LogEntry["module"];
-    traceId: LogEntry["traceId"];
-    nodeId?: LogEntry["nodeId"];
-}
+type LogRestParams = {
+    topic: string;
+    extra?: LogEntry["extra"];
+    data?: unknown;
+};
 
-type LogRestParams = Omit<LogParams, "message">;
+type LogParams = { message: LogEntry["message"] } & LogRestParams;
 
-interface LogEntryPayload {
+interface LogEntryPayload extends LogScope {
     message: LogEntry["message"];
-    topic?: LogEntry["topic"];
+    topic: LogEntry["topic"];
     extra?: LogEntry["extra"];
-    context?: LogEntry["context"];
+    data?: LogEntry["data"];
     level: LogEntry["level"];
-    module: LogEntry["module"];
-    traceId: LogEntry["traceId"];
-    nodeId?: LogEntry["nodeId"];
 }
 
-type LogParams = Pick<LogEntryPayload, "message" | "topic" | "extra" | "context">;
-
 interface LogOptions {
-    defaultTopic: LogEntry["topic"];
     formatTimestamp: boolean;
     formatEmoji: boolean;
     formatPrefix: string;
-    maxHistoryLength: number;
     /** Logs below this level are skipped. Defaults to DEBUG in dev, INFO in production. */
     minLevel?: LogLevel;
     onLog?: (entry: LogEntry) => void;
 }
 
+/** Per-scoped-logger options for {@link LogManager.withScope}. */
+interface WithScopeOptions {
+    /** Overrides global {@link LogOptions.minLevel} for this logger instance. */
+    minLevel?: LogLevel;
+}
+
 const DEFAULT_OPTIONS: LogOptions = {
-    defaultTopic: null,
     formatTimestamp: true,
     formatEmoji: true,
     formatPrefix: "",
-    maxHistoryLength: 4096,
     minLevel: isDevEnvironment() ? LogLevel.DEBUG : LogLevel.INFO,
 };
 
-interface LoggerWithContext {
-    /** Rank 0 — diagnostic detail; dev/troubleshooting only. */
-    debug: (message: LogParams["message"], restParams?: LogRestParams) => void;
-    /** Rank 1 — normal operational flow. */
-    info: (message: LogParams["message"], restParams?: LogRestParams) => void;
-    /** Rank 2 — positive milestone (semantic INFO, not higher severity). */
-    success: (message: LogParams["message"], restParams?: LogRestParams) => void;
-    /** Rank 3 — recoverable anomaly; system continues. */
-    warn: (message: LogParams["message"], restParams?: LogRestParams) => void;
-    /** Rank 4 — a concrete operation failed; needs investigation. */
-    error: (message: LogParams["message"], restParams?: LogRestParams) => void;
-    /** Rank 5 — invariant / design / integrity breach; escalate immediately. */
-    critical: (message: LogParams["message"], restParams?: LogRestParams) => void;
-    /** Merge partial fields into this logger's bound context (e.g. nodeId after register). */
-    resetContext: (fields: Partial<LogContext>) => void;
+interface LoggerWithScope {
+    debug: (message: LogParams["message"], restParams: LogRestParams) => void;
+    info: (message: LogParams["message"], restParams: LogRestParams) => void;
+    success: (message: LogParams["message"], restParams: LogRestParams) => void;
+    warn: (message: LogParams["message"], restParams: LogRestParams) => void;
+    error: (message: LogParams["message"], restParams: LogRestParams) => void;
+    critical: (message: LogParams["message"], restParams: LogRestParams) => void;
+    /** Merge labels / module into this logger's bound scope (trace fields are not mutable). */
+    resetScope: (patch: LoggerResetScopePatch) => void;
 }
 
 function mergeLogOptions(options?: Partial<LogOptions>): LogOptions {
     return { ...DEFAULT_OPTIONS, ...options };
 }
 
-function formatContextValue(value: unknown): string {
+function formatDataValue(value: unknown): string {
     if (value === undefined) {
         return "";
     }
@@ -124,23 +110,25 @@ function formatContextValue(value: unknown): string {
     }
 }
 
-function validateLogContext(logContext: LogContext): void {
+function validateLogScope(logScope: LogScope): void {
     const missing: string[] = [];
-    if (!logContext.module?.trim()) {
+    if (!logScope.module?.trim()) {
         missing.push("module");
     }
-    if (!logContext.traceId?.trim()) {
+    if (!logScope.traceId?.trim()) {
         missing.push("traceId");
     }
+    if (logScope.traceParentId !== null && typeof logScope.traceParentId !== "string") {
+        missing.push("traceParentId");
+    }
     if (missing.length > 0) {
-        console.warn(`[LogManager] LogContext missing or empty: ${missing.join(", ")}`, logContext);
+        console.warn(`[LogManager] LogScope missing or invalid: ${missing.join(", ")}`, logScope);
     }
 }
 
 class LogManager {
     private static instance: LogManager;
     private options: LogOptions;
-    private history: LogEntry[] = [];
     private readonly levelEmojis = {
         [LogLevel.DEBUG]: "🔍",
         [LogLevel.INFO]: "ℹ️",
@@ -158,7 +146,9 @@ class LogManager {
         if (!LogManager.instance) {
             LogManager.instance = new LogManager(options);
         } else if (options != null && Object.keys(options).length > 0) {
-            console.warn("[LogManager] getInstance(options) ignored — singleton already created. Use setOptions() instead.");
+            console.warn(
+                "[LogManager] getInstance(options) ignored — singleton already created. Use setOptions() instead.",
+            );
         }
         return LogManager.instance;
     }
@@ -167,42 +157,28 @@ class LogManager {
         this.options = mergeLogOptions({ ...this.options, ...options });
     }
 
-    public getHistory(): LogEntry[] {
-        return [...this.history];
-    }
-
-    public clearHistory(): void {
-        this.history = [];
-    }
-
     private getMinLevel(): LogLevel {
         return this.options.minLevel ?? DEFAULT_OPTIONS.minLevel ?? LogLevel.INFO;
     }
 
-    private shouldLog(level: LogLevel): boolean {
-        return LOG_LEVEL_RANK[level] >= LOG_LEVEL_RANK[this.getMinLevel()];
+    private shouldLog(level: LogLevel, scopeMinLevel?: LogLevel): boolean {
+        const minLevel = scopeMinLevel ?? this.getMinLevel();
+        return LOG_LEVEL_RANK[level] >= LOG_LEVEL_RANK[minLevel];
     }
 
-    private createLogEntry({
-        level,
-        message,
-        topic,
-        module,
-        traceId,
-        nodeId,
-        extra,
-        context,
-    }: LogEntryPayload): LogEntry {
+    private createLogEntry(payload: LogEntryPayload): LogEntry {
+        const { level, message, topic, extra, data, module, traceId, traceParentId, labels } = payload;
         return {
             timestamp: Date.now(),
             level,
             message,
-            topic: topic === undefined ? this.options.defaultTopic : topic,
+            topic,
             module,
             traceId,
-            nodeId,
+            traceParentId,
+            labels,
             extra,
-            context,
+            data,
         };
     }
 
@@ -223,24 +199,23 @@ class LogManager {
 
         parts.push(this.formatLevelTag(entry));
         parts.push(
-            `traceId=${entry.traceId} nodeId=${entry.nodeId ?? "--"} module=${entry.module} topic=${entry.topic ?? "--"}`
+            `traceId=${entry.traceId} parent=${entry.traceParentId ?? "null"} labels=${formatScopeLabels(entry.labels)} module=${entry.module} topic=${entry.topic}`,
         );
 
         if (this.options.formatPrefix) {
             parts.push(`prefix=${this.options.formatPrefix}`);
         }
 
-        const message =
-            entry.level === LogLevel.CRITICAL ? `>>> ${entry.message} <<<` : entry.message;
+        const message = entry.level === LogLevel.CRITICAL ? `>>> ${entry.message} <<<` : entry.message;
         parts.push(`| ${message}`);
 
         if (entry.extra) {
             parts.push(`| extra=${entry.extra}`);
         }
 
-        const contextText = formatContextValue(entry.context);
-        if (contextText) {
-            parts.push(`| context=${contextText}`);
+        const dataText = formatDataValue(entry.data);
+        if (dataText) {
+            parts.push(`| data=${dataText}`);
         }
 
         return parts.join(" ");
@@ -263,78 +238,94 @@ class LogManager {
     private log(
         level: LogLevel,
         message: LogParams["message"],
-        logContext: LogContext,
-        restParams?: LogRestParams
+        logScope: LogScope,
+        restParams: LogRestParams,
+        scopeMinLevel?: LogLevel,
     ) {
-        if (!this.shouldLog(level)) {
+        if (!this.shouldLog(level, scopeMinLevel)) {
             return;
         }
 
-        validateLogContext(logContext);
-
-        const { topic, extra, context } = restParams ?? {};
-        const { module, traceId, nodeId } = logContext;
-        const entry = this.createLogEntry({ level, message, topic, extra, context, module, traceId, nodeId });
-
-        this.history.push(entry);
-        if (this.history.length > this.options.maxHistoryLength) {
-            this.history.shift();
+        validateLogScope(logScope);
+        if (!restParams.topic?.trim()) {
+            throw new Error("[LogManager] topic is required on every log call");
         }
 
+        const { topic, extra } = restParams;
+        const data = resolveLogData(restParams);
+        const entry = this.createLogEntry({
+            level,
+            message,
+            topic,
+            extra,
+            data,
+            ...logScope,
+        });
+
         const formatted = this.formatLog(entry);
         this.emitLog(entry, formatted);
         this.options.onLog?.(entry);
+        offerToLogPersist(entry);
     }
 
     public generateTraceId(): string {
         return generateUniqueId();
     }
 
-    public debug(message: LogParams["message"], logContext: LogContext, restParams?: LogRestParams) {
-        this.log(LogLevel.DEBUG, message, logContext, restParams);
+    public debug(message: LogParams["message"], logScope: LogScope, restParams: LogRestParams) {
+        this.log(LogLevel.DEBUG, message, logScope, restParams);
     }
 
-    public info(message: LogParams["message"], logContext: LogContext, restParams?: LogRestParams) {
-        this.log(LogLevel.INFO, message, logContext, restParams);
+    public info(message: LogParams["message"], logScope: LogScope, restParams: LogRestParams) {
+        this.log(LogLevel.INFO, message, logScope, restParams);
     }
 
-    public success(message: LogParams["message"], logContext: LogContext, restParams?: LogRestParams) {
-        this.log(LogLevel.SUCCESS, message, logContext, restParams);
+    public success(message: LogParams["message"], logScope: LogScope, restParams: LogRestParams) {
+        this.log(LogLevel.SUCCESS, message, logScope, restParams);
     }
 
-    public warn(message: LogParams["message"], logContext: LogContext, restParams?: LogRestParams) {
-        this.log(LogLevel.WARN, message, logContext, restParams);
+    public warn(message: LogParams["message"], logScope: LogScope, restParams: LogRestParams) {
+        this.log(LogLevel.WARN, message, logScope, restParams);
     }
 
-    public error(message: LogParams["message"], logContext: LogContext, restParams?: LogRestParams) {
-        this.log(LogLevel.ERROR, message, logContext, restParams);
+    public error(message: LogParams["message"], logScope: LogScope, restParams: LogRestParams) {
+        this.log(LogLevel.ERROR, message, logScope, restParams);
     }
 
-    public critical(message: LogParams["message"], logContext: LogContext, restParams?: LogRestParams) {
-        this.log(LogLevel.CRITICAL, message, logContext, restParams);
+    public critical(message: LogParams["message"], logScope: LogScope, restParams: LogRestParams) {
+        this.log(LogLevel.CRITICAL, message, logScope, restParams);
     }
 
-    public withContext(context: LogContext): { logger: LoggerWithContext; context: LogContext } {
-        const boundContext: LogContext = { ...context };
-
-        const logger: LoggerWithContext = {
-            debug: (message, restParams) => this.debug(message, boundContext, restParams),
-            info: (message, restParams) => this.info(message, boundContext, restParams),
-            success: (message, restParams) => this.success(message, boundContext, restParams),
-            warn: (message, restParams) => this.warn(message, boundContext, restParams),
-            error: (message, restParams) => this.error(message, boundContext, restParams),
-            critical: (message, restParams) => this.critical(message, boundContext, restParams),
-            resetContext: (fields) => {
-                Object.assign(boundContext, fields);
+    public withScope(scope: LogScope, options?: WithScopeOptions): { logger: LoggerWithScope; scope: LogScope } {
+        const boundScope: LogScope = { ...scope, labels: scope.labels ? { ...scope.labels } : undefined };
+        const scopeMinLevel = options?.minLevel;
+
+        const logger: LoggerWithScope = {
+            debug: (message, restParams) => this.log(LogLevel.DEBUG, message, boundScope, restParams, scopeMinLevel),
+            info: (message, restParams) => this.log(LogLevel.INFO, message, boundScope, restParams, scopeMinLevel),
+            success: (message, restParams) =>
+                this.log(LogLevel.SUCCESS, message, boundScope, restParams, scopeMinLevel),
+            warn: (message, restParams) => this.log(LogLevel.WARN, message, boundScope, restParams, scopeMinLevel),
+            error: (message, restParams) => this.log(LogLevel.ERROR, message, boundScope, restParams, scopeMinLevel),
+            critical: (message, restParams) =>
+                this.log(LogLevel.CRITICAL, message, boundScope, restParams, scopeMinLevel),
+            resetScope: (patch) => {
+                const next = patchScope({
+                    scope: boundScope,
+                    patch,
+                    allowTraceMutation: false,
+                });
+                boundScope.module = next.module;
+                boundScope.traceId = next.traceId;
+                boundScope.traceParentId = next.traceParentId;
+                boundScope.labels = next.labels;
             },
         };
 
-        return { logger, context: boundContext };
+        return { logger, scope: boundScope };
     }
 }
 
 export const logManager = LogManager.getInstance();
-export { LogManager, LogLevel };
-export { createApiLogger } from "./create-api-logger";
-export type { CreateApiLoggerOptions } from "./create-api-logger";
-export type { LogOptions, LogEntry, LogContext, LoggerWithContext, LogRestParams };
+export type { LogEntry, LoggerWithScope, LogOptions, LogRestParams, WithScopeOptions };
+export { LogLevel, LogManager };

package/src/shared/log/log-persist-batch-id.ts

@@ -0,0 +1,43 @@
+import { createHash } from "node:crypto";
+import type { LogEntry } from "./log-manager";
+import type { LogPersistLane } from "./log-persist.interface";
+
+const BATCH_ID_VERSION = 1;
+
+/** Stable subset of LogEntry for idempotency hashing (same batch → same key). */
+function canonicalLogEntry(entry: LogEntry): Record<string, unknown> {
+    return {
+        timestamp: entry.timestamp,
+        level: entry.level,
+        message: entry.message,
+        topic: entry.topic,
+        module: entry.module,
+        traceId: entry.traceId,
+        traceParentId: entry.traceParentId ?? null,
+        extra: entry.extra ?? null,
+        data: entry.data ?? null,
+        labels: entry.labels ?? null,
+    };
+}
+
+/**
+ * Deterministic List.value for a log batch — retries after timeout map to the same row key.
+ * SHA-256 over canonical JSON (service + process + lane + entries in order).
+ */
+export function computeLogBatchIdempotencyKey(input: {
+    service: string;
+    process: string;
+    lane: LogPersistLane;
+    entries: LogEntry[];
+}): string {
+    const payload = {
+        v: BATCH_ID_VERSION,
+        service: input.service,
+        process: input.process,
+        lane: input.lane,
+        entries: input.entries.map(canonicalLogEntry),
+    };
+
+    const hash = createHash("sha256").update(JSON.stringify(payload), "utf8").digest("hex");
+    return `${hash.slice(0, 32)}`;
+}