@honua/app-platform 0.1.12 → 0.1.13

package/offline/snapshot.d.ts.map

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

package/offline/snapshot.js

@@ -0,0 +1,312 @@
+import { normalizeDiscoveryEndpoint } from "../contract/discovery.js";
+import { canonicalJson, compareCodeUnits, sha256 } from "./digest.js";
+import { createOfflineRegionManifest } from "./region.js";
+import { canonicalizeOfflineRegionQuery, offlineRegionAuthorizationScopeDigest, offlineRegionQueryFingerprint, offlineRegionResourceId, } from "./selection.js";
+import { HonuaOfflineRegionError, } from "./types.js";
+/**
+ * Snapshot planning: turn a protocol-neutral selection into a downloadable region.
+ *
+ * The planner is the missing producer between the contract and the region store.
+ * It takes a source identity, a canonical {@link Query}, a bounded extent, and the
+ * payloads an application already holds, and emits a manifest whose resource
+ * identities are deterministic functions of those inputs — never of a signed or
+ * token-bearing request URL. The same identity function answers the later read,
+ * so a snapshot and a read agree without persisting any addressing state.
+ *
+ * @experimental
+ */
+export const HONUA_OFFLINE_REGION_SNAPSHOT_KIND = "honua.offline-region-snapshot";
+export const HONUA_OFFLINE_REGION_SNAPSHOT_VERSION = "1.0";
+export const HONUA_OFFLINE_FEATURE_BATCH_KIND = "honua.offline-feature-batch";
+export const HONUA_OFFLINE_FEATURE_BATCH_VERSION = "1.0";
+/** Default ceiling on how many resources one planned snapshot may contain. */
+export const DEFAULT_OFFLINE_REGION_SNAPSHOT_MAX_CONTENTS = 10_000;
+const encoder = new TextEncoder();
+const decoder = new TextDecoder("utf-8", { fatal: true });
+/**
+ * Plan one bounded snapshot of a source, a query, and an extent.
+ *
+ * Every resource identity is derived from the selection — source identity,
+ * authorization-scope digest, captured versions, extent, canonical query, and the
+ * resource's own kind and selector. Identities are therefore stable across runs
+ * and processes, contain no request URL, and cannot collide across authorization
+ * scopes.
+ */
+export async function planOfflineRegionSnapshot(selection) {
+    const record = plainRecord(selection, "selection");
+    const authorizationScopeDigest = await offlineRegionAuthorizationScopeDigest(record.authorizationScopeFingerprint);
+    // Pagination is accepted but never enters identity: a window is a property of
+    // the captured batch, not of the question. `createOfflineRegionFeatureBatch()`
+    // records the window that was actually captured, and the read path answers
+    // pagination from that record instead of from a second identity.
+    const scope = canonicalizeOfflineRegionQuery(selection.query, selection.sourceId);
+    const queryFingerprint = await offlineRegionQueryFingerprint(scope.canonical);
+    // Identity binds the *normalized* endpoint, so a caller passing a signed or
+    // unnormalized URL can never produce a different identity than the manifest.
+    const boundIdentity = {
+        sourceId: selection.sourceId,
+        endpoint: normalizeSelectionEndpoint(selection.endpoint),
+        authorizationScopeDigest,
+        sourceVersion: selection.sourceVersion,
+        schemaVersion: selection.schemaVersion,
+        planVersion: selection.planVersion,
+        bounds: selection.bounds,
+        ...(selection.minZoom !== undefined ? { minZoom: selection.minZoom } : {}),
+        ...(selection.maxZoom !== undefined ? { maxZoom: selection.maxZoom } : {}),
+    };
+    const maxContents = selection.limits?.maxContents ?? DEFAULT_OFFLINE_REGION_SNAPSHOT_MAX_CONTENTS;
+    const contents = selection.contents;
+    if (!Array.isArray(contents))
+        throw invalid("selection.contents must be an array.", "selection.contents");
+    if (contents.length > maxContents) {
+        throw new HonuaOfflineRegionError("resource-limit-exceeded", `selection.contents contains ${contents.length} entries; maximum is ${maxContents}.`, { path: "selection.contents" });
+    }
+    const payloads = new Map();
+    const entries = [];
+    const resources = [];
+    for (let index = 0; index < contents.length; index += 1) {
+        const content = contents[index];
+        const path = `selection.contents[${index}]`;
+        const bytes = ownedBytes(content?.bytes, path);
+        const id = await offlineRegionResourceId({
+            kind: requireKind(content?.kind, path),
+            selection: boundIdentity,
+            queryFingerprint,
+            ...(content.selector !== undefined ? { selector: content.selector } : {}),
+        });
+        if (payloads.has(id)) {
+            throw invalid(`${path} repeats a resource identity already planned in this snapshot.`, path);
+        }
+        const integrity = await sha256(bytes);
+        payloads.set(id, bytes);
+        entries.push({
+            id,
+            kind: content.kind,
+            byteLength: bytes.byteLength,
+            integrity,
+            ...(content.contentType ? { contentType: content.contentType } : {}),
+        });
+        resources.push({
+            id,
+            kind: content.kind,
+            byteLength: bytes.byteLength,
+            integrity,
+            ...(content.contentType ? { contentType: content.contentType } : {}),
+            sourceVersion: selection.sourceVersion,
+            schemaVersion: selection.schemaVersion,
+            planVersion: selection.planVersion,
+            ...(content.attributionIds ? { attributionIds: content.attributionIds } : {}),
+        });
+    }
+    entries.sort((left, right) => compareCodeUnits(left.id, right.id));
+    const manifestInput = {
+        name: selection.name,
+        sourceId: selection.sourceId,
+        endpoint: selection.endpoint,
+        authorizationScopeFingerprint: selection.authorizationScopeFingerprint,
+        bounds: selection.bounds,
+        ...(selection.minZoom !== undefined ? { minZoom: selection.minZoom } : {}),
+        ...(selection.maxZoom !== undefined ? { maxZoom: selection.maxZoom } : {}),
+        sourceVersion: selection.sourceVersion,
+        schemaVersion: selection.schemaVersion,
+        planVersion: selection.planVersion,
+        observation: selection.observation,
+        ...(selection.validator ? { validator: selection.validator } : {}),
+        ...(selection.expiresAt ? { expiresAt: selection.expiresAt } : {}),
+        ...(selection.attribution ? { attribution: selection.attribution } : {}),
+        resources,
+        ...(selection.limits ? { limits: selection.limits } : {}),
+    };
+    const manifest = await createOfflineRegionManifest(manifestInput);
+    if (manifest.source.authorizationScopeDigest !== authorizationScopeDigest) {
+        throw invalid("Snapshot scope digest does not match the manifest it produced.", "authorizationScopeFingerprint");
+    }
+    return Object.freeze({
+        kind: HONUA_OFFLINE_REGION_SNAPSHOT_KIND,
+        version: HONUA_OFFLINE_REGION_SNAPSHOT_VERSION,
+        manifest,
+        selection: Object.freeze(boundIdentity),
+        query: scope.canonical,
+        queryFingerprint,
+        entries: Object.freeze(entries),
+        payloads,
+    });
+}
+/**
+ * Serve a planned snapshot's payloads to {@link downloadOfflineRegion}.
+ *
+ * The loader is offline by construction: it hands back the exact bytes the
+ * identities were computed from and refuses anything the plan does not name.
+ */
+export function createOfflineRegionSnapshotLoader(snapshot) {
+    const payloads = snapshot.payloads;
+    return async (resource) => {
+        const bytes = payloads.get(resource.id);
+        if (!bytes) {
+            throw new HonuaOfflineRegionError("resource-load-failed", `Planned snapshot does not carry a payload for resource "${resource.id}".`, { resourceId: resource.id });
+        }
+        return Uint8Array.from(bytes);
+    };
+}
+/** Capture a `Result` as the durable batch envelope a later read answers from. */
+export function createOfflineRegionFeatureBatch(result, options = {}) {
+    const features = result?.features;
+    if (!Array.isArray(features))
+        throw invalid("result.features must be an array.", "result.features");
+    const offset = options.pagination?.offset ?? 0;
+    if (!Number.isSafeInteger(offset) || offset < 0)
+        throw invalid("pagination.offset must be a non-negative safe integer.", "pagination.offset");
+    const limit = options.pagination?.limit;
+    if (limit !== undefined && (!Number.isSafeInteger(limit) || limit < 0)) {
+        throw invalid("pagination.limit must be a non-negative safe integer.", "pagination.limit");
+    }
+    if (limit !== undefined && features.length > limit) {
+        throw invalid("result.features exceeds the captured pagination limit.", "result.features");
+    }
+    return {
+        kind: HONUA_OFFLINE_FEATURE_BATCH_KIND,
+        version: HONUA_OFFLINE_FEATURE_BATCH_VERSION,
+        pagination: { offset, ...(limit === undefined ? {} : { limit }) },
+        exceededTransferLimit: result.exceededTransferLimit === true,
+        features: features.map((feature, index) => canonicalFeature(feature, `result.features[${index}]`)),
+        ...(result.totalCount === undefined ? {} : { totalCount: requireCount(result.totalCount) }),
+        ...(result.fields === undefined ? {} : { fields: jsonClone(result.fields, "result.fields") }),
+    };
+}
+/** Encode a batch as the deterministic UTF-8 bytes the manifest pins. */
+export function encodeOfflineRegionFeatureBatch(batch) {
+    return encoder.encode(canonicalJson(batch));
+}
+/** Decode and validate stored batch bytes. Anything unexpected fails closed. */
+export function decodeOfflineRegionFeatureBatch(bytes) {
+    let parsed;
+    try {
+        parsed = JSON.parse(decoder.decode(bytes));
+    }
+    catch (cause) {
+        throw new HonuaOfflineRegionError("integrity-mismatch", "Stored offline feature batch is not valid UTF-8 JSON.", {
+            cause,
+        });
+    }
+    const record = plainRecord(parsed, "batch");
+    if (record.kind !== HONUA_OFFLINE_FEATURE_BATCH_KIND || record.version !== HONUA_OFFLINE_FEATURE_BATCH_VERSION) {
+        throw invalid("Stored offline feature batch has an unsupported kind or version.", "batch");
+    }
+    const pagination = plainRecord(record.pagination, "batch.pagination");
+    const offset = pagination.offset;
+    if (typeof offset !== "number" || !Number.isSafeInteger(offset) || offset < 0) {
+        throw invalid("batch.pagination.offset must be a non-negative safe integer.", "batch.pagination.offset");
+    }
+    const limit = pagination.limit;
+    if (limit !== undefined && (typeof limit !== "number" || !Number.isSafeInteger(limit) || limit < 0)) {
+        throw invalid("batch.pagination.limit must be a non-negative safe integer.", "batch.pagination.limit");
+    }
+    if (typeof record.exceededTransferLimit !== "boolean") {
+        throw invalid("batch.exceededTransferLimit must be a boolean.", "batch.exceededTransferLimit");
+    }
+    if (!Array.isArray(record.features))
+        throw invalid("batch.features must be an array.", "batch.features");
+    const features = record.features.map((feature, index) => canonicalFeature(feature, `batch.features[${index}]`));
+    if (limit !== undefined && features.length > limit) {
+        throw invalid("batch.features exceeds its recorded pagination limit.", "batch.features");
+    }
+    return {
+        kind: HONUA_OFFLINE_FEATURE_BATCH_KIND,
+        version: HONUA_OFFLINE_FEATURE_BATCH_VERSION,
+        pagination: { offset, ...(limit === undefined ? {} : { limit: limit }) },
+        exceededTransferLimit: record.exceededTransferLimit,
+        features,
+        ...(record.totalCount === undefined ? {} : { totalCount: requireCount(record.totalCount) }),
+        ...(record.fields === undefined ? {} : { fields: jsonClone(record.fields, "batch.fields") }),
+    };
+}
+/** Reuse the one endpoint normalizer the manifest itself persists through. */
+function normalizeSelectionEndpoint(endpoint) {
+    if (typeof endpoint !== "string" && !(endpoint instanceof URL)) {
+        throw invalid("selection.endpoint must be a string or URL.", "selection.endpoint");
+    }
+    try {
+        return normalizeDiscoveryEndpoint(endpoint);
+    }
+    catch (cause) {
+        throw new HonuaOfflineRegionError("invalid-manifest", "selection.endpoint must be a valid absolute URL.", {
+            cause,
+            path: "selection.endpoint",
+        });
+    }
+}
+function canonicalFeature(value, path) {
+    const record = plainRecord(value, path);
+    for (const key in record) {
+        if (Object.hasOwn(record, key) && key !== "attributes" && key !== "geometry") {
+            throw invalid(`${path}.${key} is not supported on a stored feature.`, `${path}.${key}`);
+        }
+    }
+    const attributes = jsonClone(plainRecord(record.attributes, `${path}.attributes`), `${path}.attributes`);
+    const geometry = record.geometry;
+    return {
+        attributes: attributes,
+        ...(geometry === undefined
+            ? {}
+            : { geometry: geometry === null ? null : jsonClone(geometry, `${path}.geometry`) }),
+    };
+}
+function requireCount(value) {
+    if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 0) {
+        throw invalid("totalCount must be a non-negative safe integer.", "totalCount");
+    }
+    return value;
+}
+function ownedBytes(value, path) {
+    if (value instanceof Uint8Array)
+        return Uint8Array.from(value);
+    if (value instanceof ArrayBuffer)
+        return new Uint8Array(value.slice(0));
+    throw invalid(`${path}.bytes must be a Uint8Array or ArrayBuffer.`, `${path}.bytes`);
+}
+function requireKind(value, path) {
+    if (value !== "metadata" &&
+        value !== "features" &&
+        value !== "tile" &&
+        value !== "asset" &&
+        value !== "attribution") {
+        throw invalid(`${path}.kind is invalid.`, `${path}.kind`);
+    }
+    return value;
+}
+function jsonClone(value, path, depth = 0) {
+    if (value === null || typeof value === "string" || typeof value === "boolean")
+        return value;
+    if (typeof value === "number") {
+        if (!Number.isFinite(value))
+            throw invalid(`${path} must be finite.`, path);
+        return Object.is(value, -0) ? 0 : value;
+    }
+    if (depth >= 32)
+        throw invalid(`${path} exceeds the stored nesting limit.`, path);
+    if (Array.isArray(value))
+        return value.map((entry, index) => jsonClone(entry, `${path}[${index}]`, depth + 1));
+    const record = plainRecord(value, path);
+    const out = {};
+    for (const key in record) {
+        if (!Object.hasOwn(record, key))
+            continue;
+        const child = record[key];
+        if (child === undefined)
+            continue;
+        out[key] = jsonClone(child, `${path}.${key}`, depth + 1);
+    }
+    return out;
+}
+function plainRecord(value, path) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        throw invalid(`${path} must be a plain object.`, path);
+    }
+    const prototype = Object.getPrototypeOf(value);
+    if (prototype !== Object.prototype && prototype !== null)
+        throw invalid(`${path} must be a plain object.`, path);
+    return value;
+}
+function invalid(message, path) {
+    return new HonuaOfflineRegionError("invalid-manifest", message, { path });
+}

package/offline/status.d.ts

@@ -0,0 +1,136 @@
+import type { OfflineEditQueueStateCounts, OfflineQueuedEdit } from "./edit-queue.js";
+import { type OfflineReplaySyncConflictBinding, type OfflineReplaySyncConflictProjectionV1 } from "./replay-conflict.js";
+import { type OfflineRegionDiagnosticV1 } from "./types.js";
+/** Stable discriminator and version for composed local-first status snapshots. */
+export declare const HONUA_LOCAL_FIRST_STATUS_KIND: "honua.local-first-status";
+export declare const HONUA_LOCAL_FIRST_STATUS_VERSION: "1.0";
+/** Conservative ceilings applied before any input array is copied or sorted. */
+export declare const DEFAULT_LOCAL_FIRST_MAX_REGIONS = 1000;
+export declare const DEFAULT_LOCAL_FIRST_MAX_EDITS = 10000;
+export declare const DEFAULT_LOCAL_FIRST_MAX_LISTED_EDIT_IDS = 100;
+/**
+ * Reachability of the data endpoint, decided by the host. The SDK never reads
+ * `navigator.onLine`: link state is not origin reachability, so an `online`
+ * state the SDK cannot verify would be a claim rather than an observation.
+ */
+export type LocalFirstConnectivity = "online" | "offline";
+/** The seven states an application renders for a local-first workflow. */
+export type LocalFirstState = "online" | "offline" | "stale" | "partial" | "pending" | "conflicted" | "expired";
+/** Stable machine explanation of the headline state. */
+export type LocalFirstStateReason = "conflicted-edits" | "expired-regions" | "missing-regions" | "partial-regions" | "undelivered-edits" | "stale-regions" | "disconnected" | "connected";
+export type LocalFirstReadAvailability = "live" | "cached" | "unavailable";
+export type LocalFirstFreshness = "fresh" | "stale" | "expired";
+export type LocalFirstCompleteness = "complete" | "partial" | "missing";
+export type LocalFirstWriteState = "idle" | "pending" | "conflicted";
+export type LocalFirstWriteCoverage = "complete" | "sampled";
+type DiagnosticCacheReason = OfflineRegionDiagnosticV1["cache"]["reason"];
+/** Secret-safe projection of one region diagnostic. */
+export interface LocalFirstRegionSummary {
+    readonly regionId: string;
+    readonly sourceId: string;
+    /** Safe to expose; the originating scope fingerprint is never persisted or returned. */
+    readonly authorizationScopeDigest: `sha256:${string}`;
+    readonly state: "offline" | "missing";
+    readonly freshness: LocalFirstFreshness;
+    readonly completeness: LocalFirstCompleteness;
+    readonly reason: DiagnosticCacheReason;
+    readonly readable: boolean;
+    readonly observedAt: string;
+    readonly ageMs: number;
+    readonly expiresAt?: string;
+    readonly pinned: boolean;
+}
+export interface LocalFirstReads {
+    readonly availability: LocalFirstReadAvailability;
+    /** Worst-case across stored regions; `fresh` when nothing is stored. */
+    readonly freshness: LocalFirstFreshness;
+    /** Worst-case across every supplied region; `missing` when none were supplied. */
+    readonly completeness: LocalFirstCompleteness;
+    readonly regionCount: number;
+    readonly storedRegionCount: number;
+    readonly readableRegionCount: number;
+    readonly oldestObservedAt?: string;
+    readonly earliestExpiresAt?: string;
+    readonly regions: readonly LocalFirstRegionSummary[];
+}
+export interface LocalFirstWrites {
+    readonly state: LocalFirstWriteState;
+    /**
+     * `complete` when authoritative queue totals were supplied; `sampled` when
+     * the counts were derived from a bounded `edits` list, which `list` caps at
+     * 100 records without a cursor.
+     */
+    readonly coverage: LocalFirstWriteCoverage;
+    readonly counts: OfflineEditQueueStateCounts;
+    /** `pending`, `leased`, and `retryable` work: local, durable, unacknowledged. */
+    readonly undeliveredCount: number;
+    readonly conflictedCount: number;
+    /** Bounded, code-unit ordered; `conflictedCount` remains the complete total. */
+    readonly conflictedEditIds: readonly `sha256:${string}`[];
+    readonly conflictedEditIdsTruncated: boolean;
+    /**
+     * The same conflicted edits, projected onto the shipped sync-conflict
+     * contracts — one entry per `conflictedEditIds` id, in the same order. Empty
+     * unless `options.replica` supplied a replica binding, because a conflict
+     * cannot be attributed to a replica the SDK never saw. An entry may be a
+     * typed refusal; `conflictedEditIdsTruncated` still governs completeness.
+     */
+    readonly syncConflicts: readonly OfflineReplaySyncConflictProjectionV1[];
+    readonly nextRetryAt?: string;
+    readonly oldestUndeliveredAt?: string;
+}
+/** Versioned, immutable, payload-free explanation of one local-first workflow. */
+export interface LocalFirstStatusV1 {
+    readonly kind: typeof HONUA_LOCAL_FIRST_STATUS_KIND;
+    readonly version: typeof HONUA_LOCAL_FIRST_STATUS_VERSION;
+    readonly generatedAt: string;
+    readonly state: LocalFirstState;
+    readonly reason: LocalFirstStateReason;
+    readonly connectivity: LocalFirstConnectivity;
+    readonly reads: LocalFirstReads;
+    readonly writes: LocalFirstWrites;
+}
+/** Caller limits can tighten, but never raise, the SDK's conservative ceilings. */
+export interface LocalFirstStatusLimits {
+    readonly maxRegions?: number;
+    readonly maxEdits?: number;
+    readonly maxListedEditIds?: number;
+}
+export interface CreateLocalFirstStatusOptions {
+    /** Host-owned reachability decision; the SDK never infers it. */
+    readonly connectivity: LocalFirstConnectivity;
+    /** Explicit clock input so a persisted status stays reproducible. */
+    readonly now: Date;
+    readonly regions?: readonly OfflineRegionDiagnosticV1[];
+    /**
+     * Bounded detail sample used for conflicted identities and timing. `list`
+     * caps at 100 records with no cursor, so supply `editCounts` whenever a
+     * partition can hold more work than the sample can show.
+     */
+    readonly edits?: readonly OfflineQueuedEdit[];
+    /** Authoritative partition totals from `OfflineEditQueue.countByState`. */
+    readonly editCounts?: OfflineEditQueueStateCounts;
+    /**
+     * Replica identity used to project conflicted edits onto the shipped
+     * sync-conflict contracts. Omit it and `writes.syncConflicts` stays empty;
+     * nothing else about the status changes either way.
+     */
+    readonly replica?: OfflineReplaySyncConflictBinding;
+    readonly limits?: LocalFirstStatusLimits;
+}
+/**
+ * Compose one local-first status from region diagnostics, durable queue state,
+ * and a host-supplied connectivity signal.
+ *
+ * The headline `state` is decided by a total precedence over cache and queue
+ * facets, with connectivity supplying only the base case:
+ *
+ * `conflicted` > `expired` > `partial` > `pending` > `stale` > `offline` > `online`
+ *
+ * Data problems therefore outrank undelivered work, which outranks mere
+ * staleness, which outranks being disconnected. Reads no payload bytes,
+ * performs no network or storage I/O, and mutates nothing.
+ */
+export declare function createLocalFirstStatus(options: CreateLocalFirstStatusOptions): LocalFirstStatusV1;
+export {};
+//# sourceMappingURL=status.d.ts.map

package/offline/status.d.ts.map

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