@honua/react 0.1.2-beta.0 → 0.1.7-beta.0

package/realtime/resumable.js

@@ -0,0 +1,632 @@
+/**
+ * Transport-neutral, resumable delivery gate for realtime feature events.
+ *
+ * This module deliberately does not reconnect a transport. It protects the
+ * boundary between a transport and a consumer: compatible checkpoints resume,
+ * ordered events advance durably, duplicates are bounded, and gaps or queue
+ * overflow require an explicit replacement snapshot.
+ *
+ * @module
+ */
+import { HonuaSdkError, mergeHonuaErrorContext } from "../core/error-envelope.js";
+export const REALTIME_DURABLE_CHECKPOINT_VERSION = 1;
+/**
+ * Public realtime failure with the original detailed reason on `.code` and a
+ * stable common-envelope recovery class on `.sdkCode`. Classification metadata
+ * does not reconnect a transport or request a replacement snapshot.
+ */
+export class HonuaRealtimeResumeError extends HonuaSdkError {
+    code;
+    constructor(code, message, options) {
+        super(realtimeResumeSdkCode(code), message, {
+            ...options,
+            context: mergeHonuaErrorContext({ reasonCode: realtimeResumeContextReason(code) }),
+        });
+        this.code = code;
+        this.name = "HonuaRealtimeResumeError";
+    }
+}
+const REALTIME_RESUME_ERROR_CODES = {
+    compatible: "realtime.protocol.terminal",
+    "invalid-checkpoint": "realtime.checkpoint.invalid",
+    "source-changed": "realtime.checkpoint.invalid",
+    "query-changed": "realtime.checkpoint.invalid",
+    "source-version-changed": "realtime.checkpoint.invalid",
+    "schema-version-changed": "realtime.checkpoint.invalid",
+    "authorization-scope-changed": "realtime.checkpoint.invalid",
+    "snapshot-required": "realtime.sequence.gap",
+    "replacement-snapshot-required": "realtime.sequence.gap",
+    "invalid-event": "realtime.protocol.terminal",
+    "sequence-missing": "realtime.sequence.gap",
+    "checkpoint-conflict": "realtime.checkpoint.invalid",
+    "sequence-gap": "realtime.sequence.gap",
+    "event-id-reused": "realtime.sequence.gap",
+    "buffer-overflow": "realtime.sequence.gap",
+    "consumer-failed": "realtime.protocol.terminal",
+    "delivery-failed": "realtime.protocol.terminal",
+    "checkpoint-load-failed": "realtime.protocol.terminal",
+    "checkpoint-save-failed": "realtime.protocol.terminal",
+    "cursor-expired": "realtime.transport.reconnectable",
+    "resume-unsupported": "realtime.transport.reconnectable",
+    "transport-gap": "realtime.transport.reconnectable",
+    cancelled: "realtime.cancelled",
+    closed: "realtime.cancelled",
+};
+function realtimeResumeSdkCode(code) {
+    return isRegisteredRealtimeResumeReason(code) ? REALTIME_RESUME_ERROR_CODES[code] : "realtime.protocol.terminal";
+}
+function realtimeResumeContextReason(code) {
+    return isRegisteredRealtimeResumeReason(code) ? code : "invalid-event";
+}
+function isRegisteredRealtimeResumeReason(code) {
+    return typeof code === "string" && Object.hasOwn(REALTIME_RESUME_ERROR_CODES, code);
+}
+const DEFAULT_MAX_PENDING_EVENTS = 64;
+const DEFAULT_MAX_RECENT_EVENT_IDS = 256;
+const MAX_RECENT_EVENT_IDS = 4096;
+/** Validate a checkpoint against the exact source/query/schema/ACL context. */
+export function evaluateRealtimeCheckpoint(context, checkpoint) {
+    if (!isCheckpointShape(checkpoint)) {
+        return compatibility(false, "invalid-checkpoint", "Checkpoint shape or version is invalid.");
+    }
+    if (checkpoint.context.sourceId !== context.sourceId) {
+        return compatibility(false, "source-changed", "Checkpoint source identity does not match the subscription.");
+    }
+    if (checkpoint.context.queryFingerprint !== context.queryFingerprint) {
+        return compatibility(false, "query-changed", "Checkpoint query identity does not match the accepted query.");
+    }
+    if (checkpoint.context.sourceVersion !== context.sourceVersion) {
+        return compatibility(false, "source-version-changed", "Checkpoint source version requires a new snapshot.");
+    }
+    if (checkpoint.context.schemaVersion !== context.schemaVersion) {
+        return compatibility(false, "schema-version-changed", "Checkpoint schema version requires a new snapshot.");
+    }
+    if (checkpoint.context.authorizationScopeFingerprint !== context.authorizationScopeFingerprint) {
+        return compatibility(false, "authorization-scope-changed", "Checkpoint authorization scope does not match the current grants.");
+    }
+    return compatibility(true, "compatible", "Checkpoint is compatible with the subscription context.");
+}
+/**
+ * Create a serial, bounded delivery gate. Loading a durable checkpoint is the
+ * only asynchronous construction step; no transport is opened here.
+ */
+export async function createResumableRealtimeSubscription(options) {
+    const context = normalizeContext(options.context);
+    const maxPendingEvents = positiveInteger(options.maxPendingEvents ?? DEFAULT_MAX_PENDING_EVENTS, "maxPendingEvents");
+    const maxRecentEventIds = positiveInteger(options.maxRecentEventIds ?? DEFAULT_MAX_RECENT_EVENT_IDS, "maxRecentEventIds");
+    if (maxRecentEventIds > MAX_RECENT_EVENT_IDS) {
+        throw new HonuaRealtimeResumeError("invalid-checkpoint", `maxRecentEventIds cannot exceed the ${MAX_RECENT_EVENT_IDS}-entry safety ceiling.`);
+    }
+    const lifecycle = new AbortController();
+    const externalAbort = () => lifecycle.abort(options.signal?.reason);
+    if (options.signal?.aborted)
+        externalAbort();
+    else
+        options.signal?.addEventListener("abort", externalAbort, { once: true });
+    let loadedCheckpoint = options.initialCheckpoint;
+    if (!loadedCheckpoint && options.checkpointStore && !lifecycle.signal.aborted) {
+        try {
+            loadedCheckpoint = await options.checkpointStore.load(context, lifecycle.signal);
+        }
+        catch (cause) {
+            if (lifecycle.signal.aborted)
+                loadedCheckpoint = undefined;
+            else {
+                options.signal?.removeEventListener("abort", externalAbort);
+                throw new HonuaRealtimeResumeError("checkpoint-load-failed", "Unable to load the realtime checkpoint.", {
+                    cause,
+                });
+            }
+        }
+    }
+    const compatibilityResult = loadedCheckpoint ? evaluateRealtimeCheckpoint(context, loadedCheckpoint) : undefined;
+    const initialCheckpoint = loadedCheckpoint && compatibilityResult?.compatible
+        ? cloneCheckpoint(loadedCheckpoint, maxRecentEventIds)
+        : undefined;
+    let state = freezeState({
+        phase: lifecycle.signal.aborted
+            ? "closed"
+            : compatibilityResult && !compatibilityResult.compatible
+                ? "resnapshot-required"
+                : initialCheckpoint
+                    ? "resuming"
+                    : "awaiting-snapshot",
+        ...(lifecycle.signal.aborted
+            ? { reason: "cancelled", detail: "Subscription was cancelled before it started." }
+            : compatibilityResult && !compatibilityResult.compatible
+                ? { reason: compatibilityResult.code, detail: compatibilityResult.reason }
+                : {}),
+        ...(initialCheckpoint ? { checkpoint: initialCheckpoint } : {}),
+        checkpointPersisted: initialCheckpoint !== undefined,
+        pendingEvents: 0,
+        acceptedEventCount: 0,
+        duplicateEventCount: 0,
+        gapCount: 0,
+        overflowCount: 0,
+    });
+    const queue = [];
+    let active;
+    let activeAbort;
+    let generation = 0;
+    const subscription = {
+        get state() {
+            return state;
+        },
+        enqueue(event) {
+            if (state.phase === "closed")
+                return Promise.resolve(delivery("cancelled", state.reason ?? "closed", state));
+            if (state.phase === "error")
+                return Promise.resolve(delivery("error", state.reason, state));
+            const capture = captureRealtimeEvent(event);
+            if ("conflict" in capture) {
+                const reason = capture.reason ?? "invalid-event";
+                transitionToResnapshot(reason, capture.conflict);
+                return Promise.resolve(delivery("resnapshot-required", reason, state));
+            }
+            const replacementSnapshot = capture.replacementSnapshot;
+            if (state.phase === "resnapshot-required" && !replacementSnapshot) {
+                return Promise.resolve(delivery("resnapshot-required", state.reason, state));
+            }
+            const recoveringFromGap = state.phase === "resnapshot-required" && replacementSnapshot;
+            if (recoveringFromGap) {
+                invalidatePending("replacement-snapshot-required");
+                setState({ phase: "awaiting-snapshot", reason: undefined, detail: undefined });
+            }
+            // A replacement snapshot is the sole recovery path. Let one recovery
+            // item wait behind an abort-ignoring active consumer even when the data
+            // queue is full; ordinary events remain strictly bounded.
+            if (!recoveringFromGap && queue.length + (active ? 1 : 0) >= maxPendingEvents) {
+                transitionToResnapshot("buffer-overflow", `Pending realtime delivery exceeded the configured ${maxPendingEvents}-event bound.`, true);
+                return Promise.resolve(delivery("resnapshot-required", "buffer-overflow", state));
+            }
+            return new Promise((resolve) => {
+                queue.push({ captured: Object.freeze({ ...capture, recoverySnapshot: recoveringFromGap }), resolve });
+                setState({ pendingEvents: queue.length + (active ? 1 : 0) });
+                pump();
+            });
+        },
+        requireResnapshot(reason, detail = "The transport requires a replacement snapshot before delivery can continue.") {
+            if (state.phase === "closed" || state.phase === "error")
+                return;
+            transitionToResnapshot(reason, detail);
+        },
+        close(reason = "Subscription closed by caller.") {
+            closeSubscription(reason, "closed", true);
+        },
+    };
+    if (lifecycle.signal.aborted) {
+        options.signal?.removeEventListener("abort", externalAbort);
+        if (state.phase !== "closed")
+            closeSubscription("Subscription signal was aborted.", "cancelled", false);
+    }
+    else {
+        lifecycle.signal.addEventListener("abort", () => closeSubscription("Subscription signal was aborted.", "cancelled", false), { once: true });
+    }
+    return subscription;
+    function pump() {
+        if (active || state.phase === "closed" || state.phase === "error")
+            return;
+        const next = queue.shift();
+        if (!next) {
+            setState({ pendingEvents: 0 });
+            return;
+        }
+        active = next;
+        activeAbort = new AbortController();
+        const operationGeneration = generation;
+        setState({ pendingEvents: queue.length + 1 });
+        void process(next.captured, activeAbort.signal, operationGeneration)
+            .then(next.resolve, (cause) => {
+            transitionToError("delivery-failed", errorMessage(cause));
+            next.resolve(delivery("error", "delivery-failed", state));
+        })
+            .finally(() => {
+            active = undefined;
+            activeAbort = undefined;
+            setState({ pendingEvents: queue.length });
+            pump();
+        });
+    }
+    async function process(captured, signal, operationGeneration) {
+        if (signal.aborted || lifecycle.signal.aborted || operationGeneration !== generation) {
+            return delivery("cancelled", "cancelled", state);
+        }
+        const { event, eventId, position, replacementSnapshot, recoverySnapshot } = captured;
+        if (position.conflict) {
+            transitionToResnapshot("checkpoint-conflict", position.conflict);
+            return delivery("resnapshot-required", "checkpoint-conflict", state);
+        }
+        if (!isSequence(position.sequence)) {
+            transitionToResnapshot("sequence-missing", "Sequenced snapshot and delta events require a safe integer sequence.");
+            return delivery("resnapshot-required", "sequence-missing", state);
+        }
+        const previousSequence = state.checkpoint?.resume.sequence;
+        if (!state.checkpoint && !replacementSnapshot) {
+            transitionToResnapshot("snapshot-required", "A replacement snapshot is required before delta delivery.");
+            return delivery("resnapshot-required", "snapshot-required", state);
+        }
+        if (event.type === "snapshot" && !replacementSnapshot && state.phase !== "live") {
+            transitionToResnapshot("replacement-snapshot-required", "A merging snapshot cannot establish a resume baseline.");
+            return delivery("resnapshot-required", "replacement-snapshot-required", state);
+        }
+        if (previousSequence !== undefined && position.sequence === previousSequence) {
+            const conflict = sameSequenceCheckpointConflict(state.checkpoint?.resume, position.resume);
+            if (conflict) {
+                transitionToResnapshot("checkpoint-conflict", conflict);
+                return delivery("resnapshot-required", "checkpoint-conflict", state);
+            }
+        }
+        if (previousSequence !== undefined && !recoverySnapshot) {
+            if (position.sequence <= previousSequence) {
+                setState({ duplicateEventCount: state.duplicateEventCount + 1 });
+                return delivery("duplicate", undefined, state);
+            }
+            if (!replacementSnapshot &&
+                (previousSequence === Number.MAX_SAFE_INTEGER || position.sequence !== previousSequence + 1)) {
+                transitionToResnapshot("sequence-gap", `Expected realtime sequence ${previousSequence + 1}, received ${position.sequence}.`);
+                return delivery("resnapshot-required", "sequence-gap", state);
+            }
+        }
+        const recentIds = recoverySnapshot ? [] : (state.checkpoint?.recentEventIds ?? []);
+        if (eventId && recentIds.includes(eventId)) {
+            transitionToResnapshot("event-id-reused", `Event id "${eventId}" was reused at a new sequence.`);
+            return delivery("resnapshot-required", "event-id-reused", state);
+        }
+        try {
+            await options.apply(event, signal);
+        }
+        catch (cause) {
+            if (signal.aborted || lifecycle.signal.aborted || operationGeneration !== generation) {
+                return delivery("cancelled", "cancelled", state);
+            }
+            transitionToError("consumer-failed", errorMessage(cause));
+            return delivery("error", "consumer-failed", state);
+        }
+        if (signal.aborted || lifecycle.signal.aborted || operationGeneration !== generation) {
+            return delivery("cancelled", "cancelled", state);
+        }
+        const checkpoint = createCheckpoint(context, recoverySnapshot ? undefined : state.checkpoint, { ...position, sequence: position.sequence }, eventId, maxRecentEventIds, options.now?.() ?? Date.now());
+        setState({
+            phase: "live",
+            reason: undefined,
+            detail: undefined,
+            checkpoint,
+            checkpointPersisted: false,
+            acceptedEventCount: state.acceptedEventCount + 1,
+        });
+        if (options.checkpointStore) {
+            try {
+                await options.checkpointStore.save(checkpoint, signal);
+            }
+            catch (cause) {
+                if (signal.aborted || lifecycle.signal.aborted || operationGeneration !== generation) {
+                    return delivery("cancelled", "cancelled", state);
+                }
+                transitionToError("checkpoint-save-failed", errorMessage(cause), false);
+                return delivery("error", "checkpoint-save-failed", state);
+            }
+            if (signal.aborted || lifecycle.signal.aborted || operationGeneration !== generation) {
+                return delivery("cancelled", "cancelled", state);
+            }
+            setState({ checkpointPersisted: true });
+        }
+        return delivery("applied", undefined, state);
+    }
+    function transitionToResnapshot(reason, detail, overflow = false) {
+        generation += 1;
+        activeAbort?.abort(detail);
+        drainQueue("resnapshot-required", reason);
+        setState({
+            phase: "resnapshot-required",
+            reason,
+            detail,
+            gapCount: state.gapCount + (reason === "sequence-gap" || reason === "transport-gap" ? 1 : 0),
+            overflowCount: state.overflowCount + (overflow ? 1 : 0),
+            pendingEvents: active ? 1 : 0,
+        });
+    }
+    function invalidatePending(reason) {
+        generation += 1;
+        activeAbort?.abort(reason);
+        drainQueue("resnapshot-required", reason);
+    }
+    function transitionToError(reason, detail, checkpointPersisted = state.checkpointPersisted) {
+        generation += 1;
+        activeAbort?.abort(detail);
+        drainQueue("error", reason);
+        setState({
+            phase: "error",
+            reason,
+            detail,
+            checkpointPersisted,
+            pendingEvents: active ? 1 : 0,
+        });
+    }
+    function closeSubscription(reason, reasonCode, abortLifecycle) {
+        if (state.phase === "closed")
+            return;
+        generation += 1;
+        activeAbort?.abort(reason);
+        options.signal?.removeEventListener("abort", externalAbort);
+        drainQueue("cancelled", reasonCode);
+        setState({ phase: "closed", reason: reasonCode, detail: reason, pendingEvents: active ? 1 : 0 });
+        if (abortLifecycle && !lifecycle.signal.aborted)
+            lifecycle.abort(reason);
+    }
+    function drainQueue(status, reason) {
+        for (const pending of queue.splice(0))
+            pending.resolve(delivery(status, reason, state));
+    }
+    function setState(patch) {
+        state = freezeState({ ...state, ...patch });
+    }
+}
+function normalizeContext(context) {
+    if (!isResumeContextShape(context)) {
+        throw new HonuaRealtimeResumeError("invalid-checkpoint", "Realtime resume context kind or version is invalid.");
+    }
+    return Object.freeze({
+        kind: context.kind,
+        version: context.version,
+        sourceId: requiredText(String(context.sourceId), "sourceId"),
+        queryFingerprint: requiredText(context.queryFingerprint, "queryFingerprint"),
+        sourceVersion: requiredText(context.sourceVersion, "sourceVersion"),
+        schemaVersion: requiredText(context.schemaVersion, "schemaVersion"),
+        authorizationScopeFingerprint: requiredText(context.authorizationScopeFingerprint, "authorizationScopeFingerprint"),
+    });
+}
+function createCheckpoint(context, previous, position, eventId, maxRecentEventIds, now) {
+    const recentEventIds = eventId
+        ? [...(previous?.recentEventIds ?? []), eventId].slice(-maxRecentEventIds)
+        : [...(previous?.recentEventIds ?? [])];
+    return freezeCheckpoint({
+        kind: "honua.realtime-checkpoint",
+        version: REALTIME_DURABLE_CHECKPOINT_VERSION,
+        context,
+        resume: Object.freeze({
+            ...projectResumeCheckpoint(previous?.resume),
+            ...projectResumeCheckpoint(position.resume),
+            sequence: position.sequence,
+        }),
+        recentEventIds: Object.freeze(recentEventIds),
+        savedAt: new Date(finiteNow(now)).toISOString(),
+    });
+}
+function captureRealtimeEvent(input) {
+    if (!isRecord(input))
+        return { conflict: "Realtime delivery must be an event object." };
+    if (!isSequencedEventType(input.type)) {
+        return { conflict: `Realtime event type "${String(input.type)}" is not a sequenced data event.` };
+    }
+    if (input.eventId !== undefined && typeof input.eventId !== "string") {
+        return { conflict: "Realtime eventId must be a string when provided." };
+    }
+    if (input.checkpoint !== undefined && !isRecord(input.checkpoint)) {
+        return { conflict: "Realtime event checkpoint must be an object when provided." };
+    }
+    if (input.receivedAt !== undefined && typeof input.receivedAt !== "number") {
+        return { conflict: "Realtime event receivedAt must be a number when provided." };
+    }
+    const checkpoint = input.checkpoint ? Object.freeze(projectResumeCheckpoint(input.checkpoint)) : undefined;
+    const base = {
+        ...(input.eventId !== undefined ? { eventId: input.eventId } : {}),
+        ...(input.cursor !== undefined ? { cursor: input.cursor } : {}),
+        ...(input.watermark !== undefined ? { watermark: input.watermark } : {}),
+        ...(input.timestamp !== undefined ? { timestamp: input.timestamp } : {}),
+        ...(input.deltaToken !== undefined ? { deltaToken: input.deltaToken } : {}),
+        ...(checkpoint ? { checkpoint } : {}),
+        ...(input.sequence !== undefined ? { sequence: input.sequence } : {}),
+        ...(input.receivedAt !== undefined ? { receivedAt: input.receivedAt } : {}),
+    };
+    let event;
+    switch (input.type) {
+        case "snapshot":
+            if (!Array.isArray(input.features))
+                return { conflict: "Realtime snapshot features must be an array." };
+            if (input.replace !== undefined && typeof input.replace !== "boolean") {
+                return { conflict: "Realtime snapshot replace must be a boolean when provided." };
+            }
+            event = Object.freeze({
+                ...base,
+                type: "snapshot",
+                features: Object.freeze(input.features.slice()),
+                ...(input.replace !== undefined ? { replace: input.replace } : {}),
+            });
+            break;
+        case "upsert":
+            if (!isRecord(input.feature))
+                return { conflict: "Realtime upsert feature must be an object." };
+            event = Object.freeze({
+                ...base,
+                type: "upsert",
+                feature: input.feature,
+            });
+            break;
+        case "delete":
+            if (!isFeatureId(input.id))
+                return { conflict: "Realtime delete id must be a string or number." };
+            event = Object.freeze({
+                ...base,
+                type: "delete",
+                id: input.id,
+                ...(typeof input.sourceId === "string" ? { sourceId: input.sourceId } : {}),
+                ...(typeof input.version === "number" ? { version: input.version } : {}),
+                ...(typeof input.updatedAt === "string" ? { updatedAt: input.updatedAt } : {}),
+                ...(typeof input.deletedAt === "number" ? { deletedAt: input.deletedAt } : {}),
+            });
+            break;
+        case "delta":
+            if (input.upserts !== undefined && !Array.isArray(input.upserts)) {
+                return { conflict: "Realtime delta upserts must be an array when provided." };
+            }
+            if (input.deletes !== undefined && !Array.isArray(input.deletes)) {
+                return { conflict: "Realtime delta deletes must be an array when provided." };
+            }
+            event = Object.freeze({
+                ...base,
+                type: "delta",
+                ...(input.upserts !== undefined
+                    ? {
+                        upserts: Object.freeze(input.upserts.slice()),
+                    }
+                    : {}),
+                ...(input.deletes !== undefined
+                    ? {
+                        deletes: Object.freeze(input.deletes.slice()),
+                    }
+                    : {}),
+            });
+            break;
+    }
+    const position = eventPosition(event);
+    if (position.conflict)
+        return { conflict: position.conflict, reason: "checkpoint-conflict" };
+    return Object.freeze({
+        event,
+        ...(input.eventId !== undefined ? { eventId: input.eventId } : {}),
+        position,
+        replacementSnapshot: event.type === "snapshot" && event.replace !== false,
+        recoverySnapshot: false,
+    });
+}
+function eventPosition(event) {
+    const pairs = [
+        ["cursor", event.cursor, event.checkpoint?.cursor],
+        ["watermark", event.watermark, event.checkpoint?.watermark],
+        ["timestamp", event.timestamp, event.checkpoint?.timestamp],
+        ["sequence", event.sequence, event.checkpoint?.sequence],
+        ["deltaToken", event.deltaToken, event.checkpoint?.deltaToken],
+    ];
+    for (const [name, direct, nested] of pairs) {
+        const expectedType = name === "sequence" ? "number" : "string";
+        const directInvalid = name === "sequence" ? typeof direct !== "number" : typeof direct !== "string";
+        if (direct !== undefined && directInvalid) {
+            return { resume: {}, conflict: `Event ${name} must be a ${expectedType}.` };
+        }
+        const nestedInvalid = name === "sequence" ? typeof nested !== "number" : typeof nested !== "string";
+        if (nested !== undefined && nestedInvalid) {
+            return { resume: {}, conflict: `Nested checkpoint ${name} must be a ${expectedType}.` };
+        }
+        if (direct !== undefined && nested !== undefined && direct !== nested) {
+            return { resume: {}, conflict: `Event ${name} conflicts with its nested checkpoint value.` };
+        }
+    }
+    const sequence = event.sequence ?? event.checkpoint?.sequence;
+    return {
+        sequence,
+        resume: Object.freeze({
+            ...projectResumeCheckpoint(event.checkpoint),
+            ...(event.cursor !== undefined ? { cursor: event.cursor } : {}),
+            ...(event.watermark !== undefined ? { watermark: event.watermark } : {}),
+            ...(event.timestamp !== undefined ? { timestamp: event.timestamp } : {}),
+            ...(event.deltaToken !== undefined ? { deltaToken: event.deltaToken } : {}),
+            ...(sequence !== undefined ? { sequence } : {}),
+        }),
+    };
+}
+function sameSequenceCheckpointConflict(previous, incoming) {
+    for (const name of ["cursor", "deltaToken"]) {
+        const previousValue = previous?.[name];
+        const incomingValue = incoming[name];
+        if (previousValue !== undefined && incomingValue !== undefined && previousValue !== incomingValue) {
+            return `Realtime sequence ${String(incoming.sequence)} reuses ${name} with a conflicting value.`;
+        }
+    }
+    return undefined;
+}
+function projectResumeCheckpoint(value) {
+    if (!isRecord(value))
+        return {};
+    return {
+        ...(value.cursor !== undefined ? { cursor: value.cursor } : {}),
+        ...(value.watermark !== undefined ? { watermark: value.watermark } : {}),
+        ...(value.timestamp !== undefined ? { timestamp: value.timestamp } : {}),
+        ...(value.sequence !== undefined ? { sequence: value.sequence } : {}),
+        ...(value.deltaToken !== undefined ? { deltaToken: value.deltaToken } : {}),
+    };
+}
+function isSequencedEventType(value) {
+    return value === "snapshot" || value === "upsert" || value === "delete" || value === "delta";
+}
+function isFeatureId(value) {
+    return typeof value === "string" || typeof value === "number";
+}
+function cloneCheckpoint(checkpoint, maxRecentEventIds) {
+    return freezeCheckpoint({
+        kind: checkpoint.kind,
+        version: checkpoint.version,
+        context: normalizeContext(checkpoint.context),
+        resume: Object.freeze(projectResumeCheckpoint(checkpoint.resume)),
+        recentEventIds: Object.freeze(checkpoint.recentEventIds.slice(-maxRecentEventIds)),
+        savedAt: checkpoint.savedAt,
+    });
+}
+function freezeCheckpoint(checkpoint) {
+    return Object.freeze(checkpoint);
+}
+function freezeState(state) {
+    return Object.freeze(state);
+}
+function compatibility(compatibleValue, code, reason) {
+    return Object.freeze({ compatible: compatibleValue, code, reason });
+}
+function delivery(status, reason, state) {
+    return Object.freeze({
+        status,
+        ...(reason ? { reason } : {}),
+        ...(state.checkpoint ? { checkpoint: state.checkpoint } : {}),
+    });
+}
+function positiveInteger(value, name) {
+    if (!Number.isSafeInteger(value) || value < 1) {
+        throw new HonuaRealtimeResumeError("invalid-checkpoint", `${name} must be a safe integer greater than zero.`);
+    }
+    return value;
+}
+function requiredText(value, name) {
+    const normalized = value.trim();
+    if (!normalized)
+        throw new HonuaRealtimeResumeError("invalid-checkpoint", `${name} must be non-empty.`);
+    return normalized;
+}
+function isSequence(value) {
+    return Number.isSafeInteger(value) && value >= 0;
+}
+function isCheckpointShape(value) {
+    if (!isRecord(value))
+        return false;
+    if (value.kind !== "honua.realtime-checkpoint" || value.version !== REALTIME_DURABLE_CHECKPOINT_VERSION)
+        return false;
+    if (!isResumeContextShape(value.context) || !isRecord(value.resume) || !isSequence(value.resume.sequence))
+        return false;
+    for (const name of ["cursor", "watermark", "timestamp", "deltaToken"]) {
+        if (value.resume[name] !== undefined && typeof value.resume[name] !== "string")
+            return false;
+    }
+    if (!Array.isArray(value.recentEventIds) ||
+        value.recentEventIds.length > MAX_RECENT_EVENT_IDS ||
+        value.recentEventIds.some((entry) => typeof entry !== "string"))
+        return false;
+    return typeof value.savedAt === "string" && Number.isFinite(Date.parse(value.savedAt));
+}
+function isResumeContextShape(value) {
+    return (isRecord(value) &&
+        value.kind === "honua.realtime-resume-context" &&
+        value.version === 1 &&
+        typeof value.sourceId === "string" &&
+        typeof value.queryFingerprint === "string" &&
+        typeof value.sourceVersion === "string" &&
+        typeof value.schemaVersion === "string" &&
+        typeof value.authorizationScopeFingerprint === "string");
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null;
+}
+function finiteNow(value) {
+    if (!Number.isFinite(value))
+        throw new HonuaRealtimeResumeError("invalid-checkpoint", "now() must return a finite time.");
+    return value;
+}
+function errorMessage(value) {
+    return value instanceof Error ? value.message : String(value);
+}

package/realtime/sse.d.ts

@@ -0,0 +1,23 @@
+import type { RealtimeFeatureEvent, RealtimeFeatureTransport, RealtimeSubscriptionRequest } from "./types.js";
+export interface RealtimeServerSentEventSource {
+    readonly readyState?: number;
+    onopen: ((event: Event) => void) | null;
+    onmessage: ((event: MessageEvent<string>) => void) | null;
+    onerror: ((event: Event) => void) | null;
+    close(): void;
+    addEventListener?(type: string, listener: (event: MessageEvent<string>) => void): void;
+    removeEventListener?(type: string, listener: (event: MessageEvent<string>) => void): void;
+}
+export type RealtimeServerSentEventSourceFactory = (url: string, init?: EventSourceInit) => RealtimeServerSentEventSource;
+export interface RealtimeServerSentEventsTransportOptions<TFeature = unknown> {
+    readonly url: string;
+    readonly eventSourceFactory?: RealtimeServerSentEventSourceFactory;
+    readonly withCredentials?: boolean;
+    readonly eventTypes?: ReadonlyArray<string>;
+    readonly encodeRequest?: (url: URL, request: RealtimeSubscriptionRequest) => void;
+    readonly decodeEvent?: (payload: unknown) => RealtimeFeatureEvent<TFeature>;
+}
+export declare function createRealtimeServerSentEventsTransport<TFeature = unknown>(options: RealtimeServerSentEventsTransportOptions<TFeature>): RealtimeFeatureTransport<TFeature>;
+export declare function encodeDefaultRealtimeRequest(url: URL, request: RealtimeSubscriptionRequest): URL;
+export declare function decodeRealtimeServerSentEvent<TFeature = unknown>(payload: unknown): RealtimeFeatureEvent<TFeature>;
+//# sourceMappingURL=sse.d.ts.map

package/realtime/sse.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sse.d.ts","sourceRoot":"","sources":["../../../src/realtime/sse.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,oBAAoB,EACpB,wBAAwB,EAExB,2BAA2B,EAC5B,MAAM,YAAY,CAAC;AAGpB,MAAM,WAAW,6BAA6B;IAC5C,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,MAAM,EAAE,CAAC,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC,GAAG,IAAI,CAAC;IACxC,SAAS,EAAE,CAAC,CAAC,KAAK,EAAE,YAAY,CAAC,MAAM,CAAC,KAAK,IAAI,CAAC,GAAG,IAAI,CAAC;IAC1D,OAAO,EAAE,CAAC,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC,GAAG,IAAI,CAAC;IACzC,KAAK,IAAI,IAAI,CAAC;IACd,gBAAgB,CAAC,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,KAAK,EAAE,YAAY,CAAC,MAAM,CAAC,KAAK,IAAI,GAAG,IAAI,CAAC;IACvF,mBAAmB,CAAC,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,KAAK,EAAE,YAAY,CAAC,MAAM,CAAC,KAAK,IAAI,GAAG,IAAI,CAAC;CAC3F;AAED,MAAM,MAAM,oCAAoC,GAAG,CACjD,GAAG,EAAE,MAAM,EACX,IAAI,CAAC,EAAE,eAAe,KACnB,6BAA6B,CAAC;AAEnC,MAAM,WAAW,wCAAwC,CAAC,QAAQ,GAAG,OAAO;IAC1E,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,kBAAkB,CAAC,EAAE,oCAAoC,CAAC;IACnE,QAAQ,CAAC,eAAe,CAAC,EAAE,OAAO,CAAC;IACnC,QAAQ,CAAC,UAAU,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IAC5C,QAAQ,CAAC,aAAa,CAAC,EAAE,CAAC,GAAG,EAAE,GAAG,EAAE,OAAO,EAAE,2BAA2B,KAAK,IAAI,CAAC;IAClF,QAAQ,CAAC,WAAW,CAAC,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,oBAAoB,CAAC,QAAQ,CAAC,CAAC;CAC7E;AAID,wBAAgB,uCAAuC,CAAC,QAAQ,GAAG,OAAO,EACxE,OAAO,EAAE,wCAAwC,CAAC,QAAQ,CAAC,GAC1D,wBAAwB,CAAC,QAAQ,CAAC,CAqGpC;AAED,wBAAgB,4BAA4B,CAAC,GAAG,EAAE,GAAG,EAAE,OAAO,EAAE,2BAA2B,GAAG,GAAG,CAsBhG;AAED,wBAAgB,6BAA6B,CAAC,QAAQ,GAAG,OAAO,EAAE,OAAO,EAAE,OAAO,GAAG,oBAAoB,CAAC,QAAQ,CAAC,CAElH"}