target-supabase-sdk 0.1.9 → 0.2.1

package/src/task/task.api.ts

@@ -1,8 +1,18 @@
-import { createTarget, getPossibleTarget, QueryFilter, updateTargetDetails, validateWithSchema, isOptimisticLockError, OPTIMISTIC_LOCK_FAILED_MESSAGE } from "../core.api";
-import { generateResponse, type SupabaseResponse } from "../core.interface";
-import { createApiLogger, type LoggerWithContext } from "../shared/log/log-manager";
 import { z } from "zod";
-import { CategoryTask, ResultCode, Task, TaskDetails, TaskStatus, TaskStatusAction } from "./task.interface";
+import {
+    getTargetList,
+    isOptimisticLockError,
+    OPTIMISTIC_LOCK_ERROR_CODE,
+    OPTIMISTIC_LOCK_FAILED_MESSAGE,
+    type QueryFilter,
+    updateTargetDetails,
+    validateWithSchema,
+} from "../core.api";
+import { generateResponse, type SupabaseResponse } from "../core.interface";
+import { createLogger, type LoggerWithScope } from "../shared/log";
+import { getErrorMessage } from "../shared/utils/error.utils";
+import { LOG_TOPIC_TASK } from "./task.constant";
+import { CategoryTask, ResultCode, type Task, type TaskDetails, TaskStatus, TaskStatusAction } from "./task.interface";
 
 const TASK_STATUS_FIELD = "details->>status" as const;
 const TASK_NODE_ID_FIELD = "details->>nodeId" as const;
@@ -44,8 +54,9 @@ const TASK_NODE_ID_FIELD = "details->>nodeId" as const;
 
 const taskIdSchema = z.string().trim().min(1);
 const nodeIdSchema = z.string().trim().min(1);
-/** Optional — orchestrator (e.g. NodeManager loop) passes its trace to correlate logs. */
+/** Optional — orchestrator (e.g. TaskNode loop) passes its trace to correlate logs. */
 const traceIdSchema = z.string().trim().min(1).optional();
+const _traceParentIdSchema = z.string().trim().min(1).nullable().optional();
 
 const patchChangeTaskStatusBaseSchema = {
     id: taskIdSchema,
@@ -107,25 +118,6 @@ export const patchClaimTaskSchema = z.object({
 
 export type PatchClaimTaskPayload = z.infer<typeof patchClaimTaskSchema>;
 
-/** Initial status for a new task — OPEN (draft) or TODO (claimable by workers). */
-const postTaskInitialStatusSchema = z
-    .union([z.literal(TaskStatus.OPEN), z.literal(TaskStatus.TODO)])
-    .optional()
-    .default(TaskStatus.TODO);
-
-export const postTaskSchema = z.object({
-    name: z.string().trim().min(1),
-    /** Task type key — matches `task.value`, {@link patchClaimTask}, {@link Repo.value}, and local Repo registry. */
-    value: z.string().trim().min(1),
-    params: z.unknown(),
-    taskStatus: postTaskInitialStatusSchema,
-    tagList: z.array(z.string()).optional().default([]),
-    extra: z.string().optional(),
-    traceId: traceIdSchema,
-});
-
-export type PostTaskPayload = z.infer<typeof postTaskSchema>;
-
 // ─── Optimistic lock helpers ─────────────────────────────────────────────────
 
 function lockOnStatus(...allowed: TaskStatus[]): QueryFilter[] {
@@ -178,20 +170,20 @@ async function transitionTask({
 }
 
 function logTaskTransition(
-    logger: LoggerWithContext,
+    logger: LoggerWithScope,
     action: TaskStatusAction | "patchTaskProgress" | "patchClaimTask",
     task: Task,
-    context?: Record<string, unknown>
+    data?: Record<string, unknown>,
 ): void {
-    logger.info("任务状态迁移成功", {
-        topic: "task",
-        context: {
+    logger.debug("任務狀態遷移成功", {
+        topic: LOG_TOPIC_TASK,
+        data: {
             action,
             taskId: task.id,
             taskValue: task.value,
             status: task.details.status,
             nodeId: task.details.nodeId,
-            ...context,
+            ...data,
         },
     });
 }
@@ -222,9 +214,9 @@ async function claimTaskById({
 
 export const patchChangeTaskStatus = validateWithSchema(
     patchChangeTaskStatusSchema,
-    "patchChangeTaskStatusSchema"
+    "patchChangeTaskStatusSchema",
 )(async (params) => {
-    const logger = createApiLogger("patchChangeTaskStatus", { traceId: params.traceId });
+    const logger = createLogger({ module: "patchChangeTaskStatus", traceId: params.traceId });
     const { id, action, extra } = params;
     const updateExtraFn = extra == null ? undefined : () => extra;
 
@@ -314,7 +306,9 @@ export const patchChangeTaskStatus = validateWithSchema(
         }
         default: {
             const _exhaustive: never = action;
-            throw new Error(`[patchChangeTaskStatus] Unknown action: ${_exhaustive}`);
+            const message = `[patchChangeTaskStatus] Unknown action: ${String(_exhaustive)}`;
+            logger.error(message, { topic: "task", data: { action: String(_exhaustive) } });
+            return generateResponse.error(message);
         }
     }
 });
@@ -324,9 +318,9 @@ export const patchChangeTaskStatus = validateWithSchema(
 /** Update progress on a DOING task; only the owning node may write (see `lockOnDoingOwner`). */
 export const patchTaskProgress = validateWithSchema(
     patchTaskProgressSchema,
-    "patchTaskProgressSchema"
+    "patchTaskProgressSchema",
 )(async ({ id, progress, nodeId, traceId }) => {
-    const logger = createApiLogger("patchTaskProgress", { traceId, nodeId });
+    const logger = createLogger({ module: "patchTaskProgress", traceId, labels: { nodeId } });
     const data = await transitionTask({
         id,
         optimisticLockFilterList: lockOnDoingOwner(nodeId),
@@ -344,86 +338,68 @@ export const patchTaskProgress = validateWithSchema(
 /**
  * Discover and claim one TODO task for this node.
  *
- * Flow: filter by `availableTaskList` → {@link claimTaskById} (same as `action: CLAIM`).
+ * Flow: oldest TODO in `availableTaskList` (FIFO by `created_at`) → {@link claimTaskById}.
  * Equivalent to `patchChangeTaskStatus({ id, action: CLAIM, nodeId })` when `id` is already known.
  *
  * Returns `data: null` when no TODO task matches.
- * Optimistic lock conflicts return `{ error }` with `code: "OPTIMISTIC_LOCK"` (not thrown).
+ * Optimistic lock conflicts return `{ error, code: OPTIMISTIC_LOCK_ERROR_CODE }` (not thrown).
  */
 export const patchClaimTask = validateWithSchema(
     patchClaimTaskSchema,
-    "patchClaimTaskSchema"
+    "patchClaimTaskSchema",
 )(async ({ nodeId, availableTaskList, traceId }): Promise<SupabaseResponse<Task | null>> => {
-    const logger = createApiLogger("patchClaimTask", { traceId, nodeId });
+    const logger = createLogger({ module: "patchClaimTask", traceId, labels: { nodeId } });
 
+    let todoTask: Task;
     try {
-        const { data: possibleTask } = await getPossibleTarget({
+        const { data: taskCandidates } = await getTargetList<Task>({
+            category: CategoryTask.TASK,
             filterList: [
-                { field: "category", operator: "eq", value: CategoryTask.TASK },
                 { field: TASK_STATUS_FIELD, operator: "eq", value: TaskStatus.TODO },
                 { field: "value", operator: "in", value: availableTaskList },
             ],
+            limit: 1,
+            orderBy: { field: "created_at", ascending: true },
         });
-
+        const possibleTask = taskCandidates?.[0] ?? null;
         if (possibleTask == null) {
             return generateResponse.success(null);
         }
+        todoTask = possibleTask;
+    } catch (error) {
+        const message = getErrorMessage(error);
+        logger.error("獲取 TODO 任務失敗", { topic: LOG_TOPIC_TASK, data: { error: message, availableTaskList } });
+        return generateResponse.error(message) as SupabaseResponse<Task | null>;
+    }
 
-        const todoTask = possibleTask as Task;
+    const taskLogger = createLogger({
+        module: "patchClaimTask",
+        traceId,
+        traceParentId: todoTask.details.traceId,
+        labels: { nodeId },
+    });
+
+    try {
         const data = await claimTaskById({ taskId: todoTask.id, nodeId });
-        logTaskTransition(logger, "patchClaimTask", data);
+        logTaskTransition(taskLogger, "patchClaimTask", data);
         return generateResponse.success(data);
     } catch (error) {
         if (isOptimisticLockError(error)) {
-            logger.debug("認領競爭失敗，本輪無可認領任務", { topic: "task" });
-            return generateResponse.error(OPTIMISTIC_LOCK_FAILED_MESSAGE, undefined, "OPTIMISTIC_LOCK") as SupabaseResponse<Task | null>;
+            taskLogger.debug("認領競爭失敗，任務已被其他節點認領", {
+                topic: LOG_TOPIC_TASK,
+                data: { taskId: todoTask.id, taskTypeKey: todoTask.value },
+            });
+            return generateResponse.error(
+                OPTIMISTIC_LOCK_FAILED_MESSAGE,
+                undefined,
+                OPTIMISTIC_LOCK_ERROR_CODE,
+            ) as SupabaseResponse<Task | null>;
         }
-        const message = error instanceof Error ? error.message : String(error);
-        logger.error("認領任務失敗", { topic: "task", context: { error: message } });
+        const message = getErrorMessage(error);
+        taskLogger.error("認領任務失敗", {
+            topic: LOG_TOPIC_TASK,
+            data: { error: message, taskId: todoTask.id, taskTypeKey: todoTask.value },
+        });
         return generateResponse.error(message) as SupabaseResponse<Task | null>;
     }
 });
-
-// ─── postTask ────────────────────────────────────────────────────────────────
-
-/**
- * Create a task row (scheduler / admin).
- *
- * `taskStatus` defaults to **TODO** (worker-claimable). Pass **OPEN** for draft tasks
- * that require {@link patchChangeTaskStatus} `publish` before workers can claim.
- */
-export const postTask = validateWithSchema(
-    postTaskSchema,
-    "postTaskSchema"
-)(async ({ name, value, params, taskStatus, tagList, extra, traceId }) => {
-    const logger = createApiLogger("postTask", { traceId });
-
-    const result = await createTarget<Task, PostTaskPayload>({
-        payload: { name, value, params, taskStatus, tagList, extra, traceId },
-        createFn: () => ({
-            name,
-            value,
-            category: CategoryTask.TASK,
-            tagList,
-            extra,
-            details: {
-                manifestVersion: 0,
-                status: taskStatus,
-                params,
-                progress: 0,
-                nodeId: null,
-            },
-        }),
-    });
-
-    logger.info("任務已創建", {
-        topic: "task",
-        context: {
-            taskId: result.data?.id,
-            taskTypeKey: value,
-            status: taskStatus,
-        },
-    });
-
-    return result;
-});

package/src/task/task.constant.ts

@@ -0,0 +1,4 @@
+/** Log topic for task domain (`topic` field on structured logs). */
+export const LOG_TOPIC_TASK = "task";
+
+export const CRITICAL_UNKNOWN_TASK_TRACE_ID = "CRITICAL_UNKNOWN_TASK_TRACE_ID";

package/src/task/task.interface.ts

@@ -1,4 +1,4 @@
-import { Target } from "../core.interface";
+import type { Target } from "../core.interface";
 
 export enum CategoryTask {
     TASK = "task",
@@ -53,16 +53,15 @@ export interface TaskDetails {
     /** [0,100] */
     progress: number;
     nodeId: null | string;
+    /** Task lifecycle correlation id (written at postTask). */
+    traceId?: string;
     result?: {
         cost: number;
         code: ResultCode;
         errorMessage?: string;
         data?: unknown;
-    }
-};
-
-// TODO loop condition combination
-export interface TaskFlow extends Target {
-
+    };
 }
 
+// TODO loop condition combination
+export interface TaskFlow extends Target {}

package/src/trigger/trigger-manager.ts

@@ -0,0 +1,287 @@
+import type { NodeLoopContext } from "../node/node-runtime.base";
+import { createLogger, createScope, withModule } from "../shared/log";
+import { getErrorMessage } from "../shared/utils/error.utils";
+import {
+    LOG_TOPIC_TRIGGER,
+    TRIGGER_LOOP_INTERVAL_MS,
+    TRIGGER_RUNNER_DEFAULT_RETRY_COUNT,
+    TRIGGER_RUNNER_DEFAULT_RETRY_DELAY_MS,
+} from "./trigger.constant";
+import type { RegisterTriggerRunnerOptions, TriggerRunnerContext, TriggerRunnerFn } from "./trigger.interface";
+
+export type { RegisterTriggerRunnerOptions, TriggerRunnerContext, TriggerRunnerFn } from "./trigger.interface";
+
+interface TriggerRunnerState {
+    key: string;
+    intervalMs: number;
+    fn: TriggerRunnerFn;
+    retryCount: number;
+    retryDelayMs: number;
+    timeoutMs: number | undefined;
+    nextRunAt: number;
+    running: boolean;
+}
+
+const runnerRegistry = new Map<string, TriggerRunnerState>();
+let registrationClosed = false;
+
+function normalizeRunnerKey(key: string): string {
+    const normalized = key.trim();
+    if (normalized.length === 0) {
+        throw new Error("[TriggerManager] key must be a non-empty string");
+    }
+    return normalized;
+}
+
+function tryNormalizeRunnerKey(key: string): string | null {
+    const normalized = key.trim();
+    return normalized.length > 0 ? normalized : null;
+}
+
+function validateRunnerOptions(options: RegisterTriggerRunnerOptions): void {
+    if (!Number.isFinite(options.intervalMs) || options.intervalMs < 1) {
+        throw new Error(`[TriggerManager] intervalMs must be a positive number, got ${options.intervalMs}`);
+    }
+    const retryCount = options.retryCount ?? TRIGGER_RUNNER_DEFAULT_RETRY_COUNT;
+    if (!Number.isInteger(retryCount) || retryCount < 0) {
+        throw new Error(`[TriggerManager] retryCount must be a non-negative integer, got ${retryCount}`);
+    }
+    const initialDelayMs = options.initialDelayMs ?? 0;
+    if (!Number.isFinite(initialDelayMs) || initialDelayMs < 0) {
+        throw new Error(`[TriggerManager] initialDelayMs must be a non-negative number, got ${initialDelayMs}`);
+    }
+    const retryDelayMs = options.retryDelayMs ?? TRIGGER_RUNNER_DEFAULT_RETRY_DELAY_MS;
+    if (!Number.isFinite(retryDelayMs) || retryDelayMs < 0) {
+        throw new Error(`[TriggerManager] retryDelayMs must be a non-negative number, got ${retryDelayMs}`);
+    }
+    if (options.timeoutMs != null) {
+        if (!Number.isFinite(options.timeoutMs) || options.timeoutMs < 1) {
+            throw new Error(`[TriggerManager] timeoutMs must be a positive number when set, got ${options.timeoutMs}`);
+        }
+    }
+}
+
+function delay(ms: number): Promise<void> {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+async function invokeRunnerFn(
+    fn: TriggerRunnerFn,
+    ctx: TriggerRunnerContext,
+    timeoutMs: number | undefined,
+): Promise<void> {
+    if (timeoutMs == null) {
+        await fn(ctx);
+        return;
+    }
+
+    let timeoutHandle: ReturnType<typeof setTimeout> | undefined;
+    const timeoutPromise = new Promise<never>((_, reject) => {
+        timeoutHandle = setTimeout(() => {
+            reject(new Error(`Runner timed out after ${timeoutMs}ms`));
+        }, timeoutMs);
+    });
+
+    try {
+        await Promise.race([Promise.resolve(fn(ctx)), timeoutPromise]);
+    } finally {
+        if (timeoutHandle != null) {
+            clearTimeout(timeoutHandle);
+        }
+    }
+}
+
+/** In-process registry and tick loop for {@link TriggerNode}. */
+export const TriggerManager = {
+    registerRunner(options: RegisterTriggerRunnerOptions): void {
+        if (registrationClosed) {
+            throw new Error("[TriggerManager] Registration closed — call registerRunner before TriggerNode.start()");
+        }
+
+        const key = normalizeRunnerKey(options.key);
+        validateRunnerOptions(options);
+        if (typeof options.fn !== "function") {
+            throw new Error(`[TriggerManager] fn must be a function (runner key: ${key})`);
+        }
+        if (runnerRegistry.has(key)) {
+            throw new Error(`[TriggerManager] Duplicate runner key: ${key}`);
+        }
+
+        const now = Date.now();
+        runnerRegistry.set(key, {
+            key,
+            intervalMs: options.intervalMs,
+            fn: options.fn,
+            retryCount: options.retryCount ?? TRIGGER_RUNNER_DEFAULT_RETRY_COUNT,
+            retryDelayMs: options.retryDelayMs ?? TRIGGER_RUNNER_DEFAULT_RETRY_DELAY_MS,
+            timeoutMs: options.timeoutMs,
+            nextRunAt: now + (options.initialDelayMs ?? 0),
+            running: false,
+        });
+    },
+
+    hasRunner(key: string): boolean {
+        const normalized = tryNormalizeRunnerKey(key);
+        return normalized != null && runnerRegistry.has(normalized);
+    },
+
+    unregisterRunner(key: string): boolean {
+        const normalized = tryNormalizeRunnerKey(key);
+        if (normalized == null) {
+            return false;
+        }
+        const runner = runnerRegistry.get(normalized);
+        if (runner == null) {
+            return false;
+        }
+        if (runner.running) {
+            throw new Error(`[TriggerManager] Cannot unregister running runner: ${normalized}`);
+        }
+        return runnerRegistry.delete(normalized);
+    },
+
+    getRunnerKeys(): string[] {
+        return [...runnerRegistry.keys()];
+    },
+
+    getRunnersBelowLoopInterval(): Array<{ key: string; intervalMs: number }> {
+        return [...runnerRegistry.values()]
+            .filter((runner) => runner.intervalMs < TRIGGER_LOOP_INTERVAL_MS)
+            .map((runner) => ({ key: runner.key, intervalMs: runner.intervalMs }));
+    },
+
+    /** Called by TriggerNode during bootstrap — blocks further registerRunner calls. */
+    closeRegistration(): void {
+        registrationClosed = true;
+    },
+
+    /** Re-open registration (tests only). */
+    _resetRegistrationForTests(): void {
+        registrationClosed = false;
+    },
+
+    /**
+     * Remove all runners. Throws if any runner is still executing.
+     * Wait for in-flight ticks to finish before calling in tests.
+     */
+    clearRunners(): void {
+        for (const runner of runnerRegistry.values()) {
+            if (runner.running) {
+                throw new Error(`[TriggerManager] Cannot clearRunners while runner is running: ${runner.key}`);
+            }
+        }
+        runnerRegistry.clear();
+        registrationClosed = false;
+    },
+
+    async tick(ctx: NodeLoopContext): Promise<void> {
+        const { loopTraceId, nodeId } = ctx;
+        const loopScope = createScope({ module: "tickRunners", traceId: loopTraceId, labels: { nodeId } });
+        const logger = createLogger({ scope: loopScope });
+
+        const now = Date.now();
+        const runners = [...runnerRegistry.values()];
+        if (runners.length === 0) {
+            logger.debug("無 runner 可調度", { topic: LOG_TOPIC_TRIGGER });
+            return;
+        }
+
+        // Overlap: if fn is still running when due, skip that tick (no catch-up / backlog).
+        // Safe while intervals are large; missed ticks increase if fn duration exceeds intervalMs.
+        const dueRunners = runners.filter((runner) => !runner.running && now >= runner.nextRunAt);
+        if (dueRunners.length === 0) {
+            logger.debug("本輪無到期 runner", { topic: LOG_TOPIC_TRIGGER });
+            return;
+        }
+
+        logger.debug("調度到期 runner", {
+            topic: LOG_TOPIC_TRIGGER,
+            data: { due: dueRunners.map((r) => r.key) },
+        });
+
+        const results = await Promise.all(dueRunners.map((runner) => runRunner(ctx, runner)));
+        const executed = results.filter(Boolean).length;
+        if (executed > 0) {
+            logger.info("Runner 調度完成", {
+                topic: LOG_TOPIC_TRIGGER,
+                data: { due: dueRunners.length, executed },
+            });
+        } else {
+            logger.warn("本輪到期 runner 均未成功", {
+                topic: LOG_TOPIC_TRIGGER,
+                data: {
+                    due: dueRunners.length,
+                    runnerKeys: dueRunners.map((r) => r.key),
+                },
+            });
+        }
+    },
+};
+
+async function runRunner(ctx: NodeLoopContext, runner: TriggerRunnerState): Promise<boolean> {
+    const { loopTraceId, nodeId } = ctx;
+    if (runner.running) {
+        return false;
+    }
+
+    runner.running = true;
+    const runnerLogger = createLogger({
+        scope: withModule(
+            createScope({ module: "runRunner", traceId: loopTraceId, labels: { nodeId, runnerKey: runner.key } }),
+            runner.key,
+        ),
+    });
+
+    const maxAttempts = 1 + runner.retryCount;
+    let succeeded = false;
+
+    try {
+        for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+            try {
+                runnerLogger.info("Runner 觸發", {
+                    topic: LOG_TOPIC_TRIGGER,
+                    data: { attempt, maxAttempts },
+                });
+                await invokeRunnerFn(
+                    runner.fn,
+                    {
+                        loopTraceId,
+                        nodeId,
+                        runnerKey: runner.key,
+                        logger: runnerLogger,
+                        attempt,
+                        maxAttempts,
+                    },
+                    runner.timeoutMs,
+                );
+                runnerLogger.success("Runner 完成", {
+                    topic: LOG_TOPIC_TRIGGER,
+                    data: { attempt, maxAttempts },
+                });
+                succeeded = true;
+                break;
+            } catch (error) {
+                const message = getErrorMessage(error);
+                if (attempt < maxAttempts) {
+                    runnerLogger.warn("Runner 失敗，準備重試", {
+                        topic: LOG_TOPIC_TRIGGER,
+                        data: { attempt, maxAttempts, error: message },
+                    });
+                    if (runner.retryDelayMs > 0) {
+                        await delay(runner.retryDelayMs);
+                    }
+                } else {
+                    runnerLogger.error("Runner 重試用盡仍失敗", {
+                        topic: LOG_TOPIC_TRIGGER,
+                        data: { attempt, maxAttempts, error: message },
+                    });
+                }
+            }
+        }
+    } finally {
+        runner.running = false;
+        runner.nextRunAt = Date.now() + runner.intervalMs;
+    }
+
+    return succeeded;
+}

package/src/trigger/trigger-node.ts

@@ -0,0 +1,80 @@
+import { BaseNodeRuntime, LOG_TOPIC_NODE, type NodeLoopContext } from "../node/node-runtime.base";
+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";
+import { TriggerManager } from "./trigger-manager";
+
+/**
+ * Local interval scheduler node.
+ * Main loop: commands → heartbeat → {@link TriggerManager.tick}.
+ *
+ * Register runners via {@link TriggerManager.registerRunner} before {@link start}.
+ * Does not scan Supabase trigger rows — see `trigger.api.ts` for remote admin APIs.
+ *
+ * Deploy **one** TriggerNode per logical scheduler — multiple processes duplicate runner work.
+ */
+class TriggerNode extends BaseNodeRuntime {
+    private readonly requireRunners: boolean;
+
+    constructor(options?: TriggerNodeOptions) {
+        super("triggerNode");
+        this.requireRunners = options?.requireRunners ?? false;
+    }
+
+    protected getLoopIntervalMs(): number {
+        return TRIGGER_LOOP_INTERVAL_MS;
+    }
+
+    protected loopLoggerMinLevel(): LogLevel {
+        return LogLevel.WARN;
+    }
+
+    protected async onBeforeRegisterNode(logger: LoggerWithScope): Promise<void> {
+        TriggerManager.closeRegistration();
+
+        const runnerKeys = TriggerManager.getRunnerKeys();
+        if (runnerKeys.length === 0) {
+            if (this.requireRunners) {
+                throw new Error("[TriggerNode] requireRunners is true but no runners are registered");
+            }
+            logger.warn("未注册任何 Trigger runner，主循環將空轉", {
+                topic: LOG_TOPIC_TRIGGER,
+            });
+            return;
+        }
+
+        for (const { key, intervalMs } of TriggerManager.getRunnersBelowLoopInterval()) {
+            logger.warn("Runner interval 小於主循環 tick 間隔，實際觸發精度受限", {
+                topic: LOG_TOPIC_TRIGGER,
+                data: {
+                    runnerKey: key,
+                    intervalMs,
+                    loopIntervalMs: TRIGGER_LOOP_INTERVAL_MS,
+                },
+            });
+        }
+
+        logger.success("Trigger 節點啟動", {
+            topic: LOG_TOPIC_TRIGGER,
+            data: { runnerKeys },
+        });
+    }
+
+    protected async runLoopSteps(ctx: NodeLoopContext, heartbeatOk: boolean): Promise<void> {
+        if (!heartbeatOk) {
+            const logger = createLogger({
+                scope: createScope({
+                    module: `${this.runtimeModule}-runLoopSteps`,
+                    traceId: ctx.loopTraceId,
+                    labels: { nodeId: ctx.nodeId },
+                }),
+            });
+            logger.warn("心跳失敗，本輪跳過 runner", { topic: LOG_TOPIC_NODE });
+            return;
+        }
+        await TriggerManager.tick(ctx);
+    }
+}
+
+export type { TriggerNodeOptions } from "./trigger.interface";
+export { TriggerNode };