@danxbot/ui 3.7.0 → 3.8.0

package/dist/types/lib/realtime/types.d.ts

@@ -0,0 +1,202 @@
+import type { RecordPayload } from "../records";
+/**
+ * What the socket says about itself.
+ *
+ * IT IS NOT THE SAME QUESTION AS "am I receiving events". A registry entry can
+ * lapse server-side while this reads `"connected"` forever, which is exactly
+ * why liveness is computed from three inputs and not from this one.
+ */
+export type RealtimeConnectionState = "connecting" | "connected" | "disconnected";
+/**
+ * WHICH RECORDS a subscription is asking to hear about.
+ *
+ * - `ids` — the rows on screen. The backend keys its registry entry per model
+ *   id, so this is the scope that pins specific records.
+ * - `filter` — a server-evaluated predicate. The backend re-runs it per save,
+ *   which is what makes a `created` event authoritative about set entry. It
+ *   answers "does this record match my filter" and NOTHING about sort position
+ *   or page boundary.
+ * - `all` — every record of the type for this tenant.
+ */
+export type RealtimeScope = {
+    readonly kind: "ids";
+    readonly ids: readonly string[];
+} | {
+    readonly kind: "filter";
+    readonly filter: Readonly<Record<string, unknown>>;
+} | {
+    readonly kind: "all";
+};
+/** What a caller may write, before normalization. `"all"` or ids or a filter. */
+export type RealtimeScopeInput = "all" | readonly (string | number)[] | {
+    readonly filter: Readonly<Record<string, unknown>>;
+};
+/** One server-side registration, as the transport receives it. */
+export interface SubscriptionRequest {
+    /** The NORMALIZED model name — never a `Resource` suffix. */
+    readonly type: string;
+    readonly scope: RealtimeScope;
+    /**
+     * The tenant this registration belongs to, passed rather than inferred so a
+     * request issued before a team switch can never be attributed to the team
+     * that came after it.
+     */
+    readonly tenant: string | number | undefined;
+    /** A stable identity for this (type, scope) pair. Useful as a request key. */
+    readonly key: string;
+}
+/**
+ * What the server said about a registration.
+ *
+ * `expiresAt` IS THE WHOLE POINT OF THIS TYPE. The registry holds it and treats
+ * a subscription as DEAD once the clock passes it minus a margin — never
+ * "letting it expire naturally", which is the prior art's exact wording and its
+ * exact bug: two failed keepalives inside one TTL window and that resource
+ * stops updating forever, silently, with a healthy socket.
+ */
+export interface SubscriptionLease {
+    /** Milliseconds since epoch. Omit only if the server genuinely does not say. */
+    readonly expiresAt?: number;
+}
+/** A joined socket channel. One per type per tenant, and no more. */
+export interface RealtimeChannel {
+    /**
+     * Bind one event name.
+     *
+     * CALLED AGAIN FOR EVERY NEW EVENT NAME A LATER SUBSCRIBER BRINGS, on the
+     * SAME channel object. The prior art returns early when the channel already
+     * exists and never reaches its own bind call, so only the FIRST subscriber's
+     * event names are ever live — two real subscribers collide on that today and
+     * one of them is silently dead in production. A transport implementation must
+     * therefore accept `bind` at any time, not only immediately after joining.
+     */
+    bind(event: string, handler: (payload: RecordPayload) => void): void;
+    /** Leave the channel entirely. Called on a tenant switch and on teardown. */
+    leave(): void;
+}
+/**
+ * Everything environment-specific, in one injected object: the socket, the
+ * three registry endpoints, and the connection observer.
+ *
+ * ONE CONSTRAINT ON THE IMPLEMENTATION THAT IS NOT EXPRESSIBLE IN THE TYPE, and
+ * it is the sharpest one: `subscribe`, `unsubscribe` and `keepalive` MUST NOT
+ * route their failures through an application's global 401 handler. A
+ * background resubscribe is allowed to fail; if that failure clears the
+ * session, a transient auth blip logs somebody out mid-screen — strictly worse
+ * than the stale screen the resubscribe existed to prevent. Reusing the app's
+ * default HTTP client is the easy thing to do and is exactly the bug. The
+ * registry holds up its half: it catches every rejection, backs off, and
+ * renders a DEAD state rather than escalating anything.
+ */
+export interface RealtimeTransport {
+    /** Register interest server-side. Rejecting is normal and is handled. */
+    subscribe(request: SubscriptionRequest): Promise<SubscriptionLease>;
+    /**
+     * Drop a registration.
+     *
+     * CALLED ONLY ON A TENANT SWITCH, never on unmount. The server keys its entry
+     * by USER, so two browser tabs belonging to one person share one entry — and
+     * one tab unmounting a screen would kill the other tab's still-mounted
+     * subscription, silently, with that tab's socket perfectly healthy. In-tab
+     * refcounting cannot fix that; the collision is above the tab. On unmount the
+     * entry is left to lapse against its own TTL, which costs a subscription
+     * outliving its component by a few minutes and nothing else.
+     */
+    unsubscribe(request: SubscriptionRequest): Promise<void>;
+    /**
+     * Renew several registrations at once.
+     *
+     * Resolve with one lease per request, in the SAME ORDER. Rejecting marks
+     * every request in the batch as failed — which is a DEAD subscription, not a
+     * warning, and the registry resubscribes rather than waiting.
+     */
+    keepalive(requests: readonly SubscriptionRequest[]): Promise<readonly SubscriptionLease[]>;
+    /** Join (or return) the channel carrying this type for this tenant. */
+    channel(type: string, tenant: string | number | undefined): RealtimeChannel;
+    connectionState(): RealtimeConnectionState;
+    observeConnection(listener: (state: RealtimeConnectionState) => void): () => void;
+}
+/**
+ * Why a subscription is not delivering, in the words a screen can print.
+ *
+ * A DEBUG PANEL SERVES DEVELOPERS; THE READER NEEDS A WORD ON SCREEN. This app
+ * refuses to collapse distinct absences everywhere else it has them, and a
+ * silently dead realtime layer is exactly the absence that gets collapsed by
+ * default — the prior art's observability is console-only behind a keyboard
+ * shortcut, which is why two live bugs in it went unnoticed for years.
+ */
+export type RealtimeStatus = 
+/** No transport was provided. Realtime is off and the app still works. */
+"unconfigured"
+/** Configured, nothing subscribed yet. */
+ | "idle"
+/** A first subscribe is in flight. */
+ | "connecting"
+/** Every active subscription is registered and the socket is connected. */
+ | "live"
+/** At least one subscription is not delivering. The screen should say so. */
+ | "dead";
+/** One subscription, as a devtools panel or a status line would render it. */
+export interface SubscriptionHealth {
+    readonly key: string;
+    readonly type: string;
+    readonly scope: RealtimeScope;
+    /** Bound event names — the UNION of every subscriber's, never the first's. */
+    readonly events: readonly string[];
+    readonly subscribers: number;
+    readonly expiresAt: number | undefined;
+    readonly dead: boolean;
+    /** Consecutive failed resubscribe attempts. Resets on success. */
+    readonly attempts: number;
+    readonly lastError: string | undefined;
+}
+/** The renderable liveness state. */
+export interface RealtimeHealth {
+    readonly status: RealtimeStatus;
+    readonly connection: RealtimeConnectionState;
+    readonly subscriptions: readonly SubscriptionHealth[];
+    /**
+     * Bumps whenever a subscription that WAS dead is restored.
+     *
+     * It is the "you may have missed events" signal, and it is deliberately a
+     * monotonic counter rather than a set of keys: a lapsed registry entry stops
+     * broadcasts without saying which ones were dropped, so the only honest claim
+     * is that something may be missing. The read binding folds it into a refetch
+     * of what is mounted — which keeps the answer on screen and marks it
+     * refreshing, rather than blanking to a skeleton.
+     */
+    readonly epoch: number;
+    readonly lastError: string | undefined;
+}
+/** Something worth recording. Observability only; never control flow. */
+export interface RealtimeDiagnostic {
+    readonly kind: "subscribed" | "resubscribed" | "subscribe-failed" | "keepalive-failed" | "expired" | "disconnected" | "event" | "self-event-dropped" | "unsubscribed";
+    readonly key?: string;
+    readonly type?: string;
+    readonly event?: string;
+    readonly message?: string;
+    readonly at: number;
+}
+/** One broadcast, after the registry has written it into the store. */
+export interface RealtimeEvent {
+    /** Normalized model name. */
+    readonly type: string;
+    /** The event name as bound, e.g. `"created"`. */
+    readonly event: string;
+    /**
+     * `Type:id`, or `undefined` when the payload was not a record OR the store
+     * refused the write — a record that did not land must not reach a list
+     * either.
+     */
+    readonly key: string | undefined;
+    /**
+     * Whether this is the event that means "entered the set".
+     *
+     * COMPUTED HERE rather than compared by the consumer, because the name is the
+     * backend's (`"created"` by default, configurable on the provider) and a
+     * consumer comparing the string would be the second place that fact lives.
+     */
+    readonly isCreate: boolean;
+    readonly payload: RecordPayload;
+    readonly tenant: string | number | undefined;
+}

package/dist/types/lib/records/define-record-type.d.ts

@@ -0,0 +1,29 @@
+import type { RecordTypeOptions, RecordTypeToken } from "./types";
+/**
+ * Declare a record type.
+ *
+ * THE NAME IS THE NORMALIZED MODEL NAME — `"WorkflowRun"`, NEVER
+ * `"WorkflowRunResource"`. This is the single most likely thing in this module
+ * to be built wrong, because both readings are plausible and exactly one
+ * matches: the store strips a trailing `Resource` from every incoming `__type`
+ * before keying (created payloads carry the suffix, deletes do not), so the
+ * caller always writes the model name. The wrong one produces a store that
+ * fills up and a screen that never moves, with no error anywhere — which is
+ * why passing the suffixed name warns loudly rather than quietly working.
+ *
+ * @param name normalized model name, e.g. `"WorkflowRun"`
+ * @param options `staleFields` — the fields this type's broadcast cannot carry
+ */
+export declare function defineRecordType<T>(name: string, options?: RecordTypeOptions): RecordTypeToken<T>;
+/**
+ * What a type declared, for the store's own use.
+ *
+ * An UNREGISTERED type is not an error: a nested child of a type nobody
+ * declared is still a record with an identity, and refusing it would lose data
+ * the parent legitimately carries. It simply has no stale fields, which is the
+ * correct default — a type that never declared a gap in its broadcast is
+ * treated as having none.
+ */
+export declare function staleFieldsFor(type: string): readonly string[] | "*";
+/** Test seam. Nothing in the library calls this. */
+export declare function resetRecordTypes(): void;

package/dist/types/lib/records/hooks.d.ts

@@ -0,0 +1,46 @@
+import type { ReadOptions, RecordState, RecordTypeToken, StalenessEntry } from "./types";
+/**
+ * Read one record.
+ *
+ * `needs` IS REQUIRED. It names the field set that must have landed from a
+ * FETCH before this key reports `present`; until then the answer is `unknown`,
+ * even when a broadcast has already seeded the key with real values. That is
+ * the whole guard: a projection function handed a broadcast-seeded record
+ * assumes absent means empty and renders a confident, wrong answer.
+ *
+ * `id` may be `null`/`undefined` for a conditional read — the hook then holds
+ * no subscription and reports `unknown`, rather than forcing a caller into two
+ * code paths around a rule of hooks.
+ */
+export declare function useRecord<T>(token: RecordTypeToken<T>, id: string | number | null | undefined, options: ReadOptions): RecordState<T>;
+/**
+ * Read many records at once, sharing one hydration per key with every other
+ * reader of that key.
+ *
+ * IT TAKES A KEY LIST AND DERIVES A STRING FROM IT rather than depending on the
+ * array's identity, so a caller passing a freshly-mapped array on every render
+ * — the normal thing to do — does not re-subscribe and does not violate
+ * `getSnapshot` identity. The alternative, subscribing to the whole store for a
+ * set of records, is the anti-pattern this package already ships once in
+ * `createSimStore.useById`; per-key notification is the entire reason this
+ * store exists.
+ */
+export declare function useRecords<T>(token: RecordTypeToken<T>, ids: readonly (string | number)[], options: ReadOptions): readonly RecordState<T>[];
+/**
+ * The staleness signal: affected ROOTS and their now-stale field sets.
+ *
+ * ITS ONLY CONSUMER IS THE LAYER THAT PERFORMED THE ORIGINAL FETCH. It
+ * re-issues the request it already made — it needs no registry of loaders,
+ * because "which field set" is not a question it has to answer; it is the one
+ * it already asked. The library contributes the signal and nothing else, which
+ * is what keeps every endpoint and every type name out of this package.
+ *
+ * TWO PROPERTIES THE CONSUMER MUST SUPPLY, because they are not expressible
+ * here: coalescing in BREADTH (twenty-five rows going stale in one burst is one
+ * list refetch, not twenty-five record refetches) and in TIME (a minimum
+ * interval, plus dedup against a refetch already in flight — a second signal
+ * arriving mid-flight sets a re-run flag rather than issuing a second request).
+ * Breadth alone is not enough: an event with no change guard on the server
+ * fires continuously during a long job, so it is a stream rather than a burst.
+ */
+export declare function useStaleness(): readonly StalenessEntry[];

package/dist/types/lib/records/index.d.ts

@@ -0,0 +1,5 @@
+export { defineRecordType, resetRecordTypes } from "./define-record-type";
+export { useRecord, useRecords, useStaleness } from "./hooks";
+export { write, writeAll, peekRecord, readState, readStaleness, subscribeToKey, subscribeToStaleness, retainKeys, sweepRecords, setRecordStoreTenant, getRecordStoreTenant, flushRecordNotifications, resetRecordStore, recordStoreStats, UNKNOWN_STATE, } from "./store";
+export { normalizeTypeName, normalizeTimestamp, recordKey, isRecordRef, type RecordRef } from "./wire";
+export type { ReadOptions, RecordPayload, RecordState, RecordTypeOptions, RecordTypeToken, StalenessEntry, WriteAllResult, WriteOptions, WriteResult, WriteSource, WriteVerdict, } from "./types";

package/dist/types/lib/records/store.d.ts

@@ -0,0 +1,117 @@
+import type { RecordPayload, RecordState, StalenessEntry, WriteAllResult, WriteOptions, WriteResult } from "./types";
+/**
+ * Declare which tenant this store is holding records for.
+ *
+ * Changing it CLEARS the store. The keys are `Type:id` with no tenant in them,
+ * so team B's demand #7 would merge onto team A's demand #7 — in an app whose
+ * read key is deliberately team-scoped precisely to prevent that. Clearing
+ * handles what is already written; the `tenant` parameter on `write` handles
+ * what is still in the air.
+ */
+export declare function setRecordStoreTenant(tenant: string | number | undefined): void;
+export declare function getRecordStoreTenant(): string | number | undefined;
+/**
+ * The single writer. A fetch response, a mutation's returned item and a
+ * broadcast all arrive here, so fetch-versus-broadcast reconciliation lives in
+ * ONE place rather than split across two modules that would each hold half the
+ * rule.
+ */
+export declare function write(payload: RecordPayload, options: WriteOptions): WriteResult;
+/**
+ * The plural form — REQUIRED, not a convenience.
+ *
+ * A list page is fifty payloads, and fifty singular writes are fifty
+ * notification passes and fifty render passes for one page load. Every write
+ * in one call coalesces into a single notification.
+ */
+export declare function writeAll(payloads: readonly RecordPayload[], options: WriteOptions): WriteAllResult;
+/**
+ * The `unknown` state, as ONE module-level frozen constant.
+ *
+ * `getServerSnapshot` returns this. A fresh literal there throws under the only
+ * condition it exists for.
+ */
+export declare const UNKNOWN_STATE: RecordState<never>;
+export declare function getUnknownState(): RecordState<never>;
+/**
+ * What a reader is told about one key, gated on the field set it declared it
+ * needs.
+ *
+ * The gate is what stops a record seeded ONLY by a broadcast from reaching a
+ * projection function that assumes absent means empty — which renders a
+ * confident "0 documents" for a record with hundreds.
+ */
+export declare function readState(key: string, needs: string): RecordState<unknown>;
+/** Non-reactive read, for callers outside a component. */
+export declare function peekRecord(type: string, id: string | number, needs: string): RecordState<unknown>;
+/**
+ * NOTIFICATION IS COALESCED PER ANIMATION FRAME, and that is a requirement.
+ *
+ * A document transcoding page by page broadcasts once per row. Un-coalesced,
+ * every one of those is a separate notification, a separate dep scan per
+ * subscriber and a separate render pass. Coalescing collapses a burst into a
+ * handful.
+ *
+ * Exported so a caller that must observe the effect of a write synchronously —
+ * a test, or a measurement taken immediately after a write — can flush rather
+ * than wait for a frame.
+ */
+export declare function flushRecordNotifications(): void;
+export declare function subscribeToKey(key: string, listener: () => void): () => void;
+export declare function subscribeToStaleness(listener: () => void): () => void;
+/**
+ * Affected ROOTS and their now-stale field sets.
+ *
+ * The signal names ROOTS rather than the key that went stale, because the key
+ * that goes stale is often a nested one — a run under a demand — and a list of
+ * demands can never match a run's key. Roots come from the hydration memo's
+ * deps map, so a root is by definition something a mounted read or a list slot
+ * is already holding.
+ *
+ * The library names no type it understands and no endpoint: the layer that
+ * performed the original fetch re-issues it, because it is the only layer that
+ * knows which field set it asked for.
+ */
+export declare function readStaleness(): readonly StalenessEntry[];
+export declare function getEmptyStaleness(): readonly StalenessEntry[];
+/**
+ * Pin keys as ROOTS for the duration of the returned release.
+ *
+ * A key is retained if it is REACHABLE from a root, never if it is itself
+ * pinned: a file is never independently subscribed — it is reached only by
+ * hydrating its demand — so evicting by direct subscription would evict exactly
+ * what hydration walks and leave dangling refs everywhere.
+ *
+ * Release is IDEMPOTENT and exactly paired with acquire, which is what makes
+ * StrictMode's mount / unmount / mount survivable. A subscription whose
+ * teardown is not idempotent tears down the one it just created — and it
+ * misbehaves only in development, which is the worst place for that to live,
+ * because that is where it is being debugged.
+ */
+export declare function retainKeys(keys: readonly string[]): () => void;
+/**
+ * Mark from the roots, then sweep everything unreachable.
+ *
+ * AN IDENTITY MAP THAT ONLY GROWS IS A LEAK, and the failure mode is a tab that
+ * gets slower over an afternoon with nobody connecting it to this. Browsing ten
+ * documents at 435 rows each is roughly 4,000 entries nothing releases.
+ *
+ * WHEN TO CALL IT IS THE CALLER'S DECISION, and it needs to be more than a
+ * navigation boundary: a broadcast can CREATE a key no root reaches, and on a
+ * screen nobody navigates away from — a long extraction, say — those accumulate
+ * for as long as the tab is open. A navigation boundary AND a bounded schedule.
+ * This module deliberately installs no timer of its own; a design-system module
+ * that starts an interval on import is a worse defect than the leak.
+ *
+ * @returns how many keys were dropped
+ */
+export declare function sweepRecords(): number;
+/** Wipes everything, including listeners, roots and the tenant. */
+export declare function resetRecordStore(): void;
+/** What the store holds right now, for a devtools panel or a test. */
+export declare function recordStoreStats(): {
+    records: number;
+    memos: number;
+    roots: number;
+    listeners: number;
+};

package/dist/types/lib/records/types.d.ts

@@ -0,0 +1,188 @@
+/**
+ * A payload as it arrives off the wire — from a fetch response, from a
+ * mutation's returned item, or from a broadcast.
+ *
+ * DELIBERATELY LOOSE. The store requires exactly two things of it (`__type`
+ * and `id`) and interprets five more (`__timestamp`, `__deleted_at`,
+ * `deleted_at`, `__stale`, `__model`). Everything else is data it carries
+ * without understanding — which is the whole of this module's claim to being
+ * domain-agnostic.
+ */
+export interface RecordPayload {
+    readonly [field: string]: unknown;
+}
+/**
+ * How a payload arrived. NOT telemetry — each value changes real behaviour:
+ *
+ * - `"fetch"` may SATISFY a field-set tag and CLEARS staleness on every field
+ *   it carries. A broadcast can never do either, because a broadcast is
+ *   partial by whitelist and can never complete a record.
+ * - `"broadcast"` is the only source that MARKS a field stale, using the
+ *   `staleFields` its type declared. Saying so out loud prevents the obvious
+ *   wrong reading, in which a fetch that omits a stale-declared field re-marks
+ *   it and the refetch loop never settles.
+ *
+ * A mutation's returned item is a `"fetch"`: it is a full server answer to a
+ * request this client made, so it may satisfy a tag.
+ */
+export type WriteSource = "fetch" | "broadcast";
+/** Options every write carries. */
+export interface WriteOptions {
+    readonly source: WriteSource;
+    /**
+     * The tenant the REQUEST was issued under — stamped by the caller at request
+     * time, never read from module state inside `write`.
+     *
+     * Reading it inside `write` would read the tenant as it is NOW, which is
+     * precisely the bug this parameter exists to prevent: a team-A response that
+     * resolves after a switch to team B would write team A's records into a
+     * store now being read as team B's. A broadcast is stamped with the tenant
+     * whose channel delivered it, which the subscription already knows. So both
+     * sources carry it and neither infers it.
+     */
+    readonly tenant?: string | number;
+    /**
+     * An OPAQUE field-set name — `"card"`, `"detail"`, whatever the caller's own
+     * api layer already calls the selector it asked for. The store never
+     * interprets it; it records which tags a key has satisfied and compares them
+     * for equality, so the library still knows nothing about any type's fields.
+     *
+     * Only a `"fetch"` may satisfy a tag. It is what makes `useRecord(…,
+     * {needs:"card"})` report `unknown` for a record seeded only by a broadcast,
+     * rather than handing a projection function a record with no `files` and no
+     * `workflow_runs` — which renders a confident "0 documents" card for a
+     * 434-page demand.
+     */
+    readonly tag?: string;
+}
+/**
+ * What a write did. Every value is observable so a refusal leaves a trace: the
+ * prior art in this codebase records nothing at all on rejection, which is why
+ * its out-of-order guard was inert for years without anyone noticing.
+ *
+ * - `applied` — accepted, and something a reader can observe changed.
+ * - `unchanged` — accepted, and nothing changed. NOBODY IS NOTIFIED. A
+ *   redelivered duplicate must not invalidate every hydration memo that
+ *   touched the key and re-render every subscriber.
+ * - `dropped-older` — strictly older than the record's own stored timestamp.
+ * - `dropped-tenant` — stamped for a tenant this store is no longer serving.
+ * - `rejected-shape` — not a record at all: no `__type`, no `id`, or a
+ *   `{__stale:true}` ping, which carries neither.
+ */
+export type WriteVerdict = "applied" | "unchanged" | "dropped-older" | "dropped-tenant" | "rejected-shape";
+/** The result of one `write`. */
+export interface WriteResult {
+    readonly verdict: WriteVerdict;
+    /**
+     * Every key this write touched, INCLUDING nested ones — a demand payload
+     * carrying 434 files returns 435 keys.
+     *
+     * The caller that issued a refetch to clear a staleness signal needs this to
+     * decide whether the write it just made actually satisfied what it was
+     * issued for. Empty for every dropped or rejected verdict.
+     */
+    readonly keys: readonly string[];
+    /** Why, for the verdicts that are refusals. Present only when it helps. */
+    readonly reason?: string;
+}
+/** The result of one `writeAll`. */
+export interface WriteAllResult {
+    /** One entry per payload, in the order they were given. */
+    readonly results: readonly WriteResult[];
+    /** The union of every payload's touched keys, de-duplicated. */
+    readonly keys: readonly string[];
+}
+/**
+ * What a reader is told about one key.
+ *
+ * FOUR ABSENCES, NOT ONE. Never-fetched, deleted and broadcast-partial are
+ * different answers and a screen renders each of them differently. The fourth —
+ * a 404 — is deliberately NOT a member: a refusal carries a message and a
+ * remedy that the store has no way to build, so it belongs to whatever layer
+ * performed the request.
+ *
+ * `stale` is part of the state rather than a side channel because a write that
+ * changes no value but marks a field stale must still notify — and notifying
+ * for something no reader can observe is worse than not notifying at all.
+ */
+export type RecordState<T> = {
+    readonly status: "unknown";
+} | {
+    readonly status: "present";
+    readonly record: T;
+    /** Bumps on every accepted write that changed something observable. */
+    readonly version: number;
+    /**
+     * Fields the last broadcast could not carry. Sorted, so two structurally
+     * equal stale sets compare equal.
+     *
+     * A held stale value can only be stale-LOW for a monotonic high-water
+     * mark, never stale-high, so holding the last number on screen while the
+     * refetch lands is honest. Dimming it is available, not mandatory.
+     */
+    readonly stale: readonly string[];
+} | {
+    readonly status: "deleted";
+    readonly at: string;
+};
+/** What `useRecord`/`useRecords` require of their caller. */
+export interface ReadOptions {
+    /**
+     * REQUIRED, not optional. The tag a `"fetch"` must have satisfied before
+     * this key reports `present`.
+     *
+     * The tag mechanism existed once as an optional parameter and nothing forced
+     * a caller to use it, which reopened the exact hole it was introduced to
+     * close. One word in the signature is the whole fix.
+     */
+    readonly needs: string;
+}
+/**
+ * A registered record type: the runtime string and the compile-time type, so
+ * the two can never drift.
+ *
+ * `_record` is a phantom — it carries `T` through inference and holds no value
+ * at runtime.
+ */
+export interface RecordTypeToken<T> {
+    /** The NORMALIZED model name. Never carries a `Resource` suffix. */
+    readonly type: string;
+    /** @see RecordTypeOptions.staleFields */
+    readonly staleFields: readonly string[] | "*";
+    /** Phantom. Never read. */
+    readonly _record?: T;
+}
+/** What a type may declare at registration. */
+export interface RecordTypeOptions {
+    /**
+     * The fields this type's BROADCAST cannot carry — because they are computed,
+     * or deliberately withheld from the whitelist. Everything else in a
+     * broadcast merges normally.
+     *
+     * Staleness is PER FIELD and never a whole-type on/off switch. A per-type
+     * binary discards the twelve real fields a broadcast does carry in order to
+     * signal the two it does not.
+     *
+     * `"*"` means every data field — the case where a type's broadcast carries
+     * identity and nothing else, and where the field set is not knowable at
+     * registration because it is a bag of dynamic attributes. It resolves at
+     * write time against the keys the record actually holds; see
+     * `resolveStaleFields` in `store.ts` for what that buys and what it costs.
+     */
+    readonly staleFields?: readonly string[] | "*";
+}
+/**
+ * One root affected by a staleness mark, and the fields under it that are now
+ * suspect.
+ *
+ * `key` is a ROOT, not the key that went stale. For a queue, the key that goes
+ * stale is a run while the list holds demands; naming the raw key would match
+ * no list slot and nothing would ever refetch. Roots are resolved through the
+ * hydration memo's deps map, which is safe in a way a maintained reverse index
+ * is not: it is rebuilt by the same walk that reads it, so there is no separate
+ * maintenance step to get wrong.
+ */
+export interface StalenessEntry {
+    readonly key: string;
+    readonly fields: readonly string[];
+}