@graphrefly/graphrefly 0.44.0 → 0.45.0

package/dist/index-DisjX8a-.d.ts

@@ -1,221 +0,0 @@
-import { N as Node } from './node-kK3CvTrR.js';
-import { B as BaseAuditRecord } from './index-Yq60JP3s.js';
-import { a as ReactiveLogBundle } from './reactive-log-BKALbfal.js';
-import { NodeInput } from './extra/sources.js';
-import { AppendLogStorageTier } from './extra/storage-tiers.js';
-import { G as Graph, a as GraphOptions } from './graph-D9LFnda9.js';
-
-/**
- * Job queue patterns (roadmap §4.2).
- *
- * Queue / flow primitives modeled as graph factories:
- * - `jobQueue()` — claim/ack/nack workflow with reactive depth.
- * - `jobFlow()` — multi-stage queue chain.
- *
- * Topic / subscription / hub primitives live in `patterns/messaging`.
- */
-
-type JobState = "queued" | "inflight";
-type JobEnvelope<T> = {
-    id: string;
-    payload: T;
-    attempts: number;
-    metadata: Readonly<Record<string, unknown>>;
-    state: JobState;
-};
-/** Audit record for a job-queue mutation (Audit 2 cross-cutting). */
-type JobEventAction = "enqueue" | "claim" | "ack" | "nack" | "remove";
-interface JobEvent<T = unknown> extends BaseAuditRecord {
-    readonly action: JobEventAction;
-    readonly id: string;
-    readonly attempts?: number;
-    readonly payload?: T;
-}
-/** Recommended `keyOf` for keyed-storage adapters (Audit 2 #7). */
-declare const jobEventKeyOf: <T>(e: JobEvent<T>) => string;
-type JobQueueOptions = {
-    graph?: GraphOptions;
-};
-declare class JobQueueGraph<T> extends Graph {
-    private readonly _pending;
-    private readonly _jobs;
-    private readonly _seqCursor;
-    readonly pending: Node<readonly string[]>;
-    readonly jobs: Node<ReadonlyMap<string, JobEnvelope<T>>>;
-    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>>;
-    private readonly _enqueueImpl;
-    private readonly _ackImpl;
-    private readonly _nackImpl;
-    private readonly _removeByIdImpl;
-    constructor(name: string, opts?: JobQueueOptions);
-    /**
-     * Wire append-log storage tiers (Audit 4). Returns a disposer.
-     *
-     * Named `attachEventStorage` to avoid colliding with {@link Graph.attachSnapshotStorage}.
-     */
-    attachEventStorage(tiers: readonly AppendLogStorageTier<JobEvent<T>>[]): () => void;
-    enqueue(payload: T, opts?: {
-        id?: string;
-        metadata?: Record<string, unknown>;
-    }): string;
-    claim(limit?: number): readonly JobEnvelope<T>[];
-    ack(id: string): boolean;
-    nack(id: string, opts?: {
-        requeue?: boolean;
-    }): boolean;
-    /**
-     * Remove a job by id regardless of its current state. Returns `true` if
-     * the job existed and was removed, `false` if no job has this id.
-     *
-     * `ack` only works on inflight; `nack` only works on inflight.
-     * `removeById` is the state-agnostic escape hatch — useful for
-     * audit/observability layers that enqueue but never claim, and need to
-     * finalize a job when an external decision (e.g. harness verify
-     * outcome) resolves it. Distinct name from the inherited
-     * {@link Graph.remove}, which removes a mounted child subgraph by path.
-     *
-     * When the job is in `queued` state, its id is also pulled from the
-     * `pending` list — depth + pending snapshot stay consistent.
-     */
-    removeById(id: string): boolean;
-    /**
-     * Subscribe to a Node and enqueue each DATA payload into this queue.
-     * Returns a disposer that stops consuming when called.
-     *
-     * Used internally by {@link JobFlowGraph} for stage-to-stage wiring but
-     * also useful for users wiring an external source into a job queue.
-     *
-     * @param source - Node whose DATA values are enqueued.
-     * @param opts - Optional enqueue options (id generator, metadata prefix).
-     */
-    consumeFrom(source: Node<T>, opts?: {
-        metadata?: Record<string, unknown>;
-    }): () => void;
-}
-/**
- * Work function for a job flow stage. Receives the full job envelope and
- * an optional per-claim options object carrying an `AbortSignal`; returns
- * a `NodeInput<T>` — raw value (sync), Promise (async), or Node (composed
- * pipeline). `fromAny` coerces any of these shapes.
- *
- * On error / rejection: the stage nacks the job (no requeue by default).
- *
- * **Per-claim signal (Tier 6.5 2.5b, 2026-04-29).** The pump mints an
- * `AbortController` per claim and supplies its `signal` via `opts`. The
- * signal aborts when (a) the result node settles (first DATA / first
- * ERROR — auto-cleanup after the pump captures), OR (b) the pump itself
- * tears down (e.g. parent Graph `destroy()`). User-supplied work fns that
- * do long-running async (HTTP, LLM streams, evaluator subgraphs) can
- * forward this signal into `fetch({ signal })`, `adapter.invoke({ signal
- * })`, etc. for cooperative cancellation. Sync work fns ignore `opts` —
- * the second arg is optional, no behavior change for legacy callers.
- *
- * Mirrors the `LLMInvokeOptions.signal` / `apply(item, { signal })` /
- * tool-handler `(args, { signal })` precedents — same shape across the
- * library's user-callback boundaries.
- */
-type WorkFn<T> = (job: JobEnvelope<T>, opts?: {
-    signal: AbortSignal;
-}) => NodeInput<T>;
-/**
- * Stage definition for {@link JobFlowGraph}. Either a bare name string
- * (no work hook, pure pass-through) or a full definition object.
- */
-type StageDef<T> = string | {
-    name: string;
-    work?: WorkFn<T>;
-    handlerVersion?: {
-        id: string;
-        version: string | number;
-    };
-    /**
-     * Per-stage cap on `claim → work → ack` cycles per pump tick.
-     * Overrides {@link JobFlowOptions.maxPerPump} for this stage. Useful
-     * when stages have asymmetric cost (e.g. an LLM-execute stage capped
-     * at 4 concurrent calls while a cheap verify stage runs unbounded).
-     *
-     * Falls back to the top-level `JobFlowOptions.maxPerPump`, which in
-     * turn falls back to `DEFAULT_MAX_PER_PUMP` (256).
-     */
-    maxPerPump?: number;
-    /**
-     * Per-stage cap on TOTAL concurrent inflight claims (Tier 6.5 3.1,
-     * 2026-04-29). Distinct from {@link maxPerPump}: `maxPerPump` caps
-     * claims per pump tick, while `maxInflight` caps the number of
-     * unsettled in-flight claims at any moment across all ticks. Use
-     * for rigorous LLM cost ceilings (e.g. "no more than 4 concurrent
-     * adapter.invoke calls regardless of pending depth").
-     *
-     * When set, the stage mounts an internal `state(0)` counter as a
-     * pump dep so the pump re-fires on each settle — pending items
-     * resume claiming as soon as inflight drops below the cap.
-     *
-     * Unset (default): unbounded inflight, gated only by `maxPerPump`.
-     */
-    maxInflight?: number;
-};
-type JobFlowOptions<T = unknown> = {
-    graph?: GraphOptions;
-    /**
-     * Stage definitions. Each stage is either a bare name string (pure
-     * pass-through) or a `{ name, work?, handlerVersion?, maxPerPump? }` object.
-     *
-     * For back-compat, `string[]` values behave as stages with no work hook.
-     */
-    stages?: readonly StageDef<T>[];
-    /**
-     * Default cap on claims per pump tick across all stages. Per-stage
-     * overrides can be set on each {@link StageDef.maxPerPump}; if neither is
-     * set, falls back to `DEFAULT_MAX_PER_PUMP` (256).
-     */
-    maxPerPump?: number;
-};
-declare class JobFlowGraph<T> extends Graph {
-    private readonly _stageNames;
-    private readonly _stageWorkFns;
-    private readonly _queues;
-    private readonly _completed;
-    readonly completed: Node<readonly JobEnvelope<T>[]>;
-    readonly completedCount: Node<number>;
-    constructor(name: string, opts?: JobFlowOptions<T>);
-    stages(): readonly string[];
-    queue(stage: string): JobQueueGraph<T>;
-    enqueue(payload: T, opts?: {
-        id?: string;
-        metadata?: Record<string, unknown>;
-    }): string;
-    retainedCompleted(): readonly JobEnvelope<T>[];
-}
-/**
- * Creates a Pulsar-inspired job queue graph with claim/ack/nack workflow.
- */
-declare function jobQueue<T>(name: string, opts?: JobQueueOptions): JobQueueGraph<T>;
-/**
- * Creates an autonomous multi-stage queue chain graph.
- */
-declare function jobFlow<T>(name: string, opts?: JobFlowOptions<T>): JobFlowGraph<T>;
-
-type index_JobEnvelope<T> = JobEnvelope<T>;
-type index_JobEvent<T = unknown> = JobEvent<T>;
-type index_JobEventAction = JobEventAction;
-type index_JobFlowGraph<T> = JobFlowGraph<T>;
-declare const index_JobFlowGraph: typeof JobFlowGraph;
-type index_JobFlowOptions<T = unknown> = JobFlowOptions<T>;
-type index_JobQueueGraph<T> = JobQueueGraph<T>;
-declare const index_JobQueueGraph: typeof JobQueueGraph;
-type index_JobQueueOptions = JobQueueOptions;
-type index_JobState = JobState;
-type index_StageDef<T> = StageDef<T>;
-type index_WorkFn<T> = WorkFn<T>;
-declare const index_jobEventKeyOf: typeof jobEventKeyOf;
-declare const index_jobFlow: typeof jobFlow;
-declare const index_jobQueue: typeof jobQueue;
-declare namespace index {
-  export { type index_JobEnvelope as JobEnvelope, type index_JobEvent as JobEvent, type index_JobEventAction as JobEventAction, index_JobFlowGraph as JobFlowGraph, type index_JobFlowOptions as JobFlowOptions, index_JobQueueGraph as JobQueueGraph, type index_JobQueueOptions as JobQueueOptions, type index_JobState as JobState, type index_StageDef as StageDef, type index_WorkFn as WorkFn, index_jobEventKeyOf as jobEventKeyOf, index_jobFlow as jobFlow, index_jobQueue as jobQueue };
-}
-
-export { type JobEnvelope as J, type StageDef as S, type WorkFn as W, JobFlowGraph as a, JobQueueGraph as b, type JobEvent as c, type JobEventAction as d, type JobFlowOptions as e, type JobQueueOptions as f, type JobState as g, jobFlow as h, index as i, jobEventKeyOf as j, jobQueue as k };