@happyvertical/smrt-jobs 0.30.0

package/dist/smrt-knowledge.json

@@ -0,0 +1,508 @@
+{
+  "schemaVersion": 1,
+  "generatedAt": "2026-06-23T01:11:19.800Z",
+  "packageName": "@happyvertical/smrt-jobs",
+  "packageVersion": "0.30.0",
+  "sourceManifestPath": "dist/manifest.json",
+  "agentDocPath": "AGENTS.md",
+  "sourceHashes": {
+    "manifest": "8bed9aec574feed7d15e21164393b59c9f976f2533e62f588445f314e8326ed4",
+    "packageJson": "3b3e6a6efac6ef8f88e0a8c91b899c37d21a90cc922fe6d4d05d6d40f23f073c",
+    "agents": "407e0ecd3f0ce3ae02d7dc84e86e457ddb6e75677d682b017768b4155b5a68ac"
+  },
+  "exports": [
+    ".",
+    "./manifest",
+    "./manifest.json",
+    "./playground",
+    "./runner",
+    "./svelte",
+    "./ui",
+    "./worker-liveness-thread"
+  ],
+  "dependencies": {
+    "@happyvertical/jobs": "catalog:",
+    "@happyvertical/logger": "catalog:",
+    "@happyvertical/smrt-config": "workspace:*",
+    "@happyvertical/smrt-core": "workspace:*",
+    "@happyvertical/smrt-tenancy": "workspace:*",
+    "@happyvertical/smrt-types": "workspace:*",
+    "@happyvertical/smrt-ui": "workspace:*",
+    "@happyvertical/sql": "catalog:",
+    "@happyvertical/utils": "catalog:",
+    "@happyvertical/smrt-vitest": "workspace:*",
+    "@sveltejs/package": "^2.5.7",
+    "@sveltejs/vite-plugin-svelte": "^6.2.4",
+    "@types/node": "25.0.9",
+    "svelte": "^5.18.0",
+    "svelte-check": "^4.3.5",
+    "typescript": "^5.9.3",
+    "vite": "^7.3.1",
+    "vitest": "^4.0.17"
+  },
+  "smrtDependencies": [
+    "@happyvertical/smrt-config",
+    "@happyvertical/smrt-core",
+    "@happyvertical/smrt-tenancy",
+    "@happyvertical/smrt-types",
+    "@happyvertical/smrt-ui",
+    "@happyvertical/smrt-vitest"
+  ],
+  "sdkDependencies": [
+    "@happyvertical/jobs",
+    "@happyvertical/logger",
+    "@happyvertical/sql",
+    "@happyvertical/utils"
+  ],
+  "tags": [],
+  "risks": [],
+  "objects": [
+    {
+      "name": "SmrtJobEvent",
+      "qualifiedName": "@happyvertical/smrt-jobs:SmrtJobEvent",
+      "collection": "smrtjobevents",
+      "tableName": "_smrt_job_events",
+      "packageName": "@happyvertical/smrt-jobs",
+      "extends": "SmrtObject",
+      "fields": [
+        {
+          "name": "tenantId",
+          "type": "text",
+          "required": false,
+          "columnType": "UUID"
+        },
+        {
+          "name": "jobId",
+          "type": "foreignKey",
+          "required": true,
+          "related": "SmrtJob",
+          "columnType": "UUID"
+        },
+        {
+          "name": "type",
+          "type": "text",
+          "required": true,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "level",
+          "type": "text",
+          "required": true,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "stage",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "progress",
+          "type": "integer",
+          "required": false,
+          "columnType": "INTEGER"
+        },
+        {
+          "name": "message",
+          "type": "text",
+          "required": true,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "data",
+          "type": "json",
+          "required": false,
+          "columnType": "JSON"
+        },
+        {
+          "name": "createdAt",
+          "type": "datetime",
+          "required": true,
+          "columnType": "TIMESTAMP"
+        }
+      ],
+      "relationships": [
+        {
+          "name": "jobId",
+          "type": "foreignKey",
+          "required": true,
+          "related": "SmrtJob",
+          "columnType": "UUID"
+        }
+      ],
+      "methods": [
+        "toCursor"
+      ],
+      "surfaces": [
+        {
+          "kind": "cli",
+          "name": "smrtjobevent_list",
+          "operation": "list",
+          "objectName": "@happyvertical/smrt-jobs:SmrtJobEvent"
+        },
+        {
+          "kind": "cli",
+          "name": "smrtjobevent_get",
+          "operation": "get",
+          "objectName": "@happyvertical/smrt-jobs:SmrtJobEvent"
+        }
+      ],
+      "relationshipFeatures": [
+        "foreignKey",
+        "uuidColumns"
+      ],
+      "tags": [],
+      "risks": []
+    },
+    {
+      "name": "SmrtJobEventCollection",
+      "qualifiedName": "@happyvertical/smrt-jobs:SmrtJobEventCollection",
+      "collection": "smrtjobevents",
+      "tableName": "_smrt_job_events",
+      "packageName": "@happyvertical/smrt-jobs",
+      "extends": "SmrtCollection",
+      "fields": [],
+      "relationships": [],
+      "methods": [
+        "append",
+        "initialize",
+        "latestProgressByJobIds",
+        "listByJob",
+        "listSinceCursor"
+      ],
+      "surfaces": [],
+      "relationshipFeatures": [
+        "uuidColumns"
+      ],
+      "tags": [],
+      "risks": []
+    },
+    {
+      "name": "SmrtJob",
+      "qualifiedName": "@happyvertical/smrt-jobs:SmrtJob",
+      "collection": "smrtjobs",
+      "tableName": "_smrt_jobs",
+      "packageName": "@happyvertical/smrt-jobs",
+      "extends": "SmrtObject",
+      "fields": [
+        {
+          "name": "tenantId",
+          "type": "text",
+          "required": false,
+          "columnType": "UUID"
+        },
+        {
+          "name": "queue",
+          "type": "text",
+          "required": true,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "objectType",
+          "type": "text",
+          "required": true,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "objectId",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "method",
+          "type": "text",
+          "required": true,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "args",
+          "type": "json",
+          "required": false,
+          "columnType": "JSON"
+        },
+        {
+          "name": "runAt",
+          "type": "datetime",
+          "required": true,
+          "columnType": "TIMESTAMP"
+        },
+        {
+          "name": "priority",
+          "type": "integer",
+          "required": true,
+          "columnType": "INTEGER"
+        },
+        {
+          "name": "status",
+          "type": "text",
+          "required": true,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "attempts",
+          "type": "integer",
+          "required": true,
+          "columnType": "INTEGER"
+        },
+        {
+          "name": "maxAttempts",
+          "type": "integer",
+          "required": true,
+          "columnType": "INTEGER"
+        },
+        {
+          "name": "timeout",
+          "type": "integer",
+          "required": true,
+          "columnType": "INTEGER"
+        },
+        {
+          "name": "timeoutBehavior",
+          "type": "text",
+          "required": true,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "startedAt",
+          "type": "datetime",
+          "required": false,
+          "columnType": "TIMESTAMP"
+        },
+        {
+          "name": "completedAt",
+          "type": "datetime",
+          "required": false,
+          "columnType": "TIMESTAMP"
+        },
+        {
+          "name": "lastError",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "resultPointer",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "retryStrategy",
+          "type": "json",
+          "required": false,
+          "columnType": "JSON"
+        },
+        {
+          "name": "workerId",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "workerHeartbeat",
+          "type": "datetime",
+          "required": false,
+          "columnType": "TIMESTAMP"
+        }
+      ],
+      "relationships": [],
+      "methods": [
+        "cancel",
+        "getDescription",
+        "retry",
+        "save"
+      ],
+      "surfaces": [
+        {
+          "kind": "cli",
+          "name": "smrtjob_list",
+          "operation": "list",
+          "objectName": "@happyvertical/smrt-jobs:SmrtJob"
+        },
+        {
+          "kind": "cli",
+          "name": "smrtjob_get",
+          "operation": "get",
+          "objectName": "@happyvertical/smrt-jobs:SmrtJob"
+        },
+        {
+          "kind": "cli",
+          "name": "smrtjob_retry",
+          "operation": "retry",
+          "objectName": "@happyvertical/smrt-jobs:SmrtJob"
+        },
+        {
+          "kind": "cli",
+          "name": "smrtjob_cancel",
+          "operation": "cancel",
+          "objectName": "@happyvertical/smrt-jobs:SmrtJob"
+        }
+      ],
+      "relationshipFeatures": [
+        "uuidColumns"
+      ],
+      "tags": [],
+      "risks": []
+    },
+    {
+      "name": "SmrtJobCollection",
+      "qualifiedName": "@happyvertical/smrt-jobs:SmrtJobCollection",
+      "collection": "smrtjobs",
+      "tableName": "_smrt_jobs",
+      "packageName": "@happyvertical/smrt-jobs",
+      "extends": "SmrtCollection",
+      "fields": [],
+      "relationships": [],
+      "methods": [
+        "claimReady",
+        "cleanup",
+        "countInFlightForTenant",
+        "enqueueJob",
+        "initialize",
+        "listByStatus",
+        "listReady",
+        "stats"
+      ],
+      "surfaces": [],
+      "relationshipFeatures": [
+        "uuidColumns"
+      ],
+      "tags": [],
+      "risks": []
+    },
+    {
+      "name": "SmrtWorker",
+      "qualifiedName": "@happyvertical/smrt-jobs:SmrtWorker",
+      "collection": "smrtworkers",
+      "tableName": "_smrt_workers",
+      "packageName": "@happyvertical/smrt-jobs",
+      "extends": "SmrtObject",
+      "fields": [
+        {
+          "name": "workerId",
+          "type": "text",
+          "required": true,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "pid",
+          "type": "integer",
+          "required": false,
+          "columnType": "INTEGER"
+        },
+        {
+          "name": "hostname",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "startedAt",
+          "type": "datetime",
+          "required": false,
+          "columnType": "TIMESTAMP"
+        },
+        {
+          "name": "heartbeatAt",
+          "type": "datetime",
+          "required": false,
+          "columnType": "TIMESTAMP"
+        },
+        {
+          "name": "leaseExpiresAt",
+          "type": "datetime",
+          "required": false,
+          "columnType": "TIMESTAMP"
+        },
+        {
+          "name": "status",
+          "type": "text",
+          "required": true,
+          "columnType": "TEXT"
+        }
+      ],
+      "relationships": [],
+      "methods": [],
+      "surfaces": [],
+      "relationshipFeatures": [
+        "uuidColumns"
+      ],
+      "tags": [],
+      "risks": []
+    },
+    {
+      "name": "SmrtWorkerCollection",
+      "qualifiedName": "@happyvertical/smrt-jobs:SmrtWorkerCollection",
+      "collection": "smrtworkers",
+      "tableName": "_smrt_workers",
+      "packageName": "@happyvertical/smrt-jobs",
+      "extends": "SmrtCollection",
+      "fields": [],
+      "relationships": [],
+      "methods": [
+        "assertReady",
+        "expireWorker",
+        "freshLeaseWorkerKeys",
+        "pruneExpired",
+        "registerWorker",
+        "renewLease",
+        "tableReady"
+      ],
+      "surfaces": [],
+      "relationshipFeatures": [
+        "uuidColumns"
+      ],
+      "tags": [],
+      "risks": []
+    }
+  ],
+  "surfaces": [
+    {
+      "kind": "cli",
+      "name": "smrtjobevent_list",
+      "operation": "list",
+      "objectName": "@happyvertical/smrt-jobs:SmrtJobEvent"
+    },
+    {
+      "kind": "cli",
+      "name": "smrtjobevent_get",
+      "operation": "get",
+      "objectName": "@happyvertical/smrt-jobs:SmrtJobEvent"
+    },
+    {
+      "kind": "cli",
+      "name": "smrtjob_list",
+      "operation": "list",
+      "objectName": "@happyvertical/smrt-jobs:SmrtJob"
+    },
+    {
+      "kind": "cli",
+      "name": "smrtjob_get",
+      "operation": "get",
+      "objectName": "@happyvertical/smrt-jobs:SmrtJob"
+    },
+    {
+      "kind": "cli",
+      "name": "smrtjob_retry",
+      "operation": "retry",
+      "objectName": "@happyvertical/smrt-jobs:SmrtJob"
+    },
+    {
+      "kind": "cli",
+      "name": "smrtjob_cancel",
+      "operation": "cancel",
+      "objectName": "@happyvertical/smrt-jobs:SmrtJob"
+    }
+  ],
+  "prompts": [],
+  "relationshipsV2": {
+    "foreignKeyFields": 1,
+    "crossPackageRefFields": 0,
+    "junctionCollections": 0,
+    "hierarchicalObjects": 0,
+    "polymorphicAssociations": 0,
+    "uuidColumns": 9
+  },
+  "agentDoc": "# @happyvertical/smrt-jobs\n\nBackground job execution with persistent queue, scheduling, and fluent builder API.\n\n## Architecture\n\n```\nSmrtObject.bg('method') → SmrtJob (in _smrt_jobs) → TaskRunner picks up → executes via ObjectRegistry\nAgentSchedule (cron) → ScheduleRunner creates SmrtJob → TaskRunner executes → ScheduleRunner updates\nTaskRunner.start() → SmrtWorker lease (in _smrt_workers) → recovery keys on worker liveness, not heartbeat\n```\n\n## SmrtJob\n\nPersistent in `_smrt_jobs`. Fields: `queue` (default), `objectType`, `objectId`, `method`, `args`, `runAt`, `priority` (higher=sooner), `status`, `attempts`/`maxAttempts`, `timeout` (default 5min), `retryStrategy`, `workerId` (the owning runner's incarnation key), `workerHeartbeat` (telemetry only — no longer gates recovery).\n\nStatus: `pending → running → completed/failed/cancelled`.\n\n## TaskRunner\n\nPolling-based execution engine. Config: `concurrency` (5), `pollInterval` (1s), `heartbeatInterval` (30s, telemetry only), `leaseTtlMs` (30s), `leaseTickMs` (10s), `shutdownTimeout` (30s).\n\n1. `start()` calls `assertReady()` (fail fast if `_smrt_workers` unmigrated), registers a seeded `SmrtWorker` lease, and adds its worker key to the process-global live set — all **before** polling\n2. Polls `claimReady()` to atomically claim pending jobs (`runAt <= NOW`, ordered by `priority DESC, runAt ASC, created_at ASC, id ASC`)\n3. Claim sets `status='running'`, `workerId=<incarnation key>`, heartbeat/start timestamps, and increments `attempts`\n4. Resolves class via `ObjectRegistry.getClass(objectType)`, creates instance, calls method\n5. **Internal args**: `_agentConfig` and `_scheduleId` stripped from args before calling method\n6. Terminal/retry writes are **conditional** (`WHERE worker_id=? AND status='running'`) so a recovered row is never stomped\n7. Retry: uses strategy from `@happyvertical/jobs`, schedules future `runAt` on failure\n8. Events: `job:started`, `job:completed`, `job:failed`, `job:retrying`, `runner:started/stopped`\n\n## Worker liveness & recovery (#1474)\n\nRecovery keys on **worker-process liveness**, never per-job heartbeat freshness (a CPU-bound synchronous handler used to starve the heartbeat and false-recover its own running jobs).\n\n- **`SmrtWorker` / `_smrt_workers`**: one lease row per runner *incarnation* (`workerId` is per-incarnation unique via `createWorkerKey`, so a restart never looks like it still owns the previous crash's jobs). `leaseExpiresAt` is a `datetime` (an integer epoch-ms column overflows `int4`/`INT32` on Postgres/DuckDB). Stage 1 writes/compares it against the host clock — the same approach the old heartbeat recovery used, so it's no more skew-sensitive than the code it replaced.\n- **Process-global live set** (`worker-liveness.ts`, `globalThis.__smrtLiveWorkers`): checked synchronously, so it can't be starved by a blocked loop. Covers all same-process topologies.\n- **Off-loop ticker** (`worker-liveness-ticker.ts` + `worker-liveness-thread.ts`): for engines a second connection can reach (Postgres, file-backed SQLite — `offLoopEligible()`), `start()` spawns a `node:worker_threads` ticker that renews the lease on its own thread, so a CPU-bound synchronous handler on the main loop can't starve it. In-memory SQLite / DuckDB, a thread-spawn failure, a start-handshake timeout, or the thread dying mid-run all fall back to main-loop renewal; the in-process live set keeps same-process correct regardless. The worker entry is a separate build entry resolved via `import.meta.resolve('@happyvertical/smrt-jobs/worker-liveness-thread')`.\n- **Recovery rule** (both runners): a `running` job is orphaned iff its worker is *not alive* = not in the live set **and** no fresh `_smrt_workers` lease. The live set takes precedence over a stale lease. TaskRunner also never recovers a job in its own `activeJobs`. If `_smrt_workers` is absent, recovery skips lease checks (never mass-recovers). Recovery is swept at most once per lease tick, and terminal/recovery writes use `RETURNING id` (not `rowCount`, which DuckDB/JSON adapters always report as ≥1).\n- **Lease clock**: the lease is compared against the host clock (same as the old heartbeat; fine with NTP + a 30s TTL). A dead process stops renewing and the lease expires within its TTL — that is how recovery detects death. (Instant cross-process detection via Postgres session advisory locks was prototyped on `@happyvertical/sql`'s `acquireSession()` but deferred — treating a free lock as proof-of-death false-recovers any worker legitimately in main-loop fallback mode.)\n\n## ScheduleRunner\n\nPolls `_smrt_agent_schedules` every 60s for due entries. Creates SmrtJob with `queue='agents'`, `priority=75`. Wires to TaskRunner events for completion/failure tracking. Slot reconciliation keys on worker liveness (it has no in-process active-job set, so the lease/live-set is its whole mechanism).\n\nCustom cron parser: 5-field (minute hour dom month dow). `*`, ranges, lists, steps supported. **Not timezone-aware** (UTC).\n\n## JobBuilder — Fluent API\n\n```typescript\nconst handle = await doc.background('analyze', { detailed: true })\n  .delay('5m').priority('high').retries(5).queue('analysis').timeout(600000).enqueue();\n\nawait handle.wait({ timeout: 60000, pollInterval: 100 }); // polling-based\n```\n\n`bg()` is shorthand: `await doc.bg('analyze', args)` → enqueues immediately, returns JobHandle.\n\n## withBackgroundJobs(Class)\n\nMixin that adds `bg()` and `background()` to any SmrtObject. Uses WeakMap for collection caching per DB instance.\n\n## Gotchas\n\n- **Cron not timezone-aware**: all times treated as UTC\n- **No dead letter queue**: failed jobs stay in DB with `status='failed'` — manual intervention\n- **Result storage**: `resultPointer` is just a string — app must implement result backend\n- **Lazy builder**: `background()` returns builder — nothing happens until `enqueue()`\n- **wait() is polling**: JobHandle.wait() polls DB every 100ms (configurable)\n- **Migrate before start()**: `TaskRunner.start()` throws if `_smrt_workers` is missing — run `smrt db:migrate` after upgrading. Tables are never created at runtime.\n- **Recovery is liveness-based**: don't reintroduce heartbeat-threshold recovery; a blocked event loop must not look dead (see Worker liveness section, #1474)\n"
+}

package/dist/smrt-worker.d.ts

@@ -0,0 +1,72 @@
+import { SmrtCollection, SmrtObject } from '@happyvertical/smrt-core';
+/**
+ * Liveness record for a single TaskRunner / ScheduleRunner incarnation,
+ * stored in the `_smrt_workers` system table.
+ *
+ * @remarks
+ * Job recovery asks "is this job's owning worker alive?" rather than "is this
+ * job's heartbeat fresh?" (issue #1474). Each running worker keeps a row here
+ * and renews `leaseExpiresAt` on a fixed cadence; a worker that dies stops
+ * renewing and its lease expires, so its `running` jobs are recovered.
+ *
+ * `workerId` is unique per *incarnation* (a restarted runner gets a new key —
+ * see `createWorkerKey`), which is what lets recovery distinguish a crashed
+ * worker's orphaned jobs from an identically-configured restart.
+ *
+ * `leaseExpiresAt` is a `datetime` so it maps to a real timestamp column on
+ * every engine (an integer epoch-ms column overflows `int4`/`INT32` on
+ * Postgres and DuckDB). Stage 1 writes/compares it against the host clock —
+ * the same approach the previous heartbeat recovery used; Stage 2 will move to
+ * database-side time once an off-loop writer exists.
+ */
+export declare class SmrtWorker extends SmrtObject {
+    /** Per-incarnation-unique worker key (also stored on owned jobs' workerId). */
+    workerId: string;
+    /** OS process id of the owning runner (diagnostic). */
+    pid: number | null;
+    /** Hostname of the owning runner (diagnostic). */
+    hostname: string | null;
+    /** When this incarnation started. */
+    startedAt: Date | null;
+    /** Last lease renewal time (diagnostic; liveness uses leaseExpiresAt). */
+    heartbeatAt: Date | null;
+    /** Lease expiry — the worker is alive while this is in the future. */
+    leaseExpiresAt: Date | null;
+    /** Lifecycle status (`running` while the runner is processing). */
+    status: string;
+}
+export interface RegisterWorkerInput {
+    workerKey: string;
+    pid?: number | null;
+    hostname?: string | null;
+    leaseTtlMs: number;
+}
+/**
+ * Collection for managing `_smrt_workers` liveness rows.
+ */
+export declare class SmrtWorkerCollection extends SmrtCollection<SmrtWorker> {
+    static readonly _itemClass: typeof SmrtWorker;
+    /**
+     * Fail fast if the `_smrt_workers` table has not been migrated.
+     *
+     * The framework never creates application/system tables at runtime; the
+     * table is created by `smrt db:migrate` (or `getTestDatabase`). A consumer
+     * that upgrades smrt-jobs without migrating must get a clear, actionable
+     * error at `start()` rather than a confusing recovery failure later.
+     */
+    assertReady(): Promise<void>;
+    /** Whether the `_smrt_workers` table exists (recovery skips lease checks if not). */
+    tableReady(): Promise<boolean>;
+    /** Register a worker incarnation with its lease seeded to `now + ttl`. */
+    registerWorker(input: RegisterWorkerInput): Promise<void>;
+    /** Renew a worker's lease to `now + ttl`. */
+    renewLease(workerKey: string, leaseTtlMs: number): Promise<void>;
+    /** Remove a worker incarnation (graceful shutdown). */
+    expireWorker(workerKey: string): Promise<void>;
+    /** Worker keys whose database lease is still fresh (alive cross-process). */
+    freshLeaseWorkerKeys(): Promise<Set<string>>;
+    /** Delete worker rows whose lease expired more than `graceMs` ago. */
+    pruneExpired(graceMs: number): Promise<void>;
+}
+export default SmrtWorker;
+//# sourceMappingURL=smrt-worker.d.ts.map

package/dist/smrt-worker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"smrt-worker.d.ts","sourceRoot":"","sources":["../src/smrt-worker.ts"],"names":[],"mappings":"AAEA,OAAO,wBAAwB,CAAC;AAEhC,OAAO,EAEL,cAAc,EACd,UAAU,EAEX,MAAM,0BAA0B,CAAC;AAElC;;;;;;;;;;;;;;;;;;;GAmBG;AACH,qBAOa,UAAW,SAAQ,UAAU;IACxC,+EAA+E;IAE/E,QAAQ,EAAE,MAAM,CAAM;IAEtB,uDAAuD;IAEvD,GAAG,EAAE,MAAM,GAAG,IAAI,CAAQ;IAE1B,kDAAkD;IAElD,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAQ;IAE/B,qCAAqC;IAErC,SAAS,EAAE,IAAI,GAAG,IAAI,CAAQ;IAE9B,0EAA0E;IAE1E,WAAW,EAAE,IAAI,GAAG,IAAI,CAAQ;IAEhC,sEAAsE;IAEtE,cAAc,EAAE,IAAI,GAAG,IAAI,CAAQ;IAEnC,mEAAmE;IAEnE,MAAM,EAAE,MAAM,CAAa;CAC5B;AAED,MAAM,WAAW,mBAAmB;IAClC,SAAS,EAAE,MAAM,CAAC;IAClB,GAAG,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;GAEG;AACH,qBAAa,oBAAqB,SAAQ,cAAc,CAAC,UAAU,CAAC;IAClE,MAAM,CAAC,QAAQ,CAAC,UAAU,oBAAc;IAExC;;;;;;;OAOG;IACG,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC;IAYlC,qFAAqF;IAC/E,UAAU,IAAI,OAAO,CAAC,OAAO,CAAC;IASpC,0EAA0E;IACpE,cAAc,CAAC,KAAK,EAAE,mBAAmB,GAAG,OAAO,CAAC,IAAI,CAAC;IAe/D,6CAA6C;IACvC,UAAU,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAatE,uDAAuD;IACjD,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAOpD,6EAA6E;IACvE,oBAAoB,IAAI,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;IAelD,sEAAsE;IAChE,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CASnD;AAED,eAAe,UAAU,CAAC"}

package/dist/stale-recovery.d.ts

@@ -0,0 +1,34 @@
+export declare const DEFAULT_TASK_HEARTBEAT_INTERVAL_MS = 30000;
+/**
+ * Default cadence for renewing a worker's liveness lease.
+ *
+ * Liveness is a per-*worker* lease (see {@link ../smrt-worker.js}), not a
+ * per-job heartbeat. The runner renews its lease on this interval; a dead
+ * worker stops renewing and its lease expires after {@link DEFAULT_LEASE_TTL_MS}.
+ */
+export declare const DEFAULT_LEASE_TICK_MS = 10000;
+/**
+ * Default time-to-live for a worker liveness lease.
+ *
+ * A `running` job is only recovered when its owning worker is neither live in
+ * this process nor holding a fresh lease in the database. The TTL is the
+ * cross-process detection latency for a genuinely dead worker.
+ */
+export declare const DEFAULT_LEASE_TTL_MS = 30000;
+/**
+ * Keep stale-job recovery aligned with the actual heartbeat cadence.
+ *
+ * @deprecated Recovery no longer keys on per-job heartbeat staleness (#1474);
+ * it keys on worker liveness. Retained for one release for any external caller.
+ * Use {@link getEffectiveLeaseTtlMs} with the lease tick instead.
+ */
+export declare function getEffectiveStaleJobThresholdMs(staleJobThresholdMs: number, heartbeatIntervalMs: number): number;
+/**
+ * Never let a lease expire in fewer than three renewal ticks.
+ *
+ * A single missed renewal (GC pause, a slow database round-trip) must not be
+ * enough to declare a healthy worker dead. Mirrors the floor applied by
+ * {@link getEffectiveStaleJobThresholdMs} for the legacy heartbeat path.
+ */
+export declare function getEffectiveLeaseTtlMs(leaseTtlMs: number, leaseTickMs: number): number;
+//# sourceMappingURL=stale-recovery.d.ts.map

package/dist/stale-recovery.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stale-recovery.d.ts","sourceRoot":"","sources":["../src/stale-recovery.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,kCAAkC,QAAQ,CAAC;AAGxD;;;;;;GAMG;AACH,eAAO,MAAM,qBAAqB,QAAQ,CAAC;AAE3C;;;;;;GAMG;AACH,eAAO,MAAM,oBAAoB,QAAQ,CAAC;AAI1C;;;;;;GAMG;AACH,wBAAgB,+BAA+B,CAC7C,mBAAmB,EAAE,MAAM,EAC3B,mBAAmB,EAAE,MAAM,GAC1B,MAAM,CAKR;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CACpC,UAAU,EAAE,MAAM,EAClB,WAAW,EAAE,MAAM,GAClB,MAAM,CAER"}