target-supabase-sdk 0.2.3 → 0.2.4

package/src/service/service.interface.ts

@@ -1,9 +1,14 @@
 import type { Target } from "../core.interface";
+import type { NodeStatus } from "../node/node.interface";
 import type { FieldDefinition, ServiceLifecycle } from "./base.interface";
 
 export interface Service extends Target {
     name: string;
-    /** "storage-service" 唯一键 */
+    /**
+     * Logical service key (e.g. `watch-service`). **Not unique** — each `postService` creates
+     * a new instance row. Which instance is **available** is determined by registry slots
+     * (`getTargetSystemRegistry` / `resolveActiveRegistryServiceId`), not by `getService({ value })`.
+     */
     value: string;
     category: CategoryService;
     details: ServiceDetails;
@@ -20,6 +25,36 @@ export interface ServiceDetails {
     /** 依赖的服务 Service keys */
     dependencies: string[];
     lifecycle: ServiceLifecycle;
+    /** Present on runtime instances; omitted on catalog-only rows until guard starts. */
+    runtime?: ServiceRuntime;
+}
+
+/** Per-node snapshot under a running Service — maintained by the service guard. */
+export interface ServiceNodeSnapshot {
+    nodeId: string;
+    status: NodeStatus;
+    lastHeartBeat: number;
+}
+
+/**
+ * Runtime observability for a registered Service instance.
+ * Heartbeat and node rollups are written by the service guard, not the system registry Config.
+ */
+export interface ServiceRuntime {
+    lastHeartBeat: number;
+    nodes: ServiceNodeSnapshot[];
+}
+
+export enum ServiceSlotStatus {
+    EMPTY = "EMPTY",
+    ACTIVE = "ACTIVE",
+}
+
+export interface ServiceSlot {
+    serviceValue: string;
+    /** Bound {@link Service.id} when {@link ServiceSlotStatus.ACTIVE}; null when EMPTY. */
+    serviceId: string | null;
+    status: ServiceSlotStatus;
 }
 
 export interface Api extends Target {

package/src/shared/log/index.ts

@@ -9,9 +9,22 @@ export type {
 } 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)
+export {
+    decodeLogBatch,
+    decodeLogBatchList,
+    flattenLogBatch,
+    flattenLogBatches,
+    isLogBatchList,
+    isLogEntry,
+    parseLogBatchMeta,
+} from "./log-batch";
 export type { LogEntry, LoggerWithScope, LogOptions, LogRestParams, WithScopeOptions } from "./log-manager";
 // log-manager
 export { LogLevel, LogManager, logManager } from "./log-manager";
+export type { LogBatchMeta, LogPersistLane } from "./log-persist.interface";
+export { LOG_BATCH_LOADER_KEY, LOG_PERSIST_LOADER_KEY } from "./log-persist.interface";
 export type {
     CreateScopeInput,
     LoggerResetScopePatch,

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

@@ -0,0 +1,156 @@
+/**
+ * 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`.
+ */
+
+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";
+
+const LANES: ReadonlySet<string> = new Set<LogPersistLane>(["fast", "medium", "slow"]);
+
+/** A decoded log batch: origin metadata plus its raw entries. */
+export interface DecodedLogBatch {
+    /** Source `List` row id. */
+    listId: string;
+    /** `List.created_at` (ISO string). */
+    createdAt: string;
+    meta: LogBatchMeta;
+    entries: LogEntry[];
+}
+
+/** A single {@link LogEntry} enriched with its batch-level origin fields. */
+export interface FlatLogEntry extends LogEntry {
+    service: string;
+    process: string;
+    lane: LogPersistLane;
+    pid: number;
+    /** Idempotency key of the source batch. */
+    batchId: string;
+}
+
+function asRecord(value: unknown): Record<string, unknown> | null {
+    return typeof value === "object" && value !== null ? (value as Record<string, unknown>) : null;
+}
+
+function asFiniteNumber(value: unknown): number | null {
+    return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
+
+function asString(value: unknown): string | null {
+    return typeof value === "string" ? value : null;
+}
+
+/** Parse `ListDetails.meta` (object or legacy JSON string) into typed batch meta, or null. */
+export function parseLogBatchMeta(rawMeta: unknown): LogBatchMeta | null {
+    let source: Record<string, unknown> | null;
+    if (typeof rawMeta === "string") {
+        try {
+            source = asRecord(JSON.parse(rawMeta));
+        } catch {
+            return null;
+        }
+    } else {
+        source = asRecord(rawMeta);
+    }
+    if (source == null) {
+        return 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) {
+        return null;
+    }
+
+    return {
+        service,
+        process: processName,
+        lane: laneRaw as LogPersistLane,
+        pid: asFiniteNumber(source.pid) ?? 0,
+        count: asFiniteNumber(source.count) ?? 0,
+        from: asFiniteNumber(source.from),
+        to: asFiniteNumber(source.to),
+        flushedAt: asFiniteNumber(source.flushedAt) ?? 0,
+        idempotencyKey,
+    };
+}
+
+/** Structural guard for a persisted {@link LogEntry}. */
+export function isLogEntry(value: unknown): value is LogEntry {
+    const record = asRecord(value);
+    return (
+        record != null &&
+        typeof record.timestamp === "number" &&
+        typeof record.level === "string" &&
+        typeof record.message === "string" &&
+        typeof record.topic === "string" &&
+        typeof record.module === "string" &&
+        typeof record.traceId === "string"
+    );
+}
+
+/** Is this List a persisted log batch (by loaderKey)? */
+export function isLogBatchList(list: List): boolean {
+    return list.details?.loaderKey === LOG_PERSIST_LOADER_KEY;
+}
+
+/**
+ * Decode a `List` row into a {@link DecodedLogBatch}. Returns null when the row
+ * is not a log batch or the meta/items are malformed.
+ */
+export function decodeLogBatch(list: List): DecodedLogBatch | null {
+    if (!isLogBatchList(list)) {
+        return null;
+    }
+    const meta = parseLogBatchMeta(list.details?.meta);
+    if (meta == null) {
+        return null;
+    }
+
+    const items = Array.isArray(list.details?.items) ? list.details.items : [];
+    const entries = items.filter(isLogEntry);
+
+    return {
+        listId: list.id,
+        createdAt: list.created_at,
+        meta,
+        entries,
+    };
+}
+
+/** Decode many List rows, dropping any that are not valid log batches. */
+export function decodeLogBatchList(lists: readonly List[]): DecodedLogBatch[] {
+    const decoded: DecodedLogBatch[] = [];
+    for (const list of lists) {
+        const batch = decodeLogBatch(list);
+        if (batch != null) {
+            decoded.push(batch);
+        }
+    }
+    return decoded;
+}
+
+/** Flatten one batch into per-entry rows carrying the batch origin fields. */
+export function flattenLogBatch(batch: DecodedLogBatch): FlatLogEntry[] {
+    return batch.entries.map((entry) => ({
+        ...entry,
+        service: batch.meta.service,
+        process: batch.meta.process,
+        lane: batch.meta.lane,
+        pid: batch.meta.pid,
+        batchId: batch.meta.idempotencyKey,
+    }));
+}
+
+/** Flatten many batches into a single flat entry list. */
+export function flattenLogBatches(batches: readonly DecodedLogBatch[]): FlatLogEntry[] {
+    const flat: FlatLogEntry[] = [];
+    for (const batch of batches) {
+        flat.push(...flattenLogBatch(batch));
+    }
+    return flat;
+}

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

@@ -0,0 +1,107 @@
+import {
+    disableLogPersist,
+    ensureLogPersistFromEnv,
+    getLogPersistStats,
+    logPersistEnabledFromEnv,
+    snapshotLogPersistReady,
+    waitForLogPersistReady,
+} from "./enable-log-persist";
+import type { LogPersistReadySnapshot, LogPersistStats } from "./log-persist.interface";
+
+export interface LogPersistCoordinatorOptions {
+    /** Service identity written into each registry shard (e.g. `log-service`). */
+    service: string;
+    /** Directory holding one JSON shard per process (`main.json`, `guard.json`, …). */
+    registryFilePath: string;
+    /** Process labels main waits for before accepting traffic (must match `LOG_PERSIST_PROCESS` per child). */
+    expectedProcesses: readonly string[];
+    /** Max wait for {@link LogPersistCoordinator.waitForAllProcessesReady} (default 60_000 ms). */
+    readyTimeoutMs?: number;
+}
+
+/** Service-bound facade over env-driven log-persist registration and readiness gates. */
+export interface LogPersistCoordinator {
+    /** Whether `LOG_PERSIST_ENABLED` is active in this process. */
+    isEnabled(): boolean;
+
+    /** Absolute path to the multi-process registry directory configured at construction. */
+    getRegistryFilePath(): string;
+
+    /**
+     * Enable log-persist for this process and write/update its registry shard.
+     * @param process Optional label; defaults to `LOG_PERSIST_PROCESS` env.
+     */
+    registerProcess(process?: string): Promise<boolean>;
+
+    /** Block until every {@link LogPersistCoordinatorOptions.expectedProcesses} entry is registered and fresh. */
+    waitForAllProcessesReady(): Promise<LogPersistReadySnapshot>;
+
+    /** Immediate readiness snapshot without blocking; `null` when log-persist is disabled. */
+    snapshotProcessesReady(): Promise<LogPersistReadySnapshot | null>;
+
+    /** Flush-queue stats for observability; `null` when log-persist is disabled. */
+    getPersistStats(): LogPersistStats | null;
+
+    /** Flush pending logs and tear down log-persist (call from process shutdown hooks). */
+    shutdownLogPersist(): Promise<void>;
+}
+
+/**
+ * Bind service-specific log-persist registry settings (process list, paths, timeouts).
+ * Each L3 service exports one instance from `src/startup/log-persist.ts`.
+ */
+export function createLogPersistCoordinator(options: LogPersistCoordinatorOptions): LogPersistCoordinator {
+    const { service, registryFilePath, expectedProcesses, readyTimeoutMs } = options;
+
+    return {
+        isEnabled() {
+            return logPersistEnabledFromEnv();
+        },
+
+        getRegistryFilePath() {
+            return registryFilePath;
+        },
+
+        registerProcess(process?: string) {
+            return ensureLogPersistFromEnv({
+                process,
+                service,
+                registryFilePath,
+            });
+        },
+
+        waitForAllProcessesReady() {
+            return waitForLogPersistReady({
+                registryFilePath,
+                service,
+                expectedProcesses: [...expectedProcesses],
+                timeoutMs: readyTimeoutMs,
+            });
+        },
+
+        async snapshotProcessesReady() {
+            if (!logPersistEnabledFromEnv()) {
+                return null;
+            }
+            return snapshotLogPersistReady({
+                registryFilePath,
+                service,
+                expectedProcesses: [...expectedProcesses],
+            });
+        },
+
+        getPersistStats() {
+            if (!logPersistEnabledFromEnv()) {
+                return null;
+            }
+            return getLogPersistStats();
+        },
+
+        async shutdownLogPersist() {
+            if (!logPersistEnabledFromEnv()) {
+                return;
+            }
+            await disableLogPersist();
+        },
+    };
+}

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

@@ -2,8 +2,8 @@ import { isCreateTargetAlreadyExistsError } from "../../core.api";
 import { postLogListCreate } from "../../list/list.api";
 import { CategoryList } from "../../list/list.interface";
 import type { LogEntry } from "./log-manager";
-import { LOG_PERSIST_LOADER_KEY } from "./log-persist.config";
 import type { BuildLogListDraftInput, LogListDraft } from "./log-persist.interface";
+import { LOG_PERSIST_LOADER_KEY } from "./log-persist.interface";
 import { persistLogger } from "./log-persist-logger";
 
 export function estimateEntriesBytes(entries: LogEntry[]): number {
@@ -30,7 +30,7 @@ export function buildLogListDraft(input: BuildLogListDraftInput): LogListDraft {
         details: {
             manifestVersion: 0,
             loaderKey: LOG_PERSIST_LOADER_KEY,
-            meta: JSON.stringify({
+            meta: {
                 service,
                 process,
                 pid: globalThis.process.pid,
@@ -40,7 +40,7 @@ export function buildLogListDraft(input: BuildLogListDraftInput): LogListDraft {
                 to: last?.timestamp ?? null,
                 flushedAt: Date.now(),
                 idempotencyKey,
-            }),
+            },
             preview: first?.message ?? "",
             items: entries,
         },

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

@@ -1,8 +1,6 @@
 import { envBool, envInt, envMs } from "../../node/env/env-parsers";
 import type { LogPersistConfig } from "./log-persist.interface";
 
-export const LOG_PERSIST_LOADER_KEY = "LogBatch.0";
-
 export const DEFAULT_LOG_PERSIST_CONFIG: LogPersistConfig = {
     fast: {
         maxBufferEntries: 500,

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

@@ -2,6 +2,16 @@ import type { TargetDraft } from "../../core.interface";
 import type { List } from "../../list/list.interface";
 import type { LogEntry } from "./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";
+
+/** Alias for {@link LOG_PERSIST_LOADER_KEY} — preferred when contrasting with LogTrace. */
+export const LOG_BATCH_LOADER_KEY = LOG_PERSIST_LOADER_KEY;
+
 /** Persistence lane — maps to List tagList and flush policy. */
 export type LogPersistLane = "fast" | "medium" | "slow";
 

package/src/shared/utils/config-path.utils.ts

@@ -102,3 +102,38 @@ export async function importJsConfigModule(configPath: string): Promise<unknown>
     const mod = await import(toFileImportHref(configPath));
     return mod.default ?? mod;
 }
+
+export interface ConfigSchema<T> {
+    safeParse(input: unknown): { success: true; data: T } | { success: false; error: { message: string } };
+}
+
+export interface LoadCachedJsConfigOptions<T> {
+    path: string;
+    schema: ConfigSchema<T>;
+    force?: boolean;
+}
+
+const jsConfigCache = new Map<string, { mtimeMs: number; data: unknown }>();
+
+/**
+ * Import a JS config module, validate with a schema, cache by file mtime.
+ * For hot-reload, pass `{ force: true }` or rely on mtime change.
+ */
+export async function loadCachedJsConfigModule<T>(options: LoadCachedJsConfigOptions<T>): Promise<T> {
+    const { stat } = await import("node:fs/promises");
+    const { path, schema, force } = options;
+    const fileStat = await stat(path);
+    const cached = jsConfigCache.get(path);
+    if (!force && cached != null && cached.mtimeMs === fileStat.mtimeMs) {
+        return cached.data as T;
+    }
+
+    const raw = await importJsConfigModule(path);
+    const parsed = schema.safeParse(raw);
+    if (!parsed.success) {
+        throw new Error(`Invalid config ${path}: ${parsed.error.message}`);
+    }
+
+    jsConfigCache.set(path, { mtimeMs: fileStat.mtimeMs, data: parsed.data });
+    return parsed.data;
+}

package/src/shared/utils/get-value-at-path.ts

@@ -0,0 +1,17 @@
+/** Read a dotted path (e.g. `data.items`) from a parsed JSON value. */
+export function getValueAtPath(value: unknown, path: string | null | undefined): unknown {
+    if (path == null || path.trim() === "") {
+        return value;
+    }
+    let current: unknown = value;
+    for (const segment of path.split(".")) {
+        if (segment === "") {
+            continue;
+        }
+        if (current == null || typeof current !== "object") {
+            return undefined;
+        }
+        current = (current as Record<string, unknown>)[segment];
+    }
+    return current;
+}

package/src/task/index.ts

@@ -35,6 +35,8 @@ export type {
 export { TaskManager } from "./task-manager";
 export type { PostTaskPayload } from "./task-post.api";
 export { postTask, postTaskSchema } from "./task-post.api";
+export type { PostTaskWithRetryOptions, PostTaskWithRetryResult } from "./task-post-retry.api";
+export { POST_TASK_DEFAULT_MAX_ATTEMPTS, postTaskWithRetry } from "./task-post-retry.api";
 export { postTaskWithValidation } from "./task-post-validated.api";
 export type {
     TaskRepoValidationFailureReason,

package/src/task/task-manager.ts

@@ -2,12 +2,13 @@ import { getScanRemoteRepoValues } from "../repo/repo.api";
 import { TASK_REPO_USAGE } from "../repo/repo.interface";
 import type { LoggerWithScope } from "../shared/log";
 import type { ResultCode, Task } from "./task.interface";
-import type { ExecutableTaskFn, TaskFn } from "./task-repo-context";
+import type { ExecutableTaskFn, TaskExecutionContext, TaskFn } from "./task-repo-context";
 
 export type {
     BootstrapLocalTasksResult,
     BootstrapLocalTasksStatus,
     ExecutableTaskFn,
+    TaskExecutionContext,
     TaskFn,
     TaskLocalPackageConfig,
     TaskRepoContext,
@@ -169,8 +170,8 @@ async function registerTasks({
 }
 
 /** 将 taskFn 与 params 闭包绑定，供 TaskNode 无参调用 `await taskFn()` */
-function bindTaskFn(taskFn: TaskFn, taskParams: unknown): ExecutableTaskFn {
-    const run = async () => taskFn(taskParams);
+function bindTaskFn(taskFn: TaskFn, taskParams: unknown, ctx: TaskExecutionContext): ExecutableTaskFn {
+    const run = async () => taskFn(taskParams, ctx);
     return Object.assign(run, {
         displayName: taskFn.displayName,
         taskTypeKey: taskFn.taskTypeKey,
@@ -272,7 +273,12 @@ const prepareTask = async ({
         },
     });
 
-    const boundTaskFn = bindTaskFn(repoContext.taskFn, taskParams);
+    const boundTaskFn = bindTaskFn(repoContext.taskFn, taskParams, {
+        taskId,
+        taskName,
+        taskTypeKey,
+        traceId: details.traceId ?? taskId,
+    });
     logger.debug("任務準備完成", {
         topic: LOG_TOPIC_TASK,
         data: {

package/src/task/task-post-retry.api.ts

@@ -0,0 +1,61 @@
+import type { LoggerWithScope } from "../shared/log";
+import type { Task } from "./task.interface";
+import { type PostTaskPayload, postTask } from "./task-post.api";
+
+export const POST_TASK_DEFAULT_MAX_ATTEMPTS = 3;
+
+export interface PostTaskWithRetryOptions {
+    logger: LoggerWithScope;
+    topic: string;
+    traceId: string;
+    itemLabel: string;
+    context?: Record<string, unknown>;
+    maxAttempts?: number;
+}
+
+export type PostTaskWithRetryResult = { ok: true; task: Task } | { ok: false };
+
+/**
+ * Retry wrapper for {@link postTask} — for schedule runners posting tasks over flaky network.
+ * Logs warn on intermediate failures and critical when all attempts fail.
+ */
+export async function postTaskWithRetry(
+    payload: PostTaskPayload,
+    options: PostTaskWithRetryOptions,
+): Promise<PostTaskWithRetryResult> {
+    const maxAttempts = options.maxAttempts ?? POST_TASK_DEFAULT_MAX_ATTEMPTS;
+    let lastError = "unknown error";
+
+    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+        const { data: task, error } = await postTask(payload);
+        if (error == null && task != null) {
+            return { ok: true, task };
+        }
+        lastError = error?.message ?? lastError;
+        if (attempt < maxAttempts) {
+            options.logger.warn("postTask failed, retrying", {
+                topic: options.topic,
+                data: {
+                    ...options.context,
+                    traceId: options.traceId,
+                    itemLabel: options.itemLabel,
+                    attempt,
+                    maxAttempts,
+                    error: lastError,
+                },
+            });
+        }
+    }
+
+    options.logger.critical("postTask failed after retries — skip item this cycle", {
+        topic: options.topic,
+        data: {
+            ...options.context,
+            traceId: options.traceId,
+            itemLabel: options.itemLabel,
+            maxAttempts,
+            error: lastError,
+        },
+    });
+    return { ok: false };
+}

package/src/task/task-repo-context.ts

@@ -4,10 +4,17 @@ export interface TaskRunResult {
     extra: unknown;
 }
 
+export interface TaskExecutionContext {
+    taskId: string;
+    taskName: string;
+    taskTypeKey: string;
+    traceId: string;
+}
+
 export interface TaskFn {
     displayName: string;
     taskTypeKey: string;
-    (taskParams: unknown): Promise<TaskRunResult>;
+    (taskParams: unknown, ctx: TaskExecutionContext): Promise<TaskRunResult>;
 }
 
 /** Params already bound — used by node executor after prepareTask */

package/src/trigger/trigger-manager.ts

@@ -144,9 +144,11 @@ export const TriggerManager = {
         return [...runnerRegistry.keys()];
     },
 
-    getRunnersBelowLoopInterval(): Array<{ key: string; intervalMs: number }> {
+    getRunnersBelowLoopInterval(
+        loopIntervalMs: number = TRIGGER_LOOP_INTERVAL_MS,
+    ): Array<{ key: string; intervalMs: number }> {
         return [...runnerRegistry.values()]
-            .filter((runner) => runner.intervalMs < TRIGGER_LOOP_INTERVAL_MS)
+            .filter((runner) => runner.intervalMs < loopIntervalMs)
             .map((runner) => ({ key: runner.key, intervalMs: runner.intervalMs }));
     },
 

package/src/trigger/trigger-node.ts

@@ -15,14 +15,20 @@ import { TriggerManager } from "./trigger-manager";
  */
 class TriggerNode extends BaseNodeRuntime {
     private readonly requireRunners: boolean;
+    private readonly loopIntervalMs: number;
 
     constructor(options?: TriggerNodeOptions) {
-        super("triggerNode");
+        super("triggerNode", { beforeProcessExit: options?.beforeProcessExit });
         this.requireRunners = options?.requireRunners ?? false;
+        const loopIntervalMs = options?.loopIntervalMs ?? TRIGGER_LOOP_INTERVAL_MS;
+        if (!Number.isFinite(loopIntervalMs) || loopIntervalMs < 1) {
+            throw new Error(`[TriggerNode] loopIntervalMs must be a positive number, got ${loopIntervalMs}`);
+        }
+        this.loopIntervalMs = loopIntervalMs;
     }
 
     protected getLoopIntervalMs(): number {
-        return TRIGGER_LOOP_INTERVAL_MS;
+        return this.loopIntervalMs;
     }
 
     protected loopLoggerMinLevel(): LogLevel {
@@ -43,13 +49,13 @@ class TriggerNode extends BaseNodeRuntime {
             return;
         }
 
-        for (const { key, intervalMs } of TriggerManager.getRunnersBelowLoopInterval()) {
+        for (const { key, intervalMs } of TriggerManager.getRunnersBelowLoopInterval(this.loopIntervalMs)) {
             logger.warn("Runner interval 小於主循環 tick 間隔，實際觸發精度受限", {
                 topic: LOG_TOPIC_TRIGGER,
                 data: {
                     runnerKey: key,
                     intervalMs,
-                    loopIntervalMs: TRIGGER_LOOP_INTERVAL_MS,
+                    loopIntervalMs: this.loopIntervalMs,
                 },
             });
         }

package/src/trigger/trigger.constant.ts

@@ -1,6 +1,6 @@
 export const LOG_TOPIC_TRIGGER = "trigger";
 
-/** Fixed main-loop interval for {@link TriggerNode} (ms). */
+/** Default main-loop interval for {@link TriggerNode} when `loopIntervalMs` is omitted (ms). */
 export const TRIGGER_LOOP_INTERVAL_MS = 60_000;
 
 /** Default extra retries after first failure within one runner tick. */

package/src/trigger/trigger.interface.ts

@@ -97,4 +97,14 @@ export interface TriggerNodeOptions {
      * Default `false` (warn and idle loop).
      */
     requireRunners?: boolean;
+    /**
+     * Main loop tick interval (ms). Runners are evaluated each tick; effective runner
+     * precision is bounded by this value. Default {@link TRIGGER_LOOP_INTERVAL_MS} (60s).
+     */
+    loopIntervalMs?: number;
+    /**
+     * Called after node logout, immediately before `process.exit`.
+     * Typical use: {@link unregisterServiceAtShutdown} for single-process L3 services.
+     */
+    beforeProcessExit?: () => void | Promise<void>;
 }