@graphrefly/graphrefly 0.47.2 → 0.48.0

package/dist/utils/job-queue/index.d.cts

@@ -1,7 +1,7 @@
 import { Node } from '@graphrefly/pure-ts/core';
 import { NodeInput, ReactiveLogBundle, AppendLogStorageTier } from '@graphrefly/pure-ts/extra';
 import { Graph, GraphOptions } from '@graphrefly/pure-ts/graph';
-import { BaseAuditRecord } from '../../base/mutation/index.cjs';
+import { BaseAuditRecord, ReadonlyAuditLog } from '../../base/mutation/index.cjs';
 
 /**
  * Job queue patterns (roadmap §4.2).
@@ -28,6 +28,22 @@ interface JobEvent<T = unknown> extends BaseAuditRecord {
     readonly id: string;
     readonly attempts?: number;
     readonly payload?: T;
+    /**
+     * The failure cause for a no-requeue `"nack"` (F-CATCH D-3). Present only
+     * when a job was nack'd-without-requeue because its work threw
+     * synchronously or its result Node emitted `ERROR`. Without this, a failed
+     * job is observable as a `"nack"` event but the *reason* it failed is
+     * unrecoverable from the event stream. Carries the raw thrown value /
+     * ERROR payload (not normalized) so callers keep full fidelity.
+     *
+     * Caveats: a thrown `undefined` (legal but pathological) is not recorded —
+     * it carries no diagnostic payload and the `"nack"` action itself already
+     * surfaces the failure. And like {@link JobEvent.payload}, a raw `Error` is
+     * not JSON-round-trippable, so keyed-storage codecs wired via
+     * `attachEventStorage` should normalize this field (e.g. capture
+     * `message`/`stack`) before serializing.
+     */
+    readonly error?: unknown;
 }
 /** Recommended `keyOf` for keyed-storage adapters (Audit 2 #7). */
 declare const jobEventKeyOf: <T>(e: JobEvent<T>) => string;
@@ -43,8 +59,11 @@ declare class JobQueueGraph<T> extends Graph {
     readonly depth: Node<number>;
     /** Audit log of every queue mutation (Audit 2). */
     readonly events: ReactiveLogBundle<JobEvent<T>>;
-    /** Alias for {@link JobQueueGraph.events} — Audit 2 `.audit` duplication. */
-    readonly audit: ReactiveLogBundle<JobEvent<T>>;
+    /**
+     * Read-only view of {@link JobQueueGraph.events} — Audit 2 `.audit`
+     * duplication; M7 (cannot mutate the canonical log via the alias).
+     */
+    readonly audit: ReadonlyAuditLog<JobEvent<T>>;
     private readonly _enqueueImpl;
     private readonly _ackImpl;
     private readonly _nackImpl;
@@ -62,8 +81,19 @@ declare class JobQueueGraph<T> extends Graph {
     }): string;
     claim(limit?: number): readonly JobEnvelope<T>[];
     ack(id: string): boolean;
+    /**
+     * Negatively-acknowledge an inflight job.
+     *
+     * @param opts.requeue - `true` (default) returns the job to the queue for
+     *   retry; `false` drops it permanently (terminal failure).
+     * @param opts.error - Optional failure cause for a `requeue: false` nack.
+     *   Recorded on the emitted `"nack"` {@link JobEvent} as `error` so the
+     *   reason a job failed is recoverable from the event stream (F-CATCH
+     *   D-3). Ignored when `requeue` is `true` (a retry is not a failure).
+     */
     nack(id: string, opts?: {
         requeue?: boolean;
+        error?: unknown;
     }): boolean;
     /**
      * Remove a job by id regardless of its current state. Returns `true` if

package/dist/utils/job-queue/index.d.ts

@@ -1,7 +1,7 @@
 import { Node } from '@graphrefly/pure-ts/core';
 import { NodeInput, ReactiveLogBundle, AppendLogStorageTier } from '@graphrefly/pure-ts/extra';
 import { Graph, GraphOptions } from '@graphrefly/pure-ts/graph';
-import { BaseAuditRecord } from '../../base/mutation/index.js';
+import { BaseAuditRecord, ReadonlyAuditLog } from '../../base/mutation/index.js';
 
 /**
  * Job queue patterns (roadmap §4.2).
@@ -28,6 +28,22 @@ interface JobEvent<T = unknown> extends BaseAuditRecord {
     readonly id: string;
     readonly attempts?: number;
     readonly payload?: T;
+    /**
+     * The failure cause for a no-requeue `"nack"` (F-CATCH D-3). Present only
+     * when a job was nack'd-without-requeue because its work threw
+     * synchronously or its result Node emitted `ERROR`. Without this, a failed
+     * job is observable as a `"nack"` event but the *reason* it failed is
+     * unrecoverable from the event stream. Carries the raw thrown value /
+     * ERROR payload (not normalized) so callers keep full fidelity.
+     *
+     * Caveats: a thrown `undefined` (legal but pathological) is not recorded —
+     * it carries no diagnostic payload and the `"nack"` action itself already
+     * surfaces the failure. And like {@link JobEvent.payload}, a raw `Error` is
+     * not JSON-round-trippable, so keyed-storage codecs wired via
+     * `attachEventStorage` should normalize this field (e.g. capture
+     * `message`/`stack`) before serializing.
+     */
+    readonly error?: unknown;
 }
 /** Recommended `keyOf` for keyed-storage adapters (Audit 2 #7). */
 declare const jobEventKeyOf: <T>(e: JobEvent<T>) => string;
@@ -43,8 +59,11 @@ declare class JobQueueGraph<T> extends Graph {
     readonly depth: Node<number>;
     /** Audit log of every queue mutation (Audit 2). */
     readonly events: ReactiveLogBundle<JobEvent<T>>;
-    /** Alias for {@link JobQueueGraph.events} — Audit 2 `.audit` duplication. */
-    readonly audit: ReactiveLogBundle<JobEvent<T>>;
+    /**
+     * Read-only view of {@link JobQueueGraph.events} — Audit 2 `.audit`
+     * duplication; M7 (cannot mutate the canonical log via the alias).
+     */
+    readonly audit: ReadonlyAuditLog<JobEvent<T>>;
     private readonly _enqueueImpl;
     private readonly _ackImpl;
     private readonly _nackImpl;
@@ -62,8 +81,19 @@ declare class JobQueueGraph<T> extends Graph {
     }): string;
     claim(limit?: number): readonly JobEnvelope<T>[];
     ack(id: string): boolean;
+    /**
+     * Negatively-acknowledge an inflight job.
+     *
+     * @param opts.requeue - `true` (default) returns the job to the queue for
+     *   retry; `false` drops it permanently (terminal failure).
+     * @param opts.error - Optional failure cause for a `requeue: false` nack.
+     *   Recorded on the emitted `"nack"` {@link JobEvent} as `error` so the
+     *   reason a job failed is recoverable from the event stream (F-CATCH
+     *   D-3). Ignored when `requeue` is `true` (a retry is not a failure).
+     */
     nack(id: string, opts?: {
         requeue?: boolean;
+        error?: unknown;
     }): boolean;
     /**
      * Remove a job by id regardless of its current state. Returns `true` if

package/dist/utils/job-queue/index.js

@@ -4,9 +4,9 @@ import {
   jobEventKeyOf,
   jobFlow,
   jobQueue
-} from "../../chunk-PKPO3JTZ.js";
+} from "../../chunk-AQAKDE7F.js";
 import "../../chunk-FMPF42Q4.js";
-import "../../chunk-BXGZFGZ4.js";
+import "../../chunk-C5QD5DQX.js";
 import "../../chunk-AZDQPQ3V.js";
 export {
   JobFlowGraph,