phoenix_duskmoon 10.0.11 → 10.1.0

package/assets/js/react_chat/index.js

@@ -1,28 +1,51 @@
 import React from "react";
 import { createRoot } from "react-dom/client";
+import {
+	snapshotComposerDocument,
+	snapshotComposerReceipt,
+} from "@duskmoon-dev/components/chat";
 import { ReactChat } from "./chat.js";
-import { initialState, reduceChat } from "./state.js";
+import {
+	initialState,
+	reduceChat,
+	sameChatScope,
+	validChatQueue,
+} from "./state.js";
+import {
+	assertChatJSON,
+	ChatTransportError,
+	correlatedReceipt,
+	requestId,
+	structuredSnapshot,
+	submissionSnapshot,
+	unknownReceipt,
+	chatJSONKey,
+} from "./protocol.js";
 
 export { ReactChat, useChatSubmission } from "./chat.js";
 export { initialState, reduceChat } from "./state.js";
+export { ChatTransportError } from "./protocol.js";
+
+let nextGeneration = 0;
 
 export function createDuskmoonReactChat(options = {}) {
 	return {
 		mounted() {
-			this.config = JSON.parse(this.el.dataset.chat);
-			this.state = initialState(
-				this.config.conversationId,
-				this.config.messages,
-				this.config,
-			);
-			this.root = createRoot(this.el);
 			this.connected = true;
 			this.requests = new Set();
-			this.bridge = {
-				send: (action, payload) => this.sendChat(action, payload),
-			};
+			this.recoveryFailures = new Map();
+			this.bindContext(JSON.parse(this.el.dataset.chat));
+			this.root = createRoot(this.el);
 			this.eventRef = this.handleEvent(this.config.event, (event) => {
 				if (event.id !== this.el.id) return;
+				if (
+					["chat.snapshot", "chat.reset"].includes(event.type) &&
+					event.conversation_id === this.state.conversationId &&
+					event.protocolVersion === 1 &&
+					sameChatScope(event.scope, this.state.scope) &&
+					event.instanceGeneration === this.state.instanceGeneration
+				)
+					this.reconcileReceipts(event.receipts);
 				const previous = this.state;
 				this.state = reduceChat(this.state, event);
 				if (previous === this.state) return;
@@ -31,63 +54,449 @@ export function createDuskmoonReactChat(options = {}) {
 			});
 			this.renderChat();
 		},
-		sendChat(action, payload) {
-			if (!this.connected || this.dead)
-				return Promise.reject(new Error("Chat is disconnected"));
+		bindContext(config) {
+			if (config.protocolVersion != null && config.protocolVersion !== 1)
+				throw new TypeError("Unsupported chat protocol version");
+			const generation = ++nextGeneration;
+			if (
+				config.protocolVersion === 1 &&
+				(!config.scope?.contextKey ||
+					config.scope.conversationId !== config.conversationId)
+			)
+				throw new TypeError(
+					"Structured chat requires an application context key and matching conversation",
+				);
+			this.config = config;
+			this.state = initialState(config.conversationId, config.messages, {
+				...config,
+				instanceGeneration: generation,
+			});
+			this.adapter =
+				options.adapter?.({
+					scope: this.state.scope,
+					instanceGeneration: generation,
+					config,
+					element: this.el,
+				}) || {};
+			this.submissionPending = false;
+			this.syncPending = null;
+			const current = () => {
+				if (this.dead || generation !== this.state.instanceGeneration)
+					throw new Error("Chat context has changed");
+			};
+			this.bridge = {
+				send: (action, payload) => {
+					try {
+						current();
+						return this.sendChat(action, payload);
+					} catch (error) {
+						return Promise.reject(error);
+					}
+				},
+				submit: async (snapshot, signal) => {
+					current();
+					return this.submitStructured(snapshot, signal);
+				},
+				reconcile: async (snapshot, signal) => {
+					current();
+					return this.reconcileSubmission(snapshot, signal);
+				},
+				mutateQueue: async (mutation, signal) => {
+					current();
+					return this.mutateQueue(mutation, signal);
+				},
+				getRecoveryFailures: () => [...this.recoveryFailures.values()],
+			};
+		},
+		// Explicit host operation. Mutating data-chat alone never changes ownership.
+		switchContext(config) {
+			if (config.event !== this.config.event)
+				throw new TypeError("Remount the hook to change its event channel");
+			this.requests.forEach((request) => request.cancel());
+			this.bindContext(config);
+			this.renderChat();
+		},
+		checkAction(action) {
+			if (
+				typeof this.config.actions?.[action] !== "string" ||
+				!this.config.actions[action].trim()
+			)
+				throw new TypeError(`Chat action is not configured: ${action}`);
+			if (!this.connected || this.dead) throw new Error("Chat is disconnected");
 			if (action === "send" && this.state.needsSync)
-				return Promise.reject(new Error("Chat is synchronizing"));
+				throw new Error("Chat is synchronizing");
+			if (this.requests.size >= (options.maxPendingRequests ?? 64))
+				throw new Error(
+					"Chat transport capacity reached; reconcile pending requests",
+				);
+		},
+		sendChat(action, payload = {}) {
+			if (
+				action === "send" &&
+				(payload.protocolVersion !== undefined ||
+					payload.document !== undefined)
+			)
+				return this.submitStructured(payload);
+			return this.transport(action, payload);
+		},
+		transport(action, payload, structured) {
+			try {
+				this.checkAction(action);
+				assertChatJSON(payload);
+			} catch (error) {
+				return Promise.reject(error);
+			}
+			const generation = this.state.instanceGeneration;
+			const scope = this.state.scope;
+			const correlation = {
+				request_id: payload.request_id ?? requestId(),
+				instanceGeneration: generation,
+				scope,
+				clientSubmissionId: structured?.snapshot?.clientSubmissionId,
+			};
+			if (
+				typeof correlation.request_id !== "string" ||
+				!correlation.request_id ||
+				[...this.requests].some((r) => r.id === correlation.request_id)
+			)
+				return Promise.reject(
+					new TypeError("Chat request_id must be unique while pending"),
+				);
+			const body = {
+				...payload,
+				request_id: correlation.request_id,
+				id: this.el.id,
+				conversation_id: this.state.conversationId,
+				...(this.state.protocolVersion === 1
+					? { protocolVersion: 1, scope, instanceGeneration: generation }
+					: {}),
+			};
 			return new Promise((resolve, reject) => {
+				const uncertain = (message, cause) =>
+					new ChatTransportError(
+						message,
+						{ ...correlation, dispatched: true },
+						cause,
+					);
 				const finish = (error, reply) => {
 					if (!this.requests.delete(request)) return;
 					clearTimeout(request.timer);
+					structured?.signal?.removeEventListener("abort", request.cancel);
 					error ? reject(error) : resolve(reply);
 				};
 				const request = {
+					id: correlation.request_id,
 					cancel: () =>
 						finish(
-							new Error("Chat disconnected; check status before retrying"),
+							uncertain("Chat disconnected; check status before retrying"),
 						),
 				};
+				if (structured?.signal?.aborted) {
+					reject(new Error("Chat request aborted before dispatch"));
+					return;
+				}
 				this.requests.add(request);
+				structured?.signal?.addEventListener("abort", request.cancel, {
+					once: true,
+				});
 				request.timer = setTimeout(
 					() =>
 						finish(
-							new Error("Chat request timed out; check status before retrying"),
+							uncertain("Chat request timed out; check status before retrying"),
 						),
-					15000,
+					options.requestTimeoutMs ?? 15000,
 				);
-				const body = {
-					...payload,
-					id: this.el.id,
-					conversation_id: this.state.conversationId,
-				};
 				const reply = (response) => {
-					const error =
-						response?.status === "ok"
-							? null
-							: new Error(response?.message || "Chat request rejected");
-					if (error) error.response = response;
-					finish(error, response);
+					try {
+						if (structured) {
+							const receipt = structured.validate(response, correlation);
+							structured.onReceipt?.(receipt);
+							// A late receipt resolves its original recovery record only.
+							if (generation !== this.state.instanceGeneration || this.dead) {
+								finish(uncertain("Chat context has changed"));
+								return;
+							}
+							finish(null, receipt);
+						} else if (response?.status === "ok") finish(null, response);
+						else if (response?.status === "error") {
+							const error = new Error(
+								response.message || "Chat request rejected",
+							);
+							error.response = response;
+							finish(error);
+						} else
+							finish(uncertain("Missing or malformed chat acknowledgement"));
+					} catch (error) {
+						finish(
+							uncertain(
+								"Invalid chat acknowledgement; check status before retrying",
+								error,
+							),
+						);
+					}
 				};
 				try {
 					const event = this.config.actions[action];
-					if (this.config.target || this.el.dataset.target)
-						this.pushEventTo(
-							this.config.target || this.el.dataset.target,
-							event,
-							body,
-							reply,
-						);
+					const target = this.config.target || this.el.dataset.target;
+					if (target) this.pushEventTo(target, event, body, reply);
 					else this.pushEvent(event, body, reply);
 				} catch (error) {
-					finish(error);
+					finish(uncertain("Chat dispatch outcome is unknown", error));
 				}
 			});
 		},
-		requestSync() {
-			this.sendChat("sync", { sequences: this.state.sequences }).catch(
-				() => {},
+		retain(adapter, attempt) {
+			try {
+				adapter.recovery.retain(attempt);
+				this.recoveryFailures.delete(attempt.snapshot.clientSubmissionId);
+			} catch (error) {
+				this.recoveryFailures.set(attempt.snapshot.clientSubmissionId, {
+					attempt,
+					error,
+				});
+				throw error;
+			}
+		},
+		async submitStructured(payload, signal) {
+			if (signal?.aborted)
+				throw new Error("Chat request aborted before dispatch");
+			this.checkAction("send");
+			if (this.submissionPending)
+				throw new Error("Chat is not accepting messages");
+			const snapshot = structuredSnapshot(payload, this.state);
+			const adapter = this.adapter;
+			if (!adapter.recovery?.retain || !adapter.recovery?.getSnapshot)
+				throw new TypeError(
+					"Structured submissions require an application recovery owner",
+				);
+			const generation = this.state.instanceGeneration;
+			const previous = adapter.recovery
+				.getSnapshot()
+				.find(
+					(a) => a.snapshot.clientSubmissionId === snapshot.clientSubmissionId,
+				);
+			if (previous && chatJSONKey(previous.snapshot) !== chatJSONKey(snapshot))
+				throw new TypeError(
+					"A logical submission ID cannot change its payload",
+				);
+			if (previous?.status === "accepted" || previous?.status === "rejected")
+				return previous.receipt;
+			const physicalId = payload.request_id ?? requestId();
+			const attempt = {
+				snapshot,
+				instanceId: this.el.id,
+				instanceGeneration: generation,
+				createdAt: previous?.createdAt ?? Date.now(),
+				status: "pending",
+				requestIds: [...(previous?.requestIds || []), physicalId],
+			};
+			this.submissionPending = true;
+			try {
+				// The upstream controller may already have retained this first attempt.
+				if (
+					previous &&
+					(previous.status === "unknown" || previous.requestIds?.length) &&
+					(await adapter.authorizeRetry?.(previous)) !== true
+				)
+					throw new Error(
+						"Explicit application authorization is required to retry an unresolved submission",
+					);
+				// Handoff is synchronous and must succeed before dispatch becomes possible.
+				this.retain(adapter, attempt);
+				if (generation !== this.state.instanceGeneration || this.dead)
+					throw new Error("Chat context has changed");
+				return await this.transport(
+					"send",
+					{ ...snapshot, request_id: physicalId },
+					{
+						snapshot,
+						signal,
+						validate: (response, correlation) =>
+							correlatedReceipt(response, snapshot, correlation),
+						onReceipt: (receipt) =>
+							this.retain(adapter, {
+								...attempt,
+								status: receipt.outcome,
+								receipt,
+							}),
+					},
+				);
+			} catch (error) {
+				if (!(error instanceof ChatTransportError)) throw error;
+				const receipt = unknownReceipt(snapshot, error);
+				this.retain(adapter, { ...attempt, status: "unknown", receipt });
+				return receipt;
+			} finally {
+				if (generation === this.state.instanceGeneration)
+					this.submissionPending = false;
+			}
+		},
+		async reconcileSubmission(payload, signal) {
+			const snapshot = submissionSnapshot(payload, this.state);
+			const adapter = this.adapter;
+			const attempt = adapter.recovery
+				?.getSnapshot()
+				.find(
+					(a) => a.snapshot.clientSubmissionId === snapshot.clientSubmissionId,
+				);
+			if (!attempt || chatJSONKey(attempt.snapshot) !== chatJSONKey(snapshot))
+				throw new Error("No matching scoped recovery record for submission");
+			try {
+				return await this.transport(
+					"reconcile",
+					{
+						clientSubmissionId: snapshot.clientSubmissionId,
+						operation: snapshot.operation,
+					},
+					{
+						snapshot,
+						signal,
+						validate: (response, correlation) =>
+							correlatedReceipt(response, snapshot, correlation),
+						onReceipt: (receipt) =>
+							this.retain(adapter, {
+								...attempt,
+								status: receipt.outcome,
+								receipt,
+							}),
+					},
+				);
+			} catch (error) {
+				if (!(error instanceof ChatTransportError)) throw error;
+				const receipt = unknownReceipt(snapshot, error);
+				this.retain(adapter, { ...attempt, status: "unknown", receipt });
+				return receipt;
+			}
+		},
+		async mutateQueue(mutation, signal) {
+			assertChatJSON(mutation);
+			if (
+				!["edit", "remove", "promote"].includes(mutation.operation) ||
+				!mutation.requestId
+			)
+				throw new TypeError("Unsupported queue operation");
+			const { composer, scope } = this.state;
+			const item = composer?.queue?.items.find(
+				(item) => item.id === mutation.itemId,
 			);
+			const capability = composer?.capabilities?.queue?.[mutation.operation];
+			const itemCapability = item?.capabilities?.[mutation.operation];
+			if (
+				!sameChatScope(mutation.scope, scope) ||
+				!item ||
+				!capability ||
+				capability === "none" ||
+				!itemCapability ||
+				itemCapability === "none"
+			)
+				throw new TypeError("Unsupported queue operation or item");
+			if (mutation.expectedRevision !== composer.queue.revision)
+				throw new TypeError("Queue revision has changed");
+			if (mutation.operation === "promote" && !mutation.targetTurnId)
+				throw new TypeError("Promotion requires a target turn");
+			if (mutation.operation === "edit")
+				snapshotComposerDocument(mutation.document);
+			if (
+				mutation.operation === "edit" &&
+				(!mutation.document ||
+					([capability, itemCapability].includes("text") &&
+						(mutation.document.command ||
+							mutation.document.content?.some((node) => node.type !== "text"))))
+			)
+				throw new TypeError("Queue editing supports text documents only");
+			const generation = this.state.instanceGeneration;
+			return this.transport(`queue_${mutation.operation}`, mutation, {
+				signal,
+				validate: (response, correlation) => {
+					const result = response?.result;
+					assertChatJSON(result);
+					if (
+						response?.request_id !== correlation.request_id ||
+						response?.instanceGeneration !== generation ||
+						result?.requestId !== mutation.requestId ||
+						!["accepted", "rejected"].includes(result.outcome) ||
+						!validChatQueue(result.projection, scope) ||
+						(result.outcome === "rejected" && !result.error?.code)
+					)
+						throw new TypeError("Queue response correlation mismatch");
+					return result;
+				},
+				onReceipt: (result) => {
+					if (this.dead || generation !== this.state.instanceGeneration) return;
+					const projection = result.projection;
+					if (
+						Number.isSafeInteger(projection.revision) &&
+						projection.revision > this.state.composer.queue.revision &&
+						Array.isArray(projection.items)
+					) {
+						this.state = {
+							...this.state,
+							composer: { ...this.state.composer, queue: projection },
+						};
+						this.scheduleRender();
+					}
+				},
+			});
+		},
+		reconcileReceipts(receipts = []) {
+			if (!this.adapter.reconcileOnSync || !this.adapter.recovery) return;
+			if (!Array.isArray(receipts)) receipts = [];
+			for (const attempt of this.adapter.recovery.getSnapshot()) {
+				if (
+					!sameChatScope(attempt.snapshot.scope, this.state.scope) ||
+					!["pending", "unknown"].includes(attempt.status)
+				)
+					continue;
+				const input = receipts.find(
+					(r) => r.clientSubmissionId === attempt.snapshot.clientSubmissionId,
+				);
+				let receipt;
+				try {
+					receipt = input
+						? snapshotComposerReceipt(input, attempt.snapshot)
+						: unknownReceipt(
+								attempt.snapshot,
+								new Error("No authoritative receipt in snapshot"),
+							);
+				} catch (error) {
+					receipt = unknownReceipt(attempt.snapshot, error);
+				}
+				this.retain(this.adapter, {
+					...attempt,
+					status: receipt.outcome,
+					receipt,
+				});
+			}
+		},
+		requestSync() {
+			if (this.syncPending) return this.syncPending;
+			const generation = this.state.instanceGeneration;
+			const payload = { sequences: this.state.sequences };
+			if (this.adapter.reconcileOnSync && this.adapter.recovery)
+				payload.unresolvedSubmissionIds = this.adapter.recovery
+					.getSnapshot()
+					.filter(
+						(a) =>
+							sameChatScope(a.snapshot.scope, this.state.scope) &&
+							["pending", "unknown"].includes(a.status),
+					)
+					.map((a) => a.snapshot.clientSubmissionId);
+			const pending = this.sendChat("sync", payload)
+				.catch((error) => {
+					if (
+						!this.dead &&
+						generation === this.state.instanceGeneration &&
+						this.syncPending === pending
+					) {
+						this.state = { ...this.state, error: error.message };
+						this.scheduleRender();
+					}
+				})
+				.finally(() => {
+					if (this.syncPending === pending) this.syncPending = null;
+				});
+			this.syncPending = pending;
+			return pending;
 		},
 		scheduleRender() {
 			if (!this.frame)
@@ -104,12 +513,14 @@ export function createDuskmoonReactChat(options = {}) {
 					connected: this.connected,
 					label: this.config.label,
 					options,
+					adapter: this.adapter,
 				}),
 			);
 		},
 		disconnected() {
 			this.connected = false;
 			this.requests.forEach((request) => request.cancel());
+			this.syncPending = null;
 			this.renderChat();
 		},
 		reconnected() {

package/assets/js/react_chat/protocol.js

@@ -0,0 +1,125 @@
+import {
+	ComposerUncertainTransportError,
+	snapshotComposerReceipt,
+	snapshotComposerSubmission,
+} from "@duskmoon-dev/components/chat";
+
+export function requestId() {
+	if (typeof crypto.randomUUID === "function") return crypto.randomUUID();
+	const bytes = crypto.getRandomValues(new Uint8Array(16));
+	bytes[6] = (bytes[6] & 0x0f) | 0x40;
+	bytes[8] = (bytes[8] & 0x3f) | 0x80;
+	const hex = Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0"));
+	return [
+		hex.slice(0, 4),
+		hex.slice(4, 6),
+		hex.slice(6, 8),
+		hex.slice(8, 10),
+		hex.slice(10),
+	]
+		.map((part) => part.join(""))
+		.join("-");
+}
+
+// Compatible with the upstream session controller's uncertain-transport boundary.
+export class ChatTransportError extends ComposerUncertainTransportError {
+	constructor(message, correlation, cause) {
+		super(message, { cause });
+		this.name = "ChatTransportError";
+		this.outcome = "unknown";
+		Object.assign(this, correlation);
+	}
+}
+
+export function unknownReceipt(snapshot, error) {
+	return Object.freeze({
+		protocolVersion: 1,
+		clientSubmissionId: snapshot.clientSubmissionId,
+		scope: snapshot.scope,
+		operation: snapshot.operation,
+		outcome: "unknown",
+		error: {
+			code: error.code || "uncertain_transport",
+			message: error.message,
+			...(error.request_id
+				? {
+						details: {
+							request_id: error.request_id,
+							instanceGeneration: error.instanceGeneration,
+						},
+					}
+				: {}),
+		},
+	});
+}
+
+// Reject binary handles before any JSON serialization, including the legacy path.
+export function assertChatJSON(value, ancestors = new Set()) {
+	if (value == null || ["string", "boolean"].includes(typeof value)) return;
+	if (typeof value === "number" && Number.isFinite(value)) return;
+	if (typeof value !== "object" || ancestors.has(value))
+		throw new TypeError("Chat payload must contain portable JSON only");
+	if (
+		!Array.isArray(value) &&
+		Object.getPrototypeOf(value) !== Object.prototype &&
+		Object.getPrototypeOf(value) !== null
+	)
+		throw new TypeError(
+			"Upload File/Blob objects through an application adapter before submitting JSON",
+		);
+	ancestors.add(value);
+	for (const item of Object.values(value)) assertChatJSON(item, ancestors);
+	ancestors.delete(value);
+}
+
+export function submissionSnapshot(payload, state) {
+	if (state.protocolVersion !== 1)
+		throw new TypeError("Structured composer protocol is not enabled");
+	const { request_id, ...submission } = payload;
+	assertChatJSON(submission);
+	const snapshot = snapshotComposerSubmission(submission);
+	if (
+		snapshot.scope.contextKey !== state.scope.contextKey ||
+		snapshot.scope.conversationId !== state.scope.conversationId
+	)
+		throw new TypeError("Submission scope does not match this chat instance");
+	return snapshot;
+}
+
+export function structuredSnapshot(payload, state) {
+	const snapshot = submissionSnapshot(payload, state);
+	const caps = state.composer?.capabilities;
+	if (
+		caps?.protocolVersion !== 1 ||
+		!caps.documentVersions?.includes(snapshot.document.schemaVersion)
+	)
+		throw new TypeError("Unsupported composer document version");
+	if (
+		snapshot.operation === "command"
+			? caps.commands !== true
+			: !caps.intents?.includes(snapshot.intent)
+	)
+		throw new TypeError("Unsupported composer operation or intent");
+	if (snapshot.attachments.length && caps.attachments !== true)
+		throw new TypeError("Attachments are not supported by this application");
+	return snapshot;
+}
+
+export function chatJSONKey(value) {
+	if (Array.isArray(value)) return `[${value.map(chatJSONKey).join(",")}]`;
+	if (value && typeof value === "object")
+		return `{${Object.keys(value)
+			.sort()
+			.map((key) => `${JSON.stringify(key)}:${chatJSONKey(value[key])}`)
+			.join(",")}}`;
+	return JSON.stringify(value);
+}
+
+export function correlatedReceipt(response, snapshot, correlation) {
+	if (
+		response?.request_id !== correlation.request_id ||
+		response?.instanceGeneration !== correlation.instanceGeneration
+	)
+		throw new TypeError("Chat response correlation mismatch");
+	return snapshotComposerReceipt(response.receipt, snapshot);
+}