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

package/realtime/contract.js

@@ -0,0 +1,154 @@
+/**
+ * Snapshot, delta, cursor, resume, and plan-identity contract surface for
+ * `@honua/sdk-js/realtime` (issue #556).
+ *
+ * The resumable delivery gate in `resumable.ts` already implements the
+ * durable-checkpoint state machine: versioned snapshot/delta/cursor
+ * envelopes, monotonic-sequence ordering and deduplication, delete
+ * tombstones (`reducer.ts`), and mandatory resnapshot on gap, expiry, or
+ * scope change. This module closes the three remaining contract gaps that
+ * keep that machinery a *design* rather than an ad hoc convention:
+ *
+ * 1. **Plan identity** — {@link RealtimeResumeContextV1.queryFingerprint} was
+ *    previously any caller-supplied string. {@link realtimePlanFingerprint}
+ *    and {@link assertRealtimePlanIdentity} bind it to the query planner's
+ *    canonical, credential-free `QueryExecutionPlan.fingerprint` — the same
+ *    content hash `hashQueryPlan`/`persistedPlanSnapshot` establish once,
+ *    with full protocol-compiler re-verification, when a plan is first
+ *    constructed (`explainQuery`) or reloaded (`parseQueryPlan`). That
+ *    fingerprint already folds in `capabilityPolicy` and `fallback`, so
+ *    binding to it also carries policy identity per REQ-003 without a
+ *    second fingerprint field. This module reads the already-trusted field
+ *    rather than importing `hashQueryPlan` itself: plan *integrity* is the
+ *    query planner's trust boundary, established once at construction time,
+ *    and re-deriving it here would pull every protocol compiler
+ *    (DuckDB/gRPC/GeoServices/OGC/OData/WFS — several hundred KB) into the
+ *    `@honua/sdk-js/realtime` bundle for a check that is already done.
+ * 2. **Authority** — {@link deriveRealtimeContractAuthority} projects the
+ *    resumable gate's `phase` into one explicit
+ *    `replaying | live | stale | terminal` state plus an `authoritative`
+ *    flag, so consumers stop inferring trust from reason codes.
+ * 3. **Deterministic, redacted serialization** — {@link serializeRealtimeCheckpoint}
+ *    and {@link redactRealtimeCheckpoint} give a canonical (sorted-key) JSON
+ *    form for durable storage and a form safe for logs/telemetry that never
+ *    carries a raw cursor, watermark, or delta-token value.
+ *
+ * @module
+ */
+import { canonicalStringify, sha256, toJsonValue } from "../query-planner/canonical.js";
+import { HonuaRealtimeResumeError, } from "./resumable.js";
+/**
+ * Canonical plan-identity fingerprint for
+ * {@link RealtimeResumeContextV1.queryFingerprint}: the accepted plan's own
+ * trusted `fingerprint` field (`hashQueryPlan(plan) === plan.fingerprint`
+ * for every plan produced by `explainQuery`/`parseQueryPlan`). Named and
+ * exported so call sites bind resume identity to the plan by construction
+ * instead of by convention, without importing the query planner's
+ * protocol-compiler graph into `@honua/sdk-js/realtime`. Only
+ * `QueryExecutionPlan["fingerprint"]` is type-imported; nothing from
+ * `query-planner/planner.js` is bundled here.
+ */
+export function realtimePlanFingerprint(plan) {
+    return plan.fingerprint;
+}
+/**
+ * Assert that a resume context's `queryFingerprint` matches the accepted
+ * plan's fingerprint. Throws a `"query-changed"`
+ * {@link HonuaRealtimeResumeError} — the same taxonomy
+ * {@link evaluateRealtimeCheckpoint} uses for a checkpoint whose bound query
+ * identity no longer matches — when they diverge, so a subscription can
+ * never resume against a plan other than the one it was accepted for. This
+ * checks identity, not plan authenticity: trust that `plan.fingerprint`
+ * matches the plan's actual content is established once, by the query
+ * planner, when the plan is constructed or parsed.
+ */
+export function assertRealtimePlanIdentity(context, plan) {
+    const expected = realtimePlanFingerprint(plan);
+    if (context.queryFingerprint !== expected) {
+        throw new HonuaRealtimeResumeError("query-changed", `Realtime resume context queryFingerprint does not match the accepted plan fingerprint (expected "${expected}", received "${context.queryFingerprint}").`);
+    }
+}
+/**
+ * Derive one explicit {@link RealtimeContractAuthority} from a resumable
+ * gate's state. Pure and side-effect free: call it after every
+ * `enqueue`/`requireResnapshot`/`close` transition to render connection
+ * chrome without re-deriving trust from `phase`/`reason` combinations.
+ */
+export function deriveRealtimeContractAuthority(resumable, options = {}) {
+    const ageMs = checkpointAgeMs(resumable.checkpoint, options.now);
+    switch (resumable.phase) {
+        case "awaiting-snapshot":
+        case "resuming":
+        case "resnapshot-required":
+            return freeze({ state: "replaying", authoritative: false, ...(ageMs !== undefined ? { ageMs } : {}) });
+        case "error":
+        case "closed":
+            return freeze({
+                state: "terminal",
+                authoritative: resumable.checkpoint !== undefined,
+                ...(ageMs !== undefined ? { ageMs } : {}),
+            });
+        case "live": {
+            const stale = ageMs !== undefined &&
+                typeof options.staleAfterMs === "number" &&
+                Number.isFinite(options.staleAfterMs) &&
+                ageMs > options.staleAfterMs;
+            return freeze({
+                state: stale ? "stale" : "live",
+                authoritative: true,
+                ...(ageMs !== undefined ? { ageMs } : {}),
+            });
+        }
+    }
+}
+function checkpointAgeMs(checkpoint, now) {
+    if (!checkpoint || typeof now !== "number" || !Number.isFinite(now))
+        return undefined;
+    const savedAt = Date.parse(checkpoint.savedAt);
+    if (!Number.isFinite(savedAt))
+        return undefined;
+    return Math.max(0, now - savedAt);
+}
+export function redactRealtimeCheckpoint(checkpoint) {
+    return freeze({
+        kind: checkpoint.kind,
+        version: checkpoint.version,
+        context: checkpoint.context,
+        resume: freeze({
+            sequence: checkpoint.resume.sequence,
+            ...(checkpoint.resume.cursor !== undefined ? { cursor: redactPosition("cursor", checkpoint.resume.cursor) } : {}),
+            ...(checkpoint.resume.watermark !== undefined
+                ? { watermark: redactPosition("watermark", checkpoint.resume.watermark) }
+                : {}),
+            ...(checkpoint.resume.timestamp !== undefined ? { timestamp: checkpoint.resume.timestamp } : {}),
+            ...(checkpoint.resume.deltaToken !== undefined
+                ? { deltaToken: redactPosition("deltaToken", checkpoint.resume.deltaToken) }
+                : {}),
+        }),
+        recentEventIdCount: checkpoint.recentEventIds.length,
+        savedAt: checkpoint.savedAt,
+    });
+}
+function redactPosition(field, value) {
+    return sha256(`honua-realtime-checkpoint-redaction:v1:${field}:${value}`);
+}
+/**
+ * Canonical (sorted-key) JSON serialization of the full durable checkpoint,
+ * for persistence where the caller owns access control. Two checkpoints
+ * with the same accepted content always serialize identically, regardless
+ * of property insertion order — required for content-addressed storage and
+ * for stable diffing across processes.
+ */
+export function serializeRealtimeCheckpoint(checkpoint) {
+    return canonicalStringify(toJsonValue(checkpoint));
+}
+/**
+ * Canonical, redacted JSON serialization safe for logs and telemetry
+ * sinks — never a raw cursor, watermark, or delta-token value.
+ */
+export function serializeRedactedRealtimeCheckpoint(checkpoint) {
+    return canonicalStringify(toJsonValue(redactRealtimeCheckpoint(checkpoint)));
+}
+function freeze(value) {
+    return Object.freeze(value);
+}

package/realtime/exploration.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Realtime helpers for linked exploration views.
+ *
+ * @module
+ */
+import type { SourceId } from "../contract/types.js";
+import type { ExplorationViewController, FeatureSelectionTarget } from "../exploration/types.js";
+import type { RealtimeFeatureState } from "./types.js";
+export interface ReconcileRealtimeSelectionOptions {
+    readonly sourceId?: SourceId;
+    /** Remove selections when the record is absent from live state. @default true */
+    readonly requireLiveRecord?: boolean;
+}
+export declare function filterRealtimeSelection<TFeature>(selection: ReadonlyArray<FeatureSelectionTarget>, state: RealtimeFeatureState<TFeature>, options?: ReconcileRealtimeSelectionOptions): ReadonlyArray<FeatureSelectionTarget>;
+export declare function reconcileRealtimeSelection<TFeature>(view: ExplorationViewController, state: RealtimeFeatureState<TFeature>, options?: ReconcileRealtimeSelectionOptions): void;
+//# sourceMappingURL=exploration.d.ts.map

package/realtime/exploration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"exploration.d.ts","sourceRoot":"","sources":["../../../src/realtime/exploration.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAErD,OAAO,KAAK,EAAE,yBAAyB,EAAE,sBAAsB,EAAE,MAAM,yBAAyB,CAAC;AAEjG,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAEvD,MAAM,WAAW,iCAAiC;IAChD,QAAQ,CAAC,QAAQ,CAAC,EAAE,QAAQ,CAAC;IAC7B,iFAAiF;IACjF,QAAQ,CAAC,iBAAiB,CAAC,EAAE,OAAO,CAAC;CACtC;AAED,wBAAgB,uBAAuB,CAAC,QAAQ,EAC9C,SAAS,EAAE,aAAa,CAAC,sBAAsB,CAAC,EAChD,KAAK,EAAE,oBAAoB,CAAC,QAAQ,CAAC,EACrC,OAAO,GAAE,iCAAsC,GAC9C,aAAa,CAAC,sBAAsB,CAAC,CAQvC;AAED,wBAAgB,0BAA0B,CAAC,QAAQ,EACjD,IAAI,EAAE,yBAAyB,EAC/B,KAAK,EAAE,oBAAoB,CAAC,QAAQ,CAAC,EACrC,OAAO,GAAE,iCAAsC,GAC9C,IAAI,CAIN"}

package/realtime/exploration.js

@@ -0,0 +1,32 @@
+/**
+ * Realtime helpers for linked exploration views.
+ *
+ * @module
+ */
+import { isSourceQualifiedSelectionTarget } from "../exploration/selection.js";
+import { realtimeFeatureKey } from "./reducer.js";
+export function filterRealtimeSelection(selection, state, options = {}) {
+    const { sourceId, requireLiveRecord = true } = options;
+    return selection.filter((target) => {
+        const key = selectionKey(target, sourceId);
+        if (!key)
+            return true;
+        if (state.tombstones[key])
+            return false;
+        return requireLiveRecord ? Boolean(state.records[key]) : true;
+    });
+}
+export function reconcileRealtimeSelection(view, state, options = {}) {
+    const next = filterRealtimeSelection(view.state.selection, state, options);
+    if (next.length === view.state.selection.length)
+        return;
+    view.select(next, { replace: true });
+}
+function selectionKey(target, sourceId) {
+    if (isSourceQualifiedSelectionTarget(target)) {
+        return realtimeFeatureKey(target.sourceId, target.id);
+    }
+    if (!sourceId)
+        return undefined;
+    return realtimeFeatureKey(sourceId, target);
+}

package/realtime/honua-server.d.ts

@@ -0,0 +1,131 @@
+/**
+ * First-party realtime preset for honua-server's
+ * `/api/v1/streaming/features` Server-Sent Events endpoint.
+ *
+ * The default SSE transport encoder emits `sourceId=` / `layerId=` query
+ * params and assumes events already use the SDK's `RealtimeFeatureEvent`
+ * vocabulary. honua-server instead expects `serviceId=` / `layers=` query
+ * params and emits its own feature-change envelopes. This module packages the
+ * two hooks (`encodeRequest` + `decodeEvent`) the transport already exposes so
+ * consumers do not have to re-implement the same adapter for every app.
+ *
+ * @example Use the preset options with the SSE transport.
+ * ```ts
+ * import {
+ *   createRealtimeServerSentEventsTransport,
+ *   honuaServerRealtimePreset,
+ * } from "@honua/sdk-js/realtime";
+ *
+ * const transport = createRealtimeServerSentEventsTransport({
+ *   url: "https://honua.example/api/v1/streaming/features",
+ *   ...honuaServerRealtimePreset(),
+ * });
+ * ```
+ *
+ * @example Or use the convenience factory.
+ * ```ts
+ * import { createHonuaServerRealtimeSubscription } from "@honua/sdk-js/realtime";
+ *
+ * const transport = createHonuaServerRealtimeSubscription({
+ *   baseUrl: "https://honua.example",
+ * });
+ * ```
+ *
+ * @module
+ */
+import type { FeatureId } from "../contract/types.js";
+import type { RealtimeServerSentEventsTransportOptions } from "./sse.js";
+import type { RealtimeFeatureEvent, RealtimeFeatureTransport, RealtimeSubscriptionRequest } from "./types.js";
+/** Default streaming-features path served by honua-server. */
+export declare const HONUA_SERVER_STREAMING_FEATURES_PATH = "/api/v1/streaming/features";
+/**
+ * Encode a `RealtimeSubscriptionRequest` into honua-server's
+ * `/api/v1/streaming/features` query contract: `serviceId=` (not `sourceId=`)
+ * and `layers=` (not `layerId=`). The remaining filter/resume params match the
+ * default encoder so cursors, watermarks, and where-clauses keep working.
+ */
+export declare function encodeHonuaServerRealtimeRequest(url: URL, request: RealtimeSubscriptionRequest): URL;
+/**
+ * Shape of a single change carried by a honua-server feature-change envelope.
+ * honua-server reports the change kind via `op` (`insert` / `update` / `delete`)
+ * alongside the affected feature or feature id.
+ */
+export interface HonuaServerFeatureChange<TFeature = unknown> {
+    readonly op: "insert" | "update" | "delete" | "snapshot";
+    readonly featureId?: FeatureId;
+    readonly feature?: TFeature;
+    readonly version?: number;
+    readonly updatedAt?: string;
+}
+/**
+ * Shape of the envelope honua-server writes to the
+ * `/api/v1/streaming/features` SSE stream. Each envelope carries the service /
+ * layer scope, ordering metadata, and one or more feature changes.
+ */
+export interface HonuaServerFeatureChangeEnvelope<TFeature = unknown> {
+    readonly serviceId?: string;
+    readonly sourceId?: string;
+    readonly layerId?: string | number;
+    readonly eventId?: string;
+    readonly sequence?: number;
+    readonly cursor?: string;
+    readonly watermark?: string;
+    readonly timestamp?: string;
+    readonly deltaToken?: string;
+    /** `change` (or `feature-change`) is the default envelope kind. */
+    readonly kind?: string;
+    readonly changes?: ReadonlyArray<HonuaServerFeatureChange<TFeature>>;
+    /** Single-change envelopes inline the change instead of a `changes` array. */
+    readonly op?: HonuaServerFeatureChange<TFeature>["op"];
+    readonly featureId?: FeatureId;
+    readonly objectId?: FeatureId;
+    readonly feature?: TFeature;
+    /** Current honua-server wire field; normalized to {@link HonuaServerFeatureChange.op}. */
+    readonly operation?: Exclude<HonuaServerFeatureChange<TFeature>["op"], "snapshot">;
+    /** Current honua-server GeoJSON geometry field. */
+    readonly geometry?: unknown;
+    /** Current honua-server full attribute snapshot for insert/update events. */
+    readonly attributes?: Readonly<Record<string, unknown>>;
+    readonly version?: number;
+    readonly updatedAt?: string;
+    /** Pass-through status / heartbeat / error envelopes. */
+    readonly type?: string;
+}
+/**
+ * Decode a honua-server `/api/v1/streaming/features` envelope into the SDK's
+ * `RealtimeFeatureEvent`. Feature-change envelopes become `delta` events
+ * (batching upserts and deletes); status, heartbeat, and error envelopes that
+ * already speak the SDK vocabulary pass through unchanged.
+ */
+export declare function decodeHonuaServerRealtimeEvent<TFeature = unknown>(payload: unknown): RealtimeFeatureEvent<TFeature>;
+/**
+ * Reusable hook bundle for honua-server's streaming-features endpoint. Spread
+ * this into {@link createRealtimeServerSentEventsTransport} options to opt into
+ * honua-server's query-param contract and feature-change decoding.
+ */
+export declare function honuaServerRealtimePreset<TFeature = unknown>(): Pick<RealtimeServerSentEventsTransportOptions<TFeature>, "encodeRequest" | "decodeEvent">;
+export interface CreateHonuaServerRealtimeSubscriptionOptions<TFeature = unknown> extends Omit<RealtimeServerSentEventsTransportOptions<TFeature>, "url" | "encodeRequest" | "decodeEvent"> {
+    /**
+     * honua-server origin, e.g. `https://honua.example`. The
+     * `/api/v1/streaming/features` path is appended automatically. Mutually
+     * exclusive with {@link CreateHonuaServerRealtimeSubscriptionOptions.url}.
+     */
+    readonly baseUrl?: string;
+    /**
+     * Full streaming-features URL. Use this when the endpoint lives at a
+     * non-default path. Overrides {@link CreateHonuaServerRealtimeSubscriptionOptions.baseUrl}.
+     */
+    readonly url?: string;
+    /**
+     * Override the honua-server feature-change decoder while keeping the
+     * `serviceId=` / `layers=` query encoding.
+     */
+    readonly decodeEvent?: RealtimeServerSentEventsTransportOptions<TFeature>["decodeEvent"];
+}
+/**
+ * Convenience factory that builds a {@link RealtimeFeatureTransport} wired to
+ * honua-server's `/api/v1/streaming/features` endpoint with the
+ * {@link honuaServerRealtimePreset} hooks applied.
+ */
+export declare function createHonuaServerRealtimeSubscription<TFeature = unknown>(options: CreateHonuaServerRealtimeSubscriptionOptions<TFeature>): RealtimeFeatureTransport<TFeature>;
+//# sourceMappingURL=honua-server.d.ts.map

package/realtime/honua-server.d.ts.map

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

package/realtime/honua-server.js

@@ -0,0 +1,302 @@
+/**
+ * First-party realtime preset for honua-server's
+ * `/api/v1/streaming/features` Server-Sent Events endpoint.
+ *
+ * The default SSE transport encoder emits `sourceId=` / `layerId=` query
+ * params and assumes events already use the SDK's `RealtimeFeatureEvent`
+ * vocabulary. honua-server instead expects `serviceId=` / `layers=` query
+ * params and emits its own feature-change envelopes. This module packages the
+ * two hooks (`encodeRequest` + `decodeEvent`) the transport already exposes so
+ * consumers do not have to re-implement the same adapter for every app.
+ *
+ * @example Use the preset options with the SSE transport.
+ * ```ts
+ * import {
+ *   createRealtimeServerSentEventsTransport,
+ *   honuaServerRealtimePreset,
+ * } from "@honua/sdk-js/realtime";
+ *
+ * const transport = createRealtimeServerSentEventsTransport({
+ *   url: "https://honua.example/api/v1/streaming/features",
+ *   ...honuaServerRealtimePreset(),
+ * });
+ * ```
+ *
+ * @example Or use the convenience factory.
+ * ```ts
+ * import { createHonuaServerRealtimeSubscription } from "@honua/sdk-js/realtime";
+ *
+ * const transport = createHonuaServerRealtimeSubscription({
+ *   baseUrl: "https://honua.example",
+ * });
+ * ```
+ *
+ * @module
+ */
+import { trimTrailingSlashes } from "../core/path-utils.js";
+import { HonuaRealtimeResumeError } from "./resumable.js";
+import { createRealtimeServerSentEventsTransport, decodeRealtimeServerSentEvent } from "./sse.js";
+/** Default streaming-features path served by honua-server. */
+export const HONUA_SERVER_STREAMING_FEATURES_PATH = "/api/v1/streaming/features";
+/**
+ * Encode a `RealtimeSubscriptionRequest` into honua-server's
+ * `/api/v1/streaming/features` query contract: `serviceId=` (not `sourceId=`)
+ * and `layers=` (not `layerId=`). The remaining filter/resume params match the
+ * default encoder so cursors, watermarks, and where-clauses keep working.
+ */
+export function encodeHonuaServerRealtimeRequest(url, request) {
+    url.searchParams.set("serviceId", String(request.sourceId));
+    if (request.layerId !== undefined)
+        url.searchParams.set("layers", String(request.layerId));
+    if (request.requestId)
+        url.searchParams.set("requestId", request.requestId);
+    if (request.mode)
+        url.searchParams.set("mode", request.mode);
+    if (request.where)
+        url.searchParams.set("where", request.where);
+    if (request.fields?.length)
+        url.searchParams.set("fields", request.fields.join(","));
+    if (request.cursor ?? request.resumeFrom?.cursor) {
+        url.searchParams.set("cursor", request.cursor ?? request.resumeFrom?.cursor ?? "");
+    }
+    if (request.watermark ?? request.resumeFrom?.watermark) {
+        url.searchParams.set("watermark", request.watermark ?? request.resumeFrom?.watermark ?? "");
+    }
+    if (request.timestamp ?? request.resumeFrom?.timestamp) {
+        url.searchParams.set("timestamp", request.timestamp ?? request.resumeFrom?.timestamp ?? "");
+    }
+    if (request.deltaToken ?? request.resumeFrom?.deltaToken) {
+        url.searchParams.set("deltaToken", request.deltaToken ?? request.resumeFrom?.deltaToken ?? "");
+    }
+    if (request.resumeFrom?.sequence !== undefined) {
+        url.searchParams.set("sequence", String(request.resumeFrom.sequence));
+    }
+    if (request.spatialFilter !== undefined)
+        url.searchParams.set("spatialFilter", JSON.stringify(request.spatialFilter));
+    if (request.metadata !== undefined)
+        url.searchParams.set("metadata", JSON.stringify(request.metadata));
+    return url;
+}
+/**
+ * Decode a honua-server `/api/v1/streaming/features` envelope into the SDK's
+ * `RealtimeFeatureEvent`. Feature-change envelopes become `delta` events
+ * (batching upserts and deletes); status, heartbeat, and error envelopes that
+ * already speak the SDK vocabulary pass through unchanged.
+ */
+export function decodeHonuaServerRealtimeEvent(payload) {
+    if (!isRecord(payload)) {
+        throw new HonuaRealtimeResumeError("invalid-event", "honua-server streaming payload must be a JSON object.");
+    }
+    const envelope = payload;
+    // A current-server change discriminator always wins over generic `type`.
+    // Otherwise a malformed/colliding payload could masquerade as status or
+    // error and bypass the stricter operation/after-image validation below.
+    const currentServerChange = envelope.operation !== undefined;
+    // Snapshot / status / heartbeat / error envelopes already use the SDK
+    // vocabulary. Their `cursor`, however, is honua-server's global event-store
+    // position: a JSON number on the batched `snapshot` baseline frame, where the
+    // SDK's resume gate requires the string form it checkpoints. Normalizing it
+    // here — the one place that already owns honua-server's wire dialect — keeps
+    // a batched baseline from failing closed as a checkpoint conflict.
+    if (!currentServerChange &&
+        typeof envelope.type === "string" &&
+        envelope.type !== "change" &&
+        envelope.type !== "feature-change") {
+        const framed = withNormalizedNumericCursor(payload);
+        if (envelope.type === "status" && (payload.status === "connected" || payload.status === "subscribed")) {
+            return decodeRealtimeServerSentEvent({ ...framed, status: "live" });
+        }
+        return decodeRealtimeServerSentEvent(framed);
+    }
+    const serviceId = optionalNonEmptyText(envelope.serviceId, "serviceId");
+    optionalNonEmptyText(envelope.sourceId, "sourceId");
+    const cursor = normalizeCursor(envelope.cursor);
+    const sequence = optionalSequence(envelope.sequence);
+    if (currentServerChange && serviceId === undefined) {
+        throw new HonuaRealtimeResumeError("invalid-event", "honua-server current feature-change envelope is missing serviceId.");
+    }
+    const changes = collectChanges(envelope);
+    if (changes.length === 0) {
+        throw new HonuaRealtimeResumeError("invalid-event", "honua-server feature-change envelope is missing changes.");
+    }
+    const base = {
+        eventId: envelope.eventId,
+        sequence,
+        cursor,
+        watermark: envelope.watermark,
+        timestamp: envelope.timestamp,
+        deltaToken: envelope.deltaToken,
+    };
+    const upserts = [];
+    const deletes = [];
+    for (const change of changes) {
+        if (!isRecord(change)) {
+            throw new HonuaRealtimeResumeError("invalid-event", "honua-server feature change must be an object.");
+        }
+        const operation = featureChangeOperation(change.op);
+        const featureId = featureIdValue(change.featureId);
+        if (operation === "delete") {
+            deletes.push({ id: featureId, version: change.version, updatedAt: change.updatedAt });
+            continue;
+        }
+        if (change.feature === undefined) {
+            throw new HonuaRealtimeResumeError("invalid-event", `honua-server ${operation} change is missing feature payload.`);
+        }
+        upserts.push({
+            id: featureId,
+            sourceId: serviceId,
+            feature: change.feature,
+            version: change.version,
+            updatedAt: change.updatedAt,
+        });
+    }
+    return {
+        type: "delta",
+        ...base,
+        ...(upserts.length ? { upserts } : {}),
+        ...(deletes.length ? { deletes: deletes.map((entry) => ({ ...entry, sourceId: serviceId })) } : {}),
+    };
+}
+/**
+ * Reusable hook bundle for honua-server's streaming-features endpoint. Spread
+ * this into {@link createRealtimeServerSentEventsTransport} options to opt into
+ * honua-server's query-param contract and feature-change decoding.
+ */
+export function honuaServerRealtimePreset() {
+    return {
+        encodeRequest: (url, request) => {
+            encodeHonuaServerRealtimeRequest(url, request);
+        },
+        decodeEvent: (decodeHonuaServerRealtimeEvent),
+    };
+}
+/**
+ * Convenience factory that builds a {@link RealtimeFeatureTransport} wired to
+ * honua-server's `/api/v1/streaming/features` endpoint with the
+ * {@link honuaServerRealtimePreset} hooks applied.
+ */
+export function createHonuaServerRealtimeSubscription(options) {
+    const { baseUrl, url, decodeEvent, ...rest } = options;
+    const resolvedUrl = url ?? resolveStreamingUrl(baseUrl);
+    const preset = honuaServerRealtimePreset();
+    return createRealtimeServerSentEventsTransport({
+        ...rest,
+        url: resolvedUrl,
+        encodeRequest: preset.encodeRequest,
+        decodeEvent: decodeEvent ?? preset.decodeEvent,
+    });
+}
+function resolveStreamingUrl(baseUrl) {
+    if (!baseUrl) {
+        throw new HonuaRealtimeResumeError("invalid-event", "createHonuaServerRealtimeSubscription requires either `url` or `baseUrl`.");
+    }
+    // Linear trim (no anchored `\/+$` regex) to avoid polynomial backtracking on
+    // adversarial input — mirrors the rest of the SDK's path handling.
+    return `${trimTrailingSlashes(baseUrl)}${HONUA_SERVER_STREAMING_FEATURES_PATH}`;
+}
+function collectChanges(envelope) {
+    if (envelope.operation !== undefined) {
+        const operation = currentServerOperation(envelope.operation);
+        const featureId = envelope.featureId === "" || envelope.featureId === undefined ? envelope.objectId : envelope.featureId;
+        return [
+            {
+                op: operation,
+                featureId,
+                feature: operation === "delete" ? undefined : projectCurrentServerFeature(envelope, featureId),
+                version: envelope.version,
+                updatedAt: envelope.updatedAt ?? envelope.timestamp,
+            },
+        ];
+    }
+    if (Array.isArray(envelope.changes))
+        return envelope.changes;
+    if (envelope.op !== undefined) {
+        return [
+            {
+                op: envelope.op,
+                featureId: envelope.featureId,
+                feature: envelope.feature,
+                version: envelope.version,
+                updatedAt: envelope.updatedAt,
+            },
+        ];
+    }
+    return [];
+}
+function projectCurrentServerFeature(envelope, featureId) {
+    if (!Object.hasOwn(envelope, "geometry") || envelope.geometry === undefined) {
+        throw new HonuaRealtimeResumeError("invalid-event", "honua-server insert/update change is missing a complete geometry after-image.");
+    }
+    if (!isAttributeRecord(envelope.attributes)) {
+        throw new HonuaRealtimeResumeError("invalid-event", "honua-server insert/update change is missing a complete attributes after-image.");
+    }
+    return {
+        type: "Feature",
+        ...(featureId === undefined ? {} : { id: featureId }),
+        geometry: envelope.geometry,
+        properties: envelope.attributes,
+    };
+}
+/**
+ * Render a numeric `cursor` in its string form, leaving every other payload
+ * untouched. A malformed numeric cursor is deliberately left as-is so the
+ * resume gate still reports it, rather than being converted into a decode
+ * failure that would hide which contract was actually violated.
+ */
+function withNormalizedNumericCursor(payload) {
+    const cursor = payload.cursor;
+    if (typeof cursor !== "number")
+        return payload;
+    if (!Number.isSafeInteger(cursor) || cursor < 0)
+        return payload;
+    return { ...payload, cursor: String(cursor) };
+}
+function normalizeCursor(cursor) {
+    if (cursor === undefined)
+        return undefined;
+    if (typeof cursor === "number") {
+        if (Number.isSafeInteger(cursor) && cursor >= 0)
+            return String(cursor);
+    }
+    else if (typeof cursor === "string" && cursor.length > 0) {
+        return cursor;
+    }
+    throw new HonuaRealtimeResumeError("invalid-event", "honua-server feature-change cursor must be a non-empty string or non-negative safe integer.");
+}
+function optionalSequence(sequence) {
+    if (sequence === undefined)
+        return undefined;
+    if (typeof sequence === "number" && Number.isSafeInteger(sequence) && sequence >= 0)
+        return sequence;
+    throw new HonuaRealtimeResumeError("invalid-event", "honua-server feature-change sequence must be a non-negative safe integer.");
+}
+function optionalNonEmptyText(value, field) {
+    if (value === undefined || value === null)
+        return undefined;
+    if (typeof value === "string" && value.length > 0)
+        return value;
+    throw new HonuaRealtimeResumeError("invalid-event", `honua-server feature-change ${field} must be a non-empty string.`);
+}
+function featureIdValue(value) {
+    if (typeof value === "string" && value.length > 0)
+        return value;
+    if (typeof value === "number" && Number.isSafeInteger(value))
+        return value;
+    throw new HonuaRealtimeResumeError("invalid-event", "honua-server feature change featureId must be a non-empty string or safe integer.");
+}
+function featureChangeOperation(value) {
+    if (value === "insert" || value === "update" || value === "delete" || value === "snapshot")
+        return value;
+    throw new HonuaRealtimeResumeError("invalid-event", "honua-server feature change operation must be insert, update, delete, or snapshot.");
+}
+function currentServerOperation(value) {
+    if (value === "insert" || value === "update" || value === "delete")
+        return value;
+    throw new HonuaRealtimeResumeError("invalid-event", "honua-server current feature-change operation must be insert, update, or delete.");
+}
+function isAttributeRecord(value) {
+    return isRecord(value) && !Array.isArray(value);
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null;
+}