@gobing-ai/ts-infra 0.4.59 → 0.4.62

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gobing-ai/ts-infra",
-    "version": "0.4.59",
+    "version": "0.4.62",
     "description": "@gobing-ai/ts-infra — Infrastructure backbone: event bus, job queue, scheduler, telemetry, API client, and logging.",
     "keywords": [
         "typescript",
@@ -78,12 +78,12 @@
         "release": "echo 'Manual publish is disabled. Releases go through GitHub Actions via Trusted Publishing — push a tag: git tag @gobing-ai/ts-infra-v<version> && git push --tags' && exit 1"
     },
     "dependencies": {
-        "@gobing-ai/ts-utils": "^0.4.59",
+        "@gobing-ai/ts-utils": "^0.4.62",
         "@logtape/logtape": "^2.0.0"
     },
     "peerDependencies": {
-        "@gobing-ai/ts-db": "^0.4.59",
-        "@gobing-ai/ts-runtime": "^0.4.59",
+        "@gobing-ai/ts-db": "^0.4.62",
+        "@gobing-ai/ts-runtime": "^0.4.62",
         "@opentelemetry/api": "^1.9.0",
         "@opentelemetry/sdk-trace-node": "^2.0.0",
         "@opentelemetry/sdk-metrics": "^2.0.0",
@@ -116,8 +116,8 @@
         }
     },
     "devDependencies": {
-        "@gobing-ai/ts-db": "^0.4.59",
-        "@gobing-ai/ts-runtime": "^0.4.59",
+        "@gobing-ai/ts-db": "^0.4.62",
+        "@gobing-ai/ts-runtime": "^0.4.62",
         "@types/bun": "1.3.14",
         "@opentelemetry/api": "^1.9.0",
         "@opentelemetry/sdk-trace-node": "^2.0.0",

package/src/application/index.ts

@@ -15,6 +15,7 @@ import { EventBus } from '../event-bus/event-bus';
 import { attachFileObserver } from '../event-bus/file-observer';
 import type { BusLifecycleEvents, EventMap } from '../event-bus/types';
 import type { InfraEvents } from '../events';
+import { resolveExecutionTimeoutMs } from '../execution-policy';
 import { getLogger, type Logger } from '../logger';
 import { initScheduler } from '../scheduler/factory';
 import type { SchedulerAdapter } from '../scheduler/types';
@@ -126,6 +127,8 @@ export async function runApplication<TAppConfig = unknown, TEvents extends Event
         enabled: schedOpts?.enabled ?? false,
         autoStart: schedOpts?.autoStart ?? true,
         jobs: schedOpts?.jobs ?? [],
+        // Bootstrap-level execution policy (A21): omitted resolves to unlimited.
+        timeoutMs: resolveExecutionTimeoutMs('bootstrap.scheduler', schedOpts?.timeoutMs),
     };
     const eventsEnabled = options.config?.events?.enabled ?? true;
     const eventsLifecycle = options.config?.events?.lifecycle ?? true;

package/src/application/types.ts

@@ -13,7 +13,7 @@ import type { FileObserverWriter } from '../event-bus/file-observer';
 import type { BusLifecycleEvents, EventMap } from '../event-bus/types';
 import type { InfraEvents } from '../events';
 import type { Logger, LogLevel } from '../logger';
-import type { SchedulerAdapter, SchedulerJobConfig } from '../scheduler/types';
+import type { ScheduledAction, SchedulerAdapter, SchedulerJobConfig } from '../scheduler/types';
 import type { PluginHost } from './plugins/host';
 import type { Plugin } from './plugins/types';
 
@@ -81,7 +81,7 @@ export interface SchedulerOptions {
     /** Injected adapter (skips noop default when provided). */
     adapter?: SchedulerAdapter;
     /** Cron entries to register: `[cron, action][]`. */
-    entries?: Array<[string, () => Promise<void>]>;
+    entries?: Array<[string, ScheduledAction]>;
     /** Start scheduler immediately after registration. Default `true` when enabled. */
     autoStart?: boolean;
     /**
@@ -91,6 +91,13 @@ export interface SchedulerOptions {
      * job `command` itself.
      */
     jobs?: readonly SchedulerJobConfig[];
+    /**
+     * Bootstrap-level execution policy (A21): a positive integer ms deadline
+     * or explicit `null` = unlimited; omitted resolves to unlimited. Per-job
+     * `timeoutMs` overrides this default through the shared first-match-wins
+     * resolution.
+     */
+    timeoutMs?: number | null;
 }
 
 // ── Resolved bootstrap config ─────────────────────────────────────────────
@@ -113,7 +120,13 @@ export interface ApplicationBootstrapConfig {
         filePath?: string;
     };
     readonly telemetry: { enabled: boolean; serviceName: string; environment: string; dbStatementDebug: boolean };
-    readonly scheduler: { enabled: boolean; autoStart: boolean; jobs: readonly SchedulerJobConfig[] };
+    readonly scheduler: {
+        enabled: boolean;
+        autoStart: boolean;
+        jobs: readonly SchedulerJobConfig[];
+        /** Resolved bootstrap execution policy; `null` = unlimited. */
+        timeoutMs: number | null;
+    };
 }
 
 // ── Injected services ─────────────────────────────────────────────────────

package/src/application-node.ts

@@ -39,6 +39,7 @@ import type {
     SchedulerOptions,
     TelemetryOptions,
 } from './application/types';
+import { resolveExecutionTimeoutMs } from './execution-policy';
 import { parseCronExpression } from './scheduler/cron';
 import type { SchedulerJobConfig } from './scheduler/types';
 import { NodeSchedulerAdapter } from './scheduler-node';
@@ -97,7 +98,22 @@ function validateAppConfig<TAppConfig>(
     throw new ConfigValidationError(`Unsupported validator shape for section "${section}"`);
 }
 
-// ── Scheduler job validation (task 0734) ────────────────────────────────────
+// ── Scheduler job validation (task 0734) ────────────────────────────
+
+/**
+ * Resolve and validate the bootstrap-level scheduler execution policy (A21),
+ * rethrowing invalid values as {@link ConfigValidationError} with the exact
+ * config path so startup aborts before the user `start` callback.
+ */
+function resolveBootstrapSchedulerTimeout(value: number | null | undefined): number | null {
+    try {
+        return resolveExecutionTimeoutMs('bootstrap.scheduler', value);
+    } catch {
+        throw new ConfigValidationError(
+            `bootstrap.scheduler.timeoutMs must be a positive integer or null; received ${String(value)}`,
+        );
+    }
+}
 
 /** Max `intervalMinutes` so that `intervalMinutes * 60_000` fits in the platform timer maximum. */
 const MAX_INTERVAL_MINUTES = Math.floor(MAX_TIMEOUT_MS / 60_000);
@@ -131,6 +147,22 @@ function normalizeSchedulerJobs(raw: unknown): readonly SchedulerJobConfig[] {
         const command = typeof entry.command === 'string' ? entry.command.trim() : '';
         const cron = typeof entry.cron === 'string' ? entry.cron.trim() : '';
         const interval = entry.intervalMinutes;
+        // Per-job execution policy (A21): undefined inherits, explicit null is
+        // unlimited, otherwise a positive integer. Validated here so a bad
+        // value aborts startup with the exact job path.
+        const rawTimeout = entry.timeoutMs;
+        let timeoutMs: number | null | undefined;
+        if (rawTimeout !== undefined) {
+            if (
+                rawTimeout !== null &&
+                (typeof rawTimeout !== 'number' || !Number.isInteger(rawTimeout) || rawTimeout <= 0)
+            ) {
+                throw new ConfigValidationError(
+                    `bootstrap.scheduler.jobs.${index}.timeoutMs must be a positive integer or null`,
+                );
+            }
+            timeoutMs = rawTimeout as number | null;
+        }
 
         if (name === '') {
             throw new ConfigValidationError(`bootstrap.scheduler.jobs.${index}.name must be a non-empty string`);
@@ -165,7 +197,7 @@ function normalizeSchedulerJobs(raw: unknown): readonly SchedulerJobConfig[] {
                     `bootstrap.scheduler.jobs.${index}.intervalMinutes must be an integer in 1..${MAX_INTERVAL_MINUTES}`,
                 );
             }
-            jobs.push({ name, command, intervalMinutes: interval as number });
+            jobs.push({ name, command, intervalMinutes: interval as number, timeoutMs });
         } else {
             if (cron === '') {
                 throw new ConfigValidationError(`bootstrap.scheduler.jobs.${index}.cron must be a non-empty string`);
@@ -176,7 +208,7 @@ function normalizeSchedulerJobs(raw: unknown): readonly SchedulerJobConfig[] {
                 const detail = error instanceof Error ? error.message : String(error);
                 throw new ConfigValidationError(`bootstrap.scheduler.jobs.${index}.cron: ${detail}`);
             }
-            jobs.push({ name, command, cron });
+            jobs.push({ name, command, cron, timeoutMs });
         }
     });
 
@@ -369,9 +401,13 @@ export async function runNodeApplication<TAppConfig = unknown, TEvents extends E
         enabled: schedulerOpts.enabled === true,
         autoStart: schedulerOpts.autoStart,
         jobs: normalizeSchedulerJobs((schedulerOpts as Partial<SchedulerOptions>).jobs),
+        // Bootstrap-level execution policy (A21): validated with the exact
+        // config path so a bad value aborts startup before the user callback.
+        timeoutMs: resolveBootstrapSchedulerTimeout(schedulerOpts.timeoutMs),
     };
     if (schedulerConfig.enabled) {
-        schedulerConfig.adapter = schedulerOpts.adapter ?? new NodeSchedulerAdapter();
+        schedulerConfig.adapter =
+            schedulerOpts.adapter ?? new NodeSchedulerAdapter({ timeoutMs: schedulerConfig.timeoutMs });
         if (schedulerOpts.entries) {
             schedulerConfig.entries = schedulerOpts.entries;
         }

package/src/execution-policy.ts

@@ -0,0 +1,168 @@
+/**
+ * Shared execution-deadline policy for background work (feature A21).
+ *
+ * One nullable policy (`number | null`) and one clock per execution: a finite
+ * deadline arms a single timer that requests cancellation through an
+ * `AbortController`; the executor always awaits the handler's settlement, even
+ * when the handler ignores the abort signal. Both the queue consumer and the
+ * Node scheduler run their work through this seam so deadline, cancellation,
+ * and timing semantics stay identical across surfaces.
+ *
+ * Resolution is first-match-wins down the scope chain: an explicit job value
+ * (including explicit `null` = unlimited) beats the consumer default; absence
+ * (`undefined`) inherits; an absent inherited value is unlimited. A scope
+ * never *negates* an inherited finite deadline by being omitted — only an
+ * explicit `null` opts out.
+ */
+
+/** Execution deadline policy: positive integer milliseconds, or `null` = unlimited. */
+export type ExecutionDeadlineMs = number | null;
+
+/** Cancellation context handed to job and scheduler handlers. */
+export interface ExecutionContext {
+    /** Fires when the deadline expires or the caller's signal cancels first. */
+    readonly signal: AbortSignal;
+    /** The resolved policy for this execution; `null` means unlimited. */
+    readonly deadlineMs: ExecutionDeadlineMs;
+    /**
+     * Why cancellation was requested: `'timeout'` when the execution deadline
+     * expired, `'cancelled'` when the caller's signal fired first. `undefined`
+     * while the work is not (yet) being cancelled.
+     */
+    readonly cancellationReason: 'timeout' | 'cancelled' | undefined;
+}
+
+/** Outcome of an execution run through {@link runWithExecutionDeadline}. */
+export interface ExecutionOutcome {
+    /** `'timeout'` and `'cancelled'` still mean the handler settled (or was awaited to settlement). */
+    outcome: 'completed' | 'timeout' | 'cancelled' | 'error';
+    /** The handler's error when `outcome === 'error'`. */
+    error?: unknown;
+    elapsedMs: number;
+    /** True when the deadline expired, even if the handler ignored the abort and finished late. */
+    timedOut: boolean;
+}
+
+/** Options for {@link runWithExecutionDeadline}. */
+export interface ExecutionDeadlineOptions {
+    /** Resolved deadline for this run; `undefined` is treated as unlimited. */
+    timeoutMs?: number | null;
+    /** Caller-controlled cancellation composed into the same controller. */
+    signal?: AbortSignal;
+}
+
+/**
+ * Resolve the leaf execution policy for one scope.
+ *
+ * `value === undefined` inherits `inherited` (itself `null` when absent);
+ * `value === null` explicitly opts out of this scope's deadline; a positive
+ * integer wins outright. Anything else is a configuration error.
+ */
+export function resolveExecutionTimeoutMs(
+    scope: string,
+    value: number | null | undefined,
+    inherited?: number | null,
+): number | null {
+    if (value === undefined) {
+        return inherited ?? null;
+    }
+    if (value === null) {
+        return null;
+    }
+    if (typeof value !== 'number' || !Number.isInteger(value) || value <= 0) {
+        throw new RangeError(`${scope} timeoutMs must be a positive integer or null; received ${String(value)}`);
+    }
+    return value;
+}
+
+/**
+ * A reusable unlimited context for callers that execute actions without
+ * arming a ts-infra deadline — notably the Cloudflare adapter, whose ticks
+ * run under the Workers runtime's own limits (A21).
+ */
+export function unlimitedExecutionContext(): ExecutionContext {
+    return {
+        signal: new AbortController().signal,
+        deadlineMs: null,
+        cancellationReason: undefined,
+    };
+}
+
+/**
+ * Run `action` under one shared deadline clock.
+ *
+ * A finite `timeoutMs` arms exactly one timer that aborts the context's
+ * controller (`cancellationReason: 'timeout'`); an aborted caller signal
+ * aborts the same controller (`cancellationReason: 'cancelled'`). The handler
+ * is always awaited — including after abort, so an uncooperative handler that
+ * finishes late is still reported as timed out, never as a successful
+ * cancellation — and handler rejections surface as `{ outcome: 'error' }`.
+ */
+export async function runWithExecutionDeadline<T>(
+    action: (context: ExecutionContext) => Promise<T>,
+    options: ExecutionDeadlineOptions,
+): Promise<ExecutionOutcome & { result?: T }> {
+    const deadlineMs = options.timeoutMs ?? null;
+    const controller = new AbortController();
+    const cancellation: { reason: 'timeout' | 'cancelled' | undefined } = { reason: undefined };
+
+    const context: ExecutionContext = {
+        signal: controller.signal,
+        deadlineMs,
+        get cancellationReason() {
+            return cancellation.reason;
+        },
+    };
+
+    if (options.signal !== undefined) {
+        if (options.signal.aborted) {
+            cancellation.reason = 'cancelled';
+            controller.abort();
+        } else {
+            const abortFromCaller = (): void => {
+                if (cancellation.reason === undefined) cancellation.reason = 'cancelled';
+                controller.abort();
+            };
+            options.signal.addEventListener('abort', abortFromCaller, { once: true });
+        }
+    }
+
+    const startMs = performance.now();
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    if (deadlineMs !== null) {
+        timer = setTimeout(() => {
+            if (cancellation.reason === undefined) cancellation.reason = 'timeout';
+            controller.abort();
+        }, deadlineMs);
+    }
+
+    let result: T | undefined;
+    let error: unknown;
+    let failed = false;
+    try {
+        result = await action(context);
+    } catch (caught) {
+        error = caught;
+        failed = true;
+    } finally {
+        if (timer !== undefined) clearTimeout(timer);
+    }
+
+    const elapsedMs = performance.now() - startMs;
+    const timedOut = cancellation.reason === 'timeout';
+    if (failed) {
+        return { outcome: 'error', error, elapsedMs, timedOut };
+    }
+    if (timedOut) {
+        return {
+            outcome: 'timeout',
+            error: new Error(`execution deadline (${String(deadlineMs)}ms) expired`),
+            elapsedMs,
+            timedOut,
+        };
+    }
+    if (cancellation.reason === 'cancelled') {
+        return { outcome: 'cancelled', elapsedMs, timedOut };
+    }
+    return { outcome: 'completed', result, elapsedMs, timedOut };
+}

package/src/index.ts

@@ -43,7 +43,9 @@ export type {
     SchedulerJobExecutedDetail,
     WithEventSeverity,
 } from './events';
-
+// Execution policy (A21) — shared deadline/cancellation seam for background work
+export type { ExecutionContext, ExecutionDeadlineMs, ExecutionOutcome } from './execution-policy';
+export { resolveExecutionTimeoutMs, runWithExecutionDeadline } from './execution-policy';
 export type {
     EnqueueOptions,
     Job,