@graphrefly/ts 0.0.0 → 0.0.1

package/dist/messaging/index.d.cts

@@ -1,15 +1,16 @@
-import { d as Graph } from '../graph-s23RbbFO.cjs';
-import { N as Node } from '../types-bNMSWKqF.cjs';
+import { DataIssue } from '../data/index.cjs';
+import { d as Graph } from '../graph-DCEWh4T2.cjs';
+import { N as Node } from '../types-CcPIn7sy.cjs';
+import { L as LockId } from '../messages-CAzUPPJM.cjs';
 import '../core/index.cjs';
-import '../messages-BZqrGGm1.cjs';
 import '../codec-BB7p8fJc.cjs';
-import '../describe-Ciu8SUnN.cjs';
+import '../describe-DYMw_l1C.cjs';
 
 /**
  * Reusable application-infrastructure messaging namespace.
  *
- * Retained root messaging utilities land here only after B63 re-derives them
- * onto the D125 package DAG.
+ * D279/D282/D284/D285/D276: messageBus is a retained topic-log plus independent
+ * subscription-cursor substrate. DynamicHub is intentionally retired; do not add aliases.
  */
 
 interface MessageEnvelope<T = unknown> {
@@ -17,14 +18,11 @@ interface MessageEnvelope<T = unknown> {
     readonly seq: number;
     readonly payload: T;
     readonly key?: string;
+    readonly idempotencyKey?: string;
     readonly timestampMs: number;
+    readonly commandId?: string;
 }
-/**
- * Minimal JSON Schema vocabulary for cross-graph/topic payload descriptions.
- *
- * D125/D132 keep this as passive messaging vocabulary: GraphReFly does not ship
- * a validator here and does not make schemas protocol messages.
- */
+/** Minimal JSON Schema vocabulary for passive topic payload descriptions (D125/D132). */
 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>>;
@@ -38,10 +36,7 @@ interface JsonSchema {
     readonly description?: string;
     readonly title?: string;
 }
-/**
- * Recommended passive envelope for payloads that cross topic, agent, or graph
- * boundaries. It is an application fact shape, not a required protocol type.
- */
+/** Passive envelope for payloads that cross topic, agent, or graph boundaries. */
 interface TopicMessage<T = unknown> {
     readonly id: string;
     readonly schema?: JsonSchema;
@@ -49,6 +44,36 @@ interface TopicMessage<T = unknown> {
     readonly correlationId?: string;
     readonly payload: T;
 }
+/** Passive domain event vocabulary for messageBus/eventFlow composition (D329). */
+interface EventMessage<T = unknown> {
+    readonly id: string;
+    readonly type: string;
+    readonly payload: T;
+    readonly key?: string;
+    readonly subjectId?: string;
+    readonly correlationId?: string;
+    readonly causationId?: string;
+    readonly occurredAtMs?: number;
+    readonly actor?: string;
+    readonly evidenceRefs?: readonly string[];
+    readonly schema?: JsonSchema;
+    readonly metadata?: Readonly<Record<string, unknown>>;
+}
+interface EventMessageOptions {
+    readonly id: string;
+    readonly key?: string;
+    readonly subjectId?: string;
+    readonly correlationId?: string;
+    readonly causationId?: string;
+    readonly occurredAtMs?: number;
+    readonly actor?: string;
+    readonly evidenceRefs?: readonly string[];
+    readonly schema?: JsonSchema;
+    readonly metadata?: Readonly<Record<string, unknown>>;
+}
+declare function eventMessage<T>(type: string, payload: T, opts: EventMessageOptions): EventMessage<T>;
+declare function isEventMessage(value: unknown): value is EventMessage;
+declare function eventMessageIssue(value: unknown): DataIssue | undefined;
 declare const PROMPTS_TOPIC = "prompts";
 declare const RESPONSES_TOPIC = "responses";
 declare const INJECTIONS_TOPIC = "injections";
@@ -58,178 +83,209 @@ declare const CONTEXT_TOPIC = "context";
 declare const TODOS_TOPIC = "todos";
 declare const STANDARD_TOPICS: readonly ["prompts", "responses", "injections", "deferred", "spawns", "context", "todos"];
 type StandardTopic = (typeof STANDARD_TOPICS)[number];
-interface MessageBusEvent<T = unknown> {
-    readonly kind: "publish" | "complete" | "error";
-    readonly topic: string;
-    readonly seq?: number;
-    readonly payload?: T;
-    readonly error?: unknown;
+type MessageBusTopicPolicy = "strict" | "create-as-fact";
+interface MessageBusRetentionPolicy {
+    /** Count retention. Trimming advances headSeq and never rewrites seq (D284). */
+    readonly maxMessages?: number;
 }
-interface MessageBusOptions<TTopic extends string = string> {
-    readonly topics: readonly TTopic[];
-    readonly name?: string;
-    readonly now?: () => number;
+interface MessageBusDedupePolicy {
+    /** Duplicate commandId emits status and never publishes a second retained message (D284). */
+    readonly commandId?: "status" | "issue";
 }
-interface MessageBus<TTopic extends string = string> {
-    readonly topics: readonly TTopic[];
-    topic<T = unknown>(name: TTopic): Node<MessageEnvelope<T>>;
-    publish<T = unknown>(name: TTopic, payload: T, opts?: {
-        key?: string;
-    }): MessageEnvelope<T>;
-    has(name: string): name is TTopic;
-}
-interface ToTopicOptions {
-    readonly name?: string;
-    readonly keyOf?: (value: unknown) => string | undefined;
-}
-interface ToTopicBundle<T> {
-    readonly events: Node<MessageBusEvent<T>>;
-}
-type DynamicHubUnknownTopicPolicy = "drop" | "error" | "dead-letter" | "create-as-fact";
-interface DynamicHubOptions {
+interface MessageBusOptions<TTopic extends string = string> {
+    readonly topics?: readonly TTopic[];
     readonly name?: string;
-    readonly topics?: readonly string[];
-    readonly unknownTopic?: DynamicHubUnknownTopicPolicy;
-    readonly deadLetter?: boolean;
-    readonly maxTopics?: number;
-    readonly maxTopicLength?: number;
     readonly now?: () => number;
+    readonly topicPolicy?: MessageBusTopicPolicy;
+    readonly retention?: MessageBusRetentionPolicy;
+    readonly dedupe?: MessageBusDedupePolicy;
 }
-interface DynamicHubMetadata {
-    readonly seq: number;
-    readonly cursor: number;
-    readonly timestampMs: number;
-}
-type DynamicHubEventKind = "create" | "delete" | "message" | "subscribe" | "close" | "error" | "dead-letter";
-type DynamicHubCommand<T = unknown> = {
-    readonly kind: "create";
+type MessageBusCommand<T = unknown> = {
+    readonly kind: "ensure-topic";
     readonly topic: string;
-    readonly key?: string;
-    readonly payload?: T;
+    readonly commandId?: string;
 } | {
-    readonly kind: "delete";
+    readonly kind: "close-topic";
     readonly topic: string;
-    readonly key?: string;
-    readonly payload?: T;
+    readonly commandId?: string;
 } | {
     readonly kind: "publish";
     readonly topic: string;
     readonly payload: T;
     readonly key?: string;
+    readonly commandId?: string;
+    readonly idempotencyKey?: string;
 } | {
-    readonly kind: "subscribe";
-    readonly topic: string;
-    readonly key?: string;
-    readonly payload?: T;
+    readonly kind: "topic-policy";
+    readonly topicPolicy: MessageBusTopicPolicy;
+    readonly commandId?: string;
 } | {
-    readonly kind: "close";
-    readonly key?: string;
-    readonly payload?: T;
-};
-interface DynamicHubStatus {
-    readonly open: boolean;
-    readonly topics: readonly string[];
-    readonly seq: number;
-    readonly cursor: number;
-    readonly lastEventKind?: DynamicHubEventKind;
-}
-interface DynamicHubEventFrame {
-    readonly meta: DynamicHubMetadata;
-    readonly status: DynamicHubStatus;
-}
-type DynamicHubEvent<T = unknown> = DynamicHubEventFrame & ({
-    readonly kind: "create";
+    readonly kind: "ack";
     readonly topic: string;
-    readonly key?: string;
-    readonly payload?: T;
-} | {
-    readonly kind: "delete";
-    readonly topic: string;
-    readonly key?: string;
-    readonly payload?: T;
+    readonly subscriptionId: string;
+    readonly seq: number;
+    readonly commandId?: string;
 } | {
-    readonly kind: "message";
+    readonly kind: "seek";
     readonly topic: string;
-    readonly payload: T;
-    readonly key?: string;
+    readonly subscriptionId: string;
+    readonly nextSeq: number;
+    readonly commandId?: string;
 } | {
-    readonly kind: "subscribe";
+    readonly kind: "close-subscription";
     readonly topic: string;
-    readonly key?: string;
-    readonly payload?: T;
-} | {
-    readonly kind: "close";
-    readonly key?: string;
-    readonly payload?: T;
-} | {
-    readonly kind: "error";
-    readonly topic?: string;
-    readonly error: string;
-    readonly command: unknown;
-} | {
-    readonly kind: "dead-letter";
+    readonly subscriptionId: string;
+    readonly commandId?: string;
+};
+type MessageBusMessage<T = unknown> = MessageEnvelope<T>;
+interface MessageBusStatus {
+    readonly kind: "topic-created" | "topic-closed" | "message-published" | "retention-trimmed" | "duplicate-command" | "subscription-acked" | "subscription-sought" | "subscription-closed" | "command-rejected" | "projection-ready" | "projection-partial";
     readonly topic?: string;
-    readonly reason: string;
-    readonly command: unknown;
-});
-interface DynamicHubError {
+    readonly seq?: number;
+    readonly headSeq?: number;
+    readonly subscriptionId?: string;
+    readonly nextSeq?: number;
+    readonly commandId?: string;
+    readonly issueCode?: string;
+    readonly timestampMs: number;
+    readonly details?: unknown;
+}
+interface MessageBusCatalogEntry {
+    readonly topic: string;
+    readonly closed: boolean;
+    readonly headSeq: number;
+    readonly nextSeq: number;
+    readonly messageCount: number;
+}
+interface MessageBusCatalogPage {
+    readonly topics: readonly MessageBusCatalogEntry[];
+    readonly nextAfterTopic?: string;
+    readonly hasMore: boolean;
+}
+interface MessageBusDeadLetterEntry<T = unknown> {
+    readonly entrySeq: number;
     readonly topic?: string;
-    readonly error: string;
-    readonly command: unknown;
-    readonly meta: DynamicHubMetadata;
+    readonly command?: MessageBusCommand<T>;
+    readonly message?: MessageBusMessage<T>;
+    readonly issue: DataIssue;
+    readonly timestampMs: number;
+}
+interface MessageBusDeadLetterPage<T = unknown> {
+    readonly entries: readonly MessageBusDeadLetterEntry<T>[];
+    readonly nextAfterEntrySeq?: number;
+    readonly hasMore: boolean;
+}
+interface MessageBusTopicPage<T = unknown> {
+    readonly topic: string;
+    readonly messages: readonly MessageBusMessage<T>[];
+    readonly fromSeq: number;
+    readonly throughSeq?: number;
+    readonly nextAfterSeq?: number;
+    readonly hasMore: boolean;
 }
-interface DynamicHubDeadLetter {
+interface MessageBusCursor {
+    readonly topic: string;
+    readonly subscriptionId: string;
+    readonly nextSeq: number;
+    readonly closed: boolean;
+    readonly retentionGap: boolean;
+    readonly headSeq: number;
+}
+interface MessageBusAvailablePage<T = unknown> {
+    readonly topic: string;
+    readonly subscriptionId: string;
+    readonly cursor: MessageBusCursor;
+    readonly messages: readonly MessageBusMessage<T>[];
+    readonly fromSeq: number;
+    readonly throughSeq?: number;
+    readonly nextAfterSeq?: number;
+    readonly hasMore: boolean;
+}
+interface MessageBusPageParams {
+    readonly limit?: number;
+}
+interface MessageBusCatalogParams extends MessageBusPageParams {
+    readonly afterTopic?: string;
+    readonly includeClosed?: boolean;
+}
+interface MessageBusDeadLetterParams extends MessageBusPageParams {
+    readonly afterEntrySeq?: number;
     readonly topic?: string;
-    readonly reason: string;
-    readonly command: unknown;
-    readonly meta: DynamicHubMetadata;
-}
-interface DynamicHub<T = unknown> {
-    readonly command: Node<DynamicHubCommand<T>>;
-    readonly events: Node<DynamicHubEvent<T>>;
-    readonly status: Node<DynamicHubStatus>;
-    readonly errors: Node<DynamicHubError>;
-    readonly deadLetter?: Node<DynamicHubDeadLetter>;
-    create(topic: string, opts?: {
-        key?: string;
-        payload?: T;
-    }): DynamicHubCommand<T>;
-    delete(topic: string, opts?: {
-        key?: string;
-        payload?: T;
-    }): DynamicHubCommand<T>;
-    publish(topic: string, payload: T, opts?: {
-        key?: string;
-    }): DynamicHubCommand<T>;
-    subscribeTopic(topic: string, opts?: {
-        key?: string;
-        payload?: T;
-    }): DynamicHubCommand<T>;
+    readonly code?: string;
+}
+interface MessageBusTopicParams extends MessageBusPageParams {
+    readonly afterSeq?: number;
+}
+interface MessageBusAvailableParams extends MessageBusPageParams {
+    readonly afterSeq?: number;
+}
+interface MessageBusPullProjection<TPage> {
+    readonly snapshot: Node<TPage>;
+    readonly snapshotPullId: LockId;
+    readonly status: Node<MessageBusStatus>;
+    readonly issues: Node<DataIssue>;
+}
+interface MessageBusTopicProjection<T = unknown> extends MessageBusPullProjection<MessageBusTopicPage<T>> {
+}
+interface MessageBusSubscription<T = unknown> {
+    readonly available: Node<MessageBusAvailablePage<T>>;
+    readonly availablePullId: LockId;
+    readonly cursor: Node<MessageBusCursor>;
+    readonly status: Node<MessageBusStatus>;
+    readonly issues: Node<DataIssue>;
+    ack(seq: number, opts?: {
+        commandId?: string;
+    }): MessageBusCommand;
+    seek(nextSeq: number, opts?: {
+        commandId?: string;
+    }): MessageBusCommand;
     close(opts?: {
+        commandId?: string;
+    }): MessageBusCommand;
+}
+interface MessageBus<TTopic extends string = string> {
+    readonly commands: Node<MessageBusCommand>;
+    readonly messages: Node<MessageBusMessage>;
+    readonly status: Node<MessageBusStatus>;
+    readonly issues: Node<DataIssue>;
+    ensureTopic(topic: TTopic | string, opts?: {
+        commandId?: string;
+    }): MessageBusCommand;
+    closeTopic(topic: TTopic | string, opts?: {
+        commandId?: string;
+    }): MessageBusCommand;
+    publish<T = unknown>(topic: TTopic | string, payload: T, opts?: {
         key?: string;
-        payload?: T;
-    }): DynamicHubCommand<T>;
+        commandId?: string;
+        idempotencyKey?: string;
+    }): MessageBusCommand<T>;
+    topic<T = unknown>(topic: TTopic | string, opts?: {
+        name?: string;
+    }): MessageBusTopicProjection<T>;
+    catalog(opts?: {
+        name?: string;
+    }): MessageBusPullProjection<MessageBusCatalogPage>;
+    deadLetter<T = unknown>(opts?: {
+        name?: string;
+    }): MessageBusPullProjection<MessageBusDeadLetterPage<T>>;
+    subscription<T = unknown>(opts: {
+        topic: TTopic | string;
+        subscriptionId: string;
+        from?: "earliest" | "latest" | number;
+        name?: string;
+    }): MessageBusSubscription<T>;
 }
-interface ToHubTopicOptions<T> {
+interface ToTopicOptions {
     readonly name?: string;
-    readonly keyOf?: (value: T) => string | undefined;
+    readonly keyOf?: (value: unknown) => string | undefined;
+    readonly commandIdOf?: (value: unknown) => string | undefined;
 }
-interface ToHubTopicBundle<T> {
-    readonly commands: Node<DynamicHubCommand<T>>;
+interface ToTopicBundle<T> {
+    readonly commands: Node<MessageBusCommand<T>>;
+    release(): void;
 }
-declare function messageBus<TTopic extends string>(graph: Graph, opts: MessageBusOptions<TTopic>): MessageBus<TTopic>;
-/**
- * D135 dynamic messaging hub: topic lifecycle is DATA facts over fixed graph-visible
- * command/event/status/error nodes. Topic keys never create or delete graph nodes.
- */
-declare function dynamicHub<T = unknown>(graph: Graph, opts?: DynamicHubOptions): DynamicHub<T>;
-/** Static D135 projection over hub event facts for one topic key; no topic node is created. */
-declare function fromHubTopic<T = unknown>(hub: DynamicHub<unknown>, topic: string, opts?: {
-    name?: string;
-}): Node<MessageEnvelope<T>>;
-/** Static D135 command helper: source DATA becomes publish command facts for one topic key. */
-declare function toHubTopic<T>(graph: Graph, source: Node<T>, hub: DynamicHub<unknown>, topic: string, opts?: ToHubTopicOptions<T>): ToHubTopicBundle<T>;
-declare function fromTopic<T = unknown, TTopic extends string = string>(bus: MessageBus<TTopic>, topic: TTopic): Node<MessageEnvelope<T>>;
-declare function toTopic<T, TTopic extends string>(graph: Graph, source: Node<T>, bus: MessageBus<TTopic>, topic: TTopic, opts?: ToTopicOptions): ToTopicBundle<T>;
+declare function messageBus<TTopic extends string>(graph: Graph, opts?: MessageBusOptions<TTopic>): MessageBus<TTopic>;
+declare function fromTopic<T = unknown, TTopic extends string = string>(bus: MessageBus<TTopic>, topic: TTopic | string): Node<MessageBusTopicPage<T>>;
+declare function toTopic<T, TTopic extends string>(graph: Graph, source: Node<T>, bus: MessageBus<TTopic>, topic: TTopic | string, opts?: ToTopicOptions): ToTopicBundle<T>;
 
-export { CONTEXT_TOPIC, DEFERRED_TOPIC, type DynamicHub, type DynamicHubCommand, type DynamicHubDeadLetter, type DynamicHubError, type DynamicHubEvent, type DynamicHubEventKind, type DynamicHubMetadata, type DynamicHubOptions, type DynamicHubStatus, type DynamicHubUnknownTopicPolicy, INJECTIONS_TOPIC, type JsonSchema, type MessageBus, type MessageBusEvent, type MessageBusOptions, type MessageEnvelope, PROMPTS_TOPIC, RESPONSES_TOPIC, SPAWNS_TOPIC, STANDARD_TOPICS, type StandardTopic, TODOS_TOPIC, type ToHubTopicBundle, type ToHubTopicOptions, type ToTopicBundle, type ToTopicOptions, type TopicMessage, dynamicHub, fromHubTopic, fromTopic, messageBus, toHubTopic, toTopic };
+export { CONTEXT_TOPIC, DEFERRED_TOPIC, type EventMessage, type EventMessageOptions, INJECTIONS_TOPIC, type JsonSchema, type MessageBus, type MessageBusAvailablePage, type MessageBusAvailableParams, type MessageBusCatalogEntry, type MessageBusCatalogPage, type MessageBusCatalogParams, type MessageBusCommand, type MessageBusCursor, type MessageBusDeadLetterEntry, type MessageBusDeadLetterPage, type MessageBusDeadLetterParams, type MessageBusDedupePolicy, type MessageBusMessage, type MessageBusOptions, type MessageBusPageParams, type MessageBusPullProjection, type MessageBusRetentionPolicy, type MessageBusStatus, type MessageBusSubscription, type MessageBusTopicPage, type MessageBusTopicParams, type MessageBusTopicPolicy, type MessageBusTopicProjection, type MessageEnvelope, PROMPTS_TOPIC, RESPONSES_TOPIC, SPAWNS_TOPIC, STANDARD_TOPICS, type StandardTopic, TODOS_TOPIC, type ToTopicBundle, type ToTopicOptions, type TopicMessage, eventMessage, eventMessageIssue, fromTopic, isEventMessage, messageBus, toTopic };