@foir/sdk 0.9.0 → 0.11.0

package/dist/graphql/cdn-route.d.ts

@@ -21,6 +21,6 @@ export { buildCdnUrl, documentHash, hasFoirErrorCode, NOT_SHAREABLE, PERSISTED_Q
  * `/graphql` when it does — but every condition checked here is one round trip
  * saved.
  */
-export declare function isCdnEligible(env: FoirEnv, documentText: string, bearerToken?: string): boolean;
+export declare function isCdnEligible(env: FoirEnv, documentText: string, bearerToken?: string, orgId?: string): boolean;
 /** Print a document once, so eligibility and the URL agree on the same text. */
 export declare function printDocument<TData, TVariables>(document: TypedDocumentNode<TData, TVariables>): string;

package/dist/graphql/foir-request.d.ts

@@ -24,7 +24,7 @@
  */
 import type { TypedDocumentNode } from '@graphql-typed-document-node/core';
 import { type FoirEnv, type FoirRequestOptions } from '../transport/foir-http';
-export { FoirRequestError, isFoirPreview, isFoirRateLimited, isFoirUnauthenticated, isFoirForbidden, isFoirNotFound, readFoirRateLimit, type FoirEnv, type FoirErrorCode, type FoirErrorExtensions, type FoirGraphQLErrorItem, type FoirRateLimitSnapshot, type FoirRequestOptions, } from '../transport/foir-http';
+export { FoirRequestError, isFoirPreview, isFoirRateLimited, isFoirUnauthenticated, isFoirForbidden, isFoirNotFound, readFoirRateLimit, type FoirEnv, type FoirErrorCode, type FoirErrorExtensions, type FoirGraphQLErrorItem, type FoirRateLimitSnapshot, type FoirRequestOptions, type FoirAuthDowngrade, } from '../transport/foir-http';
 export { withFoirRetry, foirRetryDelayMs, type FoirRetryPolicy, } from '../transport/retry';
 /** Default Foir CDN origin used to absolutise relative media URLs. */
 export declare const FOIR_CDN_BASE = "https://cdn.foir.dev/";

package/dist/index.js

@@ -256,15 +256,6 @@ function EditorProvider({
           type: "request-operation",
           payload: { operationKey, input, requestId, mode: options?.mode ?? "sync" }
         });
-        setTimeout(() => {
-          if (pendingOperationsRef.current.has(requestId)) {
-            pendingOperationsRef.current.delete(requestId);
-            resolve({
-              success: false,
-              error: { code: "TIMEOUT", message: "Operation timed out" }
-            });
-          }
-        }, 6e4);
       });
     },
     [postMessage]

package/dist/live/coalesce.d.ts

@@ -0,0 +1,57 @@
+/**
+ * live/coalesce.ts — the difference between "live" and "thrashing".
+ *
+ * The invalidation graph is exact, which is the whole point of it — and exact
+ * still means N invalidations for N writes. A bulk import, a scheduled publish
+ * sweep or someone holding down a keyboard shortcut fires a burst on one model,
+ * and a client that refetched each one would spend the burst doing nothing but
+ * refetching, on the exact screen a burst is most likely to be watched from.
+ *
+ * Three things fix that, and they are three different problems:
+ *
+ *   - **Coalesce.** Fifty invalidations of one key inside a window are one
+ *     refetch. This is the big one, because a burst usually IS one key.
+ *   - **Cap.** A burst that spans many keys must not open fifty requests at
+ *     once — that is a self-inflicted denial of service on the caller's own
+ *     connection pool, and every extra request slows the ones already running.
+ *   - **Supersede.** A key invalidated again while its refetch is in flight
+ *     gets exactly one more refetch afterwards, not one per invalidation. The
+ *     `seq` last-write-wins rule in the store already makes a late arrival
+ *     harmless; this is about the WASTE, not the correctness.
+ */
+export interface FoirCoalescerOptions {
+    /**
+     * What to do for one key. Its returned promise, if any, is awaited — that is
+     * how the concurrency cap knows a refetch has finished. A query library's
+     * `invalidateQueries` returns exactly that promise.
+     */
+    run: (key: string) => unknown;
+    /**
+     * How long to gather before running. 25ms by default: long enough to swallow
+     * a burst arriving over one socket read, short enough that a single change
+     * still feels immediate.
+     */
+    windowMs?: number;
+    /** How many refetches may be in flight at once. */
+    maxConcurrent?: number;
+    /** Injectable timers, so a test can drive the window without waiting. */
+    timers?: {
+        setTimeout: (fn: () => void, ms: number) => unknown;
+        clearTimeout: (handle: unknown) => void;
+    };
+    /** Reported rather than thrown: one key's refetch failing must not stop the rest. */
+    onError?: (error: unknown, key: string) => void;
+}
+export interface FoirCoalescer {
+    /** Ask for a key to be refetched, eventually and at most once per window. */
+    invalidate(key: string): void;
+    /** Run everything waiting, now. Resolves when the queue is empty. */
+    flush(): Promise<void>;
+    /** Keys gathered but not yet started. */
+    readonly pending: number;
+    /** Refetches currently running. */
+    readonly inFlight: number;
+    /** Forget everything waiting. Does not cancel what is already running. */
+    dispose(): void;
+}
+export declare function createFoirCoalescer(options: FoirCoalescerOptions): FoirCoalescer;

package/dist/live/drift.d.ts

@@ -0,0 +1,58 @@
+import type { FoirSchemaDrift } from '../data/transport';
+/**
+ * live/drift.ts — the deploy that changes what a cached response MEANS.
+ *
+ * Every other invalidation in this subpath answers "is this data still
+ * current". Drift answers a different question: "is this data still the same
+ * SHAPE". A deploy that adds a field, renames one, or changes a scalar's wire
+ * form leaves every cached entry perfectly current and quietly wrong — the
+ * bytes are what the server sent, and they no longer match what the code
+ * reading them expects.
+ *
+ * Nothing else catches it. The dependency graph is about records, and no record
+ * changed. `seq` is about ordering, and nothing is out of order. The entry is
+ * fresh, correctly tagged, correctly stamped, and describes a schema that no
+ * longer exists — until the tab is reloaded, which on a long-lived admin
+ * session can be days.
+ *
+ * The SDK already detects this: the data client compares the surface version
+ * its generated types came from against the one the server is serving, and
+ * reports `FoirSchemaDrift`. What was missing is anyone acting on it.
+ *
+ * ONE HOOK, and it closes a whole class of "worked until the deploy" bugs.
+ */
+export interface FoirDriftHandlerOptions {
+    /**
+     * Throw away everything cached. Usually the store's `resync` and the query
+     * client's `clear`, in that order.
+     */
+    resync: (drift: FoirSchemaDrift) => void;
+    /**
+     * Called instead of resyncing when the drift is not one that can invalidate
+     * anything — see `foirDriftIsActionable`.
+     */
+    onIgnored?: (drift: FoirSchemaDrift) => void;
+}
+/**
+ * Whether a reported drift is worth clearing the cache for.
+ *
+ * Any surface other than the one the types were generated from is. The versions
+ * are content hashes, so there is no ahead or behind: a deploy that added a
+ * field and a rollback that removed one are both a different surface, and in
+ * both the cache holds responses resolved against a shape the code no longer
+ * reads, which is the torn state this exists to remove.
+ *
+ * What is NOT actionable is equality, or a version missing on either side: a
+ * report the detector should not produce, and one that costs nothing to refuse
+ * here rather than to clear the world for.
+ */
+export declare function foirDriftIsActionable(drift: FoirSchemaDrift): boolean;
+/**
+ * Build the handler to hand to `createFoirClient({ onSchemaDrift })`.
+ *
+ * It clears rather than revalidates, and that is the point: a revalidation
+ * would refetch each entry through the same code that no longer matches the
+ * schema, one query at a time, while continuing to serve the old shape in
+ * between. Whatever is cached is unusable as a set, so it goes as a set.
+ */
+export declare function createFoirDriftHandler(options: FoirDriftHandlerOptions): (drift: FoirSchemaDrift) => void;

package/dist/live/events.d.ts

@@ -0,0 +1,13 @@
+import type { FoirRecordChangedEvent } from '../data/subscriptions';
+/** `rec:{id}` for one record id. */
+export declare function foirRecordTag(recordId: string): string;
+/** `model:{key}:published` for one model. */
+export declare function foirModelTag(modelKey: string): string;
+/**
+ * The tags one record change invalidates.
+ *
+ * An action nobody has taught this about is treated as a membership change,
+ * which is the WIDE answer. Over-invalidating costs a refetch; the narrow answer
+ * on an action that actually moved a record between lists costs the update.
+ */
+export declare function foirTagsForRecordChange(event: FoirRecordChangedEvent): string[];

package/dist/live/headers.d.ts

@@ -0,0 +1,53 @@
+/**
+ * live/headers.ts — what a read tells the cache about itself.
+ *
+ * Two headers, and they arrive for different reasons.
+ */
+/**
+ * The dependency set a BROWSER may read.
+ *
+ * `Surrogate-Key` is the CDN's contract and names records a response was shaped
+ * by but did not show, so it is deliberately not exposed cross-origin. This
+ * header is the same set projected down to records the caller was actually
+ * served, and it is the one on api-public's CORS exposed-header list.
+ */
+export declare const FOIR_CACHE_TAGS_HEADER = "X-Foir-Cache-Tags";
+/**
+ * The CDN's wider set. Present and readable on a SAME-ORIGIN or server-side
+ * read, where CORS never applies.
+ *
+ * Preferred when both are present, because it is the more complete answer to
+ * "what would make this response stale" — an entry shaped by a record it
+ * filtered out still has to drop when that record changes.
+ */
+export declare const FOIR_SURROGATE_KEY_HEADER = "Surrogate-Key";
+/**
+ * The project's logical clock at the moment the response was RESOLVED.
+ *
+ * Absent means UNKNOWN, never zero — a cold project, an unreachable Redis and a
+ * cache entry written before the stamp existed all report nothing rather than a
+ * position. Zero would mean "before everything", and a client applying
+ * monotonic reads to it would discard every response it holds.
+ */
+export declare const FOIR_PROJECT_SEQ_HEADER = "X-Foir-Project-Seq";
+/** The minimal header shape this module reads; a real `Headers` satisfies it. */
+export interface FoirHeaderSource {
+    get(name: string): string | null | undefined;
+}
+/** What a response says about its own place in the graph and in time. */
+export interface FoirLiveHeaders {
+    /** The response's dependency set. Empty when it published none. */
+    tags: string[];
+    /** The project seq it resolved under, or `null` for "unknown". */
+    seq: number | null;
+}
+/**
+ * Read a response's dependency set and logical timestamp.
+ *
+ * A seq that is not a positive integer is treated as unknown rather than
+ * coerced. `Number('')` is 0 and `Number('abc')` is NaN, and both would become
+ * a position in seq space if this used the plain conversion — the first
+ * silently the WORST position, which is the one that makes a client throw away
+ * good data.
+ */
+export declare function readFoirLiveHeaders(headers: FoirHeaderSource): FoirLiveHeaders;

package/dist/live/index.d.ts

@@ -0,0 +1,54 @@
+/**
+ * `@foir/sdk/live` — the client half of Foir's invalidation graph.
+ *
+ * ## What this is
+ *
+ * The API already computes, for every cacheable response, the exact set of
+ * records and collections it depends on — it has to, to invalidate its own
+ * cache — and ships it on a response header. It already streams the change
+ * events that make those dependencies stale, each carrying the project's
+ * monotonic `seq`. This subpath is the join, on the client: a bidirectional tag
+ * index, a store that honours ordering and completeness, and the mapping from
+ * one record change to the entries it invalidates.
+ *
+ * Apollo, urql and TanStack Query all GUESS at that graph — manual query keys or
+ * normalised-cache heuristics. Here it is computed by the process that actually
+ * resolved the query, which makes invalidation exact and schema-agnostic.
+ *
+ * ## What this is NOT, and will not become
+ *
+ * **Not a state-management library.** No local mutation log, no offline mode, no
+ * conflict resolution, no optimistic rollback. The server is authoritative:
+ * mutations go over the wire and the invalidation comes back.
+ *
+ * That is a product boundary, not a phasing one. The moment optimistic mutations
+ * with rollback are added this becomes a different category of product, with its
+ * own roadmap and a permanent support surface. It is written here so it is not
+ * filed as a bug.
+ *
+ * **Framework-free.** Nothing here imports React, and nothing here is a
+ * rendering concern. The React binding is a separate, thin adapter over a query
+ * library the consumer already has.
+ */
+export { foirQueryKey, foirStableKey, foirDecimalKey } from './keys';
+export type { FoirLiveCall } from './keys';
+export { readFoirLiveHeaders, FOIR_CACHE_TAGS_HEADER, FOIR_SURROGATE_KEY_HEADER, FOIR_PROJECT_SEQ_HEADER, } from './headers';
+export type { FoirHeaderSource, FoirLiveHeaders } from './headers';
+export { readFoirWriteToken, foirWriteTokenHeaders, FOIR_WRITE_TOKEN_HEADER, } from './writetoken';
+export { foirTagsForRecordChange, foirRecordTag, foirModelTag } from './events';
+export { createFoirTagIndex } from './tagIndex';
+export type { FoirTagIndex } from './tagIndex';
+export { createFoirLiveStore } from './store';
+export type { FoirLiveEntry, FoirLiveInvalidation, FoirLiveReadOptions, FoirLiveStore, FoirLiveStoreOptions, FoirLiveWrite, FoirWriteFence, } from './store';
+export { foirRequiresResync, foirResumeCursor, FOIR_RESYNC_ERROR_CODES } from './resync';
+export type { FoirResyncErrorCode } from './resync';
+export { createFoirReconciler, foirHeldRecordIds, foirTagsForGoneRecords, } from './reconcile';
+export type { FoirReconcileResolveFn, FoirReconciler, FoirReconcilerOptions, } from './reconcile';
+export { createFoirLiveManager } from './manager';
+export type { FoirLiveManager, FoirLiveManagerOptions, FoirLiveSubscribeFn, FoirLiveSubscribeHandlers, FoirLiveSubscription, } from './manager';
+export { applyFoirRecordChange, foirModelQueryKey, foirQueryKeys, foirTagsForQueryInvalidation, FOIR_QUERY_KEY_ROOT, } from './tanstack';
+export type { FoirApplyOptions, FoirLiveEffect, FoirLiveMode, FoirQueryClientLike, } from './tanstack';
+export { createFoirCoalescer } from './coalesce';
+export type { FoirCoalescer, FoirCoalescerOptions } from './coalesce';
+export { createFoirDriftHandler, foirDriftIsActionable } from './drift';
+export type { FoirDriftHandlerOptions } from './drift';

package/dist/live/keys.d.ts

@@ -0,0 +1,72 @@
+import { FoirDecimal } from '../data/decimal';
+import type { FoirCall, FoirNamespaceCall } from '../data/document';
+/**
+ * live/keys.ts — one call, one key.
+ *
+ * A cache key has exactly one job: two calls that would return the same bytes
+ * must produce the same key, and two that would not must never. Everything here
+ * is in service of that, and every rule below exists because some ordinary
+ * JavaScript would otherwise break it.
+ */
+/**
+ * Canonicalise a decimal for a KEY, and only for a key.
+ *
+ * `decimal('1.0')` and `decimal('1.00')` are the same number and different
+ * strings, so a key built from `toString()` makes two entries for one logical
+ * query. The fix is to key on a canonical representative of the value.
+ *
+ * MINIMAL SCALE, not a fixed one. Rescaling to a fixed number of places is the
+ * obvious move and it is unsafe in the direction that matters: any fixed scale
+ * short enough to be useful ROUNDS, and rounding in a key makes two genuinely
+ * different values collide — `1.001` and `1.002` at 2dp are one key, and one
+ * query is then served the other's cached answer. Stripping trailing zeros is
+ * lossless, so two decimals share a key if and only if they are `.equals()`.
+ *
+ * # KEYS NORMALISE, PAYLOADS NEVER DO
+ *
+ * This is half of a rule whose other half points the opposite way. Scale is
+ * display, not identity: trailing zeros are significant for money, which is why
+ * `toString()` preserves them and `equals()` ignores them. Normalising a decimal
+ * on the way INTO the store would serve `"1.0"` where the server sent `"1.00"` —
+ * a silent change to how a price renders. The store never holds a decimal at
+ * all (it holds raw wire JSON, where a decimal is a string), so that half falls
+ * out for free. Do not undo it.
+ */
+export declare function foirDecimalKey(value: FoirDecimal): string;
+/**
+ * A stable, injective string for any value a call argument can hold.
+ *
+ * `JSON.stringify` is not enough on its own for three reasons, and each one is a
+ * wrong cache hit rather than a cosmetic difference:
+ *
+ *   - **Key order.** `{a:1,b:2}` and `{b:2,a:1}` are the same argument and
+ *     stringify differently. Object keys are sorted here.
+ *   - **`undefined`.** `stringify` DROPS an undefined property, so
+ *     `{a:1,b:undefined}` and `{a:1}` collapse to one key — usually right, and
+ *     wrong the moment a caller distinguishes "not set" from "set to nothing".
+ *     Both are written explicitly.
+ *   - **Type collisions.** `1` and `"1"` stringify to `1` and `"1"`, which is
+ *     fine, but `null` and the string `"null"` are one keystroke apart in a
+ *     hand-built key. Every scalar is tagged with its type.
+ *
+ * `FoirDecimal` gets its own tag and its own canonical form: it is a class with
+ * `#`-private fields, so `JSON.stringify` would reach `toJSON()` and produce the
+ * scale-preserving string this function exists to normalise away.
+ */
+export declare function foirStableKey(value: unknown): string;
+/** A model or namespace call, as the live store keys it. */
+export type FoirLiveCall = FoirCall | FoirNamespaceCall;
+/**
+ * The cache key for one call.
+ *
+ * Every input that changes the RESPONSE is in it, and nothing that does not.
+ * `omit` and `pick` are in it deliberately: two calls differing only by a narrow
+ * are two different response shapes, and folding them together is how a caller
+ * asking for the whole record gets served one with a field missing. The
+ * completeness mask in the store is the second line of defence for the case
+ * where an entry is reachable through something other than its own key.
+ *
+ * `omit` and `pick` are SORTED — they are sets, and a caller who writes them in
+ * a different order has not written a different query.
+ */
+export declare function foirQueryKey(call: FoirLiveCall): string;

package/dist/live/manager.d.ts

@@ -0,0 +1,77 @@
+import type { FoirRecordChangedEvent } from '../data/subscriptions';
+import type { FoirRequestError } from '../transport/foir-http';
+/**
+ * live/manager.ts — one subscription per model, however many things are
+ * watching it.
+ *
+ * Framework-free on purpose. What it claims — that the Nth watcher of a model
+ * opens no second stream, that the last one to leave closes the first, and that
+ * a reconnect resumes from where the stream got to — is a statement about
+ * refcounts and cursors, provable without React, a socket or a server.
+ */
+/** One live subscription, as the data client's `onChange` returns it. */
+export interface FoirLiveSubscription {
+    unsubscribe(): void;
+}
+/** The handlers the manager wires onto each subscription. */
+export interface FoirLiveSubscribeHandlers {
+    onData: (event: FoirRecordChangedEvent) => void;
+    onError?: (error: FoirRequestError) => void;
+    onReconnect?: () => void;
+    onComplete?: () => void;
+}
+/**
+ * How the manager opens a stream. Injected rather than taking a client, so the
+ * refcounting can be tested for what it is.
+ *
+ * `after` is the resume cursor and is absent on a first subscribe: a watcher
+ * joining now has missed nothing, and asking the server to replay history it
+ * does not want would spend the backlog budget for no reason.
+ */
+export type FoirLiveSubscribeFn = (modelKey: string, options: {
+    after?: number;
+}, handlers: FoirLiveSubscribeHandlers) => FoirLiveSubscription;
+export interface FoirLiveManagerOptions {
+    subscribe: FoirLiveSubscribeFn;
+    /** Every admitted change, for every watched model. */
+    onChange: (event: FoirRecordChangedEvent) => void;
+    /**
+     * The cache can no longer be trusted and must be thrown away — the server
+     * refused the resume cursor. See `resync.ts` for why those two refusals are
+     * the only signal of this kind there is.
+     */
+    onResync?: (reason: FoirRequestError, modelKey: string) => void;
+    /** A subscription failed for a reason that is not a resync. */
+    onError?: (error: FoirRequestError, modelKey: string) => void;
+    /**
+     * Re-read the record ids this client holds for a model, because the cursor
+     * cannot report what VANISHED.
+     *
+     * Called on every reconnect, alongside resuming the cursor rather than
+     * instead of it — the two answer different questions. The cursor replays what
+     * CHANGED while the socket was down. This reports what is no longer there,
+     * which by construction produced no event to replay: on a caller-partitioned
+     * model the server's confined read is an INNER join to `records`, and a
+     * deleted or lost record does not match it. See `reconcile.ts`.
+     *
+     * Optional because a consumer that caches nothing has nothing to reconcile.
+     * Omitting it on a confined model means deletes are never observed.
+     */
+    reconcile?: (modelKey: string) => void;
+}
+export interface FoirLiveManager {
+    /**
+     * Watch a model, and return the release. The FIRST caller opens the stream;
+     * the LAST release closes it.
+     */
+    retain(modelKey: string): () => void;
+    /** The highest seq applied for a model, or `null` before anything arrives. */
+    cursorFor(modelKey: string): number | null;
+    /** How many watchers a model has. */
+    watchers(modelKey: string): number;
+    /** The models with a live stream open. */
+    readonly watching: string[];
+    /** Close everything. */
+    dispose(): void;
+}
+export declare function createFoirLiveManager(options: FoirLiveManagerOptions): FoirLiveManager;

package/dist/live/react/index.d.ts

@@ -0,0 +1,143 @@
+import { type ReactNode } from 'react';
+import type { FoirRecordChangedEvent } from '../../data/subscriptions';
+import type { FoirRequestError } from '../../transport/foir-http';
+import { type FoirLiveManager, type FoirLiveSubscribeFn } from '../manager';
+import { foirModelQueryKey, type FoirApplyOptions, type FoirLiveEffect, type FoirLiveMode, type FoirQueryClientLike } from '../tanstack';
+/**
+ * `@foir/sdk/live/react` — one socket, and the React lifetime that owns it.
+ *
+ * ## What this is, and what it is not
+ *
+ * An ADAPTER over a query library the consumer already has. `<FoirLive>` opens
+ * one stream per watched model and turns each change into the invalidation the
+ * server's own dependency graph says it is. It renders nothing, owns no cache,
+ * and replaces no hook.
+ *
+ * There is no local mutation log, no offline mode, no conflict resolution and no
+ * optimistic rollback. **The server is authoritative.** That is a product
+ * boundary rather than a phase: the moment optimistic mutations with rollback
+ * are added this becomes a different category of library with its own roadmap
+ * and a permanent support surface.
+ *
+ * ## Live is OPT-IN per model
+ *
+ * Nothing subscribes because a provider is mounted. A component says
+ * `useFoirLive('product')` and the model is watched for as long as something is
+ * saying it; the last one to leave closes the stream.
+ *
+ * That default is not timidity. The shared CDN lane is a major asset, and a
+ * blanket "everything is live" pushes read traffic off it onto the origin — so
+ * liveness is something a screen asks for, on the models where it earns the
+ * connection.
+ *
+ * ## The limitation to document rather than defeat
+ *
+ * A query ordered by a MUTABLE sort key — `updatedAt`, or a `position` a user
+ * drags — can have a record move between pages when it is updated, so it may
+ * appear twice or vanish until the next full refetch. Detecting that needs
+ * client-side knowledge of the sort fields, and the fully correct alternative
+ * turns a routine edit into an N-page refetch on most feeds. It is a known
+ * limitation, not a bug.
+ */
+export interface FoirLiveContextValue {
+    manager: FoirLiveManager;
+    /** Watch a model for the caller's lifetime; returns the release. */
+    retain(modelKey: string): () => void;
+    /** Subscribe to the effect stream (for `useSyncExternalStore`). */
+    subscribeEffects(listener: () => void): () => void;
+    /** The current snapshot, stable between changes. */
+    snapshot(): FoirLiveSnapshot;
+}
+/**
+ * What a UI can render that the adapter deliberately does not do for it.
+ *
+ * `newCounts` is the create case: a create cannot be spliced into a loaded page
+ * — record events carry no body, and even with one you could not place the row
+ * without knowing the query's sort — and refetching the head page instead
+ * prepends under a reader mid-scroll. So the count is the answer, and "3 new
+ * products — show" is the UI's decision to make.
+ */
+export interface FoirLiveSnapshot {
+    /** Records created per model since the last acknowledgement. */
+    newCounts: Readonly<Record<string, number>>;
+    /** Models whose `totalCount` is now approximate. */
+    totalCountStale: readonly string[];
+    /** The last change seen, per model. */
+    lastEvent: Readonly<Record<string, FoirRecordChangedEvent>>;
+}
+export interface FoirLiveProps extends FoirApplyOptions {
+    /**
+     * How to open a stream for a model. Usually
+     * `(modelKey, options, handlers) => (foir as never)[modelKey].onChange({ ...handlers, ...options })`.
+     *
+     * Injected rather than taking the client, because the client's model
+     * accessors are generated per project and this package cannot name them.
+     */
+    subscribe: FoirLiveSubscribeFn;
+    /** The query client to invalidate. Structurally typed; a real one satisfies it. */
+    queryClient: FoirQueryClientLike;
+    /** Default liveness for every model. Per-model overrides ride on `useFoirLive`. */
+    mode?: FoirLiveMode;
+    /**
+     * The cache can no longer be trusted — the server refused the resume cursor.
+     * Throw away what you hold and refetch; there is no way to know what was
+     * missed, which is why this is a callback rather than a quiet retry.
+     */
+    onResync?: (error: FoirRequestError, modelKey: string) => void;
+    onError?: (error: FoirRequestError, modelKey: string) => void;
+    /** Called for every applied change, after the query client has been told. */
+    onEffect?: (effect: FoirLiveEffect, event: FoirRecordChangedEvent) => void;
+    /**
+     * Re-read the record ids held for a model, on every reconnect.
+     *
+     * SUPPLY THIS ON ANY MODEL WHOSE RECORDS ARE PARTITIONED PER CALLER, or you
+     * will never see deletes. The server serves those models through a confined
+     * read that INNER JOINs `events` to `records` under the caller's own claims,
+     * and a deleted record — or one whose ownership moved away — matches nothing,
+     * so no event is ever emitted for it. The cursor replays what CHANGED; only
+     * this reports what VANISHED.
+     *
+     * Build it with `createFoirReconciler` from `@foir/sdk/live`, giving it a
+     * `resolve` that asks the model's own by-ids query which of the ids are still
+     * visible. That call discloses nothing, because the caller supplies the ids.
+     *
+     * Injected for the same reason `subscribe` is: the op that answers it is
+     * published per project in the manifest, so this package cannot name it.
+     */
+    reconcile?: (modelKey: string) => void;
+    /**
+     * How long to gather invalidations before refetching, in milliseconds.
+     *
+     * A burst on one model is one refetch, not fifty. 25ms by default: long
+     * enough to swallow a burst arriving over one socket read, short enough that
+     * a single change still feels immediate. `0` still coalesces within a tick.
+     */
+    coalesceWindowMs?: number;
+    /**
+     * How many refetches may run at once. Four by default — a burst spanning many
+     * keys must not open a request per key, which is a self-inflicted denial of
+     * service on the caller's own connection pool.
+     */
+    maxConcurrentRefetches?: number;
+    children?: ReactNode;
+}
+export declare function FoirLive(props: FoirLiveProps): ReactNode;
+/**
+ * Watch a model for as long as this component is mounted.
+ *
+ * The FIRST caller opens the stream and the LAST unmount closes it, so N
+ * components watching one model cost one subscription — and a screen that
+ * navigates away stops paying for one it is not reading.
+ */
+export declare function useFoirLive(modelKey: string): void;
+/**
+ * What has changed that the adapter deliberately did not apply.
+ *
+ * `useSyncExternalStore` rather than `useState`, so React 18 concurrent
+ * rendering cannot tear: two components reading this in the same render must
+ * see the same snapshot, and an event arriving mid-render must not give them
+ * different ones.
+ */
+export declare function useFoirLiveStatus(): FoirLiveSnapshot;
+/** Every query key for one model, for a caller driving its own refetch. */
+export { foirModelQueryKey };

package/dist/live/reconcile.d.ts

@@ -0,0 +1,82 @@
+import type { FoirTagIndex } from './tagIndex';
+/**
+ * The record ids this client currently holds for one model.
+ *
+ * Derived from the tag index rather than tracked separately, because the index
+ * already IS this bookkeeping: every cached response was written with the
+ * server's own `Surrogate-Key`, which names `rec:{id}` for each record it served
+ * and `model:{key}:{channel}` for the collection. Keeping a second list beside
+ * it would be a mirror with nothing detecting drift, and the direction it would
+ * drift in is an id that is quietly never reconciled.
+ *
+ * Entries are found by the MODEL tag and the ids read off their record tags, so
+ * an id only counts as held while some cached entry actually depends on it.
+ * Dropping that entry un-indexes it and it stops being reconciled, which is
+ * correct: nothing is showing it any more.
+ */
+export declare function foirHeldRecordIds(index: FoirTagIndex, modelKey: string): string[];
+/**
+ * Ask which of `ids` the caller can still see, for one model.
+ *
+ * Injected rather than built here, and that is deliberate twice over. The op
+ * that answers this is published per project in the manifest, so its NAME is not
+ * something this module can know; and injecting it keeps the reconcile logic
+ * testable for what it is — a set difference — without a client, a socket or a
+ * server.
+ *
+ * It must resolve to the ids that are STILL VISIBLE. Returning the ones that are
+ * gone would invert the result silently, so the contract is stated in the name.
+ *
+ * Whatever implements it must read under the CALLER's own authority. A resolve
+ * that ran with wider reach would report a record as still visible when the
+ * caller has lost it, which is precisely the case this exists to catch.
+ */
+export type FoirReconcileResolveFn = (modelKey: string, ids: readonly string[]) => Promise<readonly string[]>;
+export interface FoirReconcilerOptions {
+    resolve: FoirReconcileResolveFn;
+    /**
+     * The ids currently held for a model. Defaults to reading them off the tag
+     * index, which is the shape every consumer of this module already has.
+     */
+    heldIds?: (modelKey: string) => readonly string[];
+    /**
+     * A record the caller can no longer see. Evict it and anything that lists it.
+     *
+     * Called once per reconcile with every gone id, rather than once per id: the
+     * caller almost always wants a single invalidation pass, and N callbacks
+     * invite N refetches of the same list.
+     */
+    onGone: (modelKey: string, goneIds: readonly string[]) => void;
+    /**
+     * The largest number of ids to resolve in one call. Defaults to 200.
+     *
+     * A cap rather than an unbounded request, because the held set grows with
+     * everything the session has ever paged through, and one enormous request on
+     * every reconnect is how a flaky connection turns into a load problem.
+     */
+    batchSize?: number;
+    /**
+     * A resolve that failed. The reconcile is ABANDONED rather than treated as
+     * "everything is gone" — see below.
+     */
+    onError?: (error: unknown, modelKey: string) => void;
+}
+export interface FoirReconciler {
+    /**
+     * Reconcile one model, returning the ids found to be gone.
+     *
+     * Concurrent calls for the same model collapse onto the first: a reconnect
+     * storm must not multiply the read.
+     */
+    reconcile(modelKey: string): Promise<string[]>;
+}
+export declare function createFoirReconciler(options: FoirReconcilerOptions): FoirReconciler;
+/**
+ * The tags a set of gone records invalidates.
+ *
+ * The record tag for each, plus the MODEL tag once — a disappearance is a
+ * membership change, so every cached list on that model is now wrong in a way
+ * no `rec:` tag can express. That is the same rule `foirTagsForRecordChange`
+ * applies to a create, arrived at from the other end.
+ */
+export declare function foirTagsForGoneRecords(modelKey: string, goneIds: readonly string[]): string[];