@semiont/jobs 0.5.39 → 0.6.1

package/README.md

@@ -48,10 +48,7 @@ const job: PendingJob<DetectionParams> = {
   metadata: {
     id: jobId('job-abc123'),
     type: 'reference-annotation',
-    userId: userId('user@example.com'),
-    userName: 'Jane Doe',
-    userEmail: 'jane@example.com',
-    userDomain: 'example.com',
+    userId: userId('did:web:example.com:users:f47ac10b-58cc-4372-a567-0e02b2c3d479'),
     created: new Date().toISOString(),
     retryCount: 0,
     maxRetries: 1,
@@ -91,10 +88,7 @@ All jobs share common metadata:
 interface JobMetadata {
   id: JobId;
   type: JobType;
-  userId: UserId;
-  userName: string;       // Audit-only snapshot of the requesting user
-  userEmail: string;      // Audit-only snapshot of the requesting user
-  userDomain: string;     // Audit-only snapshot of the requesting user
+  userId: UserId;         // Who requested it — the verified DID, the job's only identity
   created: string;
   retryCount: number;
   maxRetries: number;
@@ -103,7 +97,7 @@ interface JobMetadata {
 }
 ```
 
-The `userName`, `userEmail`, and `userDomain` fields are an audit-only snapshot of the requesting user, persisted in the on-disk job file. Workers derive annotation `creator` attribution from `userId` via `didToAgent()`. `completedUnits` is written only by `failJob`, unioned across attempts, and carried on the `job:fail` event — see Failure discipline below.
+`userId` is the job's only identity — the DID the gateway verified on the `job:create`. The dispatcher records it as the requester when it accepts a claim, and that record is what lets the knowledge base attribute a write citing this job; a worker never states it. `completedUnits` is written only by `failJob`, unioned across attempts, and carried on the `job:fail` event — see Failure discipline below.
 
 ## Annotation Workers
 
@@ -142,7 +136,7 @@ Workers are not subclassed. To add a job type:
 2. Add a `process*Job` function in `src/processors.ts` that runs the inference and returns the annotations/result.
 3. Dispatch the new `jobType` to that processor in `handleJobInner()` in `src/worker-process.ts`.
 
-Processors are transport-agnostic: they take content, an `InferenceClient`, the job params, the user id, the `generator` (W3C SoftwareAgent), and an `onProgress` callback, and return annotations plus a result. The worker process handles claiming, content fetching, and lifecycle event emission.
+Processors are transport-agnostic: they take content, an `InferenceClient`, the job params, a `buildAnnotation` closure (which carries the `generator` — the worker's own `Software` agent), an `onProgress` callback and a per-chunk commit callback, and return a result. No user identity reaches a processor: an annotation states what produced it, and who requested it is derived by the knowledge base from the job the commit cites. The worker process handles claiming, content fetching, committing, and lifecycle event emission.
 
 ## Discriminated Unions
 

package/dist/index.d.ts

@@ -23,17 +23,14 @@ type JobStatus = 'pending' | 'running' | 'complete' | 'failed' | 'cancelled';
 interface JobMetadata {
     id: JobId;
     type: JobType;
-    userId: UserId;
     /**
-     * Audit-only snapshot of the requesting user (with `userEmail` and
-     * `userDomain` below), stamped at job creation and persisted in the
-     * on-disk job file. No code path reads these back — annotation
-     * `creator` attribution is derived from `userId` via `didToAgent()`.
-     * Kept intentionally so job files are self-describing to a human.
+     * Who requested the job: the verified DID the gateway stamped on the
+     * `job:create`, and the ONLY identity a job carries. The dispatcher
+     * records it as the requester on `job:assigned`, which is what lets a
+     * write citing this job be attributed — so nothing else about the
+     * requester needs to travel with the job, or be trusted from it.
      */
-    userName: string;
-    userEmail: string;
-    userDomain: string;
+    userId: UserId;
     created: string;
     retryCount: number;
     maxRetries: number;
@@ -524,7 +521,9 @@ declare class FsJobQueue implements JobQueue {
 
 /**
  * JetStreamJobQueue — the JetStream driver behind the `JobQueue` interface
- * (JOB-QUEUE-DRIVER P1, topology ruling M: gateway-mediated).
+ * (JOB-QUEUE-DRIVER P1, topology ruling M: broker-mediated — the queue's own
+ * process holds the broker connection and the leases; workers never touch the
+ * broker. That process was the gateway; it is the dispatcher now.)
  *
  * Two primitives, one authority each:
  *
@@ -535,12 +534,12 @@ declare class FsJobQueue implements JobQueue {
  *  - **Stream `JOBS`** (subjects `jobs.<category>.<type>`, work-queue
  *    retention) is the DELIVERY vehicle and redelivery timer. A delivered
  *    message is the lease this process holds for a job; `working()`
- *    heartbeats extend it, and a gateway that dies stops heartbeating, so
- *    `AckWait` redelivers the job to a live instance — gateway-death
+ *    heartbeats extend it, and a dispatcher that dies stops heartbeating, so
+ *    `AckWait` redelivers the job to a live instance — dispatcher-death
  *    recovery, protocol-native.
  *
  * Worker-death recovery is NOT AckWait's job under the mediated topology
- * (the gateway holding the lease is alive; the worker vanished): it is the
+ * (the dispatcher holding the lease is alive; the worker vanished): it is the
  * `lastProgressAt` sweep (`recoverStaleRunningJobs`), the same contract the
  * fs driver's mtime janitor implemented. The redelivery handler checks KV
  * state, so the two recovery paths can never double-apply.
@@ -566,6 +565,14 @@ declare const JOBS_STREAM_SUBJECTS: readonly ["jobs.>"];
 interface JetStreamJobQueueOptions {
     /** NATS server address(es), e.g. "192.168.64.42:4222". */
     servers: string | string[];
+    /**
+     * Broker credentials (INTER-COMPONENT-ACCESS P3). The same broker the signal
+     * plane connects to, so the same pair. Absent means an unauthenticated
+     * broker — which is what every deployment had before this, and means anyone
+     * who can reach NATS can read and write the job stream.
+     */
+    user?: string;
+    pass?: string;
     /** Worker presumed dead after this long without progress (default 30 min). */
     staleRunningMs?: number;
     /** Lease redelivery window when THIS process stops heartbeating (default 30 s). */
@@ -597,13 +604,15 @@ declare class JetStreamJobQueue implements JobQueue {
     private readonly tickMs;
     constructor(options: JetStreamJobQueueOptions, logger: Logger, eventBus?: EventBus | undefined);
     initialize(): Promise<void>;
+    /** An outage is never silent: one line down, one line back, one line if the client gives up. */
+    private watchConnection;
     destroy(): void;
     /**
-     * A delivery is a job arriving at this gateway. What it means depends on
+     * A delivery is a job arriving at this dispatcher. What it means depends on
      * the job's authoritative (KV) state:
      *  - pending  → hold the lease, announce for a worker to claim;
      *  - running  → hold silently (a claim raced ahead of the delivery, or a
-     *               redelivery reached a fresh instance after a gateway death);
+     *               redelivery reached a fresh instance after a dispatcher death);
      *  - terminal → the work already concluded elsewhere; consume the message;
      *  - unknown  → not ours to run; terminate it.
      */
@@ -1019,12 +1028,13 @@ declare function generateResourceFromTopic(topic: string, entityTypes: string[],
 
 /**
  * Stall watchdog (WORKER-LIVENESS.md P3) — the fail-fast line behind the
- * inference timeout. There is no poll loop to heartbeat; the honest
- * stall signal in this push-driven architecture is *processing without
- * activity*: an agent holding a claimed job whose `lastActivityAt`
- * (claim / progress / finish) has stopped advancing is wedged — the
- * adapter ignores every announcement while `isProcessing`, so a wedged
- * agent never recovers on its own. Silent hang → loud crash → whatever
+ * inference timeout. There is no poll timer to heartbeat — the worker pulls
+ * when idle, and a parked idle worker is not a stall; the honest stall
+ * signal is *processing without activity*: an agent holding a claimed job
+ * whose `lastActivityAt` (claim / progress / finish) has stopped advancing
+ * is wedged — the adapter defers every wake-up while a job is held and
+ * pulls at settle, so a wedged agent never settles and never recovers on
+ * its own. Silent hang → loud crash → whatever
  * restart policy the deployment chose.
  *
  * Thresholds are fixed by design (no env knobs) and deliberately

package/dist/index.js

@@ -2,7 +2,7 @@ import { promises, mkdtempSync, writeFileSync, readFileSync, rmSync } from 'fs';
 import * as path from 'path';
 import { join } from 'path';
 import { replyChannelsFor, jobId, deriveViews, GENERATABLE_MEDIA_TYPES, estimateTokens, isObject, isString, reconcileSelector, getLocaleEnglishName, cutChunk, chunkText } from '@semiont/core';
-import { connect, RetentionPolicy, DeliverPolicy, AckPolicy, nanos } from 'nats';
+import { connect, RetentionPolicy, DeliverPolicy, AckPolicy, nanos, NatsError } from 'nats';
 import { withSpan, recordAnchorOutcome, recordDetectionCall } from '@semiont/observability';
 import { StructuredReadError } from '@semiont/inference';
 import { execFileSync } from 'child_process';
@@ -556,9 +556,18 @@ var JetStreamJobQueue = class {
   async initialize() {
     this.nc = await connect({
       servers: this.options.servers,
+      // The same broker as the signal plane, so the same credentials. Connect
+      // options rather than a URL: this address is logged on every reconnect.
+      ...this.options.user === void 0 ? {} : { user: this.options.user },
+      ...this.options.pass === void 0 ? {} : { pass: this.options.pass },
       reconnect: this.options.reconnect ?? true,
+      // For as long as the broker is unreachable: a manual broker restart is
+      // the recovery, and the library's ten attempts (~20 s) closed the
+      // signal plane's connection for good in its first live outage.
+      maxReconnectAttempts: -1,
       timeout: 1e4
     });
+    this.watchConnection();
     this.js = this.nc.jetstream();
     this.jsm = await this.nc.jetstreamManager();
     this.kv = await this.js.views.kv(BUCKET);
@@ -625,6 +634,26 @@ var JetStreamJobQueue = class {
     }, this.tickMs);
     this.tick.unref?.();
   }
+  /** An outage is never silent: one line down, one line back, one line if the client gives up. */
+  watchConnection() {
+    const servers = this.options.servers;
+    void (async () => {
+      for await (const status of this.nc.status()) {
+        if (status.type === "disconnect") {
+          this.logger.warn("[jobs BROKER-DOWN] NATS connection lost; queue operations fail until reconnect", { servers });
+        } else if (status.type === "reconnect") {
+          this.logger.info("[jobs BROKER-RECONNECTED] NATS connection restored", { servers });
+        }
+      }
+    })();
+    void this.nc.closed().then((err) => {
+      if (!err) return;
+      this.logger.error("[jobs BROKER-CLOSED] NATS connection closed; the client will not reconnect", {
+        servers,
+        reason: err instanceof NatsError ? err.code : err.message
+      });
+    });
+  }
   destroy() {
     this.iter?.stop();
     this.iter = null;
@@ -636,11 +665,11 @@ var JetStreamJobQueue = class {
     void this.nc?.close();
   }
   /**
-   * A delivery is a job arriving at this gateway. What it means depends on
+   * A delivery is a job arriving at this dispatcher. What it means depends on
    * the job's authoritative (KV) state:
    *  - pending  → hold the lease, announce for a worker to claim;
    *  - running  → hold silently (a claim raced ahead of the delivery, or a
-   *               redelivery reached a fresh instance after a gateway death);
+   *               redelivery reached a fresh instance after a dispatcher death);
    *  - terminal → the work already concluded elsewhere; consume the message;
    *  - unknown  → not ours to run; terminate it.
    */