@ai-matrx/records 0.42.0 → 0.44.1

package/dist/react/index.d.cts

@@ -2078,6 +2078,11 @@ declare const STORE_DOORS: readonly [{
     readonly args: "p_organization_id uuid, p_table_id uuid, p_by_id boolean DEFAULT false, p_limit integer DEFAULT 200, p_offset integer DEFAULT 0";
     readonly returns: "TABLE(id uuid, document jsonb, level permission_level)";
     readonly security: "definer";
+}, {
+    readonly name: "read_records_by_ids";
+    readonly args: "p_organization_id uuid, p_table_id uuid, p_record_ids uuid[], p_by_id boolean DEFAULT false";
+    readonly returns: "TABLE(id uuid, document jsonb, level permission_level)";
+    readonly security: "definer";
 }, {
     readonly name: "realtime_topic_admits";
     readonly args: "p_topic text";
@@ -2198,6 +2203,11 @@ declare const STORE_DOORS: readonly [{
     readonly args: "p_organization_id uuid, p_record_id uuid";
     readonly returns: "TABLE(field_key text, field_id uuid, value jsonb, value_version integer, source jsonb, absent_reason text, actor text, on_behalf_of text, written_at timestamp with time zone, alternates jsonb)";
     readonly security: "definer";
+}, {
+    readonly name: "record_words";
+    readonly args: "p_organization_id uuid, p_record_id uuid, p_noun text DEFAULT NULL::text";
+    readonly returns: "text";
+    readonly security: "definer";
 }, {
     readonly name: "record_write";
     readonly args: "p_organization_id uuid, p_table_id uuid, p_data jsonb";
@@ -2253,6 +2263,16 @@ declare const STORE_DOORS: readonly [{
     readonly args: "p_organization_id uuid, p_container_id uuid, p_item_id uuid";
     readonly returns: "integer";
     readonly security: "definer";
+}, {
+    readonly name: "relation_words";
+    readonly args: "p_organization_id uuid, p_field_id uuid, p_value text";
+    readonly returns: "text";
+    readonly security: "definer";
+}, {
+    readonly name: "relation_words_many";
+    readonly args: "p_organization_id uuid, p_field_id uuid, p_record_ids uuid[]";
+    readonly returns: "TABLE(record_id uuid, words text)";
+    readonly security: "definer";
 }, {
     readonly name: "reopen_declared_doors";
     readonly args: "";
@@ -3141,7 +3161,7 @@ declare const STORE_KNOBS: readonly [{
  */
 declare const STORE_REFUSAL_CODES: readonly [{
     readonly code: "02000";
-    readonly raised_by: "_checklist_instantiate,checklist_declare,checklist_run,checklist_step_complete,checklist_step_refusal,checklist_template_shape,conversation_scope_bind,dashboard_delete,dashboard_run,doc_letterhead,doc_render_body,doc_render_document,doc_render_read,doc_sign,doc_signature_intact,doc_signature_read,doc_template_delete,doc_template_read,doc_template_save,enrich_pin,entity_field_retire,entity_field_update,entity_record_read,entity_value_write,external_history_event,external_rows,external_stub_upsert,external_writes_set,io_restore,migrate_delete,migrate_extract_parent,migrate_merge,migrate_reclass,migrate_rename,migrate_reparent,migrate_retype,migrate_split,migrate_undo,organization_clear,portal_card,portal_declare,portal_invite,portal_preview,portal_principal_bind,portal_revoke,read_record,record_delete,record_restore,record_restore_preview,record_table,record_update,relation_uncarry,share_access,share_grant,share_lane_set,share_people,share_revoke,sign_request_cancel,sign_request_create,sign_request_remind,sign_request_unchanged,table_share_outside_accept,table_share_outside_invite,table_share_outside_resend,table_share_outside_revoke,visibility_as_of,work_approval_decide,work_approval_read,work_approval_request,work_assign,work_record_states,work_set_state";
+    readonly raised_by: "_checklist_instantiate,_table_share_invite_payload,checklist_declare,checklist_run,checklist_step_complete,checklist_step_refusal,checklist_template_shape,conversation_scope_bind,dashboard_delete,dashboard_run,doc_letterhead,doc_render_body,doc_render_document,doc_render_read,doc_sign,doc_signature_intact,doc_signature_read,doc_template_delete,doc_template_read,doc_template_save,enrich_pin,entity_field_retire,entity_field_update,entity_record_read,entity_value_write,external_history_event,external_rows,external_stub_upsert,external_writes_set,io_restore,migrate_delete,migrate_extract_parent,migrate_merge,migrate_reclass,migrate_rename,migrate_reparent,migrate_retype,migrate_split,migrate_undo,organization_clear,portal_card,portal_declare,portal_invite,portal_preview,portal_principal_bind,portal_revoke,read_record,record_delete,record_restore,record_restore_preview,record_table,record_update,relation_uncarry,share_access,share_grant,share_lane_set,share_people,share_revoke,sign_request_cancel,sign_request_create,sign_request_remind,sign_request_unchanged,table_share_outside_accept,table_share_outside_invite,table_share_outside_resend,table_share_outside_revoke,visibility_as_of,work_approval_decide,work_approval_read,work_approval_request,work_assign,work_record_states,work_set_state";
 }, {
     readonly code: "0A000";
     readonly raised_by: "checklist_step_complete,external_rows,external_source_declare,external_write_through,promote_field,promoted_index_expr,promoted_query_sql,promoted_read,rule_eval,work_assign";
@@ -3159,22 +3179,22 @@ declare const STORE_REFUSAL_CODES: readonly [{
     readonly raised_by: "rule_eval";
 }, {
     readonly code: "22023";
-    readonly raised_by: "_booking_availability,_entity_custom_fields_guard,_value_envelope,_work_shape_guard,actor_word,agg_assert_key,agg_sql,anon_token_issue,booking_declare,containment_parent,dashboard_block_normalize,dashboard_window_sql,doc_render_body,doc_render_write,doc_signature_write,enrich_declare,enrich_land,enrich_normalize,enrich_pin,entity_value_write,external_history_event,external_source_declare,external_stub_upsert,external_write_through,field_history,io_export,io_import_begin,io_import_finish,io_import_plan,io_import_report,io_proposal_accept,migrate_merge,migrate_reclass,my_levels,organization_clear,page_size,pin_agent_cells,pipeline_move,portal_declare,provenance_write,query_by_coordinates,query_rollup,record_update,record_write_many,relation_carry,rule_eval,rule_members,share_grant,share_lane_set,sign_request_create,sign_request_sign,subscription_declare,table_rules,visibility_as_of,work_approval_request,work_list,work_slot_hold";
+    readonly raised_by: "_booking_availability,_entity_custom_fields_guard,_take_op_id,_value_envelope,_work_shape_guard,actor_word,agg_assert_key,agg_sql,anon_token_issue,booking_declare,containment_parent,dashboard_block_normalize,dashboard_window_sql,doc_render_body,doc_render_write,doc_signature_write,enrich_declare,enrich_land,enrich_normalize,enrich_pin,entity_value_write,external_history_event,external_source_declare,external_stub_upsert,external_write_through,field_history,io_export,io_import_begin,io_import_finish,io_import_plan,io_import_report,io_proposal_accept,migrate_merge,migrate_reclass,my_levels,organization_clear,page_size,pin_agent_cells,pipeline_move,portal_declare,provenance_write,query_by_coordinates,query_rollup,record_update,record_write_many,relation_carry,rule_eval,rule_members,share_grant,share_lane_set,sign_request_create,sign_request_sign,subscription_declare,table_rules,visibility_as_of,work_approval_request,work_list,work_slot_hold";
 }, {
     readonly code: "23503";
-    readonly raised_by: "_booking_availability,_checklist_instantiate,_containment_guard,_field_document_for,_pipeline_stage_key,_record_rule_uses,agg_digest_assemble,anon_publish,anon_rate_take,anon_token_issue,anon_write,assert_organization_wall,booking_cancel,booking_confirm,booking_declare,booking_hold,booking_reschedule,capture_publish,checklist_declare,checklist_steps_table,comment_write,dashboard_declare,delete_rule,doc_sign,doc_template_save,enrich_declare,enrich_due,enrich_land,form_declare,form_submit,home_add,inbound_declare,inbound_mail_land,inbound_set,io_comment_write,io_import_begin,io_import_finish,io_import_report,io_import_rows,io_proposal_accept,migrate_demote,migrate_promote,pipeline_board,pipeline_declare,pipeline_move,pipeline_read,pipeline_transition_refusal,promote_field,promote_table,record_applicability,record_reparent,relation_carry,relation_own,resolve_first_match,rule_applies,rule_declare,rule_eval,rule_members,rule_run,sign_request_create,subscription_mute,subscription_preview,view_declare,work_set_state,work_take_assignment,work_template_instantiate";
+    readonly raised_by: "_booking_availability,_checklist_instantiate,_containment_guard,_display_spec_for,_field_document_for,_pipeline_stage_key,_record_rule_uses,agg_digest_assemble,anon_publish,anon_rate_take,anon_token_issue,anon_write,assert_organization_wall,booking_cancel,booking_confirm,booking_declare,booking_hold,booking_reschedule,capture_publish,checklist_declare,checklist_steps_table,comment_write,dashboard_declare,delete_rule,doc_sign,doc_template_save,enrich_declare,enrich_due,enrich_land,form_declare,form_submit,home_add,inbound_declare,inbound_mail_land,inbound_set,io_comment_write,io_import_begin,io_import_finish,io_import_report,io_import_rows,io_proposal_accept,migrate_demote,migrate_promote,pipeline_board,pipeline_declare,pipeline_move,pipeline_read,pipeline_transition_refusal,promote_field,promote_table,record_applicability,record_reparent,relation_carry,relation_own,resolve_first_match,rule_applies,rule_declare,rule_eval,rule_members,rule_run,sign_request_create,subscription_mute,subscription_preview,view_declare,work_set_state,work_take_assignment,work_template_instantiate";
 }, {
     readonly code: "23505";
     readonly raised_by: "_unique_rule_holds,doc_sign,doc_signature_write,entity_field_declare,field_declare,home_add,inbound_declare,io_proposal_accept,relation_carry,relation_own,share_grant,sign_request_cancel,sign_request_create,table_share_outside_invite,table_share_outside_resend,work_approval_decide,work_slot_hold";
 }, {
     readonly code: "23514";
-    readonly raised_by: "_checklist_instantiate,_checklist_step_guard,_containment_guard,_dated_values_guard,_derived_fields,_entity_custom_fields_guard,_field_class_guard,_field_document_for,_field_shape_guard,_field_type_parity_guard,_merge_field_shape_guard,_merge_field_temporal_guard,_promoted_field_cap_guard,_record_rule_uses,_resolve_choice_words,_rule_shape_guard,_rule_topology_guard,_store_relation_edge_names_its_field,_table_columns_word_guard,_table_shape_guard,_undeclared_key_guard,_value_envelope,_work_shape_guard,_workdoors_approval_guard,assert_columns_are_defined,assert_entity_is_organization_scoped,capture_publish,capture_sheet_declare,checklist_declare,checklist_step_complete,doc_sign,doc_signature_write,doc_template_save,entity_field_declare,entity_field_retire,entity_field_update,entity_records_find,entity_table,field_declare,field_retire,field_update,home_add,io_import_rows,migrate_merge,relation_carry,relation_own,sign_request_create,sign_request_sign,table_declare,validate_value_envelope,validate_values,work_set_state,work_slots_declare,work_take_assignment,work_template_instantiate";
+    readonly raised_by: "_checklist_instantiate,_checklist_step_guard,_containment_guard,_dated_values_guard,_derived_fields,_display_spec_for,_entity_custom_fields_guard,_field_class_guard,_field_document_for,_field_shape_guard,_field_type_parity_guard,_merge_field_shape_guard,_merge_field_temporal_guard,_promoted_field_cap_guard,_record_rule_uses,_resolve_choice_words,_rule_shape_guard,_rule_topology_guard,_store_relation_edge_names_its_field,_table_columns_word_guard,_table_shape_guard,_undeclared_key_guard,_value_envelope,_with_display,_work_shape_guard,_workdoors_approval_guard,assert_columns_are_defined,assert_entity_is_organization_scoped,booking_declare,capture_publish,capture_sheet_declare,checklist_declare,checklist_step_complete,doc_sign,doc_signature_write,doc_template_save,entity_field_declare,entity_field_retire,entity_field_update,entity_records_find,entity_table,field_declare,field_retire,field_update,home_add,io_import_rows,migrate_merge,relation_carry,relation_own,sign_request_create,sign_request_sign,table_declare,validate_value_envelope,validate_values,work_set_state,work_slots_declare,work_take_assignment,work_template_instantiate";
 }, {
     readonly code: "40001";
     readonly raised_by: "has_visibility_at";
 }, {
     readonly code: "42501";
-    readonly raised_by: "_doc_render_immutable,_doc_signature_immutable,_field_definition_write,_field_write_door,_rule_definition_write,_store_door,anon_capture,anon_inbound_land,anon_publish,anon_token_issue,anon_token_verify,anon_write,assert_client_may_change,assert_client_may_open,assert_client_may_reach,assert_may_know_table,assert_organization_admin,assert_store_door,booking_confirm,booking_declare,booking_hold,capture_submit,checklist_run,comment_write,conversation_scope_bind,conversation_scope_unbind,enrich_declare,enrich_due,enrich_land,enrich_normalize,entity_field_declare,entity_field_retire,entity_field_update,entity_value_write,external_write_through,form_declare,form_submit,inbound_mail_land,io_comment_resolve,io_comment_write,io_import_begin,io_import_finish,io_restore,migrate_purge,migrate_reclass,my_levels,organization_clear,portal_declare,portal_invitation,portal_invite,portal_principal_bind,promote_table,query_visibility_parity,read_record,read_records,record_table,share_grant,subscription_mute,subscription_preview,table_share_outside_accept,table_share_outside_invite,table_share_outside_resend,visibility_as_of,work_approval_decide,work_approval_read,work_approval_request,work_person";
+    readonly raised_by: "_doc_render_immutable,_doc_signature_immutable,_field_definition_write,_field_write_door,_rule_definition_write,_store_door,anon_capture,anon_inbound_land,anon_publish,anon_token_issue,anon_token_verify,anon_write,assert_client_may_change,assert_client_may_open,assert_client_may_reach,assert_may_know_table,assert_organization_admin,assert_store_door,booking_confirm,booking_declare,booking_hold,capture_submit,checklist_run,comment_write,conversation_scope_bind,conversation_scope_unbind,enrich_declare,enrich_due,enrich_land,enrich_normalize,entity_field_declare,entity_field_retire,entity_field_update,entity_value_write,external_write_through,form_declare,form_submit,inbound_mail_land,io_comment_resolve,io_comment_write,io_import_begin,io_import_finish,io_restore,migrate_purge,migrate_reclass,my_levels,organization_clear,portal_declare,portal_invitation,portal_invite,portal_principal_bind,promote_table,query_visibility_parity,read_record,read_records,read_records_by_ids,record_table,share_grant,subscription_mute,subscription_preview,table_share_outside_accept,table_share_outside_invite,table_share_outside_resend,visibility_as_of,work_approval_decide,work_approval_read,work_approval_request,work_person";
 }, {
     readonly code: "42703";
     readonly raised_by: "entity_table,portal_declare";
@@ -3757,6 +3777,31 @@ interface FieldRule {
  * `custom.field` — the ONE definitions table (FLD-8), organization-scoped, so
  * two organizations add different fields to the same standard table.
  */
+/**
+ * WHICH OF THE OTHER RECORD'S COLUMNS A RELATION SHOWS (REL-DISP, 2026-09-21).
+ *
+ * A Table has ONE stored default reference column — its `title_field` — and until
+ * this existed every relation pointing at that Table could display that column and
+ * nothing else. A Jobs board could read "Maria Chen" but never "Maria Chen —
+ * Rincon", and two columns could not be joined into one string at all.
+ *
+ * ABSENT MEANS THE TABLE'S OWN COLUMN. A field with no `display` resolves exactly
+ * as it did before, so nothing changes for a column nobody has given a spec to.
+ *
+ * The store judges it once, in `custom._display_spec_for`: every column named must
+ * exist on the target Table, and the refusal names the one that does not. It is
+ * resolved by ONE body, `custom._words_for`, which `custom.record_words`,
+ * `custom._card_words`, `custom.relation_words` and `custom.relation_words_many`
+ * are all one-liners onto — so the thirteen store-side readers inherit it too.
+ *
+ * A display column that is itself a relation resolves ONE hop and never a second.
+ */
+interface RelationDisplay {
+    /** The target's columns, in the order they are shown. */
+    columns: string[];
+    /** What goes between them. Defaults to a single space. */
+    separator: string;
+}
 interface Field {
     id: Uuid;
     organization_id: Uuid;
@@ -3785,6 +3830,8 @@ interface Field {
     on_target_delete: OnDelete | null;
     /** REL-9. The reverse is visible from both ends and is NOT a second Field. */
     inverse_key: string | null;
+    /** REL-DISP. Which of the target's columns this one shows. Null = the Table's own. */
+    display: RelationDisplay | null;
     source: FieldSource;
     source_config: Record<string, unknown>;
     /** FLD-9. A Formula declares whether it computes on read or on write. */
@@ -3912,6 +3959,12 @@ interface NewFieldDeclaration {
     relation_target?: Uuid;
     /** REL-2. What happens to this record when the thing it points at goes. */
     on_target_delete?: OnDelete;
+    /**
+     * REL-DISP. Which of the target's columns this one shows, and what joins them.
+     * A bare column name and a plain list are both accepted by the door and
+     * normalised; leaving it out keeps the target Table's own reference column.
+     */
+    display?: RelationDisplay | string[] | string;
     /**
      * Presentation and behaviour settings the store carries verbatim — a long
      * text's `multiline`, a list's existing options table. The door has always
@@ -3981,6 +4034,12 @@ interface FieldPatch {
     /** REL / FLD-11: re-point the column. The old edges are withdrawn by the door. */
     relation_target?: Uuid;
     on_target_delete?: OnDelete;
+    /**
+     * REL-DISP. Which of the target's columns this one shows. `null` REMOVES the
+     * spec and the column goes back to whatever the table it points at is titled by;
+     * the door refuses it by name on a column that points at nothing.
+     */
+    display?: RelationDisplay | string[] | string | null;
     /** SEAT-SUITES: whether the store builds an index for this column, and a unique one. */
     promoted?: boolean;
     unique?: boolean;
@@ -6565,14 +6624,37 @@ interface RecordsActor {
  */
 interface RecordsRealtimePort {
     /**
-     * Watch one organization's records of one table. Returns an unsubscribe. The
-     * callback fires with the record id that changed; the hook re-reads through
-     * the read door, because a realtime payload has NOT passed the door.
+     * Watch one organization's records of one table. Returns an unsubscribe.
+     *
+     * THE HOST NUDGES THROUGH THIS SINK AND REACHES AROUND NOTHING. Until 0.43.0 the callback
+     * was `(recordId: Uuid) => void` and a host that also wanted to say "the SHAPE moved"
+     * imported `tableShapeChanged` from `@ai-matrx/records/react` and called it directly —
+     * which worked, and which meant the port contract did not describe half of what a port
+     * actually does. A column appearing is not a row changing, and the package owns the
+     * difference.
+     *
+     * NOTHING THAT ARRIVES HERE IS DATA. A nudge has not passed the read door, so the hook
+     * re-reads — by id set when the nudge names ids, whole-page when it cannot.
      */
     subscribeRecords(args: {
         organization_id: Uuid;
         table_id: Uuid;
-    }, onChange: (recordId: Uuid) => void): () => void;
+    }, sink: RecordsChangeSink): () => void;
+}
+/** What a realtime port may tell the package. Two calls, because a column is not a row. */
+interface RecordsChangeSink {
+    /**
+     * THESE RECORDS MOVED. `null` means "I cannot tell you which" — a reconnect, a tab wake, or
+     * a change above the store's own id cap — and is the one case that costs a whole-page read.
+     * An EMPTY array is not the same thing and is not a nudge at all.
+     */
+    records(ids: readonly Uuid[] | null): void;
+    /**
+     * THIS TABLE'S SHAPE MOVED — a column added, retired or changed. Re-reading the rows would
+     * redraw the same table without the new column in it, which is a screen that is out of date
+     * while looking healthy.
+     */
+    shape(): void;
 }
 /**
  * OPTIONAL. Where a refusal that nobody asked about goes — the loud funnel.
@@ -6814,6 +6896,21 @@ interface RecordsClient {
         rows: ReadRow[];
         total: number | null;
     }>>;
+    /**
+     * DOOR-1 FOR AN ID SET. Exactly these records of this Table, through
+     * `custom.read_records_by_ids` — the same ladder, the same level, the same
+     * field masking and the same page ceiling as `list`, addressed by id instead
+     * of by page. An id the reader may not see simply does not come back, which
+     * is the same answer `list` gives by omission.
+     *
+     * It exists because a realtime notice has always named the exact ids that
+     * moved and no door could take them: three cells changing re-read a fifty-row
+     * page in every watching browser.
+     */
+    listByIds(args: {
+        table_id: Uuid;
+        ids: readonly Uuid[];
+    }): Promise<RecordsResult<ReadRow[]>>;
     query(query: RecordQuery): Promise<RecordsResult<{
         rows: ReadRow[];
         total: number | null;
@@ -6867,6 +6964,28 @@ interface RecordsClient {
         field_id: Uuid;
         patch: FieldPatch;
     }): Promise<RecordsResult<Uuid>>;
+    /**
+     * REL-DISP. THE WORDS ONE RELATION CELL SHOWS, resolved by the store through
+     * that column's own display spec — one column or several, joined by its
+     * separator. Never resolve a relation label any other way: the store's
+     * `custom._words_for` is the one body that decides what a record is called, it
+     * asks the visibility ladder BEFORE it reads the name, and a record this reader
+     * may not open comes back as the withheld sentence rather than its name or id.
+     * A value that is not an id is handed straight back — it is already words.
+     */
+    relationWords(args: {
+        field_id: Uuid;
+        value: string;
+    }): Promise<RecordsResult<string | null>>;
+    /**
+     * The same answer for a WHOLE PAGE of cells in one round trip. Prefer this
+     * wherever a grid, board, list or picker resolves more than one chip: the
+     * per-id lane is what made a page of relation cells a page of requests.
+     */
+    relationWordsMany(args: {
+        field_id: Uuid;
+        record_ids: Uuid[];
+    }): Promise<RecordsResult<Record<string, string>>>;
     /** Take a field off a table. Refuses the title field, the last field, and one another field reads through. */
     fieldRetire(args: {
         field_id: Uuid;
@@ -7979,6 +8098,61 @@ interface RecordsClient {
     }): Promise<RecordsResult<MyLevel[]>>;
 }
 
+/**
+ * THE CLIENT OPERATION LEDGER — how a browser recognises the echo of its own write.
+ *
+ * Every private-channel notice the record store broadcasts reaches EVERY browser watching that
+ * Table, including the one that caused it. Until now the writer had no way to tell its own
+ * change from a colleague's: the notice carried ids and nothing about who moved them, so
+ * `recordsRealtimePort.ts` declared `acceptEchoFromSelf: true` and the writer re-read a page it
+ * had already updated. It was named honestly rather than faked, and this is the other half.
+ *
+ * THE SHAPE. Every write through `RecordsClient` mints a uuid, sends it to the store as the
+ * platform envelope key `_op_id`, and remembers it here. The store lifts that key out before
+ * storage — it is never written onto the record — carries it on the change-feed row, and puts
+ * it in the notice as `op_id`. A notice whose `op_id` is in this ledger is this browser's own
+ * echo and is dropped.
+ *
+ * WHY A TIME WINDOW RATHER THAN A DELETE-ON-MATCH. One write can produce MORE THAN ONE notice:
+ * a record write that also moves a column produces a `record` notice and a `field` notice, and
+ * a statement touching two Tables produces one per Table. Forgetting an op the first time it
+ * came back would make the second notice look like somebody else's and cost the re-read this
+ * exists to avoid. So an op is remembered for a window and expires on its own.
+ *
+ * 🚨 THE WINDOW IS A CORRECTNESS BOUNDARY, NOT A TUNING KNOB, AND IT FAILS IN THE SAFE
+ * DIRECTION BY CONSTRUCTION. Too SHORT and a late echo is treated as a stranger's change: one
+ * extra read of a page that is already correct — invisible. Too LONG and a stranger's change
+ * that happened to reuse our uuid would be dropped — which cannot happen, because it is a v4
+ * uuid nobody else has ever seen. The only real cost of a long window is memory, so it is
+ * bounded by COUNT as well as by time.
+ *
+ * WHAT THIS IS NOT. It is not a replacement for the store's optimistic concurrency, and it
+ * never decides what is true — a dropped echo means "I already know about this", and every
+ * path that could be wrong about that (a reconnect, a tab wake, a notice with no `op_id` at
+ * all) re-reads through the door as it always did.
+ */
+
+/**
+ * Mint the id for one client operation and remember it as ours.
+ *
+ * ONE CALL IS ONE OPERATION. A fifty-row paste through `recordWriteMany` is ONE op id, because
+ * the store announces one statement once — and it REFUSES a batch carrying two different ones
+ * by name, for exactly that reason.
+ */
+declare function mintOpId(): Uuid;
+/**
+ * Is this notice the echo of a write this browser made?
+ *
+ * `undefined`/`null` is NOT ours and never has been: a notice with no `op_id` came from a
+ * server-side write, an agent tool, another client, or a store older than this mechanism —
+ * all of which are changes this browser has not seen and must read.
+ */
+declare function isOwnOp(opId: string | null | undefined): boolean;
+/** Test seam: forget everything. Never called by product code. */
+declare function forgetAllOps(): void;
+/** Test seam: how many operations are currently remembered. */
+declare function rememberedOpCount(): number;
+
 interface RecordsProviderProps {
     config: RecordsConfig;
     children: ReactNode;
@@ -8013,6 +8187,13 @@ interface Async<T> {
     /** The store's own refusal. Never null-and-empty at the same time. */
     error: RecordsError | null;
     reload: () => void;
+    /**
+     * Replace what is held WITHOUT a round trip — for a caller that has just read fresher rows
+     * through the SAME door and would otherwise throw them away and read the page again.
+     * It is never a way to put un-doored data on a screen: everything handed in here came back
+     * from a door that applied the ladder.
+     */
+    setData: (update: (current: T | null) => T | null) => void;
 }
 /** One Table's declaration. */
 declare function useTable(tableId: Uuid | null): Async<Table | null>;
@@ -8180,4 +8361,4 @@ declare function useFieldMutation(): UseFieldMutation;
  */
 declare function useMergeField(key: string | null, state?: Record<string, unknown>): MergeFieldResolution | null;
 
-export { ABSENCE_REASONS, ACTOR_VOCABULARY, type AbsenceReason, type Actor, type AggregateBucket, type AggregateFilter, type AggregateMeasure, type AggregateOperation, type AggregateRow, type AggregateWindow, type AnonTokenBinding, type BookingAvailability, type BookingDeclared, type BookingSummary, type BookingWindow, COMPUTE_ON, CONTEXT_POLICIES, type CaptureField, type CaptureFileRef, type CaptureOutcome, type CaptureQuestion, type CaptureQueue, type CaptureQueueCounts, type CaptureQueueOptions, type CaptureQueuePorts, type CaptureQueueStore, type CaptureSheetFace, type CaptureSheetSummary, type CaptureSyncReport, type ChecklistDeclared, type ChecklistRequirement, type ChecklistRequirementKind, type ChecklistRoleSpec, type ChecklistRunStarted, type ChecklistRunStep, type ChecklistRunSummary, type ChecklistSpec, type ChecklistStepCompleted, type ChecklistStepSpec, type ChecklistTemplateShape, type ChecklistTemplateSummary, type ChecklistTrigger, type ChecklistTriggerKind, type ChoiceOption, type CommentThreadRead, type CommentWritten, type ComputeOn, type ContextPolicy, type ConversationScope, type ConversationScopeContext, type CustomFieldTableType, DELIVERIES, type DashboardBlock, type DashboardBlockKind, type DashboardBlockResult, type DashboardRunResult, type DashboardSummary, type Delivery, type DigestPreview, type DocRenderRow, type DocSignatureCheck, type DocSignatureRow, type DocTemplateRow, type DocToken, type DocUnresolvedToken, ENTITY_TOKENS, type EnrichAlternate, type EnrichCell, type EnrichDeclared, type EnrichDueRow, type EnrichRun, type EnrichSource, type Enrichment, type EnrichmentSummary, type EntityFieldRights, type EntityFieldValue, type EntityRecordMatch, type EntityRecordRead, type EntityRecordsFound, type EntityTableFacts, type EntityToken, type ExternalPrincipalCard, FIELD_SENSITIVITIES, FIELD_SOURCES, FRESHNESS, type Field, type FieldBehavior, type FieldHistoryEntry, type FieldPatch, type FieldProposal, type FieldRule, type FieldSensitivity, type FieldSource, type FieldTypeWord, type ForbiddenEnvelopeWord, type FormSummary, type Freshness, type HiddenFieldNotice, type HistoryActor, type HistoryActorKind, type HistoryChange, type Home, type ImportBatchResult, type ImportColumnPlan, type ImportFinished, type ImportOpened, type ImportOutcome, type ImportPlan, type ImportPolicy, type ImportProposal, type ImportReport, type ImportRun, type InboundAddress, type InboundDeclared, KERNEL_TABLES, type KernelTableName, MERGE_FIELD_MODIFIERS, MERGE_FIELD_SEMANTIC_TYPES, MERGE_FIELD_SOURCES, type MergeField, type MergeFieldModifier, type MergeFieldProvenance, type MergeFieldResolution, type MergeFieldSemanticType, type MergeFieldSource, type MergeFieldTransform, type MissingBehavior, type MyLevel, type MySubscription, type NewEntityFieldDeclaration, type NewFieldDeclaration, ON_DELETE, OVERRIDE_POLICIES, type OnDelete, type OverridePolicy, PARITY_FIELD_TYPES, PERMISSION_LEVELS, PER_VALUE_ACCESS_WORDS, PIPELINE_RULE_KINDS, type ParityFieldType, type ParityFieldTypeDescriptor, type PerValueAccessWord, type PermissionLevel, type PgError, type Pipeline, type PipelineColumn, type PipelineDeclared, type PipelineGate, type PipelineGatePreview, type PipelineMissingField, type PipelineMoveResult, type PipelineRule, type PipelineRuleKind, type PipelineSpec, type PipelineStage, type PipelineVerdict, type PortalCard, type PortalInvitation, type PortalPreviewRow, type PortalPrincipal, type PortalRevocation, type PortalSummary, type PortalTableExposure, type PredictedRefusal, type ProvenancePointer, type PublishBinding, type QueuedCapture, type QueuedCaptureFile, type QueuedCaptureState, type QuietHours, REFUSALS_WORTH_REPEATING, RELATION_BINDINGS, RELATION_CARDINALITIES, RELATION_FLAVORS, RETIRED_ACTOR_WORDS, RULE_NODE_KINDS, RULE_USES, type ReadRow, type ReadValue, type RecordComment, type RecordDocument, type RecordHistoryEntry, type RecordRead, type RecordRevision, type RecordScopeComment, type RecordScopeContext, type RecordScopeField, type RecordScopeHistoryEntry, type RecordScopeRelation, type RecordScopeWithheld, type RecordsActor, type RecordsConfig, type RecordsDataSource, type RecordsError, type RecordsErrorCode, type RecordsErrorSink, type RecordsFilter, RecordsProvider, type RecordsProviderProps, type RecordsRealtimePort, type RecordsResolverPort, type RecordsResponse, type RecordsResult, type RecordsTableQuery, type RegisteredTable, type Relation, type RelationBinding, type RelationCardinality, type RelationCarries, type RelationCoordinate, type RelationFlavor, type RelationProperties, type RelationTarget, type ResolutionTriple, type ResolvedPublishBinding, type RestorePreview, type RestoreResult, type RetiredActorWord, type Rule, type RuleAnswer, type RuleExpression, type RuleNodeKind, type RuleUse, STAGE_RULE_ENFORCEMENT, STAGE_RULE_ON_FAIL, STORAGE_MODES, STORE_DOORS, STORE_KNOBS, STORE_REFUSAL_CODES, type SavedViewRow, type SavedViewSpecIn, type StagePending, type StagePendingOnBoard, type StageRuleEnforcement, type StageRuleOnFail, type StageRuleWarning, type StaleWriteDetail, type StorageMode, type StoreDoorName, type StoreRefusalCode, type StoredRecord, type StuckRow, type Subscription, type SubscriptionBlock, type SubscriptionCadence, type SubscriptionSpec, TABLE_DISPLAYS, TABLE_ORIGINS, TABLE_TYPES, type Table, type TableCapacity, type TableDisplay, type TableOrigin, type TableProposal, type TableType, type Timestamp, type UseEntityFieldMutation, type UseFieldMutation, type UseRecordMutation, type UseRecordsOptions, type UseRecordsState, type Uuid, VALUE_ALTERNATE_KEYS, VALUE_ENVELOPE_KEYS, type ValueAlternate, type ValueAlternateKey, type ValueEnvelope, type ValueEnvelopeKey, type ValueSource, type WorkApprovalDecision, type WorkApprovalFiled, type WorkApprover, type WorkAssignment, type WorkAssignmentField, type WorkChange, type WorkDueState, type WorkGraph, type WorkInboxItem, type WorkInboxKind, type WorkInstantiation, type WorkListFlavour, type WorkListItem, type WorkOrigin, type WorkRecordState, type WorkSlotHold, type WorkState, type WorkTemplateNode, type WorkTemplateRelation, type WorkTurn, type WriteConflict, asPermissionLevel, atLeast, bookingPath, choiceSlug, choiceValuesOf, choicesOf, err, highestLevel, holdsARetiredChoice, indexedDbStore, isDecided, isRecordsErr, isTheChosen, looksLikeAnId, mayDrag, measureKey, memoryStore, mintClientKey, ok, openCaptureQueue, optionKey, optionLabel, portalPath, publicFormPath, scopeChip, tableShapeChanged, useEntityFieldMutation, useEntityFieldRights, useEntityFields, useEntityRecord, useEntityTable, useFieldMutation, useFields, useMergeField, useMyLevel, useMyLevels, useOptionalRecordsClient, useRecord, useRecordMutation, useRecords, useRecordsActor, useRecordsClient, useTable, useTables };
+export { ABSENCE_REASONS, ACTOR_VOCABULARY, type AbsenceReason, type Actor, type AggregateBucket, type AggregateFilter, type AggregateMeasure, type AggregateOperation, type AggregateRow, type AggregateWindow, type AnonTokenBinding, type BookingAvailability, type BookingDeclared, type BookingSummary, type BookingWindow, COMPUTE_ON, CONTEXT_POLICIES, type CaptureField, type CaptureFileRef, type CaptureOutcome, type CaptureQuestion, type CaptureQueue, type CaptureQueueCounts, type CaptureQueueOptions, type CaptureQueuePorts, type CaptureQueueStore, type CaptureSheetFace, type CaptureSheetSummary, type CaptureSyncReport, type ChecklistDeclared, type ChecklistRequirement, type ChecklistRequirementKind, type ChecklistRoleSpec, type ChecklistRunStarted, type ChecklistRunStep, type ChecklistRunSummary, type ChecklistSpec, type ChecklistStepCompleted, type ChecklistStepSpec, type ChecklistTemplateShape, type ChecklistTemplateSummary, type ChecklistTrigger, type ChecklistTriggerKind, type ChoiceOption, type CommentThreadRead, type CommentWritten, type ComputeOn, type ContextPolicy, type ConversationScope, type ConversationScopeContext, type CustomFieldTableType, DELIVERIES, type DashboardBlock, type DashboardBlockKind, type DashboardBlockResult, type DashboardRunResult, type DashboardSummary, type Delivery, type DigestPreview, type DocRenderRow, type DocSignatureCheck, type DocSignatureRow, type DocTemplateRow, type DocToken, type DocUnresolvedToken, ENTITY_TOKENS, type EnrichAlternate, type EnrichCell, type EnrichDeclared, type EnrichDueRow, type EnrichRun, type EnrichSource, type Enrichment, type EnrichmentSummary, type EntityFieldRights, type EntityFieldValue, type EntityRecordMatch, type EntityRecordRead, type EntityRecordsFound, type EntityTableFacts, type EntityToken, type ExternalPrincipalCard, FIELD_SENSITIVITIES, FIELD_SOURCES, FRESHNESS, type Field, type FieldBehavior, type FieldHistoryEntry, type FieldPatch, type FieldProposal, type FieldRule, type FieldSensitivity, type FieldSource, type FieldTypeWord, type ForbiddenEnvelopeWord, type FormSummary, type Freshness, type HiddenFieldNotice, type HistoryActor, type HistoryActorKind, type HistoryChange, type Home, type ImportBatchResult, type ImportColumnPlan, type ImportFinished, type ImportOpened, type ImportOutcome, type ImportPlan, type ImportPolicy, type ImportProposal, type ImportReport, type ImportRun, type InboundAddress, type InboundDeclared, KERNEL_TABLES, type KernelTableName, MERGE_FIELD_MODIFIERS, MERGE_FIELD_SEMANTIC_TYPES, MERGE_FIELD_SOURCES, type MergeField, type MergeFieldModifier, type MergeFieldProvenance, type MergeFieldResolution, type MergeFieldSemanticType, type MergeFieldSource, type MergeFieldTransform, type MissingBehavior, type MyLevel, type MySubscription, type NewEntityFieldDeclaration, type NewFieldDeclaration, ON_DELETE, OVERRIDE_POLICIES, type OnDelete, type OverridePolicy, PARITY_FIELD_TYPES, PERMISSION_LEVELS, PER_VALUE_ACCESS_WORDS, PIPELINE_RULE_KINDS, type ParityFieldType, type ParityFieldTypeDescriptor, type PerValueAccessWord, type PermissionLevel, type PgError, type Pipeline, type PipelineColumn, type PipelineDeclared, type PipelineGate, type PipelineGatePreview, type PipelineMissingField, type PipelineMoveResult, type PipelineRule, type PipelineRuleKind, type PipelineSpec, type PipelineStage, type PipelineVerdict, type PortalCard, type PortalInvitation, type PortalPreviewRow, type PortalPrincipal, type PortalRevocation, type PortalSummary, type PortalTableExposure, type PredictedRefusal, type ProvenancePointer, type PublishBinding, type QueuedCapture, type QueuedCaptureFile, type QueuedCaptureState, type QuietHours, REFUSALS_WORTH_REPEATING, RELATION_BINDINGS, RELATION_CARDINALITIES, RELATION_FLAVORS, RETIRED_ACTOR_WORDS, RULE_NODE_KINDS, RULE_USES, type ReadRow, type ReadValue, type RecordComment, type RecordDocument, type RecordHistoryEntry, type RecordRead, type RecordRevision, type RecordScopeComment, type RecordScopeContext, type RecordScopeField, type RecordScopeHistoryEntry, type RecordScopeRelation, type RecordScopeWithheld, type RecordsActor, type RecordsChangeSink, type RecordsConfig, type RecordsDataSource, type RecordsError, type RecordsErrorCode, type RecordsErrorSink, type RecordsFilter, RecordsProvider, type RecordsProviderProps, type RecordsRealtimePort, type RecordsResolverPort, type RecordsResponse, type RecordsResult, type RecordsTableQuery, type RegisteredTable, type Relation, type RelationBinding, type RelationCardinality, type RelationCarries, type RelationCoordinate, type RelationDisplay, type RelationFlavor, type RelationProperties, type RelationTarget, type ResolutionTriple, type ResolvedPublishBinding, type RestorePreview, type RestoreResult, type RetiredActorWord, type Rule, type RuleAnswer, type RuleExpression, type RuleNodeKind, type RuleUse, STAGE_RULE_ENFORCEMENT, STAGE_RULE_ON_FAIL, STORAGE_MODES, STORE_DOORS, STORE_KNOBS, STORE_REFUSAL_CODES, type SavedViewRow, type SavedViewSpecIn, type StagePending, type StagePendingOnBoard, type StageRuleEnforcement, type StageRuleOnFail, type StageRuleWarning, type StaleWriteDetail, type StorageMode, type StoreDoorName, type StoreRefusalCode, type StoredRecord, type StuckRow, type Subscription, type SubscriptionBlock, type SubscriptionCadence, type SubscriptionSpec, TABLE_DISPLAYS, TABLE_ORIGINS, TABLE_TYPES, type Table, type TableCapacity, type TableDisplay, type TableOrigin, type TableProposal, type TableType, type Timestamp, type UseEntityFieldMutation, type UseFieldMutation, type UseRecordMutation, type UseRecordsOptions, type UseRecordsState, type Uuid, VALUE_ALTERNATE_KEYS, VALUE_ENVELOPE_KEYS, type ValueAlternate, type ValueAlternateKey, type ValueEnvelope, type ValueEnvelopeKey, type ValueSource, type WorkApprovalDecision, type WorkApprovalFiled, type WorkApprover, type WorkAssignment, type WorkAssignmentField, type WorkChange, type WorkDueState, type WorkGraph, type WorkInboxItem, type WorkInboxKind, type WorkInstantiation, type WorkListFlavour, type WorkListItem, type WorkOrigin, type WorkRecordState, type WorkSlotHold, type WorkState, type WorkTemplateNode, type WorkTemplateRelation, type WorkTurn, type WriteConflict, asPermissionLevel, atLeast, bookingPath, choiceSlug, choiceValuesOf, choicesOf, err, forgetAllOps, highestLevel, holdsARetiredChoice, indexedDbStore, isDecided, isOwnOp, isRecordsErr, isTheChosen, looksLikeAnId, mayDrag, measureKey, memoryStore, mintClientKey, mintOpId, ok, openCaptureQueue, optionKey, optionLabel, portalPath, publicFormPath, rememberedOpCount, scopeChip, tableShapeChanged, useEntityFieldMutation, useEntityFieldRights, useEntityFields, useEntityRecord, useEntityTable, useFieldMutation, useFields, useMergeField, useMyLevel, useMyLevels, useOptionalRecordsClient, useRecord, useRecordMutation, useRecords, useRecordsActor, useRecordsClient, useTable, useTables };