kaafil-js 0.1.0 → 0.2.0

package/dist/client-entry.d.cts

@@ -1036,36 +1036,10 @@ declare function createDrainer(options: CreateDrainerOptions): Drainer;
 /** Every section the vendored spec can send. */
 declare const SYNC_PULL_SECTIONS: readonly ["rooming", "stayWindows", "pickups", "seating", "bookings", "expenses", "checklist", "float", "collections", "itinerary", "closeout"];
 type SyncPullSection = (typeof SYNC_PULL_SECTIONS)[number];
-/**
- * Pulls the row array out of one section's `data`, which the spec types as
- * `unknown` — it is "the `data` half of that endpoint's envelope, verbatim",
- * and those envelopes differ per list.
- *
- * NEVER GUESSES. An array of identified rows is taken as-is; an object with
- * EXACTLY ONE array-valued property whose elements carry `id` is taken from
- * that property. Zero such properties, or two, and this returns `undefined`,
- * which the caller treats exactly like an absent section: rows untouched,
- * cursor untouched. Picking the likelier of two arrays would be a silent
- * wrong answer, and the failure mode of a silent wrong answer here is a
- * manager's screen showing the wrong list.
- *
- * TWO ARRAYS IS USUALLY NOT AMBIGUITY — IT IS ONE FEED PLUS A PROJECTION.
- * `rooming` is the worked example. `RoomingBoardResponse` carries three
- * arrays, and only `rooms[]` is delta-shaped: its items are `anyOf` a live
- * row (`id`/`version`/`updatedAt`) or a tombstone (`_tombstone`/`id`/
- * `version`/`deletedAt`). `windows[]` and `unassigned[]` are plain objects
- * keyed on `stayWindowId`/`travellerId`, with no tombstone branch and no
- * version — they are DERIVED projections the engine recomputes per read
- * (`windows[]` carries `assignedCount`/`roomCount`; `unassigned[]` carries
- * `assignSource`). So this function selecting `rooms[]` alone is the correct
- * answer here, not a limitation to route around: caching `unassigned[]` as
- * delta rows would be a real bug, because no tombstone can ever arrive for a
- * traveller who GETS a bed, and `applyPull` rebases by id rather than
- * replacing — the cached pool would grow monotonically and never shrink.
- * A consumer that needs a derived projection reads it live from its own
- * resource call; it is not cache-first data and must not be made to look so.
- */
-declare function extractSectionRows(data: unknown): readonly DeltaRow<SnapshotRow>[] | undefined;
+declare function extractSectionRows(data: unknown, 
+/** The section this `data` came from, when the caller knows it. An external
+ * caller inspecting an arbitrary payload omits it and gets the heuristic. */
+section?: SyncPullSection): readonly DeltaRow<SnapshotRow>[] | undefined;
 interface PullTripResult {
     readonly tripRef: string;
     /** The cursor now stored for every section that was PRESENT: this
@@ -1107,6 +1081,92 @@ declare function createPullCoordinator(options: {
     readonly onServerTime?: (serverTime: string) => void;
 }): PullCoordinator;
 
+/**
+ * The THIRD half of the local store: last-known-good whole responses for
+ * reads that are not delta lists.
+ *
+ * ── WHY THIS IS NOT THE SNAPSHOT STORE ────────────────────────────────────
+ *
+ * `./snapshot.ts` merges by `id` + `version`, in both directions, and that
+ * guarantee is the reason it is safe. It can only hold rows that genuinely
+ * carry a `DeltaIdentity`, because a fabricated `version` turns a
+ * version-guarded merge into a coin toss: the same row written twice either
+ * silently wins or silently loses depending on a number that means nothing.
+ *
+ * Some reads this SDK exposes are not delta lists and never will be.
+ * `GET /manager/me/trips` is the motivating one — its rows carry a
+ * `tripRef`, a name and a status, but no `id` and no `version`, because it
+ * is a projection of the caller's assignments rather than a table. It has no
+ * `?since=` window, no tombstones, and no per-row identity to merge on. It
+ * is a whole answer or it is nothing.
+ *
+ * Forcing such a response through the snapshot store would mean inventing
+ * the identity that makes the snapshot store correct. So it gets its own
+ * lane instead, with a deliberately smaller promise.
+ *
+ * ── THE PROMISE, AND ITS LIMITS ───────────────────────────────────────────
+ *
+ * Exactly one thing: **the last response that actually landed, and when the
+ * SERVER said that was.** Whole-value replace, last writer wins, no merge,
+ * no cursor, no tombstones, no events.
+ *
+ * That is enough for the case it exists for — a field surface that must
+ * paint what it last knew rather than blank when the read cannot be made —
+ * and it is deliberately not enough to build a sync lane on. Anything with a
+ * per-row identity and a delta window belongs in the snapshot store, and
+ * putting it here instead would lose rows the moment two writers overlap.
+ *
+ * `syncedAt` is the response's own `meta.serverTime` and there is no setter
+ * that takes anything else, for the same reason `applyPull` has none: a
+ * device clock would make "as of 14:02" a lie on exactly the devices whose
+ * clocks are worst.
+ *
+ * Keys are opaque to this module and chosen by the caller. They are
+ * namespaced under the engine's credential scope by `keyPrefix`, so one
+ * manager's cached answer can never be read under another's session.
+ */
+
+/** One cached response, as it sits on disk. */
+interface CachedRead<T = unknown> {
+    readonly value: T;
+    /** The `meta.serverTime` of the response this came from — never a device
+     * clock. */
+    readonly syncedAt: string;
+}
+interface ReadCacheStore {
+    /**
+     * The last response that landed for this key, or `undefined` if none ever
+     * has. Resolves from memory once `load()` has run — a first paint must not
+     * wait on a disk read it already did.
+     *
+     * The value is returned as it was stored. This module does not know the
+     * shape and does not validate it: a caller that changes what it puts under
+     * a key is responsible for tolerating the old shape, exactly as it would
+     * be for anything else that outlives a deploy.
+     */
+    get<T>(key: string): CachedRead<T> | undefined;
+    /**
+     * Replaces the value under `key` wholesale.
+     *
+     * `serverTime` MUST be the `meta.serverTime` of the response `value` came
+     * in. There is no overload that omits it, because a cached read whose age
+     * is unknown is worse than no cached read: a surface will render it with
+     * confidence.
+     */
+    set(key: string, value: unknown, serverTime: string): Promise<void>;
+    /** Drops one key. Nothing in this SDK calls it; it exists so a host that
+     * caches something sensitive can stop. */
+    purge(key: string): Promise<void>;
+    /** Hydrates from the durable adapter. Call once, before first paint. */
+    load(): Promise<void>;
+}
+interface CreateReadCacheStoreOptions {
+    readonly storage: KaafilStorageAdapter;
+    /** Namespacing key prefix, already credential-scoped by the engine. */
+    readonly keyPrefix: string;
+}
+declare function createReadCacheStore(options: CreateReadCacheStoreOptions): ReadCacheStore;
+
 /**
  * Share-token offline: local expiry enforcement, reconnect re-validation, the
  * minimal write set, and the 7-day post-expiry grace.
@@ -1264,6 +1324,12 @@ interface EnqueueWithBlobOptions extends EnqueueWriteOptions {
 interface OfflineEngine {
     readonly events: OfflineEvents;
     readonly snapshot: SnapshotStore;
+    /**
+     * Last-known-good whole responses for reads that are NOT delta lists —
+     * see `./reads.ts` for why those cannot live in `snapshot`. Durable and
+     * credential-scoped like every other store here.
+     */
+    readonly reads: ReadCacheStore;
     readonly outbox: Outbox;
     readonly drainer: Drainer;
     readonly pull: PullCoordinator;
@@ -2720,4 +2786,4 @@ declare class KaafilClient {
     static newIdempotencyKey(): string;
 }
 
-export { AgenciesResource, AgencyAdminMeResource, AgencyAdminRefreshResult, type ApplyPullResult, BATCH_THRESHOLD_OPS, type BlobBackfill, type BlobBytes, type BlobDrainReport, type BlobLane, type BlobRecord, type BlobSource, BlobStatus, type BlobUploader, BookingsResource, type BoundAgenciesResource, type BoundChecklistsResource, type BoundCreateAgencyChecklistTemplateOptions, type BoundCreateFormOptions, type BoundCreateTravellerOptions, type BoundCreateVendorOptions, type BoundDeleteAgencyChecklistTemplateOptions, type BoundDeleteVendorOptions, type BoundFeedbackNpsResource, type BoundFormsResource, type BoundGetAgencyManagerProfileOptions, type BoundGetAgencyTripOptions, type BoundGetTravellerAgencyProfileOptions, type BoundJourneyResource, type BoundListAgencyChecklistTemplatesOptions, type BoundListAgencyManagersOptions, type BoundListAgencyManagersPageOptions, type BoundListAgencyTripsOptions, type BoundListAgencyTripsPageOptions, type BoundListForAgencyOptions, type BoundListForAgencyPageOptions, type BoundListFormsOptions, type BoundListJourneyTriggersOptions, type BoundListTripManifestOptions, type BoundListTripManifestPageOptions, type BoundPatchAgencyChecklistTemplateOptions, type BoundPatchAgencySettingsOptions, type BoundPatchJourneyTriggerOptions, type BoundPublishAgencyChecklistTemplateOptions, type BoundReadAgencyFeedbackSummaryOptions, type BoundReadAgencySettingsOptions, type BoundTravellersResource, type BoundUpsertVendorOptions, type BoundVendorsResource, CONSOLIDATED_PULL_THRESHOLD_LISTS, ChecklistsResource, CloseoutResource, CollectionsResource, type CompressImageOptions, type CompressedImage, CompressionOutcome, type ConflictContext, type ConflictResolution, type ConflictResolver, CreateAgencyChecklistTemplateOptions, type CreateDrainerOptions, CreateFormOptions, type CreateOfflineEngineOptions, type CreateOutboxOptions, CreateTravellerOptions, CreateVendorOptions, DeleteAgencyChecklistTemplateOptions, DeleteVendorOptions, DeltaIdentity, DeltaMergeStats, DeltaRow, type DrainOptions, type DrainReport, type Drainer, type EnqueueOptions, type EnqueueWithBlobOptions, type EnqueueWriteOptions, type EntityReadResult, type EntityReader, Environment, ExpensesResource, FeedbackNpsResource, FilesResource, FloatResource, FormsResource, GetAgencyManagerProfileOptions, GetAgencyTripOptions, GetTravellerAgencyProfileOptions, type IndexedDbStorageAdapterOptions, ItineraryResource, JourneyResource, KaafilClient, KaafilClientAlreadyOpenError, KaafilClientNotOpenError, type KaafilClientOptions, KaafilError, KaafilErrorCode, KaafilIndexedDbUnavailableError, KaafilResponse, KaafilShareLinkExpiredError, type KaafilStorageAdapter, ListAgencyChecklistTemplatesOptions, ListAgencyManagersOptions, ListAgencyManagersPageOptions, ListAgencyTripsOptions, ListAgencyTripsPageOptions, ListForAgencyOptions, ListForAgencyPageOptions, ListFormsOptions, type ListManagerExpensesOptions, type ListManagerNotificationsOptions, type ListOwnManagerTripsOptions, type ListShareFormsOptions, ListTripManifestOptions, ListTripManifestPageOptions, type LosslessImageOptions, MAX_BATCH_OPS, type ManagerExpenseFilters, type ManagerExpensesResource, type ManagerMeResource, type ManagerOwnTrip, type ManagerOwnTripsResponse, ManagerRefreshResult, ManagerTodayResource, type MarkNotificationReadOptions, type MonotonicClock, type NotificationsResource, type OfflineEngine, type OfflineEventHandler, type OfflineEventMap, type OfflineEventName, type OfflineEvents, type OfflineTransport, type OpOutcome, type OpenAgencyAdminSessionOptions, type OpenManagerSessionOptions, type OpenOfflineOptions, type OpenShareTokenOptions, type Outbox, type OutboxCounts, type OutboxEntityRef, type OutboxOp, type OutboxParkReason, OutboxRetryCause, OutboxStatus, PatchAgencyChecklistTemplateOptions, PatchAgencySettingsOptions, PickupsResource, PublishAgencyChecklistTemplateOptions, type PullCoordinator, type PullResult, type PullSection, type PullTripResult, ReadAgencyFeedbackSummaryOptions, ReadAgencySettingsOptions, type ReadManagerExpenseLogMetaOptions, type ReadManagerExpenseOptions, type ReadShareFormOptions, type ReadShareManifestOptions, type ReadShareSnapshotOptions, type ReconcileOutcome, Resolvable, RoomingResource, SHARE_WRITE_GRACE_MS, SYNC_PULL_SECTIONS, type SaveShareFormOptions, SeatingResource, type ShareFormsResource, type ShareGuard, type ShareInvalidatedEvent, type ShareResource, ShareTokensResource, type SnapshotList, type SnapshotRow, type SnapshotStore, type SnapshotUpdatedEvent, type SubmitShareFormOptions, type SyncDrainedEvent, type SyncErrorEvent, SyncOpMethod, type SyncPullSection, SyncResource, TravellersResource, TreksResource, TripsResource, type Unsubscribe, UpsertVendorOptions, VendorsResource, compressImage, convertImageLossless, createBlobLane, createDrainer, createHttpOfflineTransport, createInMemoryStorageAdapter, createIndexedDbStorageAdapter, createOfflineEngine, createOfflineEvents, createOutbox, createPullCoordinator, createShareGuard, createSnapshotStore, extractSectionRows, isCompressibleType, isImageCompressionSupported, readCurrentVersion, reconcileConflict, scaledDimensions, shouldUseBatchTransport };
+export { AgenciesResource, AgencyAdminMeResource, AgencyAdminRefreshResult, type ApplyPullResult, BATCH_THRESHOLD_OPS, type BlobBackfill, type BlobBytes, type BlobDrainReport, type BlobLane, type BlobRecord, type BlobSource, BlobStatus, type BlobUploader, BookingsResource, type BoundAgenciesResource, type BoundChecklistsResource, type BoundCreateAgencyChecklistTemplateOptions, type BoundCreateFormOptions, type BoundCreateTravellerOptions, type BoundCreateVendorOptions, type BoundDeleteAgencyChecklistTemplateOptions, type BoundDeleteVendorOptions, type BoundFeedbackNpsResource, type BoundFormsResource, type BoundGetAgencyManagerProfileOptions, type BoundGetAgencyTripOptions, type BoundGetTravellerAgencyProfileOptions, type BoundJourneyResource, type BoundListAgencyChecklistTemplatesOptions, type BoundListAgencyManagersOptions, type BoundListAgencyManagersPageOptions, type BoundListAgencyTripsOptions, type BoundListAgencyTripsPageOptions, type BoundListForAgencyOptions, type BoundListForAgencyPageOptions, type BoundListFormsOptions, type BoundListJourneyTriggersOptions, type BoundListTripManifestOptions, type BoundListTripManifestPageOptions, type BoundPatchAgencyChecklistTemplateOptions, type BoundPatchAgencySettingsOptions, type BoundPatchJourneyTriggerOptions, type BoundPublishAgencyChecklistTemplateOptions, type BoundReadAgencyFeedbackSummaryOptions, type BoundReadAgencySettingsOptions, type BoundTravellersResource, type BoundUpsertVendorOptions, type BoundVendorsResource, CONSOLIDATED_PULL_THRESHOLD_LISTS, type CachedRead, ChecklistsResource, CloseoutResource, CollectionsResource, type CompressImageOptions, type CompressedImage, CompressionOutcome, type ConflictContext, type ConflictResolution, type ConflictResolver, CreateAgencyChecklistTemplateOptions, type CreateDrainerOptions, CreateFormOptions, type CreateOfflineEngineOptions, type CreateOutboxOptions, type CreateReadCacheStoreOptions, CreateTravellerOptions, CreateVendorOptions, DeleteAgencyChecklistTemplateOptions, DeleteVendorOptions, DeltaIdentity, DeltaMergeStats, DeltaRow, type DrainOptions, type DrainReport, type Drainer, type EnqueueOptions, type EnqueueWithBlobOptions, type EnqueueWriteOptions, type EntityReadResult, type EntityReader, Environment, ExpensesResource, FeedbackNpsResource, FilesResource, FloatResource, FormsResource, GetAgencyManagerProfileOptions, GetAgencyTripOptions, GetTravellerAgencyProfileOptions, type IndexedDbStorageAdapterOptions, ItineraryResource, JourneyResource, KaafilClient, KaafilClientAlreadyOpenError, KaafilClientNotOpenError, type KaafilClientOptions, KaafilError, KaafilErrorCode, KaafilIndexedDbUnavailableError, KaafilResponse, KaafilShareLinkExpiredError, type KaafilStorageAdapter, ListAgencyChecklistTemplatesOptions, ListAgencyManagersOptions, ListAgencyManagersPageOptions, ListAgencyTripsOptions, ListAgencyTripsPageOptions, ListForAgencyOptions, ListForAgencyPageOptions, ListFormsOptions, type ListManagerExpensesOptions, type ListManagerNotificationsOptions, type ListOwnManagerTripsOptions, type ListShareFormsOptions, ListTripManifestOptions, ListTripManifestPageOptions, type LosslessImageOptions, MAX_BATCH_OPS, type ManagerExpenseFilters, type ManagerExpensesResource, type ManagerMeResource, type ManagerOwnTrip, type ManagerOwnTripsResponse, ManagerRefreshResult, ManagerTodayResource, type MarkNotificationReadOptions, type MonotonicClock, type NotificationsResource, type OfflineEngine, type OfflineEventHandler, type OfflineEventMap, type OfflineEventName, type OfflineEvents, type OfflineTransport, type OpOutcome, type OpenAgencyAdminSessionOptions, type OpenManagerSessionOptions, type OpenOfflineOptions, type OpenShareTokenOptions, type Outbox, type OutboxCounts, type OutboxEntityRef, type OutboxOp, type OutboxParkReason, OutboxRetryCause, OutboxStatus, PatchAgencyChecklistTemplateOptions, PatchAgencySettingsOptions, PickupsResource, PublishAgencyChecklistTemplateOptions, type PullCoordinator, type PullResult, type PullSection, type PullTripResult, ReadAgencyFeedbackSummaryOptions, ReadAgencySettingsOptions, type ReadCacheStore, type ReadManagerExpenseLogMetaOptions, type ReadManagerExpenseOptions, type ReadShareFormOptions, type ReadShareManifestOptions, type ReadShareSnapshotOptions, type ReconcileOutcome, Resolvable, RoomingResource, SHARE_WRITE_GRACE_MS, SYNC_PULL_SECTIONS, type SaveShareFormOptions, SeatingResource, type ShareFormsResource, type ShareGuard, type ShareInvalidatedEvent, type ShareResource, ShareTokensResource, type SnapshotList, type SnapshotRow, type SnapshotStore, type SnapshotUpdatedEvent, type SubmitShareFormOptions, type SyncDrainedEvent, type SyncErrorEvent, SyncOpMethod, type SyncPullSection, SyncResource, TravellersResource, TreksResource, TripsResource, type Unsubscribe, UpsertVendorOptions, VendorsResource, compressImage, convertImageLossless, createBlobLane, createDrainer, createHttpOfflineTransport, createInMemoryStorageAdapter, createIndexedDbStorageAdapter, createOfflineEngine, createOfflineEvents, createOutbox, createPullCoordinator, createReadCacheStore, createShareGuard, createSnapshotStore, extractSectionRows, isCompressibleType, isImageCompressionSupported, readCurrentVersion, reconcileConflict, scaledDimensions, shouldUseBatchTransport };

package/dist/client-entry.d.ts

@@ -1036,36 +1036,10 @@ declare function createDrainer(options: CreateDrainerOptions): Drainer;
 /** Every section the vendored spec can send. */
 declare const SYNC_PULL_SECTIONS: readonly ["rooming", "stayWindows", "pickups", "seating", "bookings", "expenses", "checklist", "float", "collections", "itinerary", "closeout"];
 type SyncPullSection = (typeof SYNC_PULL_SECTIONS)[number];
-/**
- * Pulls the row array out of one section's `data`, which the spec types as
- * `unknown` — it is "the `data` half of that endpoint's envelope, verbatim",
- * and those envelopes differ per list.
- *
- * NEVER GUESSES. An array of identified rows is taken as-is; an object with
- * EXACTLY ONE array-valued property whose elements carry `id` is taken from
- * that property. Zero such properties, or two, and this returns `undefined`,
- * which the caller treats exactly like an absent section: rows untouched,
- * cursor untouched. Picking the likelier of two arrays would be a silent
- * wrong answer, and the failure mode of a silent wrong answer here is a
- * manager's screen showing the wrong list.
- *
- * TWO ARRAYS IS USUALLY NOT AMBIGUITY — IT IS ONE FEED PLUS A PROJECTION.
- * `rooming` is the worked example. `RoomingBoardResponse` carries three
- * arrays, and only `rooms[]` is delta-shaped: its items are `anyOf` a live
- * row (`id`/`version`/`updatedAt`) or a tombstone (`_tombstone`/`id`/
- * `version`/`deletedAt`). `windows[]` and `unassigned[]` are plain objects
- * keyed on `stayWindowId`/`travellerId`, with no tombstone branch and no
- * version — they are DERIVED projections the engine recomputes per read
- * (`windows[]` carries `assignedCount`/`roomCount`; `unassigned[]` carries
- * `assignSource`). So this function selecting `rooms[]` alone is the correct
- * answer here, not a limitation to route around: caching `unassigned[]` as
- * delta rows would be a real bug, because no tombstone can ever arrive for a
- * traveller who GETS a bed, and `applyPull` rebases by id rather than
- * replacing — the cached pool would grow monotonically and never shrink.
- * A consumer that needs a derived projection reads it live from its own
- * resource call; it is not cache-first data and must not be made to look so.
- */
-declare function extractSectionRows(data: unknown): readonly DeltaRow<SnapshotRow>[] | undefined;
+declare function extractSectionRows(data: unknown, 
+/** The section this `data` came from, when the caller knows it. An external
+ * caller inspecting an arbitrary payload omits it and gets the heuristic. */
+section?: SyncPullSection): readonly DeltaRow<SnapshotRow>[] | undefined;
 interface PullTripResult {
     readonly tripRef: string;
     /** The cursor now stored for every section that was PRESENT: this
@@ -1107,6 +1081,92 @@ declare function createPullCoordinator(options: {
     readonly onServerTime?: (serverTime: string) => void;
 }): PullCoordinator;
 
+/**
+ * The THIRD half of the local store: last-known-good whole responses for
+ * reads that are not delta lists.
+ *
+ * ── WHY THIS IS NOT THE SNAPSHOT STORE ────────────────────────────────────
+ *
+ * `./snapshot.ts` merges by `id` + `version`, in both directions, and that
+ * guarantee is the reason it is safe. It can only hold rows that genuinely
+ * carry a `DeltaIdentity`, because a fabricated `version` turns a
+ * version-guarded merge into a coin toss: the same row written twice either
+ * silently wins or silently loses depending on a number that means nothing.
+ *
+ * Some reads this SDK exposes are not delta lists and never will be.
+ * `GET /manager/me/trips` is the motivating one — its rows carry a
+ * `tripRef`, a name and a status, but no `id` and no `version`, because it
+ * is a projection of the caller's assignments rather than a table. It has no
+ * `?since=` window, no tombstones, and no per-row identity to merge on. It
+ * is a whole answer or it is nothing.
+ *
+ * Forcing such a response through the snapshot store would mean inventing
+ * the identity that makes the snapshot store correct. So it gets its own
+ * lane instead, with a deliberately smaller promise.
+ *
+ * ── THE PROMISE, AND ITS LIMITS ───────────────────────────────────────────
+ *
+ * Exactly one thing: **the last response that actually landed, and when the
+ * SERVER said that was.** Whole-value replace, last writer wins, no merge,
+ * no cursor, no tombstones, no events.
+ *
+ * That is enough for the case it exists for — a field surface that must
+ * paint what it last knew rather than blank when the read cannot be made —
+ * and it is deliberately not enough to build a sync lane on. Anything with a
+ * per-row identity and a delta window belongs in the snapshot store, and
+ * putting it here instead would lose rows the moment two writers overlap.
+ *
+ * `syncedAt` is the response's own `meta.serverTime` and there is no setter
+ * that takes anything else, for the same reason `applyPull` has none: a
+ * device clock would make "as of 14:02" a lie on exactly the devices whose
+ * clocks are worst.
+ *
+ * Keys are opaque to this module and chosen by the caller. They are
+ * namespaced under the engine's credential scope by `keyPrefix`, so one
+ * manager's cached answer can never be read under another's session.
+ */
+
+/** One cached response, as it sits on disk. */
+interface CachedRead<T = unknown> {
+    readonly value: T;
+    /** The `meta.serverTime` of the response this came from — never a device
+     * clock. */
+    readonly syncedAt: string;
+}
+interface ReadCacheStore {
+    /**
+     * The last response that landed for this key, or `undefined` if none ever
+     * has. Resolves from memory once `load()` has run — a first paint must not
+     * wait on a disk read it already did.
+     *
+     * The value is returned as it was stored. This module does not know the
+     * shape and does not validate it: a caller that changes what it puts under
+     * a key is responsible for tolerating the old shape, exactly as it would
+     * be for anything else that outlives a deploy.
+     */
+    get<T>(key: string): CachedRead<T> | undefined;
+    /**
+     * Replaces the value under `key` wholesale.
+     *
+     * `serverTime` MUST be the `meta.serverTime` of the response `value` came
+     * in. There is no overload that omits it, because a cached read whose age
+     * is unknown is worse than no cached read: a surface will render it with
+     * confidence.
+     */
+    set(key: string, value: unknown, serverTime: string): Promise<void>;
+    /** Drops one key. Nothing in this SDK calls it; it exists so a host that
+     * caches something sensitive can stop. */
+    purge(key: string): Promise<void>;
+    /** Hydrates from the durable adapter. Call once, before first paint. */
+    load(): Promise<void>;
+}
+interface CreateReadCacheStoreOptions {
+    readonly storage: KaafilStorageAdapter;
+    /** Namespacing key prefix, already credential-scoped by the engine. */
+    readonly keyPrefix: string;
+}
+declare function createReadCacheStore(options: CreateReadCacheStoreOptions): ReadCacheStore;
+
 /**
  * Share-token offline: local expiry enforcement, reconnect re-validation, the
  * minimal write set, and the 7-day post-expiry grace.
@@ -1264,6 +1324,12 @@ interface EnqueueWithBlobOptions extends EnqueueWriteOptions {
 interface OfflineEngine {
     readonly events: OfflineEvents;
     readonly snapshot: SnapshotStore;
+    /**
+     * Last-known-good whole responses for reads that are NOT delta lists —
+     * see `./reads.ts` for why those cannot live in `snapshot`. Durable and
+     * credential-scoped like every other store here.
+     */
+    readonly reads: ReadCacheStore;
     readonly outbox: Outbox;
     readonly drainer: Drainer;
     readonly pull: PullCoordinator;
@@ -2720,4 +2786,4 @@ declare class KaafilClient {
     static newIdempotencyKey(): string;
 }
 
-export { AgenciesResource, AgencyAdminMeResource, AgencyAdminRefreshResult, type ApplyPullResult, BATCH_THRESHOLD_OPS, type BlobBackfill, type BlobBytes, type BlobDrainReport, type BlobLane, type BlobRecord, type BlobSource, BlobStatus, type BlobUploader, BookingsResource, type BoundAgenciesResource, type BoundChecklistsResource, type BoundCreateAgencyChecklistTemplateOptions, type BoundCreateFormOptions, type BoundCreateTravellerOptions, type BoundCreateVendorOptions, type BoundDeleteAgencyChecklistTemplateOptions, type BoundDeleteVendorOptions, type BoundFeedbackNpsResource, type BoundFormsResource, type BoundGetAgencyManagerProfileOptions, type BoundGetAgencyTripOptions, type BoundGetTravellerAgencyProfileOptions, type BoundJourneyResource, type BoundListAgencyChecklistTemplatesOptions, type BoundListAgencyManagersOptions, type BoundListAgencyManagersPageOptions, type BoundListAgencyTripsOptions, type BoundListAgencyTripsPageOptions, type BoundListForAgencyOptions, type BoundListForAgencyPageOptions, type BoundListFormsOptions, type BoundListJourneyTriggersOptions, type BoundListTripManifestOptions, type BoundListTripManifestPageOptions, type BoundPatchAgencyChecklistTemplateOptions, type BoundPatchAgencySettingsOptions, type BoundPatchJourneyTriggerOptions, type BoundPublishAgencyChecklistTemplateOptions, type BoundReadAgencyFeedbackSummaryOptions, type BoundReadAgencySettingsOptions, type BoundTravellersResource, type BoundUpsertVendorOptions, type BoundVendorsResource, CONSOLIDATED_PULL_THRESHOLD_LISTS, ChecklistsResource, CloseoutResource, CollectionsResource, type CompressImageOptions, type CompressedImage, CompressionOutcome, type ConflictContext, type ConflictResolution, type ConflictResolver, CreateAgencyChecklistTemplateOptions, type CreateDrainerOptions, CreateFormOptions, type CreateOfflineEngineOptions, type CreateOutboxOptions, CreateTravellerOptions, CreateVendorOptions, DeleteAgencyChecklistTemplateOptions, DeleteVendorOptions, DeltaIdentity, DeltaMergeStats, DeltaRow, type DrainOptions, type DrainReport, type Drainer, type EnqueueOptions, type EnqueueWithBlobOptions, type EnqueueWriteOptions, type EntityReadResult, type EntityReader, Environment, ExpensesResource, FeedbackNpsResource, FilesResource, FloatResource, FormsResource, GetAgencyManagerProfileOptions, GetAgencyTripOptions, GetTravellerAgencyProfileOptions, type IndexedDbStorageAdapterOptions, ItineraryResource, JourneyResource, KaafilClient, KaafilClientAlreadyOpenError, KaafilClientNotOpenError, type KaafilClientOptions, KaafilError, KaafilErrorCode, KaafilIndexedDbUnavailableError, KaafilResponse, KaafilShareLinkExpiredError, type KaafilStorageAdapter, ListAgencyChecklistTemplatesOptions, ListAgencyManagersOptions, ListAgencyManagersPageOptions, ListAgencyTripsOptions, ListAgencyTripsPageOptions, ListForAgencyOptions, ListForAgencyPageOptions, ListFormsOptions, type ListManagerExpensesOptions, type ListManagerNotificationsOptions, type ListOwnManagerTripsOptions, type ListShareFormsOptions, ListTripManifestOptions, ListTripManifestPageOptions, type LosslessImageOptions, MAX_BATCH_OPS, type ManagerExpenseFilters, type ManagerExpensesResource, type ManagerMeResource, type ManagerOwnTrip, type ManagerOwnTripsResponse, ManagerRefreshResult, ManagerTodayResource, type MarkNotificationReadOptions, type MonotonicClock, type NotificationsResource, type OfflineEngine, type OfflineEventHandler, type OfflineEventMap, type OfflineEventName, type OfflineEvents, type OfflineTransport, type OpOutcome, type OpenAgencyAdminSessionOptions, type OpenManagerSessionOptions, type OpenOfflineOptions, type OpenShareTokenOptions, type Outbox, type OutboxCounts, type OutboxEntityRef, type OutboxOp, type OutboxParkReason, OutboxRetryCause, OutboxStatus, PatchAgencyChecklistTemplateOptions, PatchAgencySettingsOptions, PickupsResource, PublishAgencyChecklistTemplateOptions, type PullCoordinator, type PullResult, type PullSection, type PullTripResult, ReadAgencyFeedbackSummaryOptions, ReadAgencySettingsOptions, type ReadManagerExpenseLogMetaOptions, type ReadManagerExpenseOptions, type ReadShareFormOptions, type ReadShareManifestOptions, type ReadShareSnapshotOptions, type ReconcileOutcome, Resolvable, RoomingResource, SHARE_WRITE_GRACE_MS, SYNC_PULL_SECTIONS, type SaveShareFormOptions, SeatingResource, type ShareFormsResource, type ShareGuard, type ShareInvalidatedEvent, type ShareResource, ShareTokensResource, type SnapshotList, type SnapshotRow, type SnapshotStore, type SnapshotUpdatedEvent, type SubmitShareFormOptions, type SyncDrainedEvent, type SyncErrorEvent, SyncOpMethod, type SyncPullSection, SyncResource, TravellersResource, TreksResource, TripsResource, type Unsubscribe, UpsertVendorOptions, VendorsResource, compressImage, convertImageLossless, createBlobLane, createDrainer, createHttpOfflineTransport, createInMemoryStorageAdapter, createIndexedDbStorageAdapter, createOfflineEngine, createOfflineEvents, createOutbox, createPullCoordinator, createShareGuard, createSnapshotStore, extractSectionRows, isCompressibleType, isImageCompressionSupported, readCurrentVersion, reconcileConflict, scaledDimensions, shouldUseBatchTransport };
+export { AgenciesResource, AgencyAdminMeResource, AgencyAdminRefreshResult, type ApplyPullResult, BATCH_THRESHOLD_OPS, type BlobBackfill, type BlobBytes, type BlobDrainReport, type BlobLane, type BlobRecord, type BlobSource, BlobStatus, type BlobUploader, BookingsResource, type BoundAgenciesResource, type BoundChecklistsResource, type BoundCreateAgencyChecklistTemplateOptions, type BoundCreateFormOptions, type BoundCreateTravellerOptions, type BoundCreateVendorOptions, type BoundDeleteAgencyChecklistTemplateOptions, type BoundDeleteVendorOptions, type BoundFeedbackNpsResource, type BoundFormsResource, type BoundGetAgencyManagerProfileOptions, type BoundGetAgencyTripOptions, type BoundGetTravellerAgencyProfileOptions, type BoundJourneyResource, type BoundListAgencyChecklistTemplatesOptions, type BoundListAgencyManagersOptions, type BoundListAgencyManagersPageOptions, type BoundListAgencyTripsOptions, type BoundListAgencyTripsPageOptions, type BoundListForAgencyOptions, type BoundListForAgencyPageOptions, type BoundListFormsOptions, type BoundListJourneyTriggersOptions, type BoundListTripManifestOptions, type BoundListTripManifestPageOptions, type BoundPatchAgencyChecklistTemplateOptions, type BoundPatchAgencySettingsOptions, type BoundPatchJourneyTriggerOptions, type BoundPublishAgencyChecklistTemplateOptions, type BoundReadAgencyFeedbackSummaryOptions, type BoundReadAgencySettingsOptions, type BoundTravellersResource, type BoundUpsertVendorOptions, type BoundVendorsResource, CONSOLIDATED_PULL_THRESHOLD_LISTS, type CachedRead, ChecklistsResource, CloseoutResource, CollectionsResource, type CompressImageOptions, type CompressedImage, CompressionOutcome, type ConflictContext, type ConflictResolution, type ConflictResolver, CreateAgencyChecklistTemplateOptions, type CreateDrainerOptions, CreateFormOptions, type CreateOfflineEngineOptions, type CreateOutboxOptions, type CreateReadCacheStoreOptions, CreateTravellerOptions, CreateVendorOptions, DeleteAgencyChecklistTemplateOptions, DeleteVendorOptions, DeltaIdentity, DeltaMergeStats, DeltaRow, type DrainOptions, type DrainReport, type Drainer, type EnqueueOptions, type EnqueueWithBlobOptions, type EnqueueWriteOptions, type EntityReadResult, type EntityReader, Environment, ExpensesResource, FeedbackNpsResource, FilesResource, FloatResource, FormsResource, GetAgencyManagerProfileOptions, GetAgencyTripOptions, GetTravellerAgencyProfileOptions, type IndexedDbStorageAdapterOptions, ItineraryResource, JourneyResource, KaafilClient, KaafilClientAlreadyOpenError, KaafilClientNotOpenError, type KaafilClientOptions, KaafilError, KaafilErrorCode, KaafilIndexedDbUnavailableError, KaafilResponse, KaafilShareLinkExpiredError, type KaafilStorageAdapter, ListAgencyChecklistTemplatesOptions, ListAgencyManagersOptions, ListAgencyManagersPageOptions, ListAgencyTripsOptions, ListAgencyTripsPageOptions, ListForAgencyOptions, ListForAgencyPageOptions, ListFormsOptions, type ListManagerExpensesOptions, type ListManagerNotificationsOptions, type ListOwnManagerTripsOptions, type ListShareFormsOptions, ListTripManifestOptions, ListTripManifestPageOptions, type LosslessImageOptions, MAX_BATCH_OPS, type ManagerExpenseFilters, type ManagerExpensesResource, type ManagerMeResource, type ManagerOwnTrip, type ManagerOwnTripsResponse, ManagerRefreshResult, ManagerTodayResource, type MarkNotificationReadOptions, type MonotonicClock, type NotificationsResource, type OfflineEngine, type OfflineEventHandler, type OfflineEventMap, type OfflineEventName, type OfflineEvents, type OfflineTransport, type OpOutcome, type OpenAgencyAdminSessionOptions, type OpenManagerSessionOptions, type OpenOfflineOptions, type OpenShareTokenOptions, type Outbox, type OutboxCounts, type OutboxEntityRef, type OutboxOp, type OutboxParkReason, OutboxRetryCause, OutboxStatus, PatchAgencyChecklistTemplateOptions, PatchAgencySettingsOptions, PickupsResource, PublishAgencyChecklistTemplateOptions, type PullCoordinator, type PullResult, type PullSection, type PullTripResult, ReadAgencyFeedbackSummaryOptions, ReadAgencySettingsOptions, type ReadCacheStore, type ReadManagerExpenseLogMetaOptions, type ReadManagerExpenseOptions, type ReadShareFormOptions, type ReadShareManifestOptions, type ReadShareSnapshotOptions, type ReconcileOutcome, Resolvable, RoomingResource, SHARE_WRITE_GRACE_MS, SYNC_PULL_SECTIONS, type SaveShareFormOptions, SeatingResource, type ShareFormsResource, type ShareGuard, type ShareInvalidatedEvent, type ShareResource, ShareTokensResource, type SnapshotList, type SnapshotRow, type SnapshotStore, type SnapshotUpdatedEvent, type SubmitShareFormOptions, type SyncDrainedEvent, type SyncErrorEvent, SyncOpMethod, type SyncPullSection, SyncResource, TravellersResource, TreksResource, TripsResource, type Unsubscribe, UpsertVendorOptions, VendorsResource, compressImage, convertImageLossless, createBlobLane, createDrainer, createHttpOfflineTransport, createInMemoryStorageAdapter, createIndexedDbStorageAdapter, createOfflineEngine, createOfflineEvents, createOutbox, createPullCoordinator, createReadCacheStore, createShareGuard, createSnapshotStore, extractSectionRows, isCompressibleType, isImageCompressionSupported, readCurrentVersion, reconcileConflict, scaledDimensions, shouldUseBatchTransport };

package/dist/client-entry.js

@@ -2962,7 +2962,35 @@ var SYNC_PULL_SECTIONS = [
   "itinerary",
   "closeout"
 ];
-function extractSectionRows(data) {
+var SECTION_ROW_KEY = {
+  // Delta-shaped `rooms[]`; `windows[]`/`unassigned[]` are derived
+  // projections — the long note above is still exactly right about this one.
+  rooming: "rooms",
+  // The same decision in the same shape: `vehicles[]` is the feed,
+  // `unassignedPool[]` the projection that must never be cached as rows.
+  seating: "vehicles",
+  expenses: "items",
+  float: "data",
+  // The one that was silently dead. `sections[]` is a grouping projection and
+  // `availableTemplates[]` is agency-level catalogue; `items[]` is the trip's
+  // own entity list and the only one of the three carrying tombstones.
+  checklist: "items",
+  // `days[]` is the day-by-day projection the engine recomputes per read;
+  // `items[]` is the entity list.
+  itinerary: "items",
+  closeout: null
+  // `stayWindows`, `pickups`, `bookings` and `collections` send a top-level
+  // array and never reach this table.
+};
+function extractSectionRows(data, section) {
+  if (section !== void 0 && section in SECTION_ROW_KEY) {
+    const key = SECTION_ROW_KEY[section];
+    if (key === null || key === void 0 || typeof data !== "object" || data === null) {
+      return void 0;
+    }
+    const value = data[key];
+    return Array.isArray(value) && isRowArray(value) ? value : void 0;
+  }
   if (Array.isArray(data)) {
     return isRowArray(data) ? data : void 0;
   }
@@ -3032,7 +3060,7 @@ function createPullCoordinator(options) {
         absent.push(name);
         continue;
       }
-      const rows = extractSectionRows(section.data);
+      const rows = extractSectionRows(section.data, name);
       if (rows === void 0) {
         unmapped.push(name);
         continue;
@@ -3069,6 +3097,49 @@ function createPullCoordinator(options) {
   };
 }
 
+// src/offline/reads.ts
+function createReadCacheStore(options) {
+  const key = `${options.keyPrefix}:reads`;
+  let reads = /* @__PURE__ */ new Map();
+  async function persist() {
+    const shape = { reads: Object.fromEntries(reads) };
+    await options.storage.set(key, JSON.stringify(shape));
+  }
+  return {
+    get(readKey) {
+      return reads.get(readKey);
+    },
+    async set(readKey, value, serverTime) {
+      reads.set(readKey, { value, syncedAt: serverTime });
+      await persist();
+    },
+    async purge(readKey) {
+      if (!reads.delete(readKey)) {
+        return;
+      }
+      await persist();
+    },
+    async load() {
+      reads = /* @__PURE__ */ new Map();
+      const raw = await options.storage.get(key);
+      if (raw === void 0) {
+        return;
+      }
+      let parsed;
+      try {
+        parsed = JSON.parse(raw);
+      } catch {
+        return;
+      }
+      for (const [readKey, entry] of Object.entries(parsed.reads ?? {})) {
+        if (entry !== null && typeof entry === "object" && typeof entry.syncedAt === "string") {
+          reads.set(readKey, entry);
+        }
+      }
+    }
+  };
+}
+
 // src/offline/share.ts
 var SHARE_WRITE_GRACE_MS = 7 * 24 * 60 * 60 * 1e3;
 var KaafilShareLinkExpiredError = class _KaafilShareLinkExpiredError extends Error {
@@ -3443,6 +3514,7 @@ function createOfflineEngine(options) {
     ...options.onEventHandlerError !== void 0 ? { onHandlerError: (error) => options.onEventHandlerError?.(error) } : {}
   });
   const snapshot = createSnapshotStore({ storage: options.storage, keyPrefix });
+  const reads = createReadCacheStore({ storage: options.storage, keyPrefix });
   const outbox = createOutbox({
     storage: options.storage,
     keyPrefix,
@@ -3515,13 +3587,19 @@ function createOfflineEngine(options) {
   return {
     events,
     snapshot,
+    reads,
     outbox,
     drainer,
     pull,
     blobs,
     share,
     async open() {
-      await Promise.all([snapshot.load(), outbox.load(), blobs?.load() ?? Promise.resolve()]);
+      await Promise.all([
+        snapshot.load(),
+        reads.load(),
+        outbox.load(),
+        blobs?.load() ?? Promise.resolve()
+      ]);
       unbind = drainer.bindOpportunisticTriggers();
       drainer.kick();
     },
@@ -7411,6 +7489,6 @@ var KaafilClient = class {
   }
 };
 
-export { ACTIVE_TREK_REF, BATCH_THRESHOLD_OPS, BlobStatus, BoardStatus, BookingStatus, CONSOLIDATED_PULL_THRESHOLD_LISTS, ChecklistAudience, ChecklistGate, ChecklistItemStatus, ChecklistPhase, ChecklistPullTemplateMode, ClaimStatusIngest, CloseoutPackSection, CollectionMode, CompressionOutcome, Currency, ERROR_CODE_TABLE, EventType, ExpenseCategory, ExpensePaymentMode, FALLBACK_GLYPH, FileContentType, FilePurpose, FloatDirection, Gender, HEURISTIC_SEVERITY, ItineraryItemStatusUpdate, ItineraryItemType, KaafilAbortError, KaafilApiError, KaafilCapabilityUnavailableError, KaafilClient, KaafilClientAlreadyOpenError, KaafilClientNotOpenError, KaafilDeltaCursorInFlightError, KaafilEntitlementError, KaafilError, KaafilErrorCode, KaafilIndexedDbUnavailableError, KaafilInvalidRequestError, KaafilLockedError, KaafilNetworkError, KaafilNotFoundError, KaafilNotImplementedError, KaafilPaginationError, KaafilPaginationExhaustedError, KaafilPaginationInFlightError, KaafilRateLimitedError, KaafilReadOnlyRoleError, KaafilShareBatchUnauthenticatedError, KaafilShareLinkExpiredError, KaafilShareTokenExpiredError, KaafilShareTokenRevokedError, KaafilTimeoutError, KaafilTransportError, KaafilUnauthenticatedError, KaafilValidationError, KaafilVersionConflictError, MAX_BATCH_OPS, ManagerRole, ManifestMode, OutboxClass, OutboxRetryCause, OutboxStatus, PartyKind, PickupKind, Retryability, RoomType, RoomingFillOrder, RoomingGenderPolicy, RoomingHeuristicKey, SHADES_PER_FAMILY, SHARE_WRITE_GRACE_MS, SYNC_PULL_SECTIONS, SeatingFillOrder, SeatingGenderAdjacency, SeatingHeuristicKey, SyncOpMethod, TONE_FAMILIES, TriggerAnchor, TripMode, TripStatus, UNKNOWN_TONE_FAMILY, UnsatisfiableSchemeError, VehicleLayout, VehicleType, compressImage, convertImageLossless, createBlobLane, createDeltaCursor, createDrainer, createHttpOfflineTransport, createInMemoryStorageAdapter, createIndexedDbStorageAdapter, createOfflineEngine, createOfflineEvents, createOutbox, createPullCoordinator, createShareGuard, createSnapshotStore, createSyncResource, extractSectionRows, isCompressibleType, isImageCompressionSupported, isKaafilError, isRetryable, isRoomingHeuristicKey, isShareBatchPushAvailable, isTombstone, mergeDeltaRows, parseRoomingTone, readCurrentVersion, reconcileConflict, roomingHeuristicSeverity, scaledDimensions, shouldUseBatchTransport };
+export { ACTIVE_TREK_REF, BATCH_THRESHOLD_OPS, BlobStatus, BoardStatus, BookingStatus, CONSOLIDATED_PULL_THRESHOLD_LISTS, ChecklistAudience, ChecklistGate, ChecklistItemStatus, ChecklistPhase, ChecklistPullTemplateMode, ClaimStatusIngest, CloseoutPackSection, CollectionMode, CompressionOutcome, Currency, ERROR_CODE_TABLE, EventType, ExpenseCategory, ExpensePaymentMode, FALLBACK_GLYPH, FileContentType, FilePurpose, FloatDirection, Gender, HEURISTIC_SEVERITY, ItineraryItemStatusUpdate, ItineraryItemType, KaafilAbortError, KaafilApiError, KaafilCapabilityUnavailableError, KaafilClient, KaafilClientAlreadyOpenError, KaafilClientNotOpenError, KaafilDeltaCursorInFlightError, KaafilEntitlementError, KaafilError, KaafilErrorCode, KaafilIndexedDbUnavailableError, KaafilInvalidRequestError, KaafilLockedError, KaafilNetworkError, KaafilNotFoundError, KaafilNotImplementedError, KaafilPaginationError, KaafilPaginationExhaustedError, KaafilPaginationInFlightError, KaafilRateLimitedError, KaafilReadOnlyRoleError, KaafilShareBatchUnauthenticatedError, KaafilShareLinkExpiredError, KaafilShareTokenExpiredError, KaafilShareTokenRevokedError, KaafilTimeoutError, KaafilTransportError, KaafilUnauthenticatedError, KaafilValidationError, KaafilVersionConflictError, MAX_BATCH_OPS, ManagerRole, ManifestMode, OutboxClass, OutboxRetryCause, OutboxStatus, PartyKind, PickupKind, Retryability, RoomType, RoomingFillOrder, RoomingGenderPolicy, RoomingHeuristicKey, SHADES_PER_FAMILY, SHARE_WRITE_GRACE_MS, SYNC_PULL_SECTIONS, SeatingFillOrder, SeatingGenderAdjacency, SeatingHeuristicKey, SyncOpMethod, TONE_FAMILIES, TriggerAnchor, TripMode, TripStatus, UNKNOWN_TONE_FAMILY, UnsatisfiableSchemeError, VehicleLayout, VehicleType, compressImage, convertImageLossless, createBlobLane, createDeltaCursor, createDrainer, createHttpOfflineTransport, createInMemoryStorageAdapter, createIndexedDbStorageAdapter, createOfflineEngine, createOfflineEvents, createOutbox, createPullCoordinator, createReadCacheStore, createShareGuard, createSnapshotStore, createSyncResource, extractSectionRows, isCompressibleType, isImageCompressionSupported, isKaafilError, isRetryable, isRoomingHeuristicKey, isShareBatchPushAvailable, isTombstone, mergeDeltaRows, parseRoomingTone, readCurrentVersion, reconcileConflict, roomingHeuristicSeverity, scaledDimensions, shouldUseBatchTransport };
 //# sourceMappingURL=client-entry.js.map
 //# sourceMappingURL=client-entry.js.map