@graphrefly/graphrefly 0.34.0 → 0.35.0

package/dist/{index-RJX4snyi.d.cts → index-BlRVj-7Q.d.cts}

@@ -1,6 +1,6 @@
-import { j as CompileSpecOptions, G as GraphSpec, c as GraphSpecCatalog, C as CatalogFnEntry, a as CatalogSourceEntry, b as ConfigFieldSchema, F as FnFactory, d as GraphSpecFeedbackEdge, e as GraphSpecNode, f as GraphSpecTemplate, g as GraphSpecTemplateRef, h as GraphSpecValidation, S as SourceFactory } from './index-BkfL5MXh.cjs';
-import { G as Graph, o as GraphNodeFactory, m as GraphDiffResult } from './graph-DaoydJ_u.cjs';
-import { StorageTier } from './extra/storage-core.cjs';
+import { j as CompileSpecOptions, G as GraphSpec, c as GraphSpecCatalog, C as CatalogFnEntry, a as CatalogSourceEntry, b as ConfigFieldSchema, F as FnFactory, d as GraphSpecFeedbackEdge, e as GraphSpecNode, f as GraphSpecTemplate, g as GraphSpecTemplateRef, h as GraphSpecValidation, S as SourceFactory } from './index-BWH17rK_.cjs';
+import { G as Graph, o as GraphNodeFactory, m as GraphDiffResult } from './graph-kTltt95s.cjs';
+import { KvStorageTier } from './extra/storage-tiers.cjs';
 
 /**
  * Surface: create a graph from a {@link GraphSpec} (§9.3-core).
@@ -121,15 +121,15 @@ interface ReduceOptions {
 declare function runReduction(spec: GraphSpec, input: unknown, opts?: ReduceOptions): Promise<unknown>;
 
 /**
- * Surface: snapshot save/restore/diff/list over {@link StorageTier} (§9.3-core).
+ * Surface: snapshot save/restore/diff/list over {@link KvStorageTier} (§9.3-core).
  *
  * One-shot snapshot management for stateless callers (MCP tools, CLI
  * commands) layered on the existing multi-tier auto-checkpoint substrate.
  * A saved snapshot is a `mode: "full"` {@link GraphCheckpointRecord} with
  * `seq: 0` — byte-identical to the baseline anchor
- * {@link Graph.attachStorage} writes on its first flush. An
+ * {@link Graph.attachSnapshotStorage} writes on its first flush. An
  * auto-checkpointed graph can therefore be restored through this surface,
- * and a surface-saved snapshot can be picked up by `attachStorage({
+ * and a surface-saved snapshot can be picked up by `attachSnapshotStorage({
  * autoRestore: true })`.
  *
  * The wire envelope stays at {@link SNAPSHOT_WIRE_VERSION}; no new format.
@@ -139,7 +139,7 @@ declare function runReduction(spec: GraphSpec, input: unknown, opts?: ReduceOpti
 
 /**
  * Current envelope version. Re-exported from `graph.ts` so the one-shot
- * surface path and `Graph.attachStorage` write byte-identical
+ * surface path and `Graph.attachSnapshotStorage` write byte-identical
  * `format_version` fields — no silent wire drift.
  */
 declare const SNAPSHOT_WIRE_VERSION = 1;
@@ -157,11 +157,11 @@ interface RestoreSnapshotOptions {
  * Write a graph's current state as a one-shot `mode: "full"` record.
  *
  * Uses the same {@link GraphCheckpointRecord} envelope as
- * {@link Graph.attachStorage} so the two persistence paths interoperate.
+ * {@link Graph.attachSnapshotStorage} so the two persistence paths interoperate.
  *
  * @throws {SurfaceError} `snapshot-failed` when the tier's `save` throws.
  */
-declare function saveSnapshot(graph: Graph, snapshotId: string, tier: StorageTier): Promise<SaveSnapshotResult>;
+declare function saveSnapshot(graph: Graph, snapshotId: string, tier: KvStorageTier): Promise<SaveSnapshotResult>;
 /**
  * Load a snapshot from a tier and materialize it as a new {@link Graph}.
  *
@@ -171,18 +171,18 @@ declare function saveSnapshot(graph: Graph, snapshotId: string, tier: StorageTie
  *
  * **Requires a `mode: "full"` record.** Surface-written snapshots from
  * {@link saveSnapshot} always qualify. Records written by
- * {@link Graph.attachStorage} with `compactEvery > 1` may be
+ * {@link Graph.attachSnapshotStorage} with `compactEvery > 1` may be
  * `mode: "diff"` between compacts — those throw `restore-failed` until
  * the tier's next compact flush (or until Phase 8.7 WAL replay lands).
  * If you need interop during development, either call
  * {@link saveSnapshot} explicitly (always full) or configure
- * `attachStorage({compactEvery: 1})`.
+ * `attachSnapshotStorage({compactEvery: 1})`.
  *
  * @throws {SurfaceError} `snapshot-not-found` on miss; `restore-failed`
  *   when the payload shape doesn't match, when the record is
  *   `mode: "diff"`, or when `Graph.fromSnapshot` rejects.
  */
-declare function restoreSnapshot(snapshotId: string, tier: StorageTier, opts?: RestoreSnapshotOptions): Promise<Graph>;
+declare function restoreSnapshot(snapshotId: string, tier: KvStorageTier, opts?: RestoreSnapshotOptions): Promise<Graph>;
 /**
  * Load two snapshots and compute a {@link GraphDiffResult} via static
  * {@link Graph.diff}. Returns the audit shape (structural + value diff,
@@ -190,37 +190,37 @@ declare function restoreSnapshot(snapshotId: string, tier: StorageTier, opts?: R
  *
  * @throws {SurfaceError} `snapshot-not-found` on either miss.
  */
-declare function diffSnapshots(snapshotIdA: string, snapshotIdB: string, tier: StorageTier): Promise<GraphDiffResult>;
+declare function diffSnapshots(snapshotIdA: string, snapshotIdB: string, tier: KvStorageTier): Promise<GraphDiffResult>;
 /**
  * Enumerate snapshot ids on a tier.
  *
  * Only keys written by {@link saveSnapshot} are returned. Surface-written
  * records are stored under the `"snapshot:"` key prefix and decoded back to
  * the caller-visible id before being returned — other keys on the same tier
- * (notably `attachStorage` baseline/WAL keys written under `graph.name`) are
+ * (notably `attachSnapshotStorage` baseline/WAL keys written under `graph.name`) are
  * filtered out automatically. This lets a single tier back both the surface
- * and `attachStorage` without leaking graph names through `listSnapshots`.
+ * and `attachSnapshotStorage` without leaking graph names through `listSnapshots`.
  *
  * @param tier — the storage tier to enumerate.
  * @param opts.includeUnprefixed — when `true`, also return keys that are
  *   NOT under the namespacing prefix. Off by default; set this when reading
  *   pre-namespacing snapshot sets.
  *
- *   **Caveat:** when a tier is shared with {@link Graph.attachStorage}, its
+ *   **Caveat:** when a tier is shared with {@link Graph.attachSnapshotStorage}, its
  *   auto-checkpoint baseline + WAL keys (written under `graph.name`) are
  *   unprefixed. Calling with `includeUnprefixed: true` returns those keys
  *   alongside surface snapshots — and subsequent `restoreSnapshot` /
  *   `deleteSnapshot` will operate on them via the fallback-lookup path,
  *   potentially overwriting or deleting live auto-checkpoint state. Use
  *   `includeUnprefixed` only against tiers you know are NOT shared with
- *   `attachStorage`, or follow up with a predicate filter to separate
+ *   `attachSnapshotStorage`, or follow up with a predicate filter to separate
  *   ids you own from ones owned by other subsystems.
  *
  * @throws {SurfaceError} `tier-no-list` when the tier does not implement
  *   the optional `list()` method. Check `typeof tier.list === "function"`
  *   before calling if you want to branch on capability.
  */
-declare function listSnapshots(tier: StorageTier, opts?: {
+declare function listSnapshots(tier: KvStorageTier, opts?: {
     includeUnprefixed?: boolean;
 }): Promise<readonly string[]>;
 /**
@@ -232,7 +232,7 @@ declare function listSnapshots(tier: StorageTier, opts?: {
  * @throws {SurfaceError} `snapshot-failed` when `clear` is unsupported
  *   or throws.
  */
-declare function deleteSnapshot(snapshotId: string, tier: StorageTier): Promise<void>;
+declare function deleteSnapshot(snapshotId: string, tier: KvStorageTier): Promise<void>;
 
 /**
  * Surface layer (§9.3-core) — shared, JSON-safe operations consumed by
@@ -245,8 +245,8 @@ declare function deleteSnapshot(snapshotId: string, tier: StorageTier): Promise<
  * 1. {@link createGraph} — `compileSpec` wrapped with typed surface errors.
  * 2. {@link reduce} — one-shot `input → pipeline → output`.
  *
- * Snapshot persistence reuses the {@link StorageTier} substrate introduced
- * for `Graph.attachStorage`, so one-shot snapshots and auto-checkpoints
+ * Snapshot persistence reuses the {@link KvStorageTier} substrate introduced
+ * for `Graph.attachSnapshotStorage`, so one-shot snapshots and auto-checkpoints
  * share the {@link GraphCheckpointRecord} envelope. No new wire format.
  *
  * Errors throw as {@link SurfaceError} — wrappers map to their native

package/dist/index-BpFwRAf9.d.cts

@@ -0,0 +1,26 @@
+import { C as CatchOptions, a as ClassifyResult, D as Decision, b as DecisionAction, G as GateController, c as GateOptions, P as PipelineGraph, S as StepRef, T as TerminalCause, d as decisionKeyOf, p as pipelineGraph } from './pipeline-graph-B85HUrWg.cjs';
+
+/**
+ * Orchestration patterns (roadmap §4.1).
+ *
+ * Domain-layer helpers that build workflow shapes on top of core + extra primitives.
+ * Exported under the `patterns.orchestration` namespace to avoid collisions with
+ * Phase 2 operator names (for example `gate`, `forEach`).
+ */
+
+declare const index_CatchOptions: typeof CatchOptions;
+declare const index_ClassifyResult: typeof ClassifyResult;
+declare const index_Decision: typeof Decision;
+declare const index_DecisionAction: typeof DecisionAction;
+declare const index_GateController: typeof GateController;
+declare const index_GateOptions: typeof GateOptions;
+declare const index_PipelineGraph: typeof PipelineGraph;
+declare const index_StepRef: typeof StepRef;
+declare const index_TerminalCause: typeof TerminalCause;
+declare const index_decisionKeyOf: typeof decisionKeyOf;
+declare const index_pipelineGraph: typeof pipelineGraph;
+declare namespace index {
+  export { index_CatchOptions as CatchOptions, index_ClassifyResult as ClassifyResult, index_Decision as Decision, index_DecisionAction as DecisionAction, index_GateController as GateController, index_GateOptions as GateOptions, index_PipelineGraph as PipelineGraph, index_StepRef as StepRef, index_TerminalCause as TerminalCause, index_decisionKeyOf as decisionKeyOf, index_pipelineGraph as pipelineGraph };
+}
+
+export { index as i };

package/dist/{index-Ds3Rz9m9.d.cts → index-BsZlbHM5.d.cts}

@@ -1,6 +1,6 @@
-import { a as Node } from './node-8qx0kgYt.cjs';
-import { S as StatusValue, C as CircuitState, R as RateLimiterOptions, a as CircuitBreakerOptions, b as RetryOptions, F as FallbackInput, N as NS_PER_MS, c as NS_PER_SEC } from './resilience-N_VtLf7W.cjs';
-import { B as BudgetConstraint } from './index-yJY9thRY.cjs';
+import { a as Node } from './node-fSc-hCv8.cjs';
+import { S as StatusValue, C as CircuitState, R as RateLimiterOptions, a as CircuitBreakerOptions, b as RetryOptions, F as FallbackInput, N as NS_PER_MS, c as NS_PER_SEC } from './resilience-BWP2c7Af.cjs';
+import { B as BudgetConstraint } from './index-XxSeddWP.cjs';
 
 /**
  * Resilience composition with correct nesting order (roadmap §9.0b).

package/dist/{index-BFHpNSsV.d.ts → index-BtY2QVDf.d.cts}

@@ -1,9 +1,10 @@
-import { T as ToObservableOptions, t as toObservable } from './observable-DOniYM2B.js';
+import { T as ToObservableOptions, t as toObservable } from './observable-Cqty11jG.cjs';
 import { OnModuleInit, OnModuleDestroy, ExecutionContext, CanActivate, DynamicModule } from '@nestjs/common';
 import { ModuleRef } from '@nestjs/core';
-import { G as Graph, d as GraphPersistSnapshot } from './graph-BROUZPG9.js';
-import { A as Actor } from './node-8qx0kgYt.js';
-import { C as CqrsOptions, a as CqrsGraph, E as EventStoreAdapter } from './index-Cq7Uqgu4.js';
+import { G as Graph, b as GraphPersistSnapshot } from './graph-kTltt95s.cjs';
+import { A as Actor } from './node-fSc-hCv8.cjs';
+import { c as CqrsOptions, b as CqrsGraph, a as CqrsEvent } from './index-zK_mN1D-.cjs';
+import { AppendLogStorageTier } from './extra/storage-tiers.cjs';
 
 /** Class constructor key for decorator registries and Nest `ModuleRef.get()`. */
 type DecoratorHostConstructor = abstract new (...args: unknown[]) => unknown;
@@ -599,8 +600,8 @@ interface GraphReflyCqrsOptions {
     cqrs?: CqrsOptions;
     /** Build callback — registers commands, events, projections, sagas on the CqrsGraph. */
     build?: (graph: CqrsGraph) => void;
-    /** Event store adapter for persistence (wired via `useEventStore()`). */
-    eventStore?: EventStoreAdapter;
+    /** Append-log storage tiers for event persistence (wired via `attachEventStorage()`). */
+    eventStorage?: readonly AppendLogStorageTier<CqrsEvent>[];
     /**
      * Node paths (local to this feature) to expose as injectable providers.
      * Tokens are auto-qualified as `featureName::path`.
@@ -665,7 +666,7 @@ declare class GraphReflyModule {
      *   name: "orders",
      *   build: (g) => {
      *     g.event("orderPlaced");
-     *     g.projection("orderCount", ["orderPlaced"], (_s, evts) => evts.length, 0);
+     *     g.projection({ name: "orderCount", events: ["orderPlaced"], reducer: (_s, evts) => evts.length, initial: 0 });
      *   },
      * })
      * ```

package/dist/{index-BsxqmV6u.d.ts → index-BuMzxRO2.d.ts}

@@ -1,5 +1,5 @@
-import { a as Node } from './node-8qx0kgYt.js';
-import { a as GraphOptions, G as Graph } from './graph-BROUZPG9.js';
+import { a as Node } from './node-fSc-hCv8.js';
+import { a as GraphOptions, G as Graph } from './graph-Cv-8x0ZI.js';
 
 /**
  * Domain templates (roadmap §8.2).

package/dist/{index-C5uMGVJw.d.ts → index-BwYGLgmI.d.ts}

@@ -1,7 +1,7 @@
-import { a as Node } from './node-8qx0kgYt.js';
-import { R as ReactiveMapBundle } from './reactive-map-LjwjcFaW.js';
-import { a as GraphOptions, G as Graph, C as CausalChain } from './graph-BROUZPG9.js';
-import { w as watchTopologyTree } from './topology-tree-CAFOG5S5.js';
+import { a as Node } from './node-fSc-hCv8.js';
+import { R as ReactiveMapBundle } from './reactive-map-CHyeCf4D.js';
+import { a as GraphOptions, G as Graph, C as CausalChain } from './graph-Cv-8x0ZI.js';
+import { w as watchTopologyTree } from './topology-tree-CJsT24DP.js';
 
 /** Aggregate topology stats emitted by {@link LensGraph.stats}. */
 interface TopologyStats {

package/dist/{index-3L3RC3VJ.d.ts → index-C40wA8zt.d.ts}

@@ -1,11 +1,11 @@
 import { NodeInput } from './extra/sources.js';
-import { a as Node } from './node-8qx0kgYt.js';
-import { L as LLMAdapter } from './types-B2LfBvNc.js';
-import { T as TopicGraph, M as MessagingHubGraph } from './index-Bi4ZP6Hc.js';
-import { E as Evaluator, D as DatasetItem, a as EvalResult$1, R as RefineStrategy, b as RefineLoopOptions, c as RefineStatus } from './index-BUtCR0k6.js';
-import { G as Graph, s as GraphProfileResult, r as GraphProfileOptions } from './graph-BROUZPG9.js';
-import { G as GateController } from './index-HvJ90_tX.js';
-import { J as JobQueueGraph } from './index-Dtpr2FIB.js';
+import { a as Node } from './node-fSc-hCv8.js';
+import { L as LLMAdapter } from './types-CidcBDuk.js';
+import { T as TopicGraph, M as MessagingHubGraph } from './index-C9xF16gc.js';
+import { E as Evaluator, D as DatasetItem, a as EvalResult$1, R as RefineStrategy, b as RefineLoopOptions, c as RefineStatus } from './index-BF-ssbJB.js';
+import { G as Graph, s as GraphProfileResult, r as GraphProfileOptions } from './graph-Cv-8x0ZI.js';
+import { G as GateController } from './pipeline-graph-HOTU4UG0.js';
+import { J as JobQueueGraph } from './index-CAIhFfws.js';
 
 /**
  * Strategy model and priority scoring (roadmap §9.0).

package/dist/{index-Bi4ZP6Hc.d.ts → index-C9xF16gc.d.ts}

@@ -1,22 +1,11 @@
-import { a as Node } from './node-8qx0kgYt.js';
-import { G as Graph, a as GraphOptions } from './graph-BROUZPG9.js';
-
-/**
- * Messaging patterns (roadmap §4.2).
- *
- * Pulsar-inspired messaging primitives modeled as graph factories:
- * - `topic()` for append-only topic streams with a retained window.
- * - `subscription()` for cursor-based consumers.
- * - `topicBridge()` for autonomous topic-to-topic relay.
- * - `messagingHub()` for a lazy topic registry.
- *
- * Job queue / job flow primitives live in `patterns/job-queue` — they are a
- * distinct domain that happens to share reactive-log / reactive-map
- * infrastructure with topics.
- */
+import { a as Node } from './node-fSc-hCv8.js';
+import { G as Graph, a as GraphOptions } from './graph-Cv-8x0ZI.js';
+import { R as ReactiveLogBundle } from './reactive-log-ByBb8g6A.js';
+import { AppendLogStorageTier } from './extra/storage-tiers.js';
 
 type TopicOptions = {
     graph?: GraphOptions;
+    /** Bounded retention; default 1024 per cross-cutting policy (Audit 2/4). */
     retainedLimit?: number;
 };
 declare class TopicGraph<T> extends Graph {
@@ -42,14 +31,48 @@ declare class TopicGraph<T> extends Graph {
     readonly hasLatest: Node<boolean>;
     constructor(name: string, opts?: TopicOptions);
     publish(value: T): void;
+    /**
+     * Wire one or more append-log storage tiers (Audit 4). Each tier receives
+     * appended events per wave; rollback honors the wave-as-transaction model.
+     *
+     * Named `attachEventStorage` (not `attachStorage`) to avoid colliding with
+     * the inherited {@link Graph.attachSnapshotStorage} which takes the
+     * snapshot-based `StorageTier[]` shape.
+     *
+     * @returns Disposer.
+     */
+    attachEventStorage(tiers: readonly AppendLogStorageTier<T>[]): () => void;
     retained(): readonly T[];
+    /** Internal log bundle — used by TopicBridgeGraph for `attach`. */
+    get _logBundle(): ReactiveLogBundle<T>;
 }
 type SubscriptionOptions = {
     graph?: GraphOptions;
+    /**
+     * Starting cursor position.
+     * @deprecated Use `from` instead.
+     */
     cursor?: number;
+    /**
+     * Starting position for the subscription.
+     * - `"retained"` (default) — cursor starts at 0; consumer sees all retained history.
+     * - `"now"` — cursor starts at current topic length; consumer ignores history.
+     * - `number` — explicit cursor position.
+     */
+    from?: "now" | "retained" | number;
+    /**
+     * When this signal node emits DATA, the subscription auto-advances cursor
+     * to current `available.length`. Useful for "ack everything when X happens"
+     * patterns. The reactive edge `advanceOn → cursor` is visible in `explain()`.
+     */
+    advanceOn?: Node<unknown>;
+};
+/** Result of {@link SubscriptionGraph.pullAndAck}. */
+type PullAndAckResult<T> = {
+    items: readonly T[];
+    cursor: number;
 };
 declare class SubscriptionGraph<T> extends Graph {
-    readonly source: Node<readonly T[]>;
     readonly cursor: Node<number>;
     readonly available: Node<readonly T[]>;
     /**
@@ -61,24 +84,74 @@ declare class SubscriptionGraph<T> extends Graph {
      * still wires the data dependency across graph boundaries. D1(e).
      */
     readonly topic: TopicGraph<T>;
+    private _disposed;
     constructor(name: string, topicGraph: TopicGraph<T>, opts?: SubscriptionOptions);
     ack(count?: number): number;
-    pull(limit?: number, opts?: {
-        ack?: boolean;
-    }): readonly T[];
+    pull(limit?: number): readonly T[];
+    /**
+     * Atomic pull-and-acknowledge. Returns `{ items, cursor }` where `cursor`
+     * is the new cursor position after advancing. Under single-threaded JS the
+     * snapshot and advance are atomic; PY callers use a per-subscription Lock.
+     *
+     * Replaces `pull(limit, { ack: true })`.
+     */
+    pullAndAck(limit?: number): PullAndAckResult<T>;
+    /**
+     * Release internal subscriptions and mark the subscription torn-down.
+     * Subsequent `pull`, `pullAndAck`, `ack` return empty / current cursor.
+     * Emits COMPLETE on `cursor` so derived consumers (e.g. `available`) see
+     * the termination signal. Also drains `addDisposer` callbacks (including
+     * the `keepalive(advancePump)` subscription) so no keepalive leak occurs.
+     */
+    dispose(): void;
 }
 type TopicBridgeOptions<TIn, TOut> = {
     graph?: GraphOptions;
     cursor?: number;
     maxPerPump?: number;
+    /**
+     * Optional transform/filter applied to each item before republishing.
+     *
+     * **At-most-once with silent drop:** when `map` returns `undefined`, the
+     * input is consumed from the source cursor but NOT republished. Filtered
+     * items are not retained for retry. If you need filter-with-retry
+     * semantics, do the filtering in a downstream subscription on the bridged
+     * output rather than in the `map` function.
+     */
     map?: (value: TIn) => TOut | undefined;
 };
 declare class TopicBridgeGraph<TIn, TOut = TIn> extends Graph {
     private readonly _sourceSub;
-    private readonly _target;
     readonly bridgedCount: Node<number>;
+    /**
+     * Emits each mapped batch as DATA — gives downstream observers a reactive
+     * stream of bridged values. Also the link target for `target._log.attach`.
+     */
+    readonly output: Node<readonly TOut[]>;
     constructor(name: string, sourceTopic: TopicGraph<TIn>, targetTopic: TopicGraph<TOut>, opts?: TopicBridgeOptions<TIn, TOut>);
 }
+/**
+ * Private pure data structure managing a named set of {@link TopicGraph}
+ * instances. Extracted from {@link MessagingHubGraph} for separation of
+ * concerns (B.2 Unit 14 lock: D — split into TopicRegistry + facade).
+ *
+ * Reusable if other domain consumers (e.g. cqrs.eventLogs) want a shared
+ * topic registry later.
+ *
+ * @internal
+ */
+declare class TopicRegistry {
+    private readonly _map;
+    /** Reactive monotonic version counter. Advances on topic create/remove. */
+    readonly version: Node<number>;
+    constructor(versionNode: Node<number>);
+    get size(): number;
+    has(name: string): boolean;
+    get<T>(name: string): TopicGraph<T> | undefined;
+    set<T>(name: string, t: TopicGraph<T>): void;
+    delete(name: string): boolean;
+    keys(): IterableIterator<string>;
+}
 type MessagingHubOptions = {
     graph?: GraphOptions;
     /**
@@ -93,6 +166,9 @@ type MessagingHubOptions = {
  * instances with retention + cursor semantics. Topics are created on first
  * access; `removeTopic(name)` unmounts and tears down via {@link Graph.remove}.
  *
+ * Internally delegates to {@link TopicRegistry} for topic map management
+ * (B.2 Unit 14 lock: D facade split).
+ *
  * **Relationship to `pubsub()` in `src/extra/pubsub.ts`:** `pubsub` is a
  * lightweight last-value state hub (no retention, no cursors). `MessagingHubGraph`
  * is the full messaging hub — retained message logs, cursor-based subscriptions,
@@ -101,12 +177,11 @@ type MessagingHubOptions = {
  * @category patterns
  */
 declare class MessagingHubGraph extends Graph {
-    private readonly _topics;
-    private _version;
+    private readonly _registry;
+    /** Reactive monotonic version counter — advances on topic create/remove. */
+    readonly version: Node<number>;
     private readonly _defaultTopicOptions;
     constructor(name: string, opts?: MessagingHubOptions);
-    /** Monotonic counter advancing on topic create/remove. */
-    get version(): number;
     /** Number of topics currently in the hub. */
     get size(): number;
     /** Checks topic existence without creating. */
@@ -181,12 +256,18 @@ declare function messagingHub(name: string, opts?: MessagingHubOptions): Messagi
 declare function subscription<T>(name: string, topicGraph: TopicGraph<T>, opts?: SubscriptionOptions): SubscriptionGraph<T>;
 /**
  * Creates an autonomous cursor-based topic relay graph.
+ *
+ * When `opts.map` is provided, items where `map` returns `undefined` are
+ * consumed from the source cursor but NOT republished (at-most-once with
+ * silent drop). For filter-with-retry semantics, apply the filter in a
+ * downstream subscription on the bridge's `output` node instead.
  */
 declare function topicBridge<TIn, TOut = TIn>(name: string, sourceTopic: TopicGraph<TIn>, targetTopic: TopicGraph<TOut>, opts?: TopicBridgeOptions<TIn, TOut>): TopicBridgeGraph<TIn, TOut>;
 
 type index_MessagingHubGraph = MessagingHubGraph;
 declare const index_MessagingHubGraph: typeof MessagingHubGraph;
 type index_MessagingHubOptions = MessagingHubOptions;
+type index_PullAndAckResult<T> = PullAndAckResult<T>;
 type index_SubscriptionGraph<T> = SubscriptionGraph<T>;
 declare const index_SubscriptionGraph: typeof SubscriptionGraph;
 type index_SubscriptionOptions = SubscriptionOptions;
@@ -196,12 +277,14 @@ type index_TopicBridgeOptions<TIn, TOut> = TopicBridgeOptions<TIn, TOut>;
 type index_TopicGraph<T> = TopicGraph<T>;
 declare const index_TopicGraph: typeof TopicGraph;
 type index_TopicOptions = TopicOptions;
+type index_TopicRegistry = TopicRegistry;
+declare const index_TopicRegistry: typeof TopicRegistry;
 declare const index_messagingHub: typeof messagingHub;
 declare const index_subscription: typeof subscription;
 declare const index_topic: typeof topic;
 declare const index_topicBridge: typeof topicBridge;
 declare namespace index {
-  export { index_MessagingHubGraph as MessagingHubGraph, type index_MessagingHubOptions as MessagingHubOptions, index_SubscriptionGraph as SubscriptionGraph, type index_SubscriptionOptions as SubscriptionOptions, index_TopicBridgeGraph as TopicBridgeGraph, type index_TopicBridgeOptions as TopicBridgeOptions, index_TopicGraph as TopicGraph, type index_TopicOptions as TopicOptions, index_messagingHub as messagingHub, index_subscription as subscription, index_topic as topic, index_topicBridge as topicBridge };
+  export { index_MessagingHubGraph as MessagingHubGraph, type index_MessagingHubOptions as MessagingHubOptions, type index_PullAndAckResult as PullAndAckResult, index_SubscriptionGraph as SubscriptionGraph, type index_SubscriptionOptions as SubscriptionOptions, index_TopicBridgeGraph as TopicBridgeGraph, type index_TopicBridgeOptions as TopicBridgeOptions, index_TopicGraph as TopicGraph, type index_TopicOptions as TopicOptions, index_TopicRegistry as TopicRegistry, index_messagingHub as messagingHub, index_subscription as subscription, index_topic as topic, index_topicBridge as topicBridge };
 }
 
-export { MessagingHubGraph as M, SubscriptionGraph as S, TopicGraph as T, type MessagingHubOptions as a, type SubscriptionOptions as b, TopicBridgeGraph as c, type TopicBridgeOptions as d, type TopicOptions as e, topicBridge as f, index as i, messagingHub as m, subscription as s, topic as t };
+export { MessagingHubGraph as M, type PullAndAckResult as P, SubscriptionGraph as S, TopicGraph as T, type MessagingHubOptions as a, type SubscriptionOptions as b, TopicBridgeGraph as c, type TopicBridgeOptions as d, type TopicOptions as e, TopicRegistry as f, topicBridge as g, index as i, messagingHub as m, subscription as s, topic as t };

package/dist/index-CAIhFfws.d.ts

@@ -0,0 +1,171 @@
+import { a as Node } from './node-fSc-hCv8.js';
+import { R as ReactiveLogBundle } from './reactive-log-ByBb8g6A.js';
+import { NodeInput } from './extra/sources.js';
+import { AppendLogStorageTier } from './extra/storage-tiers.js';
+import { G as Graph, a as GraphOptions } from './graph-Cv-8x0ZI.js';
+import { B as BaseAuditRecord } from './imperative-audit-ahAE65a9.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>>;
+    constructor(name: string, opts?: JobQueueOptions);
+    private _bumpSeq;
+    /**
+     * 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,
+ * 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).
+ */
+type WorkFn<T> = (job: JobEnvelope<T>) => 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;
+    };
+};
+type JobFlowOptions<T = unknown> = {
+    graph?: GraphOptions;
+    /**
+     * Stage definitions. Each stage is either a bare name string (pure
+     * pass-through) or a `{ name, work?, handlerVersion? }` object.
+     *
+     * For back-compat, `string[]` values behave as stages with no work hook.
+     */
+    stages?: readonly StageDef<T>[];
+    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 { JobQueueGraph as J, type StageDef as S, type WorkFn as W, type JobEnvelope as a, type JobEvent as b, type JobEventAction as c, JobFlowGraph 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 };

package/dist/{index-BRisOxlx.d.ts → index-CDvC1m5p.d.ts}

@@ -1,4 +1,4 @@
-import { a as Node } from './node-8qx0kgYt.js';
+import { a as Node } from './node-fSc-hCv8.js';
 
 /** Solid accessor function — returns current value when called. */
 type Accessor<T> = () => T;