@happyvertical/smrt-jobs 0.55.4 → 0.55.6

package/AGENTS.md

@@ -144,6 +144,26 @@ change what the agents runtime will dispatch.
   every sibling method. Adding the decorator to one method of an existing class
   is therefore a behaviour change for the rest of it.
 
+## Terminal outcomes (#3696)
+
+Terminal state is authoritative together with its versioned event. Completion,
+permanent failure, timeout, stale-worker recovery, and cancellation update the
+owned `_smrt_jobs` row and append the safe `_smrt_job_events` projection in one
+database transaction. If either write fails, neither commits. Conditional
+ownership/status predicates prevent a lost race from appending an event.
+Build the event from the conditional update's returned row, not a caller
+snapshot, and bind that update to the row's tenant. Public cancellation must
+retain ambient-tenant isolation; only explicit bypass contexts may cross it.
+Retries are deliberately excluded until a later terminal transition. Ordinary
+progress, logs, start, and retry telemetry remain best-effort.
+
+`SmrtJobEventCollection.listTerminalOutcomes()` requires an explicit tenant
+(`null` means global), reads newest-first, scans at most 1,000 candidates, and
+returns only the safe versioned terminal shape. Never add job arguments,
+object IDs, results, raw errors, or stacks to that shape. Applications must
+intersect job IDs with their own authorized ownership records; queue/object
+type/method filters narrow the projection but do not authorize it.
+
 ## Retention (#2375)
 
 `_smrt_jobs` and `_smrt_job_events` are append-only in practice — `cleanup()`

package/README.md

@@ -158,6 +158,37 @@ long-running work when possible; make external effects idempotent because a
 process crash after an effect but before its terminal write still permits a
 later retry.
 
+### Read safe terminal outcomes
+
+Completion, permanent failure, timeout, stale-worker recovery, and cancellation
+persist the job's terminal state and a versioned `_smrt_job_events` outcome in
+one database transaction. A retry remains nonterminal and is not projected.
+Ordinary progress and log events remain best-effort telemetry.
+The event uses the row returned by the conditional update, so a concurrent
+claim cannot leave a stale attempt count in history. Public cancellation
+retains the normal ambient-tenant check; explicit system context remains the
+operator bypass.
+
+```typescript
+const events = await SmrtJobEventCollection.create({ db });
+const page = await events.listTerminalOutcomes({
+  tenantId,
+  queues: ['reports'],
+  objectTypes: ['SmrtDataSurfaceActionTask'],
+  methods: ['run'],
+  limit: 100,
+});
+```
+
+The explicit tenant boundary is required; pass `tenantId: null` only for global
+jobs. Results are newest-first and expose job ID, terminal status, queue,
+object type, method, attempt count, completion time, cursor, and the bounded
+failure class `execution`, `timeout`, or `stale-recovery`. They never expose
+arguments, object IDs, results, raw errors, or stacks. Reads inspect at most
+1,000 candidates per page and follow job-event retention (30 days by default).
+Applications must still authorize each job ID against their own durable
+ownership record before displaying it.
+
 ### Schedule recurring jobs with ScheduleRunner
 
 The `ScheduleRunner` polls the `_smrt_agent_schedules` table for due cron entries and creates `SmrtJob` records for the `TaskRunner` to execute. Wire them together via events:
@@ -195,6 +226,7 @@ taskRunner.on('job:failed', (job, error) => {
 |--------|------------|
 | `SmrtJob` | Persistent job record stored in `_smrt_jobs` |
 | `SmrtJobCollection` | Collection with `claimReady()`, `listReady()`, `listByStatus()`, `stats()`, `cleanup()` |
+| `SmrtJobEventCollection` | Durable telemetry plus explicit-tenant `listTerminalOutcomes()` safe projection |
 | `JobBuilder` | Fluent API: `.delay()`, `.priority()`, `.retries()`, `.queue()`, `.timeout()`, `.enqueue()` |
 | `JobHandle` | Track, wait, cancel, or retry an enqueued job |
 | `JobContextLogger` | Logger that auto-injects job context (jobId, attempt, queue) |