@ai-matrx/records 0.42.0 → 0.43.0

package/CHANGELOG.md

@@ -1,5 +1,46 @@
 # Changelog — @ai-matrx/records
 
+## 0.43.0
+
+**The realtime port stops being half a contract, and a nudge re-reads only what moved.**
+
+🚨 **BREAKING (one implementor):** `RecordsRealtimePort.subscribeRecords(args, onChange)` now
+takes a `RecordsChangeSink` instead of `(recordId) => void`:
+
+```ts
+subscribeRecords(args, {
+  records(ids: readonly Uuid[] | null) { … },  // null = "I cannot name them" = read the page
+  shape() { … },                               // a column moved, not a row
+})
+```
+
+*Consumer action:* a host binding this port passes the two-call sink and **deletes its
+`tableShapeChanged` import**. That import was the tell: a host that wanted to say "the SHAPE
+moved" reached around the port into `@ai-matrx/records/react`, because the contract had no way
+to say it. A column appearing is not a row changing and the package owns the difference now.
+
+* **`listByIds({ table_id, ids })`** — DOOR-1 addressed by an id SET, through the new
+  `custom.read_records_by_ids`. The same ladder (`custom.visible_set`), the same level, the
+  same field masking and the same page ceiling as `list`; an id the reader may not see simply
+  does not come back. A separate door NAME rather than a sixth argument to `read_records`,
+  because a defaulted argument beside a live Postgres function makes every existing call
+  ambiguous — `function custom.read_records(uuid, uuid, boolean, integer, integer) is not
+  unique`.
+* **`useRecords` re-reads only the ids it was nudged with.** A whole-page read is now reserved
+  for the three cases that need one: `records(null)`, a subset read the door refused, and a
+  named id that is NEW to this page (only the page door knows where it belongs in the order,
+  so the hook does not guess).
+* **Echo suppression by op id.** Every `recordWrite` / `recordWriteMany` / `recordUpdate` mints
+  a uuid and sends it as the platform envelope key `_op_id`. The store lifts it out before its
+  undeclared-key guard and before storage — **it is never written onto the record** — and
+  carries it back in the realtime notice as `op_id`. `isOwnOp(opId)` (new, from `ops.ts`) tells
+  a port that a notice is this browser's own echo, so a host can delete
+  `acceptEchoFromSelf: true` and stop re-reading a page it has already updated. One call is one
+  operation: a `recordWriteMany` batch carries ONE id, and the store refuses a batch carrying
+  two by name.
+* `useAsync` gained `setData`, so a caller that has just read fresher rows **through the same
+  door** can place them instead of throwing them away and reading the page again.
+
 ## 0.41.0
 
 **`recordWriteMany` — the door for a paste that is bigger than a page.**

package/dist/core/index.cjs

@@ -87,6 +87,7 @@ __export(core_exports, {
   err: () => err,
   exportCsv: () => exportCsv,
   exportXlsx: () => exportXlsx,
+  forgetAllOps: () => forgetAllOps,
   highestLevel: () => highestLevel,
   holdsARetiredChoice: () => holdsARetiredChoice,
   importCsv: () => importCsv,
@@ -94,6 +95,7 @@ __export(core_exports, {
   indexedDbStore: () => indexedDbStore,
   intersectIds: () => intersectIds,
   isDecided: () => isDecided,
+  isOwnOp: () => isOwnOp,
   isRecordsErr: () => isRecordsErr,
   isTheChosen: () => isTheChosen,
   looksLikeAnId: () => looksLikeAnId,
@@ -102,6 +104,7 @@ __export(core_exports, {
   measureKey: () => measureKey,
   memoryStore: () => memoryStore,
   mintClientKey: () => mintClientKey,
+  mintOpId: () => mintOpId,
   ok: () => ok,
   openCaptureQueue: () => openCaptureQueue,
   optionKey: () => optionKey,
@@ -114,6 +117,7 @@ __export(core_exports, {
   predictValueRefusals: () => predictValueRefusals,
   predictWriteRefusals: () => predictWriteRefusals,
   publicFormPath: () => publicFormPath,
+  rememberedOpCount: () => rememberedOpCount,
   scopeChip: () => scopeChip,
   staleWriteDetail: () => staleWriteDetail,
   supabaseDataSource: () => supabaseDataSource,
@@ -559,6 +563,45 @@ function isRecordsErr(result) {
 var ok = (data) => ({ ok: true, data });
 var err = (error) => ({ ok: false, error });
 
+// src/ops.ts
+var REMEMBER_MS = 3e4;
+var REMEMBER_MAX = 500;
+var ours = /* @__PURE__ */ new Map();
+function trim(now) {
+  for (const [id, at] of ours) {
+    if (now - at <= REMEMBER_MS) break;
+    ours.delete(id);
+  }
+  while (ours.size > REMEMBER_MAX) {
+    const oldest = ours.keys().next();
+    if (oldest.done === true) break;
+    ours.delete(oldest.value);
+  }
+}
+function mintOpId() {
+  const id = crypto.randomUUID();
+  const now = Date.now();
+  ours.set(id, now);
+  trim(now);
+  return id;
+}
+function isOwnOp(opId) {
+  if (!opId) return false;
+  const at = ours.get(opId);
+  if (at === void 0) return false;
+  if (Date.now() - at > REMEMBER_MS) {
+    ours.delete(opId);
+    return false;
+  }
+  return true;
+}
+function forgetAllOps() {
+  ours.clear();
+}
+function rememberedOpCount() {
+  return ours.size;
+}
+
 // src/store.generated.ts
 var ACTOR_VOCABULARY = ["user", "agent", "system"];
 var RETIRED_ACTOR_WORDS = { "ai": "agent", "code": "system", "human": "user" };
@@ -1002,6 +1045,7 @@ var STORE_DOORS = [
   { name: "read_paths_outside_the_door", args: "", returns: "TABLE(object_name text, why text)", security: "invoker" },
   { name: "read_record", args: "p_organization_id uuid, p_record_id uuid, p_by_id boolean DEFAULT false", returns: "jsonb", security: "definer" },
   { name: "read_records", 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", returns: "TABLE(id uuid, document jsonb, level permission_level)", security: "definer" },
+  { name: "read_records_by_ids", args: "p_organization_id uuid, p_table_id uuid, p_record_ids uuid[], p_by_id boolean DEFAULT false", returns: "TABLE(id uuid, document jsonb, level permission_level)", security: "definer" },
   { name: "realtime_topic_admits", args: "p_topic text", returns: "boolean", security: "definer" },
   { name: "record_aggregate", args: "p_organization_id uuid, p_table_id uuid, p_group_by jsonb DEFAULT '[]'::jsonb, p_measures jsonb DEFAULT '[]'::jsonb, p_bucket jsonb DEFAULT NULL::jsonb, p_filter jsonb DEFAULT '{}'::jsonb, p_limit integer DEFAULT 200, p_required text DEFAULT 'viewer'::text", returns: "TABLE(groups jsonb, measures jsonb, row_count bigint)", security: "definer" },
   { name: "record_applicability", args: "p_organization_id uuid, p_record_id uuid", returns: "TABLE(rule_id uuid, rule_name text, rule_version integer, applies boolean, answer jsonb)", security: "invoker" },
@@ -1026,6 +1070,7 @@ var STORE_DOORS = [
   { name: "record_values", args: "p_organization_id uuid, p_record_id uuid", returns: "jsonb", security: "invoker" },
   { name: "record_values_of", args: "p_row custom.record", returns: "jsonb", security: "invoker" },
   { name: "record_values_versioned", args: "p_organization_id uuid, p_record_id uuid", 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)", security: "definer" },
+  { name: "record_words", args: "p_organization_id uuid, p_record_id uuid, p_noun text DEFAULT NULL::text", returns: "text", security: "definer" },
   { name: "record_write", args: "p_organization_id uuid, p_table_id uuid, p_data jsonb", returns: "uuid", security: "definer" },
   { name: "record_write_many", args: "p_organization_id uuid, p_table_id uuid, p_rows jsonb[], p_ids uuid[] DEFAULT NULL::uuid[]", returns: "uuid[]", security: "definer" },
   { name: "refusals_claiming_a_level_never_asked", args: "", returns: "TABLE(function_name text, identity_args text, why text)", security: "invoker" },
@@ -1226,18 +1271,18 @@ var STORE_KNOBS = [
   { key: "world_publish_enabled", value: "false", type: "boolean" }
 ];
 var STORE_REFUSAL_CODES = [
-  { code: "02000", 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" },
+  { code: "02000", 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" },
   { code: "0A000", 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" },
   { code: "22003", raised_by: "context_resolve" },
   { code: "22004", raised_by: "_entity_custom_fields_guard,_value_envelope,actor_word,agg_assert_key,agg_sql,anon_capture,anon_token_issue,anon_write,assert_client_may_reach,booking_declare,capture_submit,checklist_declare,context_resolve,dashboard_block_normalize,dashboard_declare,dashboard_window_sql,doc_render_write,doc_sign,doc_signature_write,doc_template_save,enrich_land,enrich_normalize,external_history_event,external_rows,external_source_declare,external_stub_upsert,external_write_through,external_writes_set,field_history,form_declare,form_submit,home_add,io_comment_write,io_import_begin,io_infer_column,io_outbox_drain,io_restore,migrate_choice_keys,migrate_purge,migrate_reclass,migrate_split,migrate_undo,organization_clear,organization_contents,pipeline_declare,pipeline_gate_preview,portal_declare,portal_invite,portal_principal_bind,provenance_retention_days,provenance_write,query_across_homes,query_by_coordinates,query_rollup,record_delete,record_reparent,record_resolve,record_restore,record_update,record_write,record_write_many,relation_carry,relation_own,rule_declare,share_grant,sign_request_create,sign_request_sign,subscription_declare,table_declare,table_share_outside_invite,value_restore,view_declare,work_approval_decide,work_approval_request,work_template_declare" },
   { code: "22007", raised_by: "dashboard_window_sql" },
   { code: "22012", raised_by: "rule_eval" },
-  { code: "22023", 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" },
+  { code: "22023", 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" },
   { code: "23503", 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" },
   { code: "23505", 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" },
-  { code: "23514", 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" },
+  { code: "23514", 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,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" },
   { code: "40001", raised_by: "has_visibility_at" },
-  { code: "42501", 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" },
+  { code: "42501", 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" },
   { code: "42703", raised_by: "entity_table,portal_declare" },
   { code: "53400", raised_by: "anon_rate_take,delete_cascade_closure,enrich_due,enrich_land,promote_field" },
   { code: "54001", raised_by: "record_delete" },
@@ -2325,6 +2370,13 @@ var DOORS = {
   // this person could see.
   readRecord: "read_record",
   readRecords: "read_records",
+  // THE SAME READ DOOR, ADDRESSED BY AN ID SET. A realtime notice names the exact ids that
+  // moved; before this existed the only door that took them was the PAGE door, so a
+  // three-cell change re-read fifty rows in every watching browser. It is a separate NAME
+  // rather than a sixth argument to `read_records` because adding a defaulted argument to a
+  // live Postgres function makes every existing call ambiguous — `is not unique`. Same
+  // ladder, same level, same masking, same page ceiling.
+  readRecordsByIds: "read_records_by_ids",
   // DOOR-8, the two clocks. `p_recorded_at` is what the store SAID then;
   // `p_world_on` is what was TRUE of the world on that date, read out of dated
   // values. A client that answered either one itself would be guessing.
@@ -2909,17 +2961,18 @@ function createRecordsClient(config) {
     async recordWrite({ table_id, data }) {
       return callDoor(
         DOORS.recordWrite,
-        { p_organization_id: org, p_table_id: table_id, p_data: data },
+        { p_organization_id: org, p_table_id: table_id, p_data: { ...data, _op_id: mintOpId() } },
         "recordWrite"
       );
     },
     async recordWriteMany({ table_id, rows, ids }) {
+      const opId = mintOpId();
       return callDoor(
         DOORS.recordWriteMany,
         {
           p_organization_id: org,
           p_table_id: table_id,
-          p_rows: rows,
+          p_rows: rows.map((row) => ({ ...row, _op_id: opId })),
           ...ids === void 0 ? {} : { p_ids: ids }
         },
         "recordWriteMany"
@@ -2931,7 +2984,7 @@ function createRecordsClient(config) {
         {
           p_organization_id: org,
           p_record_id: record_id,
-          p_patch: patch,
+          p_patch: { ...patch, _op_id: mintOpId() },
           ...expectedVersion === void 0 ? {} : { p_expected_version: expectedVersion }
         },
         "recordUpdate"
@@ -2973,6 +3026,21 @@ function createRecordsClient(config) {
       }
       return ok({ record_id, document, hidden, computed, computedUnavailable });
     },
+    async listByIds({ table_id, ids }) {
+      if (ids.length === 0) return ok([]);
+      const door = await callDoor(
+        DOORS.readRecordsByIds,
+        { p_organization_id: org, p_table_id: table_id, p_record_ids: ids },
+        "listByIds"
+      );
+      if (!door.ok) return err(door.error);
+      return ok(
+        (door.data ?? []).map((row) => {
+          const { document, hidden } = unfold(row.document);
+          return { id: row.id, document, level: row.level, hidden };
+        })
+      );
+    },
     async list({ table_id, limit = 50, offset = 0 }) {
       const door = await callDoor(
         DOORS.readRecords,