@honua/app-platform 0.1.0-beta.0 → 0.1.2-beta.0

package/realtime/odata-delta.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"odata-delta.d.ts","sourceRoot":"","sources":["../../../src/realtime/odata-delta.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAEtD,OAAO,KAAK,EAIV,wBAAwB,EAEzB,MAAM,YAAY,CAAC;AAGpB,sFAAsF;AACtF,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACjC;AAED,6FAA6F;AAC7F,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACrC,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,8GAA8G;AAC9G,MAAM,WAAW,uBAAuB;IACtC,4DAA4D;IAC5D,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,uGAAuG;IACvG,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B;AAED,MAAM,WAAW,0BAA0B,CAAC,QAAQ,GAAG,OAAO;IAC5D;;;;;;OAMG;IACH,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,6EAA6E;IAC7E,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,wFAAwF;IACxF,QAAQ,CAAC,QAAQ,EAAE,CAAC,MAAM,EAAE,gBAAgB,KAAK,SAAS,CAAC;IAC3D,sHAAsH;IACtH,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC,MAAM,EAAE,gBAAgB,KAAK,QAAQ,CAAC;IAC5D,gGAAgG;IAChG,QAAQ,CAAC,YAAY,CAAC,EAAE,sBAAsB,CAAC;IAC/C,iFAAiF;IACjF,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChD,wDAAwD;IACxD,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;IAClC;;;;OAIG;IACH,QAAQ,CAAC,0BAA0B,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,KAAK,OAAO,CAAC;IACjF;;;;;;OAMG;IACH,QAAQ,CAAC,wBAAwB,CAAC,EAAE,CAAC,KAAK,EAAE,gBAAgB,KAAK,OAAO,CAAC;IACzE,sFAAsF;IACtF,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IACnC,4EAA4E;IAC5E,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;IAClC,6FAA6F;IAC7F,QAAQ,CAAC,yBAAyB,CAAC,EAAE,MAAM,CAAC;IAC5C,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC,SAAS,EAAE,uBAAuB,KAAK,IAAI,CAAC;IAC/D,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CAC7B;AAMD;;;GAGG;AACH,wBAAgB,yBAAyB,CAAC,QAAQ,GAAG,OAAO,EAC1D,OAAO,EAAE,0BAA0B,CAAC,QAAQ,CAAC,GAC5C,wBAAwB,CAAC,QAAQ,CAAC,CAkYpC"}

package/realtime/odata-delta.js

@@ -0,0 +1,483 @@
+/**
+ * OData v4 delta-link pull adapter for `@honua/sdk-js/realtime` (issue #558).
+ *
+ * OData delta links (`@odata.deltaLink`) are a *pull* change feed, not a
+ * socket transport: a client requests a scoped delta-link URL and the
+ * server returns only what changed since that link was minted, plus a fresh
+ * delta link for the next request. This module maps that request/response
+ * paging protocol onto the transport-neutral `RealtimeFeatureTransport`
+ * surface (`types.ts`, #556) so it composes with `createRealtimeFeatureStore`
+ * / `createResumableRealtimeSubscription` exactly like the SSE and WebSocket
+ * adapters (`sse.ts`, `websocket.ts`, #557) — with one deliberate
+ * difference dictated by REQ-004: this transport never claims to be live.
+ * `capabilities.kind` is `"polling"`, it never emits a `"heartbeat"`, and
+ * `onPoll` reports an explicit cadence/freshness snapshot on every request
+ * cycle so a consumer can render "checked N seconds ago, next check in M"
+ * rather than a live badge that misrepresents a poll as a stream.
+ *
+ * Ownership split from the SSE/WebSocket adapters: those open exactly one
+ * connection per `subscribe()` and never reconnect on their own, deferring
+ * reconnect entirely to `resumable-transport.ts`. This transport has no
+ * connection to reconnect — every cycle is an independent request/response —
+ * so it owns its own bounded poll loop, including the on-expiry resnapshot
+ * recovery a socket transport cannot perform for itself: an expired or
+ * rejected delta link (REQ per the User Workflow, "Expired/invalid delta
+ * state requires an explicit resnapshot") is recovered by re-running a full
+ * snapshot cycle and emitting a fresh `type: "snapshot", replace: true`
+ * event, bounded by `maxConsecutiveResnapshots` so a server that keeps
+ * rejecting the token cannot loop forever.
+ *
+ * Security posture (REQ-002): every `@odata.nextLink` / `@odata.deltaLink`
+ * this transport follows, and any caller-supplied `resumeFrom.deltaToken`,
+ * must resolve to the exact same origin and collection path as the
+ * configured `url`. A link that does not is rejected rather than followed —
+ * a delta token is an opaque, potentially attacker-influenced value once it
+ * has round-tripped through a checkpoint store, and this transport never
+ * trusts it to redirect a request elsewhere.
+ *
+ * @module
+ */
+import { HonuaRealtimeResumeError } from "./resumable.js";
+import { realtimeFailure } from "./wire.js";
+const DEFAULT_MAX_PAGES_PER_CYCLE = 500;
+const DEFAULT_MAX_SNAPSHOT_ROWS = 50_000;
+const DEFAULT_MAX_CONSECUTIVE_RESNAPSHOTS = 3;
+/**
+ * Build a {@link RealtimeFeatureTransport} that polls an OData v4 entity
+ * set's delta link. See the module doc for the full recovery/security model.
+ */
+export function createOdataDeltaTransport(options) {
+    if (typeof options.entityId !== "function") {
+        throw new TypeError("createOdataDeltaTransport requires options.entityId.");
+    }
+    const pollIntervalMs = positiveInteger(options.pollIntervalMs, "pollIntervalMs");
+    const maxPagesPerCycle = positiveInteger(options.maxPagesPerCycle ?? DEFAULT_MAX_PAGES_PER_CYCLE, "maxPagesPerCycle");
+    const maxSnapshotRows = positiveInteger(options.maxSnapshotRows ?? DEFAULT_MAX_SNAPSHOT_ROWS, "maxSnapshotRows");
+    const maxConsecutiveResnapshots = positiveInteger(options.maxConsecutiveResnapshots ?? DEFAULT_MAX_CONSECUTIVE_RESNAPSHOTS, "maxConsecutiveResnapshots");
+    const collectionUrl = parseAbsoluteUrl(options.url, `createOdataDeltaTransport requires an absolute options.url ("${options.url}").`);
+    return {
+        capabilities: {
+            kind: "polling",
+            resumeModes: ["delta-token"],
+            emitsHeartbeats: false,
+            emitsWatermarks: false,
+        },
+        subscribe(request, observer) {
+            if (request.signal?.aborted) {
+                observer.complete();
+                return { close: () => { } };
+            }
+            const resumeDeltaToken = request.deltaToken ?? request.resumeFrom?.deltaToken;
+            let initialDeltaLink;
+            if (resumeDeltaToken !== undefined) {
+                const resumeUrl = parseRelativeOdataUrl(resumeDeltaToken, collectionUrl, `Realtime resumeFrom.deltaToken "${resumeDeltaToken}" is not a valid URL.`);
+                assertSameOdataCollection(collectionUrl, resumeUrl);
+                initialDeltaLink = resumeUrl.toString();
+            }
+            const now = () => options.now?.() ?? Date.now();
+            const controller = new AbortController();
+            let closed = false;
+            let sequence = request.resumeFrom?.sequence ?? 0;
+            let resnapshotStreak = 0;
+            let timer;
+            const abortListener = () => teardown("Subscription signal was aborted.", true);
+            request.signal?.addEventListener("abort", abortListener, { once: true });
+            function teardown(reason, complete) {
+                if (closed)
+                    return;
+                closed = true;
+                if (timer !== undefined)
+                    clearTimeout(timer);
+                request.signal?.removeEventListener("abort", abortListener);
+                if (!controller.signal.aborted)
+                    controller.abort(reason);
+                if (complete)
+                    observer.complete();
+            }
+            function fail(error) {
+                if (closed)
+                    return;
+                closed = true;
+                if (timer !== undefined)
+                    clearTimeout(timer);
+                request.signal?.removeEventListener("abort", abortListener);
+                if (!controller.signal.aborted)
+                    controller.abort("OData delta transport failed.");
+                observer.error(error);
+            }
+            function emit(event) {
+                if (closed)
+                    return false;
+                try {
+                    observer.next(event);
+                    return true;
+                }
+                catch (cause) {
+                    fail(realtimeFailure("consumer-failed", "Realtime event observer rejected delivery.", cause));
+                    return false;
+                }
+            }
+            function reportPoll(partial) {
+                if (!options.onPoll)
+                    return;
+                try {
+                    options.onPoll({
+                        polledAt: now(),
+                        intervalMs: pollIntervalMs,
+                        sequence,
+                        changed: partial.changed,
+                        upsertCount: partial.upsertCount,
+                        deleteCount: partial.deleteCount,
+                        ...(partial.scheduled ? { nextPollAt: now() + pollIntervalMs } : {}),
+                    });
+                }
+                catch {
+                    // Telemetry is diagnostic only; a throwing onPoll callback must
+                    // never affect delivery.
+                }
+            }
+            function schedulePoll(link) {
+                if (closed)
+                    return;
+                timer = setTimeout(() => {
+                    timer = undefined;
+                    void runDeltaCycle(link);
+                }, pollIntervalMs);
+            }
+            async function fetchOdataDocument(target, trackChanges) {
+                const fetchImpl = resolveFetch(options.fetchImpl);
+                const headers = { Accept: "application/json", ...(options.headers?.() ?? {}) };
+                if (trackChanges)
+                    headers.Prefer = "odata.track-changes";
+                let response;
+                try {
+                    response = await fetchImpl(target, { method: "GET", headers, signal: controller.signal });
+                }
+                catch (cause) {
+                    if (controller.signal.aborted)
+                        throw cause;
+                    throw realtimeFailure("transport-gap", "OData delta request failed.", cause);
+                }
+                if (!response.ok) {
+                    const body = await safeReadJson(response);
+                    const isExpired = (options.isDeltaLinkExpiredResponse ?? defaultIsDeltaLinkExpiredResponse)(response.status, body);
+                    if (isExpired) {
+                        throw new HonuaRealtimeResumeError("cursor-expired", `OData delta link expired or was rejected by the server (HTTP ${String(response.status)}).`);
+                    }
+                    throw realtimeFailure(response.status >= 500 ? "transport-gap" : "invalid-event", `OData delta request failed with HTTP ${String(response.status)}${response.statusText ? ` ${response.statusText}` : ""}.`, body);
+                }
+                const body = await safeReadJson(response);
+                if (!isRecord(body) || !Array.isArray(body.value)) {
+                    throw realtimeFailure("invalid-event", "OData delta response is missing a JSON `value` array.", body);
+                }
+                return body;
+            }
+            function parseEntry(raw) {
+                if (!isRecord(raw)) {
+                    throw realtimeFailure("invalid-event", "OData delta entry must be a JSON object.", raw);
+                }
+                const removed = raw["@removed"] ?? raw["@odata.removed"];
+                if (removed !== undefined) {
+                    return { kind: "delete", patch: { id: removedEntryId(raw) } };
+                }
+                const isRelationshipDelta = options.isRelationshipDeltaEntry ?? defaultIsRelationshipDeltaEntry;
+                if (isRelationshipDelta(raw)) {
+                    throw realtimeFailure("invalid-event", "OData relationship (link) deltas are not supported by createOdataDeltaTransport; only entity upserts and removals are normalized (REQ-003).", raw);
+                }
+                try {
+                    const id = options.entityId(raw);
+                    const feature = (options.toFeature ?? defaultToFeature)(raw);
+                    return { kind: "upsert", patch: { id, feature } };
+                }
+                catch (cause) {
+                    throw realtimeFailure("invalid-event", "OData delta entry projection (entityId/toFeature) failed.", cause);
+                }
+            }
+            function removedEntryId(entry) {
+                const withoutAnnotations = Object.fromEntries(Object.entries(entry).filter(([key]) => !key.startsWith("@")));
+                if (Object.keys(withoutAnnotations).length > 0) {
+                    try {
+                        return options.entityId(withoutAnnotations);
+                    }
+                    catch {
+                        // Fall through to @id parsing below.
+                    }
+                }
+                const idValue = entry["@id"] ?? entry["@odata.id"];
+                if (typeof idValue !== "string") {
+                    throw realtimeFailure("invalid-event", "OData removed delta entry has neither key properties nor an @id/@odata.id to derive an id from.", entry);
+                }
+                const key = parseODataIdKey(idValue);
+                if (key === undefined) {
+                    throw realtimeFailure("invalid-event", `OData removed delta entry's id "${idValue}" uses a composite or unparseable key; the removed entry must retain key properties instead.`, entry);
+                }
+                return key;
+            }
+            async function runCycle(startUrl, mode) {
+                let target = startUrl;
+                let pages = 0;
+                const upserts = [];
+                const deletes = [];
+                let deltaLink;
+                while (true) {
+                    pages += 1;
+                    if (pages > maxPagesPerCycle) {
+                        throw realtimeFailure("delivery-failed", `OData delta paging exceeded the configured ${String(maxPagesPerCycle)}-page bound.`, undefined);
+                    }
+                    const envelope = await fetchOdataDocument(target, mode === "snapshot" && pages === 1);
+                    for (const raw of envelope.value) {
+                        const parsed = parseEntry(raw);
+                        if (parsed.kind === "delete")
+                            deletes.push(parsed.patch);
+                        else
+                            upserts.push(parsed.patch);
+                        if (mode === "snapshot" && upserts.length > maxSnapshotRows) {
+                            throw realtimeFailure("delivery-failed", `OData snapshot exceeded the configured ${String(maxSnapshotRows)}-row bound.`, undefined);
+                        }
+                    }
+                    const pageDeltaLink = envelope["@odata.deltaLink"];
+                    if (pageDeltaLink !== undefined) {
+                        const resolved = parseRelativeOdataUrl(pageDeltaLink, target, `OData response @odata.deltaLink "${pageDeltaLink}" is not a valid URL.`);
+                        assertSameOdataCollection(collectionUrl, resolved);
+                        deltaLink = resolved.toString();
+                    }
+                    const nextLink = envelope["@odata.nextLink"];
+                    if (nextLink === undefined)
+                        break;
+                    const resolvedNext = parseRelativeOdataUrl(nextLink, target, `OData response @odata.nextLink "${nextLink}" is not a valid URL.`);
+                    assertSameOdataCollection(collectionUrl, resolvedNext);
+                    target = resolvedNext.toString();
+                }
+                if (deltaLink === undefined) {
+                    throw realtimeFailure("invalid-event", "OData response did not include a terminal @odata.deltaLink; the server may not support delta-link change tracking for this collection.", undefined);
+                }
+                return { upserts, deletes, deltaLink };
+            }
+            function buildInitialUrl() {
+                const url = new URL(collectionUrl.toString());
+                const query = options.initialQuery;
+                if (query?.filter)
+                    url.searchParams.set("$filter", query.filter);
+                if (query?.select?.length)
+                    url.searchParams.set("$select", query.select.join(","));
+                if (query?.orderBy?.length)
+                    url.searchParams.set("$orderby", query.orderBy.join(","));
+                if (typeof query?.top === "number" && Number.isFinite(query.top)) {
+                    url.searchParams.set("$top", String(query.top));
+                }
+                return url.toString();
+            }
+            /**
+             * Shared recovery path for a `cursor-expired` failure from *either*
+             * cycle: a real server should only ever reject a `$deltatoken`, but a
+             * caller-supplied `isDeltaLinkExpiredResponse` could in principle
+             * classify any response that way, so both cycles route through the
+             * same bounded streak counter (REQ-005) rather than the snapshot
+             * cycle failing closed on its very first retry.
+             */
+            async function recoverFromExpiredDeltaLink(cause) {
+                resnapshotStreak += 1;
+                if (resnapshotStreak > maxConsecutiveResnapshots) {
+                    fail(realtimeFailure("delivery-failed", `OData delta link expired ${String(resnapshotStreak)} times consecutively; giving up after the configured ${String(maxConsecutiveResnapshots)}-resnapshot bound.`, cause));
+                    return;
+                }
+                reportPoll({ changed: false, upsertCount: 0, deleteCount: 0, scheduled: false });
+                const delivered = emit({
+                    type: "status",
+                    status: "reconnecting",
+                    reason: "cursor-expired",
+                    receivedAt: now(),
+                });
+                if (!delivered)
+                    return;
+                await runSnapshotCycle();
+            }
+            async function runSnapshotCycle() {
+                try {
+                    const cycle = await runCycle(buildInitialUrl(), "snapshot");
+                    if (closed)
+                        return;
+                    resnapshotStreak = 0;
+                    sequence += 1;
+                    const delivered = emit({
+                        type: "snapshot",
+                        sequence,
+                        deltaToken: cycle.deltaLink,
+                        receivedAt: now(),
+                        replace: true,
+                        features: cycle.upserts,
+                    });
+                    if (!delivered)
+                        return;
+                    reportPoll({
+                        changed: true,
+                        upsertCount: cycle.upserts.length,
+                        deleteCount: 0,
+                        scheduled: true,
+                    });
+                    schedulePoll(cycle.deltaLink);
+                }
+                catch (cause) {
+                    if (closed)
+                        return;
+                    if (cause instanceof HonuaRealtimeResumeError && cause.code === "cursor-expired") {
+                        await recoverFromExpiredDeltaLink(cause);
+                        return;
+                    }
+                    fail(cause);
+                }
+            }
+            async function runDeltaCycle(link) {
+                try {
+                    const cycle = await runCycle(link, "delta");
+                    if (closed)
+                        return;
+                    resnapshotStreak = 0;
+                    const changed = cycle.upserts.length > 0 || cycle.deletes.length > 0;
+                    if (changed)
+                        sequence += 1;
+                    const delivered = emit(changed
+                        ? {
+                            type: "delta",
+                            sequence,
+                            deltaToken: cycle.deltaLink,
+                            receivedAt: now(),
+                            ...(cycle.upserts.length ? { upserts: cycle.upserts } : {}),
+                            ...(cycle.deletes.length ? { deletes: cycle.deletes } : {}),
+                        }
+                        : {
+                            type: "status",
+                            status: "live",
+                            sequence,
+                            deltaToken: cycle.deltaLink,
+                            receivedAt: now(),
+                            reason: "poll-unchanged",
+                        });
+                    if (!delivered)
+                        return;
+                    reportPoll({
+                        changed,
+                        upsertCount: cycle.upserts.length,
+                        deleteCount: cycle.deletes.length,
+                        scheduled: true,
+                    });
+                    schedulePoll(cycle.deltaLink);
+                }
+                catch (cause) {
+                    if (closed)
+                        return;
+                    if (cause instanceof HonuaRealtimeResumeError && cause.code === "cursor-expired") {
+                        await recoverFromExpiredDeltaLink(cause);
+                        return;
+                    }
+                    fail(cause);
+                }
+            }
+            void (initialDeltaLink !== undefined ? runDeltaCycle(initialDeltaLink) : runSnapshotCycle());
+            return {
+                close() {
+                    teardown("Subscription closed by caller.", true);
+                },
+            };
+        },
+    };
+}
+function defaultIsDeltaLinkExpiredResponse(status) {
+    return status === 410;
+}
+function defaultIsRelationshipDeltaEntry(entry) {
+    return typeof entry.source === "string" && typeof entry.relationship === "string" && typeof entry.target === "string";
+}
+function defaultToFeature(entity) {
+    const clean = {};
+    for (const [key, value] of Object.entries(entity)) {
+        if (!key.startsWith("@"))
+            clean[key] = value;
+    }
+    return clean;
+}
+/**
+ * Reject a next/delta link that does not resolve to the exact origin and
+ * collection path this transport was configured for (REQ-002). Trailing
+ * slashes are normalized so `.../Incidents` and `.../Incidents/` are treated
+ * as the same collection.
+ */
+function assertSameOdataCollection(expected, candidate) {
+    if (candidate.origin !== expected.origin || normalizedPathname(candidate) !== normalizedPathname(expected)) {
+        throw new HonuaRealtimeResumeError("invalid-event", `OData delta/next link "${candidate.toString()}" does not resolve to the configured collection "${expected.toString()}"; refusing to follow a foreign link.`);
+    }
+}
+function normalizedPathname(url) {
+    return url.pathname.length > 1 && url.pathname.endsWith("/") ? url.pathname.slice(0, -1) : url.pathname;
+}
+/**
+ * Parse the single-value key predicate out of an OData `@id`/`@odata.id`
+ * value like `Incidents('AB-12')` or `Incidents(42)`. Returns `undefined`
+ * for composite keys (`Key1=1,Key2='a'`) or an unparseable shape — callers
+ * treat that as unsupported rather than guessing.
+ */
+function parseODataIdKey(idValue) {
+    const open = idValue.lastIndexOf("(");
+    if (open === -1 || !idValue.endsWith(")"))
+        return undefined;
+    const inner = idValue.slice(open + 1, -1);
+    if (inner.includes("=") || hasTopLevelComma(inner))
+        return undefined;
+    const unquoted = inner.startsWith("'") && inner.endsWith("'") ? inner.slice(1, -1).replace(/''/g, "'") : inner;
+    if (unquoted.length === 0)
+        return undefined;
+    if (/^-?\d+$/.test(unquoted) && Number.isSafeInteger(Number(unquoted)))
+        return Number(unquoted);
+    return unquoted;
+}
+function hasTopLevelComma(inner) {
+    let quoted = false;
+    for (const character of inner) {
+        if (character === "'")
+            quoted = !quoted;
+        else if (character === "," && !quoted)
+            return true;
+    }
+    return false;
+}
+function parseAbsoluteUrl(input, message) {
+    try {
+        return new URL(input);
+    }
+    catch (cause) {
+        throw new TypeError(message, { cause });
+    }
+}
+function parseRelativeOdataUrl(value, base, message) {
+    try {
+        return new URL(value, base);
+    }
+    catch (cause) {
+        throw new HonuaRealtimeResumeError("invalid-event", message, { cause });
+    }
+}
+function resolveFetch(custom) {
+    if (custom)
+        return custom;
+    const globalFetch = globalThis.fetch;
+    if (!globalFetch)
+        throw new Error("fetch is not available; provide fetchImpl for this runtime.");
+    return globalFetch.bind(globalThis);
+}
+async function safeReadJson(response) {
+    try {
+        return await response.json();
+    }
+    catch {
+        return undefined;
+    }
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null;
+}
+function positiveInteger(value, name) {
+    if (!Number.isSafeInteger(value) || value < 1) {
+        throw new TypeError(`createOdataDeltaTransport: ${name} must be a safe integer greater than zero.`);
+    }
+    return value;
+}

package/realtime/resumable-transport.d.ts

@@ -0,0 +1,111 @@
+/**
+ * Bounded, resumable SSE and WebSocket transports for `@honua/sdk-js/realtime`
+ * (issue #557), built on the #556 snapshot/delta/cursor/resume/plan-identity
+ * contract.
+ *
+ * `resumable.ts` deliberately never reconnects a transport — that ownership
+ * is explicitly deferred to this module (see
+ * `docs/decisions/realtime-snapshot-delta-cursor-resume-plan-identity-contract.md`,
+ * "the gate never reconnects a transport itself"). This module closes that
+ * gap by wrapping any raw {@link RealtimeFeatureTransport} (the SSE adapter
+ * in `sse.ts`, the WebSocket adapter in `websocket.ts`, or a custom one) with:
+ *
+ * - the bounded delivery gate from `resumable.ts` (`maxPendingEvents`,
+ *   duplicate/gap detection, cross-scope checkpoint rejection);
+ * - reconnect ownership with exponential-backoff-and-jitter retry, bounded by
+ *   `reconnect.maxAttempts` — exhausting attempts fails closed rather than
+ *   retrying forever;
+ * - a heartbeat/liveness timeout that treats prolonged silence as a
+ *   transport-detected gap;
+ * - resume-vs-resnapshot selection driven entirely by the gate's own
+ *   `phase`: a reconnect resumes from the last accepted checkpoint's cursor
+ *   only while the gate considers it valid, and requests a fresh snapshot
+ *   the moment the gate (or this module, via `requireResnapshot`) decides
+ *   otherwise — REQ-003's "resume only with a valid scoped cursor";
+ * - idempotent disposal that stops timers, the active connection, and the
+ *   delivery gate exactly once, however disposal was triggered
+ *   (caller `close()`, external `AbortSignal`, or an unrecoverable failure);
+ * - redacted telemetry (`onTelemetry`) built on `contract.ts`'s
+ *   `deriveRealtimeContractAuthority` / `redactRealtimeCheckpoint`, so a raw
+ *   cursor, watermark, or delta-token never reaches a log or metrics sink.
+ *
+ * The result still satisfies `RealtimeFeatureTransport`, so it composes with
+ * `createRealtimeFeatureStore` exactly like any other transport.
+ *
+ * @module
+ */
+import type { RealtimeContractAuthority, RedactedRealtimeCheckpointV1 } from "./contract.js";
+import { type RealtimeCheckpointStore, type RealtimeDurableCheckpointV1, type RealtimeResumeContextV1 } from "./resumable.js";
+import type { RealtimeServerSentEventsTransportOptions } from "./sse.js";
+import type { RealtimeFeatureTransport } from "./types.js";
+import type { RealtimeWebSocketTransportOptions } from "./websocket.js";
+export interface RealtimeReconnectPolicy {
+    /** Consecutive reconnect attempts allowed before failing closed. `0` disables reconnect entirely. @default 8 */
+    readonly maxAttempts?: number;
+    /** Delay before the first reconnect attempt. @default 250 */
+    readonly baseDelayMs?: number;
+    /** Upper bound on the exponential backoff delay, before jitter. @default 30000 */
+    readonly maxDelayMs?: number;
+    /** How long a connection must stay live before a subsequent failure resets the attempt counter. @default 15000 */
+    readonly resetAfterMs?: number;
+}
+export interface RealtimeResumableTransportTelemetry {
+    readonly authority: RealtimeContractAuthority;
+    readonly reconnectAttempt: number;
+    readonly acceptedEventCount: number;
+    readonly duplicateEventCount: number;
+    readonly gapCount: number;
+    readonly overflowCount: number;
+    /** Never a raw cursor, watermark, or delta-token value. */
+    readonly checkpoint?: RedactedRealtimeCheckpointV1;
+}
+export interface RealtimeResumableTransportOptions<TFeature = unknown> {
+    readonly context: RealtimeResumeContextV1;
+    readonly checkpointStore?: RealtimeCheckpointStore;
+    /**
+     * Seed resume position for the very first connection, validated the same
+     * way a loaded `checkpointStore` checkpoint is (`evaluateRealtimeCheckpoint`).
+     * This is the only supported way to seed a resume position: `subscribe()`'s
+     * `request.cursor` / `resumeFrom` and similar fields are ignored by this
+     * wrapper so a stale or unscoped caller-supplied position can never bypass
+     * checkpoint compatibility validation.
+     */
+    readonly initialCheckpoint?: RealtimeDurableCheckpointV1;
+    /** Includes the currently applying event. @default 64 */
+    readonly maxPendingEvents?: number;
+    /** Bounded event-id history persisted with each checkpoint. @default 256 */
+    readonly maxRecentEventIds?: number;
+    readonly reconnect?: RealtimeReconnectPolicy;
+    /** No event (including heartbeats) within this window is treated as a transport-detected gap. Disabled when omitted. */
+    readonly heartbeatTimeoutMs?: number;
+    /** Forwarded to {@link deriveRealtimeContractAuthority} for telemetry. */
+    readonly staleAfterMs?: number;
+    readonly onTelemetry?: (telemetry: RealtimeResumableTransportTelemetry) => void;
+    readonly now?: () => number;
+}
+/**
+ * Exponential backoff with jitter in the [0.5x, 1x] band for the given
+ * zero-based reconnect attempt — the same shape as
+ * `core/request-pipeline.ts`'s `resolveRetryDelayMs`, reimplemented locally
+ * so `@honua/sdk-js/realtime` does not pull in the HTTP request pipeline's
+ * error/type graph for one small helper. Exported so the schedule can be
+ * asserted deterministically without driving a fake transport end-to-end.
+ */
+export declare function computeReconnectDelayMs(policy: RealtimeReconnectPolicy | undefined, attempt: number): number;
+/**
+ * Wrap a raw {@link RealtimeFeatureTransport} with bounded, resumable
+ * delivery: the #556 delivery gate, reconnect/backoff, heartbeat timeout,
+ * and redacted telemetry. See the module doc for the full behavior.
+ */
+export declare function createResumableRealtimeTransport<TFeature = unknown>(transport: RealtimeFeatureTransport<TFeature>, options: RealtimeResumableTransportOptions<TFeature>): RealtimeFeatureTransport<TFeature>;
+/**
+ * Convenience factory combining {@link createRealtimeServerSentEventsTransport}
+ * with {@link createResumableRealtimeTransport}.
+ */
+export declare function createResumableServerSentEventsTransport<TFeature = unknown>(sseOptions: RealtimeServerSentEventsTransportOptions<TFeature>, resumableOptions: RealtimeResumableTransportOptions<TFeature>): RealtimeFeatureTransport<TFeature>;
+/**
+ * Convenience factory combining {@link createRealtimeWebSocketTransport}
+ * with {@link createResumableRealtimeTransport}.
+ */
+export declare function createResumableWebSocketTransport<TFeature = unknown>(webSocketOptions: RealtimeWebSocketTransportOptions<TFeature>, resumableOptions: RealtimeResumableTransportOptions<TFeature>): RealtimeFeatureTransport<TFeature>;
+//# sourceMappingURL=resumable-transport.d.ts.map

package/realtime/resumable-transport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resumable-transport.d.ts","sourceRoot":"","sources":["../../../src/realtime/resumable-transport.ts"],"names":[],"mappings":"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"}