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

package/realtime/checkpoint-store.js

@@ -0,0 +1,504 @@
+/**
+ * Durable {@link RealtimeCheckpointStore} implementations for
+ * `@honua/sdk-js/realtime` (issue #937).
+ *
+ * `resumable.ts` already owns the resume state machine: it loads a checkpoint,
+ * validates it with {@link evaluateRealtimeCheckpoint}, and requires an explicit
+ * replacement snapshot whenever the checkpoint no longer applies. What it never
+ * had was a shipped store, so a reload always resnapshotted even when a valid
+ * cursor was in hand a second earlier. This module supplies that durability
+ * without redefining any cursor semantics:
+ *
+ * - {@link createIndexedDbRealtimeCheckpointStore} persists one record per
+ *   resume scope in the browser, keyed by the authorization-scope digest,
+ *   source identity, and query identity that already define checkpoint scope.
+ * - {@link createMemoryRealtimeCheckpointStore} runs the identical
+ *   normalization, screening, expiry, and eviction logic without IndexedDB, for
+ *   tests and non-persistent hosts.
+ * - {@link createRealtimeCheckpointStore} binds that same logic to any
+ *   {@link RealtimeCheckpointRecordStorage}, for hosts this module ships no
+ *   adapter for.
+ *
+ * Four properties are deliberate:
+ *
+ * 1. **Cursors only.** A record carries the resume position (sequence, cursor,
+ *    watermark, timestamp, delta token), the scope identity it belongs to, and
+ *    two observation times. It never carries features, snapshots, request URLs,
+ *    headers, or credentials. The authorization scope is reduced to a SHA-256
+ *    digest before it reaches storage, and every remaining persisted string is
+ *    screened with the shared persisted-string screen in
+ *    `src/connect-url-safety.ts` — the same discipline the offline region store
+ *    applies through `assertCredentialFreeManifest`.
+ * 2. **Fail-closed resume.** Load revalidates through
+ *    {@link evaluateRealtimeCheckpoint} and discards the record outright when
+ *    the source, query, source version, schema version, or authorization scope
+ *    changed, when the record is corrupt, or when the checkpoint is older than
+ *    the configured maximum age. A discarded checkpoint means the subscription
+ *    resnapshots; it never means a partial delta stream is delivered as though
+ *    it were complete.
+ * 3. **Bounded and atomic.** Each scope holds exactly one record (last write
+ *    wins), the store holds at most `maxRecords` scope records, and the
+ *    IndexedDB write plus its eviction sweep share a single readwrite
+ *    transaction.
+ * 4. **Never throws into a subscription.** A storage failure, a refused
+ *    credential-shaped value, or a corrupt record resolves and reports a
+ *    {@link RealtimeCheckpointStoreDiagnosticV1} carrying a
+ *    `HonuaRealtimeResumeError`, so the subscription degrades to a resnapshot
+ *    instead of entering the gate's terminal `error` phase.
+ *
+ * The store stays opt-in: nothing here is wired into a subscription unless a
+ * caller passes it as `checkpointStore`, so no existing subscription changes
+ * behaviour by default.
+ *
+ * @module
+ */
+import { credentialScreenMessage, screenPersistedString } from "../connect-url-safety.js";
+import { canonicalStringify, sha256 } from "../query-planner/canonical.js";
+import { HonuaRealtimeResumeError, REALTIME_DURABLE_CHECKPOINT_VERSION, evaluateRealtimeCheckpoint, } from "./resumable.js";
+/**
+ * Versioned format string stamped on every persisted record. A record whose
+ * format string differs is treated as corrupt and discarded on load, the same
+ * posture the offline stores take, so a future format can never be
+ * misinterpreted as this one.
+ */
+export const HONUA_REALTIME_CHECKPOINT_STORE_FORMAT = "honua.realtime-checkpoint-store/1.0";
+/**
+ * Default maximum checkpoint age. A cursor older than this forces a resnapshot
+ * even when its scope still matches, because a server may retire a cursor
+ * window without telling the client; a silent gap is worse than an honest
+ * resnapshot.
+ */
+export const DEFAULT_REALTIME_CHECKPOINT_MAX_AGE_MS = 15 * 60 * 1000;
+/** Absolute ceiling on `maxAgeMs`. Callers may tighten it, never raise it. */
+export const MAX_REALTIME_CHECKPOINT_MAX_AGE_MS = 24 * 60 * 60 * 1000;
+/**
+ * Default cap on distinct resume scopes retained per store. Each scope holds at
+ * most one record, so this is also the record cap; the least recently written
+ * record is evicted first.
+ */
+export const DEFAULT_REALTIME_CHECKPOINT_MAX_RECORDS = 64;
+/** Absolute ceiling on `maxRecords`. Callers may tighten it, never raise it. */
+export const MAX_REALTIME_CHECKPOINT_RECORDS = 512;
+const DATABASE_VERSION = 1;
+const CHECKPOINT_STORE = "checkpoints";
+const OBSERVED_AT_INDEX = "observedAt";
+/** Reason codes mapped onto the delivery gate's existing failure taxonomy. */
+const DIAGNOSTIC_ERROR_CODES = {
+    "invalid-checkpoint": "invalid-checkpoint",
+    "source-changed": "source-changed",
+    "query-changed": "query-changed",
+    "source-version-changed": "source-version-changed",
+    "schema-version-changed": "schema-version-changed",
+    "authorization-scope-changed": "authorization-scope-changed",
+    "checkpoint-expired": "cursor-expired",
+    "credential-screened": "checkpoint-save-failed",
+    "storage-failed": "checkpoint-load-failed",
+    "unsupported-format": "invalid-checkpoint",
+};
+/**
+ * Deterministic scope key for a resume context: a digest over the
+ * authorization-scope digest, source identity, and query identity — exactly the
+ * identities checkpoint scope validation is defined against. Source and schema
+ * versions are intentionally excluded so a version bump replaces the record in
+ * place and is discarded explicitly on load, instead of orphaning it under a
+ * key nothing will read again.
+ */
+export function realtimeCheckpointScopeKey(context) {
+    return sha256(`honua-realtime-checkpoint-scope:v1:${canonicalStringify({
+        authorizationScopeDigest: realtimeAuthorizationScopeDigest(context.authorizationScopeFingerprint),
+        queryFingerprint: String(context.queryFingerprint),
+        sourceId: String(context.sourceId),
+    })}`);
+}
+/**
+ * Opaque digest of an authorization-scope fingerprint. The fingerprint is
+ * already documented as a non-secret opaque identity; persisting only its
+ * digest keeps that promise enforceable rather than assumed.
+ */
+export function realtimeAuthorizationScopeDigest(fingerprint) {
+    return sha256(`honua-realtime-checkpoint-scope-digest:v1:${fingerprint}`);
+}
+/**
+ * Bind the shared scope, screening, expiry, and eviction logic to any
+ * {@link RealtimeCheckpointRecordStorage}. The returned store never throws into
+ * a subscription: a rejected storage call, a refused value, or a corrupt record
+ * resolves and reports a diagnostic, so the subscription resnapshots.
+ */
+export function createRealtimeCheckpointStore(storage, options = {}) {
+    const normalized = normalizeOptions(options);
+    return {
+        load: (context, signal) => loadCheckpoint(storage, normalized, context, signal),
+        save: (checkpoint, signal) => saveCheckpoint(storage, normalized, checkpoint, signal),
+        records: async () => (await storage.list()).filter((record) => isCheckpointRecord(record)),
+        clear: () => storage.clear(),
+    };
+}
+/** In-memory store with the persistent store's exact semantics, for tests and non-persistent hosts. */
+export function createMemoryRealtimeCheckpointStore(options = {}) {
+    return createRealtimeCheckpointStore(createMemoryCheckpointStorage(), options);
+}
+/** Map-backed storage with the same one-record-per-scope, oldest-first eviction contract. */
+export function createMemoryCheckpointStorage() {
+    const records = new Map();
+    return {
+        read: async (key) => records.get(key),
+        write: async (record, maxRecords) => {
+            // Delete first so the re-inserted key moves to the tail of the insertion
+            // order, which is the eviction order.
+            records.delete(record.key);
+            records.set(record.key, record);
+            for (const key of [...records.keys()].slice(0, Math.max(0, records.size - maxRecords)))
+                records.delete(key);
+        },
+        remove: async (key) => {
+            records.delete(key);
+        },
+        list: async () => [...records.values()],
+        clear: async () => records.clear(),
+    };
+}
+/** Persistent browser store: one bounded, atomically written record per resume scope. */
+export function createIndexedDbRealtimeCheckpointStore(options = {}) {
+    return createRealtimeCheckpointStore(createIndexedDbCheckpointStorage(options), options);
+}
+/** IndexedDB storage; each method runs in exactly one transaction. */
+export function createIndexedDbCheckpointStorage(options = {}) {
+    const factory = options.indexedDB ?? globalThis.indexedDB;
+    if (!factory)
+        throw new Error("IndexedDB is not available in this runtime.");
+    const name = options.name ?? "honua-realtime-checkpoints";
+    if (name.trim().length === 0)
+        throw new Error("IndexedDB database name must be non-empty.");
+    const database = openDatabase(factory, name);
+    return {
+        read: async (key) => runTransaction(await database, "readonly", async (transaction) => request(transaction.objectStore(CHECKPOINT_STORE).get(key))),
+        write: async (record, maxRecords) => runTransaction(await database, "readwrite", async (transaction) => {
+            const store = transaction.objectStore(CHECKPOINT_STORE);
+            store.put(record);
+            const total = await request(store.count());
+            if (total > maxRecords)
+                await evictOldest(store, total - maxRecords, record.key);
+        }),
+        remove: async (key) => runTransaction(await database, "readwrite", async (transaction) => {
+            transaction.objectStore(CHECKPOINT_STORE).delete(key);
+        }),
+        list: async () => runTransaction(await database, "readonly", async (transaction) => request(transaction.objectStore(CHECKPOINT_STORE).getAll())),
+        clear: async () => runTransaction(await database, "readwrite", async (transaction) => {
+            transaction.objectStore(CHECKPOINT_STORE).clear();
+        }),
+    };
+}
+async function loadCheckpoint(backend, options, context, signal) {
+    if (signal?.aborted)
+        return undefined;
+    let scopeKey;
+    try {
+        scopeKey = realtimeCheckpointScopeKey(context);
+    }
+    catch (cause) {
+        // A context this store cannot even key is not a resumable context.
+        report(options, "load", "invalid-checkpoint", INVALID_SCOPE_KEY, "Resume context could not be keyed.", cause);
+        return undefined;
+    }
+    let stored;
+    try {
+        stored = await backend.read(scopeKey);
+    }
+    catch (cause) {
+        report(options, "load", "storage-failed", scopeKey, "Unable to read the stored realtime checkpoint.", cause);
+        return undefined;
+    }
+    if (stored === undefined || signal?.aborted)
+        return undefined;
+    const projection = projectStoredCheckpoint(stored, context, options);
+    if ("reason" in projection) {
+        await discard(backend, options, scopeKey, projection.reason, projection.detail);
+        return undefined;
+    }
+    return projection.checkpoint;
+}
+async function saveCheckpoint(backend, options, checkpoint, signal) {
+    if (signal?.aborted)
+        return;
+    let scopeKey = INVALID_SCOPE_KEY;
+    try {
+        const compatibility = evaluateRealtimeCheckpoint(checkpoint?.context, checkpoint);
+        if (!compatibility.compatible) {
+            report(options, "save", "invalid-checkpoint", scopeKey, compatibility.reason);
+            return;
+        }
+        scopeKey = realtimeCheckpointScopeKey(checkpoint.context);
+    }
+    catch (cause) {
+        report(options, "save", "invalid-checkpoint", scopeKey, "Checkpoint could not be projected for storage.", cause);
+        return;
+    }
+    const record = projectRecord(checkpoint, scopeKey, options.now());
+    if ("path" in record) {
+        // Refusing to persist is deliberate: the in-memory checkpoint still drives
+        // this connection, and the next load simply resnapshots.
+        report(options, "save", "credential-screened", scopeKey, credentialScreenMessage(record.path, record.reason));
+        return;
+    }
+    try {
+        await backend.write(record.record, options.maxRecords);
+    }
+    catch (cause) {
+        report(options, "save", "storage-failed", scopeKey, "Unable to persist the realtime checkpoint.", cause);
+    }
+}
+async function discard(backend, options, scopeKey, reason, detail) {
+    try {
+        await backend.remove(scopeKey);
+    }
+    catch {
+        // The record is already unusable; failing to delete it must not change the
+        // outcome, which is an explicit resnapshot either way.
+    }
+    report(options, "load", reason, scopeKey, detail);
+}
+function projectStoredCheckpoint(stored, context, options) {
+    // The format stamp is read before anything else, so a record from another
+    // store layout is reported as the version fact it is instead of being
+    // absorbed into the generic corrupt bucket. The offending value is never
+    // echoed: a hostile record could put anything in that field.
+    if (typeof stored === "object" && stored !== null && !isStoreFormat(stored.format)) {
+        return {
+            reason: "unsupported-format",
+            detail: `Stored realtime checkpoint was written in a different store format; this build reads "${HONUA_REALTIME_CHECKPOINT_STORE_FORMAT}".`,
+        };
+    }
+    if (!isCheckpointRecord(stored)) {
+        return { reason: "invalid-checkpoint", detail: "Stored realtime checkpoint record is corrupt or unreadable." };
+    }
+    if (stored.authorizationScopeDigest !== realtimeAuthorizationScopeDigest(context.authorizationScopeFingerprint)) {
+        return {
+            reason: "authorization-scope-changed",
+            detail: "Stored checkpoint authorization scope does not match the current grants.",
+        };
+    }
+    const ageMs = options.now() - Date.parse(stored.savedAt);
+    if (!Number.isFinite(ageMs) || ageMs < 0 || ageMs > options.maxAgeMs) {
+        return {
+            reason: "checkpoint-expired",
+            detail: `Stored checkpoint is outside the ${options.maxAgeMs}ms maximum resume age.`,
+        };
+    }
+    const checkpoint = Object.freeze({
+        kind: "honua.realtime-checkpoint",
+        version: REALTIME_DURABLE_CHECKPOINT_VERSION,
+        context: Object.freeze({
+            kind: "honua.realtime-resume-context",
+            version: 1,
+            sourceId: stored.sourceId,
+            queryFingerprint: stored.queryFingerprint,
+            sourceVersion: stored.sourceVersion,
+            schemaVersion: stored.schemaVersion,
+            // Safe only because the digest above already matched this exact scope.
+            authorizationScopeFingerprint: context.authorizationScopeFingerprint,
+        }),
+        resume: Object.freeze({ ...stored.resume }),
+        recentEventIds: Object.freeze([]),
+        savedAt: stored.savedAt,
+    });
+    const compatibility = evaluateRealtimeCheckpoint(context, checkpoint);
+    if (!compatibility.compatible) {
+        // `compatible` is only reported alongside `compatible: true`; an
+        // incompatible result that still carried it would be a contract break, so
+        // it degrades to the shape-level rejection rather than resuming.
+        const reason = compatibility.code === "compatible" ? "invalid-checkpoint" : compatibility.code;
+        return { reason, detail: compatibility.reason };
+    }
+    return { checkpoint };
+}
+function projectRecord(checkpoint, scopeKey, now) {
+    const context = checkpoint.context;
+    const resume = {
+        sequence: checkpoint.resume.sequence,
+        ...optionalText("cursor", checkpoint.resume),
+        ...optionalText("watermark", checkpoint.resume),
+        ...optionalText("timestamp", checkpoint.resume),
+        ...optionalText("deltaToken", checkpoint.resume),
+    };
+    const screened = [
+        ["sourceId", String(context.sourceId)],
+        ["queryFingerprint", context.queryFingerprint],
+        ["sourceVersion", context.sourceVersion],
+        ["schemaVersion", context.schemaVersion],
+        ...(resume.cursor === undefined ? [] : [["resume.cursor", resume.cursor]]),
+        ...(resume.watermark === undefined ? [] : [["resume.watermark", resume.watermark]]),
+        ...(resume.timestamp === undefined ? [] : [["resume.timestamp", resume.timestamp]]),
+        ...(resume.deltaToken === undefined ? [] : [["resume.deltaToken", resume.deltaToken]]),
+    ];
+    for (const [path, value] of screened) {
+        const reason = screenPersistedString(value, "identity");
+        if (reason)
+            return { path, reason };
+    }
+    const observedAt = new Date(Number.isFinite(now) ? now : Date.now()).toISOString();
+    return {
+        record: {
+            key: scopeKey,
+            format: HONUA_REALTIME_CHECKPOINT_STORE_FORMAT,
+            sourceId: String(context.sourceId),
+            queryFingerprint: context.queryFingerprint,
+            sourceVersion: context.sourceVersion,
+            schemaVersion: context.schemaVersion,
+            authorizationScopeDigest: realtimeAuthorizationScopeDigest(context.authorizationScopeFingerprint),
+            resume,
+            savedAt: checkpoint.savedAt,
+            observedAt,
+        },
+    };
+}
+function optionalText(name, resume) {
+    const value = resume[name];
+    return typeof value === "string" ? { [name]: value } : {};
+}
+function report(options, operation, reason, scopeKey, detail, cause) {
+    if (!options.onDiagnostic)
+        return;
+    const error = new HonuaRealtimeResumeError(DIAGNOSTIC_ERROR_CODES[reason], detail, cause === undefined ? undefined : { cause });
+    options.onDiagnostic(Object.freeze({
+        kind: "honua.realtime-checkpoint-store-diagnostic",
+        version: 1,
+        operation,
+        reason,
+        scopeKey,
+        error,
+    }));
+}
+function normalizeOptions(options) {
+    return {
+        maxAgeMs: tightenedPositive(options.maxAgeMs, DEFAULT_REALTIME_CHECKPOINT_MAX_AGE_MS, MAX_REALTIME_CHECKPOINT_MAX_AGE_MS, "maxAgeMs"),
+        maxRecords: tightenedPositive(options.maxRecords, DEFAULT_REALTIME_CHECKPOINT_MAX_RECORDS, MAX_REALTIME_CHECKPOINT_RECORDS, "maxRecords"),
+        now: options.now ?? Date.now,
+        ...(options.onDiagnostic ? { onDiagnostic: options.onDiagnostic } : {}),
+    };
+}
+function tightenedPositive(value, fallback, ceiling, name) {
+    if (value === undefined)
+        return fallback;
+    if (!Number.isSafeInteger(value) || value < 1) {
+        throw new HonuaRealtimeResumeError("invalid-checkpoint", `${name} must be a safe integer greater than zero.`);
+    }
+    if (value > ceiling) {
+        throw new HonuaRealtimeResumeError("invalid-checkpoint", `${name} cannot exceed the ${ceiling} safety ceiling.`);
+    }
+    return value;
+}
+const INVALID_SCOPE_KEY = `sha256:${"0".repeat(64)}`;
+function isStoreFormat(value) {
+    return value === HONUA_REALTIME_CHECKPOINT_STORE_FORMAT;
+}
+function isCheckpointRecord(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const record = value;
+    if (!isStoreFormat(record.format))
+        return false;
+    for (const name of ["key", "sourceId", "queryFingerprint", "sourceVersion", "schemaVersion"]) {
+        if (typeof record[name] !== "string" || record[name].length === 0)
+            return false;
+    }
+    if (typeof record.authorizationScopeDigest !== "string" || !record.authorizationScopeDigest.startsWith("sha256:")) {
+        return false;
+    }
+    if (typeof record.savedAt !== "string" || !Number.isFinite(Date.parse(record.savedAt)))
+        return false;
+    if (typeof record.observedAt !== "string" || !Number.isFinite(Date.parse(record.observedAt)))
+        return false;
+    if (typeof record.resume !== "object" || record.resume === null)
+        return false;
+    const resume = record.resume;
+    if (!Number.isSafeInteger(resume.sequence) || resume.sequence < 0)
+        return false;
+    for (const name of ["cursor", "watermark", "timestamp", "deltaToken"]) {
+        if (resume[name] !== undefined && typeof resume[name] !== "string")
+            return false;
+    }
+    return true;
+}
+function openDatabase(factory, name) {
+    return new Promise((resolve, reject) => {
+        const open = factory.open(name, DATABASE_VERSION);
+        open.onupgradeneeded = () => {
+            const database = open.result;
+            const store = database.objectStoreNames.contains(CHECKPOINT_STORE)
+                ? open.transaction?.objectStore(CHECKPOINT_STORE)
+                : database.createObjectStore(CHECKPOINT_STORE, { keyPath: "key" });
+            if (store && !store.indexNames.contains(OBSERVED_AT_INDEX))
+                store.createIndex(OBSERVED_AT_INDEX, "observedAt");
+        };
+        open.onsuccess = () => resolve(open.result);
+        open.onerror = () => reject(open.error ?? new Error("Failed to open the realtime checkpoint database."));
+        open.onblocked = () => reject(new Error("Realtime checkpoint database upgrade is blocked by another connection."));
+    });
+}
+function runTransaction(database, mode, body) {
+    return new Promise((resolve, reject) => {
+        const transaction = database.transaction([CHECKPOINT_STORE], mode);
+        let result;
+        let settled = false;
+        void body(transaction).then((value) => {
+            result = value;
+        }, (error) => {
+            settled = true;
+            try {
+                transaction.abort();
+            }
+            catch {
+                // The transaction may already have completed or aborted.
+            }
+            reject(error);
+        });
+        transaction.oncomplete = () => {
+            if (settled)
+                return;
+            settled = true;
+            resolve(result);
+        };
+        transaction.onerror = () => {
+            if (settled)
+                return;
+            settled = true;
+            reject(transaction.error ?? new Error("Realtime checkpoint transaction failed."));
+        };
+        transaction.onabort = () => {
+            if (settled)
+                return;
+            settled = true;
+            reject(transaction.error ?? new Error("Realtime checkpoint transaction aborted."));
+        };
+    });
+}
+function request(source) {
+    return new Promise((resolve, reject) => {
+        source.onsuccess = () => resolve(source.result);
+        source.onerror = () => reject(source.error ?? new Error("Realtime checkpoint request failed."));
+    });
+}
+/** Delete `count` least recently written records inside the caller's transaction. */
+function evictOldest(store, count, protectedKey) {
+    return new Promise((resolve, reject) => {
+        let remaining = count;
+        if (remaining <= 0) {
+            resolve();
+            return;
+        }
+        const cursorRequest = store.index(OBSERVED_AT_INDEX).openCursor();
+        cursorRequest.onerror = () => reject(cursorRequest.error ?? new Error("Failed to enumerate realtime checkpoint records."));
+        cursorRequest.onsuccess = () => {
+            const cursor = cursorRequest.result;
+            if (!cursor || remaining <= 0) {
+                resolve();
+                return;
+            }
+            if (cursor.primaryKey !== protectedKey) {
+                cursor.delete();
+                remaining -= 1;
+            }
+            cursor.continue();
+        };
+    });
+}

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"}