kaafil-js 0.1.0 → 0.3.0

package/dist/client-entry.d.cts

@@ -126,6 +126,27 @@ interface OutboxEntityRef {
     readonly listName: string;
     readonly id?: string;
     readonly arrayKey?: string;
+    /**
+     * Set ONLY by a create, and set to the same value as `id`: the id this
+     * device minted locally because the server had not assigned one yet.
+     *
+     * A create is the one write whose optimistic row cannot be keyed on the
+     * server's identity, and without a local key there is nothing to key it on
+     * at all — so before this existed, creates simply had no optimistic row.
+     * The manager added a checklist item out of signal and watched it not
+     * appear: queued, durable, landing on reconnect, and invisible until it
+     * did. Indistinguishable, from where they were standing, from having lost
+     * it.
+     *
+     * Its presence is what lets `applySuccess` clean up after itself. The
+     * canonical row comes back under the SERVER's id, so writing it would leave
+     * the local row beside it and show the same item twice; the drainer purges
+     * this id in the same step, and the swap is one `snapshot.updated`.
+     *
+     * A temporary id is NEVER sent to the server — it is not in `body`, not in
+     * `path`, and no request carries it. It exists only as a snapshot key.
+     */
+    readonly temporaryId?: string;
 }
 /**
  * WHY an op is waiting out a backoff rung. Recorded because the two causes
@@ -460,8 +481,21 @@ interface SnapshotUpdatedEvent {
      * from the pull never appears here — absence is not a change, and it is
      * emphatically not a purge (`06 §4.1`). */
     readonly lists: readonly string[];
-    /** The cursor now stored: the pull response's own `meta.serverTime`. */
-    readonly serverTime: string;
+    /**
+     * The cursor now stored: the pull response's own `meta.serverTime`.
+     *
+     * ABSENT for a change that never involved the server — an optimistic create
+     * painted while offline, or a queued op the host discarded. Those move rows
+     * and must repaint, but they carry no server reading, and putting a device
+     * clock in this field would be exactly the lie `../delta/cursor.ts` exists
+     * to prevent: a subscriber deriving "now" from it would age every other row
+     * against a phone's wall clock.
+     *
+     * A subscriber that only needs "something changed" ignores this field. One
+     * that shows an "as of" time, or derives the current server time, must skip
+     * an event without it and keep the last reading it had.
+     */
+    readonly serverTime?: string;
 }
 interface ShareInvalidatedEvent {
     /** The server-authored code when one arrived; absent when local
@@ -1036,36 +1070,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 +1115,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.
@@ -1248,6 +1342,22 @@ interface EnqueueWriteOptions {
     /** The row to paint immediately, rebased later from the server's canonical
      * entity. Omit for a write with nothing to show optimistically. */
     readonly optimistic?: SnapshotRow;
+    /**
+     * Set on a CREATE, where there is no server id yet to key the optimistic
+     * row on. This engine mints a temporary one, writes `optimistic` under it,
+     * and records it on the op so the drainer can swap it for the canonical row
+     * the moment the write lands (`OutboxEntityRef.temporaryId`).
+     *
+     * The caller does not mint the id and cannot see it before this resolves:
+     * identity comes from the engine's own `newId`, which keeps it injectable
+     * and keeps a UI layer out of the business of inventing identifiers. Read
+     * it back off the returned op's `entity.temporaryId` if you need it.
+     *
+     * `entity.listName` is required alongside it — without a list there is
+     * nowhere to paint — and any `entity.id` passed here is ignored, because a
+     * create has no server identity to pass.
+     */
+    readonly creates?: boolean;
     readonly idempotencyKey?: string;
     readonly enqueuedAt?: string;
 }
@@ -1264,6 +1374,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;
@@ -1276,6 +1392,21 @@ interface OfflineEngine {
     open(): Promise<void>;
     /** Write-ahead, optimistic apply, kick — in that order. */
     enqueue(options: EnqueueWriteOptions): Promise<OutboxOp>;
+    /**
+     * Abandons a queued op AND undoes its optimistic paint — the host-initiated
+     * "discard my change" that a conflict surface or a sync centre offers.
+     *
+     * Use this rather than `outbox.drop()` directly. `drop()` is a queue
+     * operation and knows nothing about the snapshot, so dropping a CREATE
+     * through it leaves the locally-keyed row on screen forever: an item the
+     * manager chose to discard, which no longer exists anywhere, and which no
+     * pull can ever remove because the server never had it.
+     *
+     * Only a create's own temporary row is purged. An update's optimistic row
+     * belongs to a server row that still exists, and the next pull rebases it —
+     * removing it here would blank a row that is really there.
+     */
+    discard(opId: string): Promise<void>;
     /** The structured op enqueues NOW with `receiptPending: true`; the bytes
      * upload opportunistically and back-fill later (`06 §3.1`). */
     enqueueWithBlob(options: EnqueueWithBlobOptions): Promise<OutboxOp>;
@@ -2720,4 +2851,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

@@ -126,6 +126,27 @@ interface OutboxEntityRef {
     readonly listName: string;
     readonly id?: string;
     readonly arrayKey?: string;
+    /**
+     * Set ONLY by a create, and set to the same value as `id`: the id this
+     * device minted locally because the server had not assigned one yet.
+     *
+     * A create is the one write whose optimistic row cannot be keyed on the
+     * server's identity, and without a local key there is nothing to key it on
+     * at all — so before this existed, creates simply had no optimistic row.
+     * The manager added a checklist item out of signal and watched it not
+     * appear: queued, durable, landing on reconnect, and invisible until it
+     * did. Indistinguishable, from where they were standing, from having lost
+     * it.
+     *
+     * Its presence is what lets `applySuccess` clean up after itself. The
+     * canonical row comes back under the SERVER's id, so writing it would leave
+     * the local row beside it and show the same item twice; the drainer purges
+     * this id in the same step, and the swap is one `snapshot.updated`.
+     *
+     * A temporary id is NEVER sent to the server — it is not in `body`, not in
+     * `path`, and no request carries it. It exists only as a snapshot key.
+     */
+    readonly temporaryId?: string;
 }
 /**
  * WHY an op is waiting out a backoff rung. Recorded because the two causes
@@ -460,8 +481,21 @@ interface SnapshotUpdatedEvent {
      * from the pull never appears here — absence is not a change, and it is
      * emphatically not a purge (`06 §4.1`). */
     readonly lists: readonly string[];
-    /** The cursor now stored: the pull response's own `meta.serverTime`. */
-    readonly serverTime: string;
+    /**
+     * The cursor now stored: the pull response's own `meta.serverTime`.
+     *
+     * ABSENT for a change that never involved the server — an optimistic create
+     * painted while offline, or a queued op the host discarded. Those move rows
+     * and must repaint, but they carry no server reading, and putting a device
+     * clock in this field would be exactly the lie `../delta/cursor.ts` exists
+     * to prevent: a subscriber deriving "now" from it would age every other row
+     * against a phone's wall clock.
+     *
+     * A subscriber that only needs "something changed" ignores this field. One
+     * that shows an "as of" time, or derives the current server time, must skip
+     * an event without it and keep the last reading it had.
+     */
+    readonly serverTime?: string;
 }
 interface ShareInvalidatedEvent {
     /** The server-authored code when one arrived; absent when local
@@ -1036,36 +1070,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 +1115,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.
@@ -1248,6 +1342,22 @@ interface EnqueueWriteOptions {
     /** The row to paint immediately, rebased later from the server's canonical
      * entity. Omit for a write with nothing to show optimistically. */
     readonly optimistic?: SnapshotRow;
+    /**
+     * Set on a CREATE, where there is no server id yet to key the optimistic
+     * row on. This engine mints a temporary one, writes `optimistic` under it,
+     * and records it on the op so the drainer can swap it for the canonical row
+     * the moment the write lands (`OutboxEntityRef.temporaryId`).
+     *
+     * The caller does not mint the id and cannot see it before this resolves:
+     * identity comes from the engine's own `newId`, which keeps it injectable
+     * and keeps a UI layer out of the business of inventing identifiers. Read
+     * it back off the returned op's `entity.temporaryId` if you need it.
+     *
+     * `entity.listName` is required alongside it — without a list there is
+     * nowhere to paint — and any `entity.id` passed here is ignored, because a
+     * create has no server identity to pass.
+     */
+    readonly creates?: boolean;
     readonly idempotencyKey?: string;
     readonly enqueuedAt?: string;
 }
@@ -1264,6 +1374,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;
@@ -1276,6 +1392,21 @@ interface OfflineEngine {
     open(): Promise<void>;
     /** Write-ahead, optimistic apply, kick — in that order. */
     enqueue(options: EnqueueWriteOptions): Promise<OutboxOp>;
+    /**
+     * Abandons a queued op AND undoes its optimistic paint — the host-initiated
+     * "discard my change" that a conflict surface or a sync centre offers.
+     *
+     * Use this rather than `outbox.drop()` directly. `drop()` is a queue
+     * operation and knows nothing about the snapshot, so dropping a CREATE
+     * through it leaves the locally-keyed row on screen forever: an item the
+     * manager chose to discard, which no longer exists anywhere, and which no
+     * pull can ever remove because the server never had it.
+     *
+     * Only a create's own temporary row is purged. An update's optimistic row
+     * belongs to a server row that still exists, and the next pull rebases it —
+     * removing it here would blank a row that is really there.
+     */
+    discard(opId: string): Promise<void>;
     /** The structured op enqueues NOW with `receiptPending: true`; the bytes
      * upload opportunistically and back-fill later (`06 §3.1`). */
     enqueueWithBlob(options: EnqueueWithBlobOptions): Promise<OutboxOp>;
@@ -2720,4 +2851,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 };