target-supabase-sdk 0.2.9 → 0.2.11

package/dist/task/task-post-validated.api.d.ts

@@ -7,13 +7,13 @@ import type { Task } from "./task.interface";
  * @see target-supabase-sdk/node
  */
 export declare const postTaskWithValidation: (payload: {
-    name: string;
     value: string;
+    name: string;
     tagList: string[];
     taskStatus: import("./task.interface").TaskStatus.OPEN | import("./task.interface").TaskStatus.TODO;
+    params?: unknown;
     extra?: string | undefined;
     traceId?: string | undefined;
     traceParentId?: string | null | undefined;
-    params?: unknown;
 }) => SupabaseResponse<Task> | Promise<SupabaseResponse<Task>>;
 //# sourceMappingURL=task-post-validated.api.d.ts.map

package/dist/task/task-post.api.d.ts

@@ -13,22 +13,22 @@ export declare const postTaskSchema: z.ZodObject<{
     traceId: z.ZodOptional<z.ZodString>;
     traceParentId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
 }, "strip", z.ZodTypeAny, {
-    name: string;
     value: string;
+    name: string;
     tagList: string[];
     taskStatus: TaskStatus.OPEN | TaskStatus.TODO;
+    params?: unknown;
     extra?: string | undefined;
     traceId?: string | undefined;
     traceParentId?: string | null | undefined;
-    params?: unknown;
 }, {
-    name: string;
     value: string;
+    name: string;
+    params?: unknown;
     tagList?: string[] | undefined;
     extra?: string | undefined;
     traceId?: string | undefined;
     traceParentId?: string | null | undefined;
-    params?: unknown;
     taskStatus?: TaskStatus.OPEN | TaskStatus.TODO | undefined;
 }>;
 export type PostTaskPayload = z.infer<typeof postTaskSchema>;
@@ -42,13 +42,13 @@ export declare function createTaskRow({ name, value, params, taskStatus, tagList
  * Execution-time checks live in {@link TaskManager.prepareTask}.
  */
 export declare const postTask: (payload: {
-    name: string;
     value: string;
+    name: string;
     tagList: string[];
     taskStatus: TaskStatus.OPEN | TaskStatus.TODO;
+    params?: unknown;
     extra?: string | undefined;
     traceId?: string | undefined;
     traceParentId?: string | null | undefined;
-    params?: unknown;
 }) => SupabaseResponse<Task> | Promise<SupabaseResponse<Task>>;
 //# sourceMappingURL=task-post.api.d.ts.map

package/dist/trigger/trigger.api.d.ts

@@ -41,10 +41,10 @@ export declare const postTriggerSchema: z.ZodObject<{
     tagList: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodString, "many">>>;
     traceId: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
-    name: string;
+    status: TriggerStatus;
     value: string;
+    name: string;
     tagList: string[];
-    status: TriggerStatus;
     action: {
         taskTypeKey: string;
         kind: "post_task";
@@ -59,8 +59,8 @@ export declare const postTriggerSchema: z.ZodObject<{
     };
     traceId?: string | undefined;
 }, {
-    name: string;
     value: string;
+    name: string;
     action: {
         taskTypeKey: string;
         kind: "post_task";
@@ -73,9 +73,9 @@ export declare const postTriggerSchema: z.ZodObject<{
         minute: number;
         kind: "daily";
     };
+    status?: TriggerStatus | undefined;
     tagList?: string[] | undefined;
     traceId?: string | undefined;
-    status?: TriggerStatus | undefined;
 }>;
 export type PostTriggerPayload = z.infer<typeof postTriggerSchema>;
 export declare const scanEnabledTriggersSchema: z.ZodObject<{
@@ -109,10 +109,10 @@ export declare const scanEnabledTriggers: (payload: {
 }) => SupabaseResponse<Trigger[]> | Promise<SupabaseResponse<Trigger[]>>;
 /** Create a trigger row (scheduler / admin). */
 export declare const postTrigger: (payload: {
-    name: string;
+    status: TriggerStatus;
     value: string;
+    name: string;
     tagList: string[];
-    status: TriggerStatus;
     action: {
         taskTypeKey: string;
         kind: "post_task";

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "target-supabase-sdk",
-    "version": "0.2.9",
+    "version": "0.2.11",
     "description": "Supabase client initializer and data access APIs",
     "license": "MIT",
     "author": "KyLoc20",
@@ -53,7 +53,8 @@
         "format": "biome check --write .",
         "format:check": "biome ci",
         "lint": "biome lint .",
-        "verify": "pnpm typecheck && pnpm typecheck:scripts && pnpm format:check",
+        "verify": "pnpm typecheck && pnpm typecheck:scripts && pnpm format:check && pnpm verify:json-state-store",
+        "verify:json-state-store": "tsx scripts/verify-json-state-store-concurrency.ts",
         "prepare": "git config core.hooksPath .githooks",
         "worker:trigger": "tsx scripts/run-trigger-node.ts",
         "post-command": "tsx scripts/post-command.ts",

package/src/browser.ts

@@ -8,6 +8,7 @@
 export type { SupabaseClient } from "@supabase/supabase-js";
 export * from "./core.api";
 export * from "./core.interface";
+export * from "./core.schema";
 export * from "./core.utils";
 export type {
     GetExtractionPayload,
@@ -28,10 +29,8 @@ export {
 export type { Extraction, ExtractionDetails } from "./extraction/extraction.interface";
 export { CategoryExtraction } from "./extraction/extraction.interface";
 export * from "./idea/idea.interface";
-export * from "./link/link.api";
-export * from "./link/link.interface";
-export * from "./list/list.api";
-export * from "./list/list.interface";
+export * from "./link/index";
+export * from "./list/index";
 export * from "./node/node.api";
 export * from "./node/node.interface";
 export type {

package/src/core.api.ts

@@ -1,14 +1,19 @@
 import type { PostgrestFilterBuilder } from "@supabase/postgrest-js";
 import type { ZodError, ZodType } from "zod";
-import { generateResponse, type Target, type TargetDraft } from "./core.interface";
-import { BaseValidator, handleSupabaseError } from "./core.utils";
+import { generateResponse, type QueryFilter, type Target, type TargetDraft } from "./core.interface";
+import { type PostTargetPayload, postTargetPayloadSchema } from "./core.schema";
+import { type BaseValidator, handleSupabaseError } from "./core.utils";
 import { supabase } from "./supabase";
 
-export interface QueryFilter {
-    field: string;
-    operator: "eq" | "neq" | "in";
-    value: unknown;
-}
+export type { QueryFilter } from "./core.interface";
+export type { PostTargetPayload } from "./core.schema";
+export {
+    formatZodError,
+    postTargetPayloadSchema,
+    queryFilterSchema,
+    safeParseWithSchema,
+    targetDraftSchema,
+} from "./core.schema";
 
 export const MAX_TARGET_LIST_PAGE_SIZE = 100;
 
@@ -379,30 +384,16 @@ export const deleteTarget = async ({ id, filterList }: { id: string; filterList?
     return generateResponse.success();
 };
 
-export interface PostTargetPayload {
-    name: Target["name"];
-    category: Target["category"];
-    value: Target["value"];
-    tagList: Target["tagList"];
-    extra?: Target["extra"];
-    details?: Target["details"];
-}
-
-class PostTargetPayloadValidator extends BaseValidator<PostTargetPayload> {
-    protected requiredFields: (keyof PostTargetPayload)[] = ["category", "name", "value", "tagList"];
-    protected optionalFields: (keyof PostTargetPayload)[] = ["extra", "details"];
-
-    constructor() {
-        super();
-        // Add custom
-        this.addCustomValidator((_val) => {
-            return true;
-        });
+function parsePostTargetPayload(payload: unknown): PostTargetPayload {
+    const result = postTargetPayloadSchema.safeParse(payload);
+    if (!result.success) {
+        throw formatZodValidationError("PostTargetPayload", result.error);
     }
+    return result.data;
 }
 
 export const postTarget = async (payload: PostTargetPayload) => {
-    const validPayload = new PostTargetPayloadValidator().validate(payload);
+    const validPayload = parsePostTargetPayload(payload);
 
     const { data, error } = await supabase.client
         .from("target")
@@ -443,7 +434,7 @@ export const patchTarget = async ({ id, ...restPayload }: PatchTargetPayload) =>
     }
     if (fetchError) handleSupabaseError("patchTarget", fetchError, "Failed to fetch target.");
 
-    const updatedTarget = new PostTargetPayloadValidator().validate(restPayload);
+    const updatedTarget = parsePostTargetPayload(restPayload);
 
     const { data, error } = await supabase.client
         .from("target")

package/src/core.interface.ts

@@ -14,6 +14,12 @@ export interface Target {
 /** Target row before persistence — no `id` or `created_at`. */
 export type TargetDraft<T extends Target> = Omit<T, "id" | "created_at">;
 
+export interface QueryFilter {
+    field: string;
+    operator: "eq" | "neq" | "in";
+    value: unknown;
+}
+
 export enum StatusCode {
     SUCCESS = 200,
     ERROR = 400,

package/src/core.schema.ts

@@ -0,0 +1,51 @@
+import { type ZodError, type ZodType, z } from "zod";
+import type { QueryFilter } from "./core.interface";
+
+/** {@link QueryFilter} — shared by createTarget redundancy checks and message payloads. */
+export const queryFilterSchema = z
+    .object({
+        field: z.string().trim().min(1),
+        operator: z.enum(["eq", "neq", "in"]),
+        value: z.any(),
+    })
+    .transform(
+        (row): QueryFilter => ({
+            field: row.field,
+            operator: row.operator,
+            value: row.value,
+        }),
+    );
+
+/** Persisted Target create/patch body (no `id` / `created_at`). */
+export const postTargetPayloadSchema = z.object({
+    name: z.string(),
+    value: z.string(),
+    category: z.string(),
+    tagList: z.array(z.string()),
+    extra: z.string().optional(),
+    details: z.unknown().optional(),
+});
+
+export type PostTargetPayload = z.infer<typeof postTargetPayloadSchema>;
+
+/** {@link TargetDraft} — stricter trim on identity fields for draft/message boundaries. */
+export const targetDraftSchema = postTargetPayloadSchema.extend({
+    name: z.string().trim().min(1),
+    value: z.string().trim().min(1),
+    category: z.string().trim().min(1),
+});
+
+export function formatZodError(error: ZodError): string {
+    return error.issues.map((issue) => issue.message).join("; ");
+}
+
+export function safeParseWithSchema<T extends ZodType>(
+    schema: T,
+    input: unknown,
+): { ok: true; data: z.infer<T> } | { ok: false; error: string } {
+    const result = schema.safeParse(input);
+    if (!result.success) {
+        return { ok: false, error: formatZodError(result.error) };
+    }
+    return { ok: true, data: result.data };
+}

package/src/link/index.ts

@@ -0,0 +1,10 @@
+/**
+ * Link domain public API — curated re-exports only.
+ */
+
+export type { PostLinkCreatePayload } from "./link.api";
+export { PostLinkValidator, postLinkCreate } from "./link.api";
+export type { LinkTargetDraftBuildInput } from "./link.build";
+export { buildLinkTargetDraft, LINK_MANIFEST_VERSION, linkTargetDraftBuildInputSchema } from "./link.build";
+export type { Link, LinkDetails } from "./link.interface";
+export { CategoryLink } from "./link.interface";

package/src/link/link.build.ts

@@ -0,0 +1,48 @@
+import { z } from "zod";
+import type { TargetDraft } from "../core.interface";
+import { CategoryLink, type Link } from "./link.interface";
+
+export const LINK_MANIFEST_VERSION = 0;
+
+/**
+ * Convenience input for {@link buildLinkTargetDraft} — must not include `category`.
+ * Also accepted in {@link buildListTargetDraft} `items` as syntactic sugar (see `list.build.ts`).
+ */
+export interface LinkTargetDraftBuildInput<O = unknown> {
+    name: string;
+    value: string;
+    description: string;
+    preview?: string;
+    loaderKey: string;
+    tagList?: string[];
+    original: O;
+}
+
+/** Runtime shape check for {@link LinkTargetDraftBuildInput} — `.strict()` rejects `category` and other extra keys. */
+export const linkTargetDraftBuildInputSchema = z
+    .object({
+        name: z.string(),
+        value: z.string(),
+        description: z.string(),
+        preview: z.string().optional(),
+        loaderKey: z.string(),
+        tagList: z.array(z.string()).optional(),
+        original: z.unknown(),
+    })
+    .strict();
+
+export function buildLinkTargetDraft<O = unknown>(input: LinkTargetDraftBuildInput<O>): TargetDraft<Link> {
+    return {
+        name: input.name,
+        value: input.value,
+        category: CategoryLink.LINK,
+        tagList: input.tagList ?? [],
+        details: {
+            manifestVersion: LINK_MANIFEST_VERSION,
+            description: input.description,
+            preview: input.preview ?? "",
+            loaderKey: input.loaderKey,
+            original: input.original,
+        },
+    };
+}

package/src/list/index.ts

@@ -0,0 +1,13 @@
+/**
+ * List domain public API — curated re-exports only.
+ */
+
+export type { PostListCreatePayload } from "./list.api";
+export { PostListValidator, postListCreate, postLogListCreate } from "./list.api";
+export type { BuildListTargetDraftInput } from "./list.build";
+export {
+    buildListTargetDraft,
+    LIST_MANIFEST_VERSION,
+} from "./list.build";
+export type { List, ListDetails } from "./list.interface";
+export { CategoryList } from "./list.interface";

package/src/list/list.build.ts

@@ -0,0 +1,51 @@
+import type { TargetDraft } from "../core.interface";
+import {
+    buildLinkTargetDraft,
+    type LinkTargetDraftBuildInput,
+    linkTargetDraftBuildInputSchema,
+} from "../link/link.build";
+import { CategoryList, type List, type ListDetails } from "./list.interface";
+
+export const LIST_MANIFEST_VERSION = 0;
+
+/**
+ * Input for {@link buildListTargetDraft}.
+ *
+ * `items`: most lists store Link rows. {@link LinkTargetDraftBuildInput} is syntactic
+ * sugar — expanded via `buildLinkTargetDraft`. Any other shape is stored as-is.
+ */
+export type BuildListTargetDraftInput<O = unknown, TCustom = unknown> = {
+    loaderKey: string;
+    name: string;
+    value: string;
+    meta?: unknown;
+    preview?: string;
+    tagList?: string[];
+    items: Array<LinkTargetDraftBuildInput<O> | TCustom>;
+};
+
+function isLinkTargetDraftBuildInput(item: unknown): item is LinkTargetDraftBuildInput {
+    return linkTargetDraftBuildInputSchema.safeParse(item).success;
+}
+
+export function buildListTargetDraft<O = unknown, TCustom = unknown>(
+    input: BuildListTargetDraftInput<O, TCustom>,
+): TargetDraft<List> {
+    const items = input.items.map((item) => (isLinkTargetDraftBuildInput(item) ? buildLinkTargetDraft(item) : item));
+
+    const details: ListDetails = {
+        manifestVersion: LIST_MANIFEST_VERSION,
+        meta: input.meta ?? "",
+        preview: input.preview ?? "",
+        loaderKey: input.loaderKey,
+        items,
+    };
+
+    return {
+        name: input.name,
+        value: input.value,
+        category: CategoryList.LIST,
+        tagList: input.tagList ?? [],
+        details,
+    };
+}

package/src/node/fs/file-write-queue.ts

@@ -0,0 +1,15 @@
+/** Per-file write queue — serializes read-modify-write for a single JSON path within one process. */
+const writeChains = new Map<string, Promise<unknown>>();
+
+export function withSerializedFileWrites<T>(filePath: string, operation: () => Promise<T>): Promise<T> {
+    const previous = writeChains.get(filePath) ?? Promise.resolve();
+    const next = previous.then(operation, operation);
+    writeChains.set(
+        filePath,
+        next.then(
+            () => undefined,
+            () => undefined,
+        ),
+    );
+    return next;
+}

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

@@ -1,5 +1,7 @@
-import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import { randomBytes } from "node:crypto";
+import { mkdir, readFile, rename, unlink, writeFile } from "node:fs/promises";
 import { dirname } from "node:path";
+import { withSerializedFileWrites } from "./file-write-queue";
 
 export type JsonStatePatch<T extends object, NK extends keyof T> = Partial<Omit<T, NK>> & {
     [K in NK]?: T[K] extends object ? Partial<T[K]> : T[K];
@@ -49,9 +51,15 @@ function mergeWithNested<T extends object>(
 async function atomicWriteJson(filePath: string, data: unknown): Promise<void> {
     await mkdir(dirname(filePath), { recursive: true });
     const content = `${JSON.stringify(data, null, 2)}\n`;
-    const tempPath = `${filePath}.${process.pid}.tmp`;
-    await writeFile(tempPath, content, "utf8");
-    await rename(tempPath, filePath);
+    JSON.parse(content);
+    const tempPath = `${filePath}.${process.pid}.${randomBytes(4).toString("hex")}.tmp`;
+    try {
+        await writeFile(tempPath, content, "utf8");
+        await rename(tempPath, filePath);
+    } catch (error) {
+        await unlink(tempPath).catch(() => undefined);
+        throw error;
+    }
 }
 
 /** JSON file-backed state with optional nested key merge and atomic writes. */
@@ -70,31 +78,43 @@ export function createJsonFileStateStore<T extends object, NK extends keyof T =
         };
     }
 
-    return {
-        async read(): Promise<T> {
-            try {
-                const raw = await readFile(filePath, "utf8");
-                const parsed = JSON.parse(raw) as Partial<T>;
-                return mergeWithNested(defaultState, parsed, {}, nestedKeys);
-            } catch (error) {
-                if ((error as NodeJS.ErrnoException).code === "ENOENT") {
-                    return mergeWithNested(defaultState, {}, {}, nestedKeys);
-                }
-                throw error;
+    async function readFromDisk(): Promise<T> {
+        try {
+            const raw = await readFile(filePath, "utf8");
+            const parsed = JSON.parse(raw) as Partial<T>;
+            return mergeWithNested(defaultState, parsed, {}, nestedKeys);
+        } catch (error) {
+            if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+                return mergeWithNested(defaultState, {}, {}, nestedKeys);
             }
+            if (error instanceof SyntaxError) {
+                await unlink(filePath).catch(() => undefined);
+                return mergeWithNested(defaultState, {}, {}, nestedKeys);
+            }
+            throw error;
+        }
+    }
+
+    return {
+        read(): Promise<T> {
+            return readFromDisk();
         },
 
-        async write(patch: JsonStatePatch<T, NK>): Promise<T> {
-            const current = await this.read();
-            const next = touchUpdatedAt(mergeWithNested(defaultState, current, patch as Partial<T>, nestedKeys));
-            await atomicWriteJson(filePath, next);
-            return next;
+        write(patch: JsonStatePatch<T, NK>): Promise<T> {
+            return withSerializedFileWrites(filePath, async () => {
+                const current = await readFromDisk();
+                const next = touchUpdatedAt(mergeWithNested(defaultState, current, patch as Partial<T>, nestedKeys));
+                await atomicWriteJson(filePath, next);
+                return next;
+            });
         },
 
-        async reset(): Promise<T> {
-            const next = touchUpdatedAt({ ...defaultState });
-            await atomicWriteJson(filePath, next);
-            return next;
+        reset(): Promise<T> {
+            return withSerializedFileWrites(filePath, async () => {
+                const next = touchUpdatedAt({ ...defaultState });
+                await atomicWriteJson(filePath, next);
+                return next;
+            });
         },
     };
 }

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

@@ -0,0 +1,16 @@
+const PERMANENT_LOG_PERSIST_ERROR_PATTERNS = [
+    /not initialized/i,
+    /call initialize\(\) first/i,
+    /missing required supabase environment/i,
+    /preload env incomplete/i,
+];
+
+export function formatLogPersistError(error: unknown): string {
+    return error instanceof Error ? error.message : String(error);
+}
+
+/** Errors that will not succeed on retry without fixing process configuration. */
+export function isPermanentLogPersistError(error: unknown): boolean {
+    const message = formatLogPersistError(error);
+    return PERMANENT_LOG_PERSIST_ERROR_PATTERNS.some((pattern) => pattern.test(message));
+}

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

@@ -8,13 +8,41 @@ export const LOG_PERSIST_INTERNAL_TOPIC = "log-persist-internal";
 
 const logger = createLogger({ module: "log-persist" });
 
+let errorLogRateLimitMs = 5_000;
+const lastLoggedAt = new Map<string, number>();
+
+export function configurePersistLoggerRateLimit(ms: number): void {
+    errorLogRateLimitMs = Math.max(0, ms);
+}
+
 export function isLogPersistInternalTopic(topic: string | undefined): boolean {
     return topic === LOG_PERSIST_INTERNAL_TOPIC;
 }
 
 type PersistLogData = Record<string, unknown>;
 
+function shouldEmit(level: "debug" | "info" | "warn" | "error", message: string): boolean {
+    if (level !== "error" && level !== "warn") {
+        return true;
+    }
+    if (errorLogRateLimitMs <= 0) {
+        return true;
+    }
+
+    const key = `${level}:${message}`;
+    const now = Date.now();
+    const last = lastLoggedAt.get(key);
+    if (last != null && now - last < errorLogRateLimitMs) {
+        return false;
+    }
+    lastLoggedAt.set(key, now);
+    return true;
+}
+
 function write(level: "debug" | "info" | "warn" | "error", message: string, data?: PersistLogData): void {
+    if (!shouldEmit(level, message)) {
+        return;
+    }
     logger[level](message, {
         topic: LOG_PERSIST_INTERNAL_TOPIC,
         ...(data != null ? { data } : {}),

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

@@ -19,6 +19,9 @@ export const DEFAULT_LOG_PERSIST_CONFIG: LogPersistConfig = {
     },
     postTimeoutMs: 30_000,
     shutdownDrainTimeoutMs: 15_000,
+    laneRetryIntervalMs: 5_000,
+    errorLogRateLimitMs: 5_000,
+    circuitBreakerPermanentFailureThreshold: 3,
 };
 
 export function resolveLogPersistConfig(partial?: Partial<LogPersistConfig>): LogPersistConfig {
@@ -29,6 +32,10 @@ export function resolveLogPersistConfig(partial?: Partial<LogPersistConfig>): Lo
         slow: { ...defaults.slow, ...partial?.slow },
         postTimeoutMs: partial?.postTimeoutMs ?? defaults.postTimeoutMs,
         shutdownDrainTimeoutMs: partial?.shutdownDrainTimeoutMs ?? defaults.shutdownDrainTimeoutMs,
+        laneRetryIntervalMs: partial?.laneRetryIntervalMs ?? defaults.laneRetryIntervalMs,
+        errorLogRateLimitMs: partial?.errorLogRateLimitMs ?? defaults.errorLogRateLimitMs,
+        circuitBreakerPermanentFailureThreshold:
+            partial?.circuitBreakerPermanentFailureThreshold ?? defaults.circuitBreakerPermanentFailureThreshold,
     };
 }
 
@@ -91,5 +98,18 @@ export function logPersistConfigFromEnv(env: NodeJS.ProcessEnv = process.env): L
             DEFAULT_LOG_PERSIST_CONFIG.shutdownDrainTimeoutMs,
             { env },
         ),
+        laneRetryIntervalMs: envMs("LOG_PERSIST_LANE_RETRY_MS", DEFAULT_LOG_PERSIST_CONFIG.laneRetryIntervalMs, {
+            env,
+        }),
+        errorLogRateLimitMs: envMs(
+            "LOG_PERSIST_ERROR_LOG_RATE_LIMIT_MS",
+            DEFAULT_LOG_PERSIST_CONFIG.errorLogRateLimitMs,
+            { env },
+        ),
+        circuitBreakerPermanentFailureThreshold: envInt(
+            "LOG_PERSIST_CIRCUIT_BREAKER_THRESHOLD",
+            DEFAULT_LOG_PERSIST_CONFIG.circuitBreakerPermanentFailureThreshold,
+            { env, min: 1 },
+        ),
     });
 }

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

@@ -41,6 +41,12 @@ export interface LogPersistConfig {
     postTimeoutMs: number;
     /** Graceful shutdown drain ceiling */
     shutdownDrainTimeoutMs: number;
+    /** Delay before medium/slow lane flush retries after failure (fast lane uses the same interval). */
+    laneRetryIntervalMs: number;
+    /** Suppress duplicate persistLogger warn/error lines with the same message within this window. */
+    errorLogRateLimitMs: number;
+    /** Disable log-persist after this many consecutive permanent flush errors. */
+    circuitBreakerPermanentFailureThreshold: number;
 }
 
 export interface EnableLogPersistOptions {
@@ -89,6 +95,8 @@ export interface LogPersistQueueBytesStats {
 export interface LogPersistStats {
     enabled: boolean;
     draining: boolean;
+    circuitBreakerTripped: boolean;
+    permanentFailureCount: number;
     service: string | null;
     process: string | null;
     queues: LogPersistQueueStats;