@graphrefly/graphrefly 0.45.0 → 0.47.0

package/dist/utils/messaging/index.d.cts

@@ -0,0 +1,562 @@
+import * as _graphrefly_pure_ts_extra from '@graphrefly/pure-ts/extra';
+import { BaseAuditRecord } from '../../base/mutation/index.cjs';
+import { Node } from '@graphrefly/pure-ts/core';
+import { Graph, GraphOptions } from '@graphrefly/pure-ts/graph';
+
+/**
+ * Messaging audit-record schemas (DS-13.5.E, locked 2026-05-01 alt A).
+ *
+ * Per-site discriminated-union audit records for the four messaging mutation
+ * sites that route through `mutate`:
+ *
+ * - {@link TopicPublishRecord} — `Topic.publish`
+ * - {@link SubscriptionAckRecord} — `Subscription.ack`
+ * - {@link SubscriptionPullAndAckRecord} — `Subscription.pullAndAck`
+ * - {@link HubRemoveTopicRecord} — `Hub.removeTopic`
+ *
+ * **Opt-in usage.** None of the four mutation sites enable an audit log by
+ * default — caller wires audit visibility by composing `mutate` with
+ * an audit `ReactiveLogBundle<R>` of the matching record type and an
+ * `onSuccess`/`onFailure` builder:
+ *
+ * ```ts
+ * import { createAuditLog, mutate } from "@graphrefly/graphrefly/extra";
+ * import {
+ *   type TopicPublishRecord,
+ *   topicPublishKeyOf,
+ * } from "@graphrefly/graphrefly/patterns/messaging";
+ *
+ * const audit = createAuditLog<TopicPublishRecord>({ name: "publishes" });
+ * const publish = mutate(
+ *   (item: MyMessage) => topic.publish(item),
+ *   {
+ *     frame: "inline",
+ *     log: audit,
+ *     onSuccessRecord: ([item], _r, m) => ({
+ *       t_ns: m.t_ns,
+ *       seq: m.seq,
+ *       kind: "topic.publish",
+ *       topicName: topic.name,
+ *       itemKey: keyOf(item),
+ *     }),
+ *   },
+ * );
+ * ```
+ *
+ * **Stability.** The `kind` discriminator strings are pre-1.0 stable;
+ * renaming downstream breaks external auditors.
+ *
+ * **Composability.** All four records extend {@link BaseAuditRecord} so they
+ * carry the cross-cutting `t_ns` / `seq?` / `handlerVersion?` fields stamped
+ * by `mutate` (Audit 2 / Audit 5).
+ *
+ * **Per-record keyOf.** Each record exports a recommended `keyOf` for
+ * keyed-storage adapters (Rule G.27-keyOf-recommended) — partition the audit
+ * log by the most natural identity (`topicName::itemKey`,
+ * `subscriptionId::cursor`, etc.).
+ *
+ * **Hub.addTopic deferred.** No `HubAddTopicRecord` ships now; the lazy
+ * topic-creation site has no caller signal asking for an audit record.
+ * Re-add when a consumer surfaces.
+ *
+ * @category patterns
+ * @module patterns/messaging/audit-records
+ */
+
+/**
+ * Audit record for a single {@link TopicGraph.publish} call.
+ *
+ * - `topicName` — the topic the publish targeted.
+ * - `itemKey` — caller-supplied identity for the published item (typically
+ *   the result of the topic's own `keyOf` derivation, when one exists).
+ */
+interface TopicPublishRecord extends BaseAuditRecord {
+    readonly kind: "topic.publish";
+    readonly topicName: string;
+    readonly itemKey: string;
+}
+/**
+ * Recommended `keyOf` for {@link TopicPublishRecord} — formats as
+ * `${topicName}::${itemKey}` for keyed-storage partitioning. Caller may
+ * override per Rule G.27-keyOf-recommended.
+ */
+declare const topicPublishKeyOf: (r: TopicPublishRecord) => string;
+/**
+ * Audit record for a single {@link SubscriptionGraph.ack} call.
+ *
+ * - `subscriptionId` — the subscription the ack advanced.
+ * - `cursor` — the post-ack cursor position.
+ */
+interface SubscriptionAckRecord extends BaseAuditRecord {
+    readonly kind: "subscription.ack";
+    readonly subscriptionId: string;
+    readonly cursor: number;
+}
+/**
+ * Recommended `keyOf` for {@link SubscriptionAckRecord} — formats as
+ * `${subscriptionId}::${cursor}`.
+ */
+declare const subscriptionAckKeyOf: (r: SubscriptionAckRecord) => string;
+/**
+ * Audit record for a single {@link SubscriptionGraph.pullAndAck} call.
+ *
+ * - `subscriptionId` — the subscription the pullAndAck advanced.
+ * - `cursor` — the post-pullAndAck cursor position.
+ * - `itemCount` — number of items returned to the caller in this call.
+ */
+interface SubscriptionPullAndAckRecord extends BaseAuditRecord {
+    readonly kind: "subscription.pullAndAck";
+    readonly subscriptionId: string;
+    readonly cursor: number;
+    readonly itemCount: number;
+}
+/**
+ * Recommended `keyOf` for {@link SubscriptionPullAndAckRecord} — formats as
+ * `${subscriptionId}::${cursor}` (identical shape to ack records so the
+ * combined audit-log partitioning matches a per-cursor-frame view).
+ */
+declare const subscriptionPullAndAckKeyOf: (r: SubscriptionPullAndAckRecord) => string;
+/**
+ * Audit record for a single {@link MessagingHubGraph.removeTopic} call.
+ *
+ * - `topicName` — the topic that was unmounted from the hub.
+ */
+interface HubRemoveTopicRecord extends BaseAuditRecord {
+    readonly kind: "hub.removeTopic";
+    readonly topicName: string;
+}
+/**
+ * Recommended `keyOf` for {@link HubRemoveTopicRecord} — the topic name itself
+ * is already the natural identity.
+ */
+declare const hubRemoveTopicKeyOf: (r: HubRemoveTopicRecord) => string;
+/**
+ * Discriminated union over every messaging audit record. Useful for callers
+ * that aggregate records from multiple sites into one log; switch on
+ * `record.kind` to narrow.
+ */
+type MessagingAuditRecord = TopicPublishRecord | SubscriptionAckRecord | SubscriptionPullAndAckRecord | HubRemoveTopicRecord;
+
+/**
+ * Standard `TopicMessage<T>` envelope for hub topics + well-known topic name
+ * constants (Phase 13.B; spec source: archive/docs/SESSION-human-llm-intervention-primitives.md
+ * §6 + archive/docs/SESSION-multi-agent-gap-analysis.md §6 cross-cut).
+ *
+ * `TopicMessage<T>` is the **recommended** wrapper for cross-agent / cross-graph
+ * topic payloads — it carries identity, schema, deadline, and correlation
+ * metadata alongside the typed `payload`. It is NOT a required protocol
+ * type; raw `topic<T>` continues to work for in-process payloads where the
+ * envelope fields would be noise.
+ *
+ * Use the envelope when:
+ * - Two or more graphs (or human + LLM consumers) communicate over a topic
+ *   and need a stable wire shape — `correlationId` is the join key, `schema`
+ *   gates payload validation, `expiresAt` enables TTL enforcement.
+ * - A topic carries multiple payload kinds and consumers need to discriminate
+ *   without parsing structurally.
+ *
+ * The standard well-known topic constants below are **conventions** — string
+ * literals callers can pass to `messagingHub().topic(NAME)` to get a
+ * predictable lookup. The hub does not enforce any topic to actually exist;
+ * topics are still lazy on first access.
+ */
+/**
+ * Minimal JSON Schema shape, scoped to what `TopicMessage<T>` validates against.
+ * Locked DS-13.B (2026-04-30): zero-dep posture, structural shape only — no
+ * full validator shipped. Callers that want full validation supply their own
+ * (e.g. `ajv`, `zod`, `valibot`) and read `Message.schema` as the rule
+ * source. The shape covers the JSON-Schema-7 subset that hub-topic payload
+ * descriptions actually need:
+ * - `type` / `properties` / `required` / `additionalProperties` for objects.
+ * - `items` for arrays.
+ * - `enum` / `const` for value constraints.
+ * - `$ref` / `definitions` for shared sub-schemas.
+ *
+ * If a concrete consumer needs a richer shape (oneOf, allOf, format, etc.),
+ * extend this type — it's a structural contract, not a tagged union, so
+ * additive fields don't break existing producers.
+ */
+interface JsonSchema {
+    readonly type?: "string" | "number" | "integer" | "boolean" | "object" | "array" | "null" | readonly ("string" | "number" | "integer" | "boolean" | "object" | "array" | "null")[];
+    readonly properties?: Readonly<Record<string, JsonSchema>>;
+    readonly required?: readonly string[];
+    readonly additionalProperties?: boolean | JsonSchema;
+    readonly items?: JsonSchema | readonly JsonSchema[];
+    readonly enum?: readonly unknown[];
+    readonly const?: unknown;
+    readonly $ref?: string;
+    readonly definitions?: Readonly<Record<string, JsonSchema>>;
+    readonly description?: string;
+    readonly title?: string;
+}
+/**
+ * Recommended envelope for hub topic payloads. Carries identity, optional
+ * schema reference, optional expiry, optional correlation, and the typed
+ * payload itself.
+ *
+ * - `id` — globally-unique identifier for this message instance. Producers
+ *   mint it (UUID, ULID, hash, etc.); consumers use it for deduplication and
+ *   trace correlation. **Required.**
+ * - `schema` — optional structural description of `payload`. Validators
+ *   (caller-supplied) read this to gate or shape consumption. Writers MAY
+ *   include the schema inline for self-describing topics, or omit when the
+ *   payload type is statically known to all consumers.
+ * - `expiresAt` — ISO 8601 timestamp; consumers SHOULD drop / fallback past
+ *   this point. Substrate enforcement is via composition (`timeout(source,
+ *   ms)` + `fallback`), not a hub-level rule.
+ * - `correlationId` — links related messages across topics (request /
+ *   response pairs, conversation threads, multi-agent handoffs). Producers
+ *   propagate it; consumers filter / group on it.
+ * - `payload` — the typed body. Type parameter `T` is the consumer-agreed
+ *   shape; the envelope adds metadata around it without coupling consumers
+ *   to a concrete payload type.
+ *
+ * Reactive composition with the envelope:
+ *
+ * ```ts
+ * const requests = hub.topic<TopicMessage<RequestBody>>(PROMPTS_TOPIC);
+ * const responses = hub.topic<TopicMessage<ResponseBody>>(RESPONSES_TOPIC);
+ *
+ * // Filter responses to one correlation
+ * const myResponse = derived([responses.latest], ([msg]) =>
+ *   msg?.correlationId === requestId ? [msg.payload] : [],
+ * );
+ * ```
+ */
+interface TopicMessage<T> {
+    readonly id: string;
+    readonly schema?: JsonSchema;
+    readonly expiresAt?: string;
+    readonly correlationId?: string;
+    readonly payload: T;
+}
+/**
+ * Well-known topic name for human / LLM prompts directed at the harness.
+ * Example payload: `TopicMessage<{ prompt: string; context?: object }>`.
+ *
+ * Co-locked with {@link RESPONSES_TOPIC} per the human-LLM intervention
+ * session §6 #4 (paired request / response convention).
+ */
+declare const PROMPTS_TOPIC = "prompts";
+/**
+ * Well-known topic name for responses to {@link PROMPTS_TOPIC} entries.
+ * Producers pair the response to its prompt via `correlationId`. Example
+ * payload: `TopicMessage<{ content: string; finishReason?: string }>`.
+ */
+declare const RESPONSES_TOPIC = "responses";
+/**
+ * Well-known topic name for out-of-band injections — runtime overrides /
+ * hot-fixes / human nudges that bypass the normal request flow. Example
+ * payload: `TopicMessage<{ kind: "context-patch" | "policy-override" | ...;
+ * data: unknown }>`. Per-injection consumers decide how (and whether) to
+ * apply.
+ */
+declare const INJECTIONS_TOPIC = "injections";
+/**
+ * Well-known topic name for items the harness deferred for later attention
+ * (parked queue, follow-up tracker, "I'll get back to this"). Producer is
+ * usually the harness itself; consumer is a tracker / dashboard / human.
+ * Example payload: `TopicMessage<{ reason: string; original: unknown }>`.
+ */
+declare const DEFERRED_TOPIC = "deferred";
+/**
+ * Well-known topic name for spawn requests (Phase 13.I `spawnable()`
+ * surface). Producer emits a `TopicMessage<SpawnRequest>` to request a child
+ * agent / subgraph; consumer is the materializer that mints the slot.
+ * Example payload: `TopicMessage<{ presetId: string; taskInput: unknown;
+ * depth?: number }>`. `correlationId` links the spawn to its parent
+ * conversation; `expiresAt` enforces TTL on long-lived requests.
+ */
+declare const SPAWNS_TOPIC = "spawns";
+/**
+ * DS-14.6.A D-B3 — well-known topic for the dynamic `actorPool()` shared
+ * tagged-context pool. Actors publish `ContextEntry` here; per-actor views
+ * render their own compressed slice.
+ */
+declare const CONTEXT_TOPIC = "context";
+/**
+ * DS-14.6.A D-B3 — well-known topic for the `actorPool()` shared todo list.
+ * Any actor may `enqueueTodo`; actors pull assigned todos via their cursor.
+ */
+declare const TODOS_TOPIC = "todos";
+/**
+ * Tuple of all well-known topic constants — useful for "register all
+ * standard topics on a hub" patterns and for compile-time exhaustiveness
+ * checks.
+ */
+declare const STANDARD_TOPICS: readonly ["prompts", "responses", "injections", "deferred", "spawns", "context", "todos"];
+/**
+ * Union of all well-known topic name string literals.
+ */
+type StandardTopic = (typeof STANDARD_TOPICS)[number];
+
+type TopicOptions = {
+    graph?: GraphOptions;
+    /** Bounded retention; default 1024 per cross-cutting policy (Audit 2/4). */
+    retainedLimit?: number;
+};
+declare class TopicGraph<T> extends Graph {
+    private readonly _log;
+    private readonly _publishImpl;
+    readonly events: Node<readonly T[]>;
+    /**
+     * Most recently published value. Stays in the protocol SENTINEL state
+     * (`cache === undefined`, no DATA emitted) until the first publish, then
+     * tracks the latest entry. Spec §5.12 reserves `undefined` as the
+     * "never sent DATA" sentinel — and `TopicGraph.publish(undefined)` is
+     * rejected — so `cache === undefined` unambiguously signals "empty topic"
+     * even when `T` itself includes `null` (i.e., `topic<number | null>`).
+     *
+     * **Within a reactive fn:** detect the empty-topic case via
+     * `ctx.prevData[i] === undefined` for the dep slot holding `topic.latest`,
+     * or check `latest.cache === undefined` outside reactive code. No
+     * separate `hasLatest` companion needed — the SENTINEL is the answer.
+     */
+    readonly latest: Node<T>;
+    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
+     * paired `AttachSnapshotTierPair[]` shape (Phase 14.6) — distinct
+     * concerns, distinct surfaces.
+     *
+     * @returns Disposer.
+     */
+    attachEventStorage(tiers: readonly _graphrefly_pure_ts_extra.AppendLogStorageTier<T>[]): () => void;
+    retained(): readonly T[];
+    /** Internal log bundle — used by TopicBridgeGraph for `attach`. */
+    get _logBundle(): _graphrefly_pure_ts_extra.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 cursor: Node<number>;
+    readonly available: Node<readonly T[]>;
+    /**
+     * Reference to the upstream topic graph. Intentionally NOT mounted
+     * under this subscription: a subscription is a VIEW over an
+     * externally-owned topic. Double-mounting (e.g. hub-owned topic +
+     * sub-mount here) would make either-side teardown leave the other
+     * holding a dead reference. Node-level `derived([topicEvents], …)`
+     * still wires the data dependency across graph boundaries. D1(e).
+     */
+    readonly topic: TopicGraph<T>;
+    private _disposed;
+    private readonly _ackImpl;
+    private readonly _pullAndAckImpl;
+    constructor(name: string, topicGraph: TopicGraph<T>, opts?: SubscriptionOptions);
+    ack(count?: number): number;
+    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;
+    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;
+    /**
+     * Default `TopicOptions` applied to every topic created via `topic(name)`
+     * without explicit options. Per-call opts override. Default: `{}`
+     * (unbounded retention per topic unless `retainedLimit` is set per call).
+     */
+    defaultTopicOptions?: TopicOptions;
+};
+/**
+ * Lazy Pulsar-inspired topic registry. Manages a named set of {@link TopicGraph}
+ * 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,
+ * and pattern-layer lifecycle management.
+ *
+ * @category patterns
+ */
+declare class MessagingHubGraph extends Graph {
+    private readonly _registry;
+    /** Reactive monotonic version counter — advances on topic create/remove. */
+    readonly version: Node<number>;
+    private readonly _defaultTopicOptions;
+    private readonly _removeTopicImpl;
+    constructor(name: string, opts?: MessagingHubOptions);
+    /** Number of topics currently in the hub. */
+    get size(): number;
+    /** Checks topic existence without creating. */
+    has(name: string): boolean;
+    /** Iterator over topic names. */
+    topicNames(): IterableIterator<string>;
+    /**
+     * Returns the {@link TopicGraph} for `name`, creating lazily on first call.
+     * Subsequent calls with the same name return the same instance (options on
+     * repeat calls are ignored — the topic is already configured).
+     */
+    topic<T = unknown>(name: string, opts?: TopicOptions): TopicGraph<T>;
+    /**
+     * Publishes a value to the topic, lazily creating it on first publish.
+     *
+     * **Late-subscriber caveat:** the topic is created lazily, so subscribers
+     * that attach AFTER a publish only see the retained window (governed by
+     * `retainedLimit` on `TopicOptions` / `defaultTopicOptions`). If
+     * `retainedLimit === 0` is set explicitly, early publishes are
+     * effectively dropped — prefer an unset `retainedLimit` (unbounded
+     * retention) or subscribe before publishing when late-subscribers matter.
+     */
+    publish<T = unknown>(name: string, value: T): void;
+    /**
+     * Bulk publish — issues all publishes inside one outer batch. New topics
+     * are created on demand. No-op if `entries` yields nothing.
+     *
+     * **Iterable consumption (F6):** `entries` is consumed once (single-pass)
+     * INSIDE the batch frame. If the iterator throws mid-way, the batch is
+     * discarded and NO publishes are visible to subscribers (all-or-nothing).
+     * Pass an array or `Set` for multi-shot callers.
+     */
+    publishMany(entries: Iterable<[string, unknown]>): void;
+    /**
+     * Creates a {@link SubscriptionGraph} over a named topic. The topic is
+     * lazily created if missing. Subscription lifecycle is owned by the caller —
+     * the hub does NOT mount the subscription.
+     *
+     * @param subName - Local name for the subscription graph.
+     * @param topicName - Hub topic to subscribe to.
+     * @param opts - `SubscriptionOptions` (initial cursor, etc.).
+     */
+    subscribe<T = unknown>(subName: string, topicName: string, opts?: SubscriptionOptions): SubscriptionGraph<T>;
+    /**
+     * Unmounts and tears down the topic's graph. Returns `true` if the topic
+     * existed. Subscribers receive `TEARDOWN` via {@link Graph.remove}.
+     *
+     * **Closure-state caveat:** the registry mutation (`_registry.delete`) and
+     * version bump happen in a `try/finally`, so registry/version converge to
+     * a consistent state even when {@link Graph.remove} throws. `mutate`
+     * does not roll back this mutation on throw — `Map.delete` on closure
+     * state is invisible to any batch frame. The pre-existing try/finally is
+     * load-bearing for that invariant.
+     */
+    removeTopic(name: string): boolean;
+}
+/**
+ * Creates a Pulsar-inspired topic graph (append-only retained stream + latest value).
+ */
+declare function topic<T>(name: string, opts?: TopicOptions): TopicGraph<T>;
+/**
+ * Creates a lazy Pulsar-inspired messaging hub. Topics are created on first access
+ * via `hub.topic(name)`; `hub.publish(name, value)` shortcuts through the registry.
+ *
+ * @example
+ * ```ts
+ * import { messagingHub } from "@graphrefly/graphrefly/patterns/messaging";
+ *
+ * const hub = messagingHub("main", { defaultTopicOptions: { retainedLimit: 256 } });
+ * hub.publish("orders", { id: 1 });
+ * hub.publishMany([["shipments", { id: 1 }], ["orders", { id: 2 }]]);
+ * const sub = hub.subscribe("orders-worker", "orders", { cursor: 0 });
+ * ```
+ */
+declare function messagingHub(name: string, opts?: MessagingHubOptions): MessagingHubGraph;
+/**
+ * Creates a cursor-based subscription graph over a topic.
+ */
+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>;
+
+export { CONTEXT_TOPIC, DEFERRED_TOPIC, type HubRemoveTopicRecord, INJECTIONS_TOPIC, type JsonSchema, type MessagingAuditRecord, MessagingHubGraph, type MessagingHubOptions, PROMPTS_TOPIC, type PullAndAckResult, RESPONSES_TOPIC, SPAWNS_TOPIC, STANDARD_TOPICS, type StandardTopic, type SubscriptionAckRecord, SubscriptionGraph, type SubscriptionOptions, type SubscriptionPullAndAckRecord, TODOS_TOPIC, TopicBridgeGraph, type TopicBridgeOptions, TopicGraph, type TopicMessage, type TopicOptions, type TopicPublishRecord, TopicRegistry, hubRemoveTopicKeyOf, messagingHub, subscription, subscriptionAckKeyOf, subscriptionPullAndAckKeyOf, topic, topicBridge, topicPublishKeyOf };