@graphrefly/ts 0.0.0

package/dist/messaging/index.d.ts

@@ -0,0 +1,235 @@
+import { d as Graph } from '../graph-DfdF9zy4.js';
+import { N as Node } from '../types-h12mNYbq.js';
+import '../core/index.js';
+import '../messages-BZqrGGm1.js';
+import '../codec-BB7p8fJc.js';
+import '../describe-BZb7AS2y.js';
+
+/**
+ * Reusable application-infrastructure messaging namespace.
+ *
+ * Retained root messaging utilities land here only after B63 re-derives them
+ * onto the D125 package DAG.
+ */
+
+interface MessageEnvelope<T = unknown> {
+    readonly topic: string;
+    readonly seq: number;
+    readonly payload: T;
+    readonly key?: string;
+    readonly timestampMs: number;
+}
+/**
+ * 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.
+ */
+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 passive envelope for payloads that cross topic, agent, or graph
+ * boundaries. It is an application fact shape, not a required protocol type.
+ */
+interface TopicMessage<T = unknown> {
+    readonly id: string;
+    readonly schema?: JsonSchema;
+    readonly expiresAt?: string;
+    readonly correlationId?: string;
+    readonly payload: T;
+}
+declare const PROMPTS_TOPIC = "prompts";
+declare const RESPONSES_TOPIC = "responses";
+declare const INJECTIONS_TOPIC = "injections";
+declare const DEFERRED_TOPIC = "deferred";
+declare const SPAWNS_TOPIC = "spawns";
+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;
+}
+interface MessageBusOptions<TTopic extends string = string> {
+    readonly topics: readonly TTopic[];
+    readonly name?: string;
+    readonly now?: () => number;
+}
+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 {
+    readonly name?: string;
+    readonly topics?: readonly string[];
+    readonly unknownTopic?: DynamicHubUnknownTopicPolicy;
+    readonly deadLetter?: boolean;
+    readonly maxTopics?: number;
+    readonly maxTopicLength?: number;
+    readonly now?: () => number;
+}
+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";
+    readonly topic: string;
+    readonly key?: string;
+    readonly payload?: T;
+} | {
+    readonly kind: "delete";
+    readonly topic: string;
+    readonly key?: string;
+    readonly payload?: T;
+} | {
+    readonly kind: "publish";
+    readonly topic: string;
+    readonly payload: T;
+    readonly key?: string;
+} | {
+    readonly kind: "subscribe";
+    readonly topic: string;
+    readonly key?: string;
+    readonly payload?: T;
+} | {
+    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 topic: string;
+    readonly key?: string;
+    readonly payload?: T;
+} | {
+    readonly kind: "delete";
+    readonly topic: string;
+    readonly key?: string;
+    readonly payload?: T;
+} | {
+    readonly kind: "message";
+    readonly topic: string;
+    readonly payload: T;
+    readonly key?: string;
+} | {
+    readonly kind: "subscribe";
+    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 topic?: string;
+    readonly reason: string;
+    readonly command: unknown;
+});
+interface DynamicHubError {
+    readonly topic?: string;
+    readonly error: string;
+    readonly command: unknown;
+    readonly meta: DynamicHubMetadata;
+}
+interface DynamicHubDeadLetter {
+    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>;
+    close(opts?: {
+        key?: string;
+        payload?: T;
+    }): DynamicHubCommand<T>;
+}
+interface ToHubTopicOptions<T> {
+    readonly name?: string;
+    readonly keyOf?: (value: T) => string | undefined;
+}
+interface ToHubTopicBundle<T> {
+    readonly commands: Node<DynamicHubCommand<T>>;
+}
+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>;
+
+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 };