target-supabase-sdk 0.2.24 → 0.3.0

package/src/service/service.interface.ts

@@ -29,7 +29,7 @@ export interface ServiceDetails {
     runtime?: ServiceRuntime;
 }
 
-/** Per-node snapshot under a running Service — maintained by the service guard. */
+/** Per-node snapshot for nodes owned by this Service instance (`Node.name === serviceId`). */
 export interface ServiceNodeSnapshot {
     nodeId: string;
     status: NodeStatus;
@@ -38,7 +38,7 @@ export interface ServiceNodeSnapshot {
 
 /**
  * Runtime observability for a registered Service instance.
- * Heartbeat and node rollups are written by the service guard, not the system registry Config.
+ * Heartbeat and node rollups are written by the service guard (scoped to this instance), not the system registry Config.
  */
 export interface ServiceRuntime {
     lastHeartBeat: number;

package/src/shared/log/README.md

@@ -18,8 +18,7 @@ src/shared/log/
 
   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
+    interface.ts           # LogBatch meta, LOG_BATCH_LIST_VALUE, lane type
     flush.ts               # buildLogListDraft, postLogBatch
     hook.ts                # LogManager → spool writer offer bridge
     logger.ts              # internal pipeline loggers (no feedback loop)
@@ -58,7 +57,7 @@ App code
   → {spoolRoot}/{serviceId}/{role}/*.tmp
 
 Guard collect-log runner (1 min tick)
-  → read *.tmp → postLogBatch → rename *.json
+  → read *.tmp → postLogBatch (List value=log-batch, name=service) → rename *.json / .synced marker
   → GC old tmp/json (once per day; 7 d retention)
 
 log-service (downstream)

package/src/shared/log/core/log-batch.ts

@@ -5,8 +5,8 @@
  */
 
 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";
+import { LOG_BATCH_LIST_VALUE, type LogBatchMeta, type LogPersistLane } from "../upload/interface";
+import type { LogEntry } from "./log-manager";
 
 const LANES: ReadonlySet<string> = new Set<LogPersistLane>(["fast", "medium", "slow"]);
 
@@ -26,8 +26,8 @@ export interface FlatLogEntry extends LogEntry {
     process: string;
     lane: LogPersistLane;
     pid: number;
-    /** Idempotency key of the source batch. */
-    batchId: string;
+    /** Source List row id. */
+    listId: string;
 }
 
 function asRecord(value: unknown): Record<string, unknown> | null {
@@ -61,8 +61,7 @@ export function parseLogBatchMeta(rawMeta: unknown): LogBatchMeta | null {
     const service = asString(source.service);
     const processName = asString(source.process);
     const laneRaw = asString(source.lane);
-    const idempotencyKey = asString(source.idempotencyKey);
-    if (service == null || processName == null || laneRaw == null || !LANES.has(laneRaw) || idempotencyKey == null) {
+    if (service == null || processName == null || laneRaw == null || !LANES.has(laneRaw)) {
         return null;
     }
 
@@ -75,7 +74,6 @@ export function parseLogBatchMeta(rawMeta: unknown): LogBatchMeta | null {
         from: asFiniteNumber(source.from),
         to: asFiniteNumber(source.to),
         flushedAt: asFiniteNumber(source.flushedAt) ?? 0,
-        idempotencyKey,
     };
 }
 
@@ -93,9 +91,9 @@ export function isLogEntry(value: unknown): value is LogEntry {
     );
 }
 
-/** Is this List a persisted log batch (by loaderKey)? */
+/** Is this List a persisted log batch (by `value`)? */
 export function isLogBatchList(list: List): boolean {
-    return list.details?.loaderKey === LOG_PERSIST_LOADER_KEY;
+    return list.value === LOG_BATCH_LIST_VALUE;
 }
 
 /**
@@ -106,6 +104,10 @@ export function decodeLogBatch(list: List): DecodedLogBatch | null {
     if (!isLogBatchList(list)) {
         return null;
     }
+    const loaderKey = list.details?.loaderKey;
+    if (typeof loaderKey === "string" && loaderKey.endsWith(".bad")) {
+        return null;
+    }
     const meta = parseLogBatchMeta(list.details?.meta);
     if (meta == null) {
         return null;
@@ -142,7 +144,7 @@ export function flattenLogBatch(batch: DecodedLogBatch): FlatLogEntry[] {
         process: batch.meta.process,
         lane: batch.meta.lane,
         pid: batch.meta.pid,
-        batchId: batch.meta.idempotencyKey,
+        listId: batch.listId,
     }));
 }
 

package/src/shared/log/index.ts

@@ -42,5 +42,6 @@ export {
     resolveLogData,
     withModule,
 } from "./core/log-scope";
+export { formatLogSpoolBatchTimestamp } from "./spool/file";
 export type { LogBatchMeta, LogPersistLane } from "./upload/interface";
-export { LOG_BATCH_LOADER_KEY, LOG_PERSIST_LOADER_KEY } from "./upload/interface";
+export { LOG_BATCH_LIST_VALUE } from "./upload/interface";

package/src/shared/log/spool/collector.ts

@@ -1,7 +1,6 @@
-import { access, constants, readdir, readFile, rename, stat, unlink } from "node:fs/promises";
+import { access, constants, readdir, readFile, rename, stat, unlink, writeFile } from "node:fs/promises";
 import { join } from "node:path";
 import { isLogEntry } from "../core/log-batch";
-import { computeLogBatchIdempotencyKey } from "../upload/batch-id";
 import { buildLogListDraft, postLogBatch } from "../upload/flush";
 import { spoolLogger } from "../upload/logger";
 import { type DEFAULT_LOG_SPOOL_CONFIG, resolveLogSpoolConfig } from "./config";
@@ -11,6 +10,7 @@ import { logSpoolProcessDir, resolveLogSpoolRoot } from "./paths";
 import { resolveAllLogSpoolProcessRoles } from "./process-roles";
 
 const UPLOAD_LANE = "slow";
+const MAX_UPLOADS_PER_COLLECT_TICK = 20;
 
 /** Per serviceId — guard collect-log tick runs GC at most once per `gc.intervalMs`. */
 const lastGcAtMsByServiceId = new Map<string, number>();
@@ -61,6 +61,10 @@ function processMetaKey(serviceId: string, processRole: LogSpoolProcessRole): st
     return `${serviceId}:${processRole}`;
 }
 
+function syncedMarkerPath(jsonPath: string): string {
+    return jsonPath.replace(/\.json$/, ".synced");
+}
+
 async function uploadTmpBatch(input: {
     serviceId: string;
     serviceValue: string;
@@ -78,6 +82,7 @@ async function uploadTmpBatch(input: {
 
     const jsonFileName = input.fileName.replace(/\.tmp$/, ".json");
     const jsonPath = join(logSpoolProcessDir(input.spoolRoot, input.serviceId, input.processRole), jsonFileName);
+    const syncedPath = syncedMarkerPath(jsonPath);
 
     if (await pathExists(jsonPath)) {
         try {
@@ -92,6 +97,19 @@ async function uploadTmpBatch(input: {
         return "skipped";
     }
 
+    if (await pathExists(syncedPath)) {
+        try {
+            await rename(input.tmpPath, jsonPath);
+        } catch {
+            try {
+                await unlink(input.tmpPath);
+            } catch {
+                // best-effort
+            }
+        }
+        return "skipped";
+    }
+
     const batch = await readBatchTmpFile(input.tmpPath);
     if (batch == null) {
         spoolLogger.warn("collect-log skipped — tmp failed validation", {
@@ -108,19 +126,10 @@ async function uploadTmpBatch(input: {
     }
 
     const processKey = processMetaKey(input.serviceId, input.processRole);
-    // TODO: `lane` is legacy transport metadata — scheduled for removal; fixed to "slow" for downstream decode compatibility.
-    const idempotencyKey = computeLogBatchIdempotencyKey({
-        service: input.serviceValue,
-        process: processKey,
-        lane: UPLOAD_LANE,
-        entries: batch.entries,
-    });
-
     const draft = buildLogListDraft({
         service: input.serviceValue,
         process: processKey,
         lane: UPLOAD_LANE,
-        idempotencyKey,
         entries: batch.entries,
     });
 
@@ -136,8 +145,20 @@ async function uploadTmpBatch(input: {
         return "failed";
     }
 
+    try {
+        await writeFile(syncedPath, `${Date.now()}\n`, "utf8");
+    } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        spoolLogger.warn("collect-log synced marker write failed", { syncedPath, error: message });
+    }
+
     try {
         await rename(input.tmpPath, jsonPath);
+        try {
+            await unlink(syncedPath);
+        } catch {
+            // best-effort
+        }
     } catch (error) {
         const message = error instanceof Error ? error.message : String(error);
         spoolLogger.error("collect-log rename tmp→json failed after upload", {
@@ -145,14 +166,13 @@ async function uploadTmpBatch(input: {
             jsonPath,
             error: message,
         });
-        return "failed";
+        return "uploaded";
     }
 
     spoolLogger.info("collect-log uploaded batch", {
         processRole: input.processRole,
         fileName: jsonFileName,
         entryCount: batch.entries.length,
-        idempotencyKey,
     });
 
     return "uploaded";
@@ -217,22 +237,22 @@ async function gcSyncedJsonFiles(input: {
         }
 
         for (const name of names) {
-            if (!name.endsWith(".json")) {
+            if (!name.endsWith(".json") && !name.endsWith(".synced")) {
                 continue;
             }
-            if (parseLogSpoolBatchFilename(name) == null) {
+            if (parseLogSpoolBatchFilename(name) == null && !name.endsWith(".synced")) {
                 continue;
             }
 
-            const jsonPath = join(processDir, name);
+            const filePath = join(processDir, name);
             try {
-                const fileStat = await stat(jsonPath);
+                const fileStat = await stat(filePath);
                 if (input.nowMs - fileStat.mtimeMs <= input.syncedRetentionMs) {
                     continue;
                 }
-                await unlink(jsonPath);
+                await unlink(filePath);
                 removed += 1;
-                spoolLogger.info("collect-log gc removed synced json", {
+                spoolLogger.info("collect-log gc removed synced file", {
                     fileName: name,
                     processRole,
                 });
@@ -256,7 +276,7 @@ function shouldRunGc(serviceId: string, nowMs: number, intervalMs: number): bool
 
 /**
  * Guard-only: upload pending `.tmp` batches, rename to `.json`, then periodic GC.
- * Upload completion is implied by `.json` presence; no sync-state file.
+ * Post success is tracked via `.json` or `.synced` marker (prevents duplicate DB inserts).
  */
 export async function runCollectLogTick(input: RunCollectLogTickInput): Promise<RunCollectLogTickResult> {
     const config = resolveLogSpoolConfig(input.config);
@@ -271,6 +291,8 @@ export async function runCollectLogTick(input: RunCollectLogTickInput): Promise<
         gcSyncedRemoved: 0,
     };
 
+    let uploadsThisTick = 0;
+
     for (const processRole of resolveAllLogSpoolProcessRoles()) {
         const processDir = logSpoolProcessDir(spoolRoot, input.serviceId, processRole);
         let names: string[] = [];
@@ -284,6 +306,9 @@ export async function runCollectLogTick(input: RunCollectLogTickInput): Promise<
             if (!name.endsWith(".tmp")) {
                 continue;
             }
+            if (uploadsThisTick >= MAX_UPLOADS_PER_COLLECT_TICK) {
+                break;
+            }
             const status = await uploadTmpBatch({
                 serviceId: input.serviceId,
                 serviceValue: input.serviceValue,
@@ -295,6 +320,7 @@ export async function runCollectLogTick(input: RunCollectLogTickInput): Promise<
             });
             if (status === "uploaded") {
                 result.uploaded += 1;
+                uploadsThisTick += 1;
             } else if (status === "skipped") {
                 result.skipped += 1;
             } else {

package/src/shared/log/spool/file.ts

@@ -1,37 +1,24 @@
-import type { LogEntry } from "../core/log-manager";
-import { computeLogBatchIdempotencyKey } from "../upload/batch-id";
+import { randomBytes } from "node:crypto";
 import type { LogSpoolProcessRole } from "./interface";
 
 /** `role.timestamp.hash.tmp|json` — role is lowercase alphanumeric + hyphen. */
-const BATCH_FILE_PATTERN = /^([a-z][a-z0-9-]*)\.(\d{14})\.([a-f0-9]{8})\.(tmp|json)$/;
+const BATCH_FILE_PATTERN = /^([a-z][a-z0-9-]*)\.(\d{14})\.([a-f0-9]{8})\.(tmp|json|synced)$/;
 
 export function formatLogSpoolBatchTimestamp(ms: number): string {
     const d = new Date(ms);
     const pad = (n: number) => String(n).padStart(2, "0");
     return (
-        `${d.getFullYear()}` +
-        `${pad(d.getMonth() + 1)}` +
-        `${pad(d.getDate())}` +
-        `${pad(d.getHours())}` +
-        `${pad(d.getMinutes())}` +
-        `${pad(d.getSeconds())}`
+        `${d.getUTCFullYear()}` +
+        `${pad(d.getUTCMonth() + 1)}` +
+        `${pad(d.getUTCDate())}` +
+        `${pad(d.getUTCHours())}` +
+        `${pad(d.getUTCMinutes())}` +
+        `${pad(d.getUTCSeconds())}`
     );
 }
 
-export function computeLogSpoolShortHash(input: {
-    serviceValue: string;
-    serviceId: string;
-    processRole: LogSpoolProcessRole;
-    entries: LogEntry[];
-}): string {
-    const processKey = `${input.serviceId}:${input.processRole}`;
-    const idempotencyKey = computeLogBatchIdempotencyKey({
-        service: input.serviceValue,
-        process: processKey,
-        lane: "slow",
-        entries: input.entries,
-    });
-    return idempotencyKey.slice(0, 8);
+export function randomLogSpoolShortId(): string {
+    return randomBytes(4).toString("hex");
 }
 
 export function buildLogSpoolBatchBaseName(input: {
@@ -47,7 +34,7 @@ export function parseLogSpoolBatchFilename(filename: string): {
     processRole: LogSpoolProcessRole;
     timestampMs: number;
     shortHash: string;
-    extension: "tmp" | "json";
+    extension: "tmp" | "json" | "synced";
 } | null {
     const match = BATCH_FILE_PATTERN.exec(filename);
     if (match == null) {
@@ -57,7 +44,7 @@ export function parseLogSpoolBatchFilename(filename: string): {
     const processRole = match[1] as LogSpoolProcessRole;
     const tsRaw = match[2];
     const shortHash = match[3];
-    const extension = match[4] as "tmp" | "json";
+    const extension = match[4] as "tmp" | "json" | "synced";
 
     const year = Number(tsRaw.slice(0, 4));
     const month = Number(tsRaw.slice(4, 6));

package/src/shared/log/spool/writer.ts

@@ -5,7 +5,7 @@ import { estimateEntriesBytes, takeEntriesWithinBytes } from "../upload/flush";
 import { registerLogPersistOffer } from "../upload/hook";
 import { isLogPersistInternalTopic, spoolLogger } from "../upload/logger";
 import { DEFAULT_LOG_SPOOL_CONFIG, resolveLogSpoolConfig } from "./config";
-import { buildLogSpoolBatchBaseName, computeLogSpoolShortHash } from "./file";
+import { buildLogSpoolBatchBaseName, randomLogSpoolShortId } from "./file";
 import type { EnableLogSpoolOptions, LogSpoolBatchFile, LogSpoolProcessRole, LogSpoolWriterStats } from "./interface";
 import { logSpoolProcessDir, resolveLogSpoolRoot } from "./paths";
 
@@ -224,12 +224,7 @@ class LogSpoolWriter {
         spoolRoot: string;
     }): Promise<{ fileName: string; tmpPath: string }> {
         const first = input.entries[0];
-        const shortHash = computeLogSpoolShortHash({
-            serviceValue: input.serviceValue,
-            serviceId: input.serviceId,
-            processRole: input.processRole,
-            entries: input.entries,
-        });
+        const shortHash = randomLogSpoolShortId();
         const baseName = buildLogSpoolBatchBaseName({
             processRole: input.processRole,
             firstEntryTimestamp: first.timestamp,

package/src/shared/log/upload/flush.ts

@@ -1,9 +1,8 @@
-import { isCreateTargetAlreadyExistsError } from "../../../core.api";
-import { postLogListCreate } from "../../../list/list.api";
+import { postListCreate } from "../../../list/list.api";
 import { CategoryList } from "../../../list/list.interface";
 import type { LogEntry } from "../core/log-manager";
 import type { BuildLogListDraftInput, LogListDraft } from "./interface";
-import { LOG_PERSIST_LOADER_KEY } from "./interface";
+import { LOG_BATCH_LIST_VALUE } from "./interface";
 import { persistLogger } from "./logger";
 
 export function estimateEntriesBytes(entries: LogEntry[]): number {
@@ -18,19 +17,18 @@ export function estimateEntriesBytes(entries: LogEntry[]): number {
 }
 
 export function buildLogListDraft(input: BuildLogListDraftInput): LogListDraft {
-    const { service, process, lane, idempotencyKey, entries } = input;
-    // TODO: `lane` is legacy transport metadata — scheduled for removal; callers still pass a fixed value for decode compatibility.
+    const { service, process, lane, entries } = input;
     const first = entries[0];
     const last = entries[entries.length - 1];
 
     return {
-        name: `log-batch:${service}:${process}:${lane}`,
-        value: idempotencyKey,
+        name: service,
+        value: LOG_BATCH_LIST_VALUE,
         category: CategoryList.LIST,
         tagList: ["log", lane, service],
         details: {
             manifestVersion: 0,
-            loaderKey: LOG_PERSIST_LOADER_KEY,
+            loaderKey: LOG_BATCH_LIST_VALUE,
             meta: {
                 service,
                 process,
@@ -40,7 +38,6 @@ export function buildLogListDraft(input: BuildLogListDraftInput): LogListDraft {
                 from: first?.timestamp ?? null,
                 to: last?.timestamp ?? null,
                 flushedAt: Date.now(),
-                idempotencyKey,
             },
             preview: first?.message ?? "",
             items: entries,
@@ -67,36 +64,24 @@ async function withTimeout<T>(promise: Promise<T>, timeoutMs: number, label: str
 }
 
 export async function postLogBatch(draft: LogListDraft, postTimeoutMs: number): Promise<void> {
-    try {
-        const result = await withTimeout(
-            postLogListCreate({
-                name: draft.name,
-                value: draft.value,
-                category: draft.category,
-                details: draft.details,
-            }),
-            postTimeoutMs,
-            "postLogListCreate",
-        );
+    const result = await withTimeout(
+        postListCreate({
+            name: draft.name,
+            value: draft.value,
+            category: draft.category,
+            details: draft.details,
+        }),
+        postTimeoutMs,
+        "postListCreate",
+    );
 
-        if (!result.success) {
-            const message = result.error?.message ?? "postLogListCreate failed";
-            persistLogger.error("post log batch failed", {
-                idempotencyKey: draft.value,
-                name: draft.name,
-                error: message,
-            });
-            throw new Error(message);
-        }
-    } catch (error) {
-        if (isCreateTargetAlreadyExistsError(error)) {
-            persistLogger.error("post log batch idempotent duplicate — treating as success", {
-                idempotencyKey: draft.value,
-                name: draft.name,
-            });
-            return;
-        }
-        throw error;
+    if (!result.success) {
+        const message = result.error?.message ?? "postListCreate failed";
+        persistLogger.error("post log batch failed", {
+            name: draft.name,
+            error: message,
+        });
+        throw new Error(message);
     }
 }
 

package/src/shared/log/upload/interface.ts

@@ -2,17 +2,10 @@ import type { TargetDraft } from "../../../core.interface";
 import type { List } from "../../../list/list.interface";
 import type { LogEntry } from "../core/log-manager";
 
-/**
- * `ListDetails.loaderKey` stamped on every persisted log batch (write + read side).
- * Business type: **LogBatch** (transport flush). Pairs with log-service **LogTrace**
- * (`LogTrace.0`) after rekeying by `traceId`.
- */
-export const LOG_PERSIST_LOADER_KEY = "LogBatch.0";
+/** Discriminator on `List.value` and `details.loaderKey` — query by `value` only, not JSON loaderKey. */
+export const LOG_BATCH_LIST_VALUE = "log-batch";
 
-/** Alias for {@link LOG_PERSIST_LOADER_KEY} — preferred when contrasting with LogTrace. */
-export const LOG_BATCH_LOADER_KEY = LOG_PERSIST_LOADER_KEY;
-
-/** Legacy transport metadata — fixed `"slow"` for spool uploads; required for downstream decode today. */
+/** Legacy transport metadata — fixed `"slow"` for spool uploads. */
 export type LogPersistLane = "fast" | "medium" | "slow";
 
 export interface LogBatchMeta {
@@ -24,14 +17,12 @@ export interface LogBatchMeta {
     from: number | null;
     to: number | null;
     flushedAt: number;
-    idempotencyKey: string;
 }
 
 export interface BuildLogListDraftInput {
     service: string;
     process: string;
     lane: LogPersistLane;
-    idempotencyKey: string;
     entries: LogEntry[];
 }
 

package/src/task/task-node.ts

@@ -1,5 +1,6 @@
 import { isOptimisticLockResponse } from "../core.api";
-import { BaseNodeRuntime, LOG_TOPIC_NODE, type NodeLoopContext } from "../node/node-runtime.base";
+import { BaseNodeRuntime, LOG_TOPIC_NODE, type NodeLoopContext } from "../node/base-node-runtime";
+import { NodeKind } from "../node/node.interface";
 import { createLogger, createScope, type LoggerWithScope, withModule } from "../shared/log";
 import { getErrorMessage, toError } from "../shared/utils/error.utils";
 import { type PatchClaimTaskPayload, patchChangeTaskStatus, patchClaimTask } from "./task.api";
@@ -28,6 +29,10 @@ class TaskNode extends BaseNodeRuntime {
         super("taskNode");
     }
 
+    protected getNodeKind(): NodeKind {
+        return NodeKind.TASK;
+    }
+
     protected async onBeforeRegisterNode(logger: LoggerWithScope): Promise<void> {
         const { availableTaskList, includeRemote } = await TaskManager.registerTasks({ logger });
         this._availableTaskList = availableTaskList;

package/src/trigger/trigger-manager.ts

@@ -1,4 +1,4 @@
-import type { NodeLoopContext } from "../node/node-runtime.base";
+import type { NodeLoopContext } from "../node/base-node-runtime";
 import { createLogger, createScope, withModule } from "../shared/log";
 import { getErrorMessage } from "../shared/utils/error.utils";
 import {

package/src/trigger/trigger-node.ts

@@ -1,4 +1,5 @@
-import { BaseNodeRuntime, LOG_TOPIC_NODE, type NodeLoopContext } from "../node/node-runtime.base";
+import { BaseNodeRuntime, LOG_TOPIC_NODE, type NodeLoopContext } from "../node/base-node-runtime";
+import { NodeKind } from "../node/node.interface";
 import { createLogger, createScope, type LoggerWithScope, LogLevel } from "../shared/log";
 import { LOG_TOPIC_TRIGGER, TRIGGER_LOOP_INTERVAL_MS } from "./trigger.constant";
 import type { TriggerNodeOptions } from "./trigger.interface";
@@ -27,6 +28,10 @@ class TriggerNode extends BaseNodeRuntime {
         this.loopIntervalMs = loopIntervalMs;
     }
 
+    protected getNodeKind(): NodeKind {
+        return NodeKind.TRIGGER;
+    }
+
     protected getLoopIntervalMs(): number {
         return this.loopIntervalMs;
     }