@honua/app-platform 0.0.20-alpha.0 → 0.1.1-beta.0

package/query-planner/wfs.js

@@ -0,0 +1,71 @@
+import { UNSUPPORTED_FES, compileSpatialFilter, compileWhere, serializeFes } from "../core/wfs-filter.js";
+import { HonuaQueryPlanningError } from "./types.js";
+export { compileSemanticWfsQuery } from "./wfs-semantic.js";
+/** Compile canonical query IR to a deterministic WFS 2.0 GetFeature request. */
+export function compileWfsQuery(source, query) {
+    if (source.protocol !== "wfs") {
+        throw new HonuaQueryPlanningError("unsupported-compiler", `wfs-2.0-get-feature-v1 does not compile protocol "${source.protocol}"`);
+    }
+    if (!source.typeName) {
+        throw new HonuaQueryPlanningError("invalid-query", `Source "${source.id}" requires locator.typeName for WFS planning`);
+    }
+    if (query.aggregation) {
+        throw new HonuaQueryPlanningError("unsupported-query", "WFS 2.0 has no portable remote aggregation; use degraded policy with an explicit bounded-local fallback");
+    }
+    if (query.spatialFilter && query.outSr !== undefined) {
+        throw new HonuaQueryPlanningError("unsupported-query", "WFS planning cannot use outSr to label input filter coordinates; stamp the input geometry through the typed WFS escape hatch");
+    }
+    // Keep this aligned with the current WFS adapter's reviewed default. A
+    // vendor-specific geometry property requires the typed WFS escape hatch
+    // until discovery carries that binding into both planner and executor.
+    const geometryProperty = "the_geom";
+    const filters = [];
+    if (query.where) {
+        const where = compileWhere(query.where.expression);
+        if (where === UNSUPPORTED_FES) {
+            throw new HonuaQueryPlanningError("unsupported-query", "The where clause is not expressible as FES 2.0");
+        }
+        if (where.kind !== "and" || where.operands.length > 0)
+            filters.push(where);
+    }
+    if (query.spatialFilter) {
+        const spatial = compileSpatialFilter({
+            geometry: query.spatialFilter.geometry,
+            geometryType: query.spatialFilter.geometryType,
+            ...(query.spatialFilter.spatialRel ? { spatialRel: query.spatialFilter.spatialRel } : {}),
+        }, {
+            geometryProperty,
+        });
+        if (spatial === UNSUPPORTED_FES) {
+            throw new HonuaQueryPlanningError("unsupported-query", "The spatial predicate is not expressible as FES 2.0");
+        }
+        filters.push(spatial);
+    }
+    let propertyName;
+    if (query.outFields && query.outFields.length > 0) {
+        const fields = [...query.outFields];
+        if (query.returnGeometry === false && fields.includes(geometryProperty)) {
+            throw new HonuaQueryPlanningError("unsupported-query", `WFS returnGeometry=false conflicts with outFields containing the geometry property "${geometryProperty}"`);
+        }
+        if (query.returnGeometry !== false && !fields.includes(geometryProperty))
+            fields.push(geometryProperty);
+        propertyName = fields;
+    }
+    else if (query.returnGeometry === false) {
+        throw new HonuaQueryPlanningError("unsupported-query", "WFS returnGeometry=false requires explicit outFields because propertyName cannot otherwise suppress geometry exactly");
+    }
+    return {
+        compiler: "wfs-2.0-get-feature-v1",
+        typeName: source.typeName,
+        ...(filters.length > 0 ? { filter: serializeFes(filters, { typeName: source.typeName }) } : {}),
+        ...(propertyName ? { propertyName } : {}),
+        ...(query.orderBy && query.orderBy.length > 0
+            ? {
+                sortBy: query.orderBy.map((sort) => `${sort.field} ${sort.direction === "desc" ? "DESC" : "ASC"}`).join(","),
+            }
+            : {}),
+        ...(query.pagination?.offset !== undefined ? { startIndex: query.pagination.offset } : {}),
+        ...(query.pagination?.limit !== undefined ? { count: query.pagination.limit } : {}),
+        ...(query.outSr !== undefined ? { srsName: String(query.outSr) } : {}),
+    };
+}

package/realtime/contract.d.ts

@@ -0,0 +1,142 @@
+/**
+ * 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 type { QueryExecutionPlan } from "../query-planner/types.js";
+import { type RealtimeDurableCheckpointV1, type RealtimeResumeContextV1, type ResumableRealtimeState } 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 declare function realtimePlanFingerprint(plan: Pick<QueryExecutionPlan, "fingerprint">): `sha256:${string}`;
+/**
+ * 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 declare function assertRealtimePlanIdentity(context: RealtimeResumeContextV1, plan: Pick<QueryExecutionPlan, "fingerprint">): void;
+/**
+ * Explicit realtime contract authority states.
+ *
+ * - `replaying`: no confirmed authoritative baseline yet — awaiting an
+ *   initial or replacement snapshot, or resuming from a durable checkpoint
+ *   whose continuity has not been reconfirmed by a live event.
+ * - `live`: an accepted snapshot establishes ground truth and the most
+ *   recent contiguous event arrived within the caller's staleness window
+ *   (or no window was supplied).
+ * - `stale`: the baseline is still authoritative but no event has arrived
+ *   within `staleAfterMs`; render the last known state but surface
+ *   liveness doubt.
+ * - `terminal`: delivery stopped on an unrecoverable error or an explicit
+ *   close. The last accepted checkpoint, if any, remains available for
+ *   read-only rendering but will never advance.
+ */
+export type RealtimeContractAuthorityState = "replaying" | "live" | "stale" | "terminal";
+export interface RealtimeContractAuthority {
+    readonly state: RealtimeContractAuthorityState;
+    /** True once an accepted snapshot has established ground truth for the current checkpoint identity. */
+    readonly authoritative: boolean;
+    /** Milliseconds since the checkpoint was accepted, when a checkpoint exists and `now` was supplied. */
+    readonly ageMs?: number;
+}
+export interface DeriveRealtimeContractAuthorityOptions {
+    /** No event within this window while `phase === "live"` demotes authority to `"stale"`. */
+    readonly staleAfterMs?: number;
+    readonly now?: number;
+}
+/**
+ * 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 declare function deriveRealtimeContractAuthority(resumable: Pick<ResumableRealtimeState, "phase" | "checkpoint">, options?: DeriveRealtimeContractAuthorityOptions): RealtimeContractAuthority;
+/** Opaque, deterministic digest of a raw resume-position value; never the raw value itself. */
+export type RedactedResumePosition = `sha256:${string}`;
+export interface RedactedRealtimeResumePosition {
+    readonly sequence: number;
+    readonly cursor?: RedactedResumePosition;
+    readonly watermark?: RedactedResumePosition;
+    readonly timestamp?: string;
+    readonly deltaToken?: RedactedResumePosition;
+}
+/**
+ * Log/telemetry-safe projection of a durable checkpoint. `context` is kept
+ * as-is because every one of its fields is already an opaque identity or
+ * fingerprint (never a credential). `resume.cursor`, `resume.watermark`, and
+ * `resume.deltaToken` are replaced with a deterministic SHA-256 digest so
+ * repeated observations of the same position stay correlatable without
+ * exposing the raw, potentially sensitive token. `timestamp` is kept in the
+ * clear because it is not an opaque credential. `recentEventIds` is
+ * collapsed to a count: individual event ids are dedup identity, not
+ * something a log line needs verbatim.
+ */
+export interface RedactedRealtimeCheckpointV1 {
+    readonly kind: "honua.realtime-checkpoint";
+    readonly version: RealtimeDurableCheckpointV1["version"];
+    readonly context: RealtimeResumeContextV1;
+    readonly resume: RedactedRealtimeResumePosition;
+    readonly recentEventIdCount: number;
+    readonly savedAt: string;
+}
+export declare function redactRealtimeCheckpoint(checkpoint: RealtimeDurableCheckpointV1): RedactedRealtimeCheckpointV1;
+/**
+ * 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 declare function serializeRealtimeCheckpoint(checkpoint: RealtimeDurableCheckpointV1): string;
+/**
+ * Canonical, redacted JSON serialization safe for logs and telemetry
+ * sinks — never a raw cursor, watermark, or delta-token value.
+ */
+export declare function serializeRedactedRealtimeCheckpoint(checkpoint: RealtimeDurableCheckpointV1): string;
+//# sourceMappingURL=contract.d.ts.map

package/realtime/contract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract.d.ts","sourceRoot":"","sources":["../../../src/realtime/contract.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAGH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AACpE,OAAO,EAEL,KAAK,2BAA2B,EAChC,KAAK,uBAAuB,EAC5B,KAAK,sBAAsB,EAC5B,MAAM,gBAAgB,CAAC;AAExB;;;;;;;;;;GAUG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,IAAI,CAAC,kBAAkB,EAAE,aAAa,CAAC,GAAG,UAAU,MAAM,EAAE,CAEzG;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,0BAA0B,CACxC,OAAO,EAAE,uBAAuB,EAChC,IAAI,EAAE,IAAI,CAAC,kBAAkB,EAAE,aAAa,CAAC,GAC5C,IAAI,CAQN;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,MAAM,8BAA8B,GAAG,WAAW,GAAG,MAAM,GAAG,OAAO,GAAG,UAAU,CAAC;AAEzF,MAAM,WAAW,yBAAyB;IACxC,QAAQ,CAAC,KAAK,EAAE,8BAA8B,CAAC;IAC/C,uGAAuG;IACvG,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC;IAChC,uGAAuG;IACvG,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,sCAAsC;IACrD,2FAA2F;IAC3F,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;;;;GAKG;AACH,wBAAgB,+BAA+B,CAC7C,SAAS,EAAE,IAAI,CAAC,sBAAsB,EAAE,OAAO,GAAG,YAAY,CAAC,EAC/D,OAAO,GAAE,sCAA2C,GACnD,yBAAyB,CA2B3B;AAYD,+FAA+F;AAC/F,MAAM,MAAM,sBAAsB,GAAG,UAAU,MAAM,EAAE,CAAC;AAExD,MAAM,WAAW,8BAA8B;IAC7C,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,MAAM,CAAC,EAAE,sBAAsB,CAAC;IACzC,QAAQ,CAAC,SAAS,CAAC,EAAE,sBAAsB,CAAC;IAC5C,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,UAAU,CAAC,EAAE,sBAAsB,CAAC;CAC9C;AAED;;;;;;;;;;GAUG;AACH,MAAM,WAAW,4BAA4B;IAC3C,QAAQ,CAAC,IAAI,EAAE,2BAA2B,CAAC;IAC3C,QAAQ,CAAC,OAAO,EAAE,2BAA2B,CAAC,SAAS,CAAC,CAAC;IACzD,QAAQ,CAAC,OAAO,EAAE,uBAAuB,CAAC;IAC1C,QAAQ,CAAC,MAAM,EAAE,8BAA8B,CAAC;IAChD,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;IACpC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,wBAAgB,wBAAwB,CAAC,UAAU,EAAE,2BAA2B,GAAG,4BAA4B,CAmB9G;AAMD;;;;;;GAMG;AACH,wBAAgB,2BAA2B,CAAC,UAAU,EAAE,2BAA2B,GAAG,MAAM,CAE3F;AAED;;;GAGG;AACH,wBAAgB,mCAAmC,CAAC,UAAU,EAAE,2BAA2B,GAAG,MAAM,CAEnG"}

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/honua-server.d.ts.map

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

@@ -34,7 +34,8 @@
  * @module
  */
 import { trimTrailingSlashes } from "../core/path-utils.js";
-import { createRealtimeServerSentEventsTransport } from "./sse.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";
 /**
@@ -83,16 +84,17 @@ export function encodeHonuaServerRealtimeRequest(url, request) {
  * already speak the SDK vocabulary pass through unchanged.
  */
 export function decodeHonuaServerRealtimeEvent(payload) {
-    if (!isRecord(payload))
-        throw new Error("honua-server streaming payload must be a JSON object.");
+    if (!isRecord(payload)) {
+        throw new HonuaRealtimeResumeError("invalid-event", "honua-server streaming payload must be a JSON object.");
+    }
     const envelope = payload;
     // Status / heartbeat / error envelopes already use the SDK vocabulary.
     if (typeof envelope.type === "string" && envelope.type !== "change" && envelope.type !== "feature-change") {
-        return payload;
+        return decodeRealtimeServerSentEvent(payload);
     }
     const changes = collectChanges(envelope);
     if (changes.length === 0) {
-        throw new Error("honua-server feature-change envelope is missing changes.");
+        throw new HonuaRealtimeResumeError("invalid-event", "honua-server feature-change envelope is missing changes.");
     }
     const base = {
         eventId: envelope.eventId,
@@ -105,15 +107,18 @@ export function decodeHonuaServerRealtimeEvent(payload) {
     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.");
+        }
         if (change.featureId === undefined) {
-            throw new Error("honua-server feature change is missing featureId.");
+            throw new HonuaRealtimeResumeError("invalid-event", "honua-server feature change is missing featureId.");
         }
         if (change.op === "delete") {
             deletes.push({ id: change.featureId, version: change.version, updatedAt: change.updatedAt });
             continue;
         }
         if (change.feature === undefined) {
-            throw new Error(`honua-server ${change.op} change is missing feature payload.`);
+            throw new HonuaRealtimeResumeError("invalid-event", `honua-server ${change.op} change is missing feature payload.`);
         }
         upserts.push({
             id: change.featureId,
@@ -161,7 +166,7 @@ export function createHonuaServerRealtimeSubscription(options) {
 }
 function resolveStreamingUrl(baseUrl) {
     if (!baseUrl) {
-        throw new Error("createHonuaServerRealtimeSubscription requires either `url` or `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.

package/realtime/index.d.ts

@@ -1,9 +1,14 @@
 /**
- * `@honua/sdk-js/realtime` — realtime transport adapters (Server-Sent Events today,
- * WebSocket/WebTransport adapters land alongside future server endpoints).
+ * `@honua/sdk-js/realtime` — realtime transport adapters. Raw Server-Sent
+ * Events (`sse.ts`) and WebSocket (`websocket.ts`) wire adapters pair with
+ * the bounded, resumable wrapper in `resumable-transport.ts` (issue #557),
+ * which adds the #556 delivery gate, reconnect/backoff, heartbeat timeout,
+ * and redacted telemetry on top of either one. `odata-delta.ts` (issue #558)
+ * adds a pull-based OData v4 delta-link adapter with its own bounded poll
+ * loop and honest, non-live freshness reporting — it satisfies the same
+ * `RealtimeFeatureTransport` surface but is not a socket transport, so it
+ * does not compose with `resumable-transport.ts`'s reconnect wrapper.
  *
- * @experimental This entrypoint is not yet covered by the SDK's semver contract
- *   — the surface may change in any minor release prior to `1.0.0`.
  * @module
  */
 export { createRealtimeServerSentEventsTransport, decodeRealtimeServerSentEvent, encodeDefaultRealtimeRequest, } from "./sse.js";
@@ -13,6 +18,16 @@ export type { CreateHonuaServerRealtimeSubscriptionOptions, HonuaServerFeatureCh
 export { emptyRealtimeFeatureState, reconcileRealtimeStaleness, reduceRealtimeFeatureState, realtimeFeatureKey, realtimeResumeCheckpoint, realtimeSubscriptionKey, } from "./reducer.js";
 export { createRealtimeFeatureStore } from "./store.js";
 export type { RealtimeFeatureStore } from "./store.js";
+export { REALTIME_DURABLE_CHECKPOINT_VERSION, HonuaRealtimeResumeError, createResumableRealtimeSubscription, evaluateRealtimeCheckpoint, } from "./resumable.js";
+export type { CreateResumableRealtimeSubscriptionOptions, RealtimeCheckpointCompatibility, RealtimeCheckpointCompatibilityCode, RealtimeCheckpointStore, RealtimeDurableCheckpointV1, RealtimeExternalResnapshotReason, RealtimeResumeContextV1, RealtimeSequencedEvent, ResumableRealtimeDelivery, ResumableRealtimeDeliveryStatus, ResumableRealtimePhase, ResumableRealtimeReasonCode, ResumableRealtimeState, ResumableRealtimeSubscription, } from "./resumable.js";
+export { assertRealtimePlanIdentity, deriveRealtimeContractAuthority, realtimePlanFingerprint, redactRealtimeCheckpoint, serializeRealtimeCheckpoint, serializeRedactedRealtimeCheckpoint, } from "./contract.js";
+export type { DeriveRealtimeContractAuthorityOptions, RealtimeContractAuthority, RealtimeContractAuthorityState, RedactedRealtimeCheckpointV1, RedactedRealtimeResumePosition, RedactedResumePosition, } from "./contract.js";
+export { createRealtimeWebSocketTransport } from "./websocket.js";
+export type { RealtimeWebSocket, RealtimeWebSocketCloseEvent, RealtimeWebSocketFactory, RealtimeWebSocketTransportOptions, } from "./websocket.js";
+export { createOdataDeltaTransport } from "./odata-delta.js";
+export type { OdataDeltaEntity, OdataDeltaInitialQuery, OdataDeltaPollTelemetry, OdataDeltaTransportOptions, } from "./odata-delta.js";
+export { computeReconnectDelayMs, createResumableRealtimeTransport, createResumableServerSentEventsTransport, createResumableWebSocketTransport, } from "./resumable-transport.js";
+export type { RealtimeReconnectPolicy, RealtimeResumableTransportOptions, RealtimeResumableTransportTelemetry, } from "./resumable-transport.js";
 export { filterRealtimeSelection, reconcileRealtimeSelection } from "./exploration.js";
 export { selectRealtimeDetail, selectRealtimeFeatureRecordMap, selectRealtimeFeatureRecords, selectRealtimeFeatureTombstones, selectRealtimeFeatures, } from "./projections.js";
 export type { RealtimeDetailSelectorOptions, RealtimeDetailState, RealtimeFeatureRecordSelectorOptions, RealtimeFeatureReference, } from "./projections.js";

package/realtime/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/realtime/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EACL,uCAAuC,EACvC,6BAA6B,EAC7B,4BAA4B,GAC7B,MAAM,UAAU,CAAC;AAClB,YAAY,EACV,6BAA6B,EAC7B,oCAAoC,EACpC,wCAAwC,GACzC,MAAM,UAAU,CAAC;AAClB,OAAO,EACL,qCAAqC,EACrC,8BAA8B,EAC9B,gCAAgC,EAChC,yBAAyB,EACzB,oCAAoC,GACrC,MAAM,mBAAmB,CAAC;AAC3B,YAAY,EACV,4CAA4C,EAC5C,wBAAwB,EACxB,gCAAgC,GACjC,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,yBAAyB,EACzB,0BAA0B,EAC1B,0BAA0B,EAC1B,kBAAkB,EAClB,wBAAwB,EACxB,uBAAuB,GACxB,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,0BAA0B,EAAE,MAAM,YAAY,CAAC;AACxD,YAAY,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AACvD,OAAO,EAAE,uBAAuB,EAAE,0BAA0B,EAAE,MAAM,kBAAkB,CAAC;AACvF,OAAO,EACL,oBAAoB,EACpB,8BAA8B,EAC9B,4BAA4B,EAC5B,+BAA+B,EAC/B,sBAAsB,GACvB,MAAM,kBAAkB,CAAC;AAC1B,YAAY,EACV,6BAA6B,EAC7B,mBAAmB,EACnB,oCAAoC,EACpC,wBAAwB,GACzB,MAAM,kBAAkB,CAAC;AAC1B,YAAY,EACV,wBAAwB,EACxB,mBAAmB,EACnB,mBAAmB,EACnB,kBAAkB,EAClB,kBAAkB,EAClB,oBAAoB,EACpB,wBAAwB,EACxB,uBAAuB,EACvB,oBAAoB,EACpB,qBAAqB,EACrB,oBAAoB,EACpB,wBAAwB,EACxB,wBAAwB,EACxB,sBAAsB,EACtB,sBAAsB,EACtB,wBAAwB,EACxB,kBAAkB,EAClB,qBAAqB,EACrB,qBAAqB,EACrB,mBAAmB,EACnB,wBAAwB,EACxB,4BAA4B,EAC5B,0BAA0B,EAC1B,wBAAwB,EACxB,2BAA2B,EAC3B,6BAA6B,EAC7B,qBAAqB,EACrB,mBAAmB,GACpB,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/realtime/index.ts"],"names":[],"mappings":"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"}

package/realtime/index.js

@@ -1,14 +1,24 @@
 /**
- * `@honua/sdk-js/realtime` — realtime transport adapters (Server-Sent Events today,
- * WebSocket/WebTransport adapters land alongside future server endpoints).
+ * `@honua/sdk-js/realtime` — realtime transport adapters. Raw Server-Sent
+ * Events (`sse.ts`) and WebSocket (`websocket.ts`) wire adapters pair with
+ * the bounded, resumable wrapper in `resumable-transport.ts` (issue #557),
+ * which adds the #556 delivery gate, reconnect/backoff, heartbeat timeout,
+ * and redacted telemetry on top of either one. `odata-delta.ts` (issue #558)
+ * adds a pull-based OData v4 delta-link adapter with its own bounded poll
+ * loop and honest, non-live freshness reporting — it satisfies the same
+ * `RealtimeFeatureTransport` surface but is not a socket transport, so it
+ * does not compose with `resumable-transport.ts`'s reconnect wrapper.
  *
- * @experimental This entrypoint is not yet covered by the SDK's semver contract
- *   — the surface may change in any minor release prior to `1.0.0`.
  * @module
  */
 export { createRealtimeServerSentEventsTransport, decodeRealtimeServerSentEvent, encodeDefaultRealtimeRequest, } from "./sse.js";
 export { createHonuaServerRealtimeSubscription, decodeHonuaServerRealtimeEvent, encodeHonuaServerRealtimeRequest, honuaServerRealtimePreset, HONUA_SERVER_STREAMING_FEATURES_PATH, } from "./honua-server.js";
 export { emptyRealtimeFeatureState, reconcileRealtimeStaleness, reduceRealtimeFeatureState, realtimeFeatureKey, realtimeResumeCheckpoint, realtimeSubscriptionKey, } from "./reducer.js";
 export { createRealtimeFeatureStore } from "./store.js";
+export { REALTIME_DURABLE_CHECKPOINT_VERSION, HonuaRealtimeResumeError, createResumableRealtimeSubscription, evaluateRealtimeCheckpoint, } from "./resumable.js";
+export { assertRealtimePlanIdentity, deriveRealtimeContractAuthority, realtimePlanFingerprint, redactRealtimeCheckpoint, serializeRealtimeCheckpoint, serializeRedactedRealtimeCheckpoint, } from "./contract.js";
+export { createRealtimeWebSocketTransport } from "./websocket.js";
+export { createOdataDeltaTransport } from "./odata-delta.js";
+export { computeReconnectDelayMs, createResumableRealtimeTransport, createResumableServerSentEventsTransport, createResumableWebSocketTransport, } from "./resumable-transport.js";
 export { filterRealtimeSelection, reconcileRealtimeSelection } from "./exploration.js";
 export { selectRealtimeDetail, selectRealtimeFeatureRecordMap, selectRealtimeFeatureRecords, selectRealtimeFeatureTombstones, selectRealtimeFeatures, } from "./projections.js";

package/realtime/odata-delta.d.ts

@@ -0,0 +1,114 @@
+/**
+ * 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 type { FeatureId } from "../contract/types.js";
+import type { RealtimeFeatureTransport } from "./types.js";
+/** Raw OData entity as delivered in a `value[]` array entry, annotations included. */
+export interface OdataDeltaEntity {
+    readonly [key: string]: unknown;
+}
+/** `$`-shaped query options applied only to the initial full-collection snapshot request. */
+export interface OdataDeltaInitialQuery {
+    readonly filter?: string;
+    readonly select?: readonly string[];
+    readonly orderBy?: readonly string[];
+    readonly top?: number;
+}
+/** Honest pull-cadence/freshness telemetry emitted after every request cycle. Never implies push liveness. */
+export interface OdataDeltaPollTelemetry {
+    /** When this cycle's response was accepted, per `now()`. */
+    readonly polledAt: number;
+    /** When the next poll is scheduled, per `now()`. Absent while a resnapshot recovery is in progress. */
+    readonly nextPollAt?: number;
+    readonly intervalMs: number;
+    readonly sequence: number;
+    readonly changed: boolean;
+    readonly upsertCount: number;
+    readonly deleteCount: number;
+}
+export interface OdataDeltaTransportOptions<TFeature = unknown> {
+    /**
+     * Absolute OData entity-set collection URL, e.g.
+     * `"https://host/odata/Incidents"`. Every `@odata.nextLink` /
+     * `@odata.deltaLink` this transport follows, and any resumed
+     * `resumeFrom.deltaToken`, must resolve to this exact origin and path
+     * (REQ-002).
+     */
+    readonly url: string;
+    /** Delay between the end of one accepted cycle and the start of the next. */
+    readonly pollIntervalMs: number;
+    /** Extract a stable entity id from a raw OData entity for `RealtimeFeaturePatch.id`. */
+    readonly entityId: (entity: OdataDeltaEntity) => FeatureId;
+    /** Project a raw OData entity into the feature payload. @default the entity with `@`-prefixed annotations stripped */
+    readonly toFeature?: (entity: OdataDeltaEntity) => TFeature;
+    /** `$filter` / `$select` / `$orderby` / `$top` applied only to the initial snapshot request. */
+    readonly initialQuery?: OdataDeltaInitialQuery;
+    /** Request headers, recomputed for every request (e.g. a fresh bearer token). */
+    readonly headers?: () => Record<string, string>;
+    /** Injectable fetch; defaults to `globalThis.fetch`. */
+    readonly fetchImpl?: typeof fetch;
+    /**
+     * Classify a non-ok response as an expired/rejected delta link that should
+     * trigger an explicit resnapshot rather than a generic transport failure.
+     * @default status => status === 410
+     */
+    readonly isDeltaLinkExpiredResponse?: (status: number, body: unknown) => boolean;
+    /**
+     * Identify an OData delta-payload entry as an unsupported relationship
+     * (link) change rather than an entity change, per REQ-003. Relationship
+     * deltas fail explicitly instead of being silently dropped or
+     * misinterpreted as an entity upsert.
+     * @default entry with string `source`, `relationship`, and `target` properties
+     */
+    readonly isRelationshipDeltaEntry?: (entry: OdataDeltaEntity) => boolean;
+    /** Safety bound on `@odata.nextLink` pages followed within one cycle. @default 500 */
+    readonly maxPagesPerCycle?: number;
+    /** Safety bound on rows collected by one snapshot cycle. @default 50_000 */
+    readonly maxSnapshotRows?: number;
+    /** Consecutive expired-delta-link resnapshots tolerated before failing closed. @default 3 */
+    readonly maxConsecutiveResnapshots?: number;
+    readonly onPoll?: (telemetry: OdataDeltaPollTelemetry) => void;
+    readonly now?: () => number;
+}
+/**
+ * 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 declare function createOdataDeltaTransport<TFeature = unknown>(options: OdataDeltaTransportOptions<TFeature>): RealtimeFeatureTransport<TFeature>;
+//# sourceMappingURL=odata-delta.d.ts.map