@ai-matrx/records 0.57.0 → 0.57.2

package/CHANGELOG.md

@@ -1,5 +1,41 @@
 # Changelog — @ai-matrx/records
 
+## 0.57.2 (unpublished — lane HUB-FIX, 2026-09-23; `custom.table_facts` is live on the main database, ledger 2026-09-23 11:51Z, and `STORE_DOORS` is regenerated to carry it)
+
+* `tableList()` folds `custom.table_facts` onto every Table: `visibility` (a record column the
+  Table document never carried, so every lane decision fell through to its default) and
+  `created_by` — set ONLY to the caller's own id and only on Tables the caller made. The call is
+  made only when `STORE_DOORS` carries the door (the door-presence pattern): a build generated
+  without it asks nothing and returns the Tables exactly as before. (The code landed inside 0.57.1's commit `7f2a737913` by a sweep; this
+  entry is its record.) Test `__tests__/table-list-facts.test.ts`.
+* New `tableArchived({ table_id })`: the archived row for one Table, or `null` — paged over the
+  Table kernel's archive, the same door a table's own archive uses.
+
+## 0.57.1 (unpublished — lane RECORDS-UI-FIX, guide re-walk 2026-09-23)
+
+* **A refusal is not an app error.** The default error sink printed every refusal through
+  `console.error`, and matrx-frontend's error capture counts every `console.error`, so one
+  refused value lit a red "2 errors" pill. The codes a person causes (`refused_by_rule`,
+  `stale_write`, `invalid_argument`, `already_exists`, `missing_reference`) now go to
+  `console.info`; everything else stays `console.error`. New exports (core):
+  `isAPersonsRefusal`, `A_PERSONS_REFUSAL`. Test: `src/__tests__/a-refusal-is-never-an-app-error.test.ts`.
+* **Every screen hears the writes made on its page.** `recordUpdate`, `recordDelete`,
+  `recordRestore`, `restoreVersion` and `valueRestore` announce the record they wrote on
+  success. New exports: core `announceRecordChanged` / `onRecordChanged`, react
+  `useRecordChangeRevision(recordId)`; `useRecord` re-reads on it.
+
+## Unreleased — STORE-RULE-GAPS (2026-09-23)
+
+* `FieldRule` gains `example` (a pattern's "how to write it") and `min` (a length's shortest);
+  `value` is optional for a min-only length rule. `NewFieldDeclaration.allow_other` (sent as
+  `config.allow_other`) and `FieldPatch.allow_other`; `allowsOtherValues(field)`.
+  `PredictedRefusal.detail`.
+* The mirror predicts the store's new sentences word for word ("… has to be at least 20
+  characters long"; a pattern with an example hints "Enter it like …" with `detail.example`),
+  and no longer predicts a refusal for a list value that is not a uuid — the store holds option
+  KEYS (CHOICE-VALUE) and a list that takes other values adds an unknown word.
+* Needs matrx-frontend `storerulegaps_an_example_a_shortest_length_and_other_choices.sql`.
+
 ## 0.57.0
 
 **The grid primitives are live, so their doors are in the catalogue.** (published by lane

package/dist/core/index.cjs

@@ -2199,6 +2199,7 @@ __export(core_exports, {
   ARCHIVE_LANES: () => ARCHIVE_LANES,
   ARCHIVE_LANE_LABEL: () => ARCHIVE_LANE_LABEL,
   ARCHIVE_LANE_MEANS: () => ARCHIVE_LANE_MEANS,
+  A_PERSONS_REFUSAL: () => A_PERSONS_REFUSAL,
   COMPUTE_ON: () => COMPUTE_ON,
   CONTEXT_POLICIES: () => CONTEXT_POLICIES,
   DECLARABLE_FIELD_KINDS: () => DECLARABLE_FIELD_KINDS,
@@ -2245,6 +2246,8 @@ __export(core_exports, {
   VALUE_ALTERNATE_KEYS: () => VALUE_ALTERNATE_KEYS,
   VALUE_ENVELOPE_KEYS: () => VALUE_ENVELOPE_KEYS,
   actionRefusals: () => actionRefusals,
+  allowsOtherValues: () => allowsOtherValues,
+  announceRecordChanged: () => announceRecordChanged,
   archivedByLine: () => archivedByLine,
   archivedWhen: () => archivedWhen,
   asPermissionLevel: () => asPermissionLevel,
@@ -2277,6 +2280,7 @@ __export(core_exports, {
   importXlsx: () => importXlsx,
   indexedDbStore: () => indexedDbStore,
   intersectIds: () => intersectIds,
+  isAPersonsRefusal: () => isAPersonsRefusal,
   isArchiveLane: () => isArchiveLane,
   isDecided: () => isDecided,
   isOwnOp: () => isOwnOp,
@@ -2291,6 +2295,7 @@ __export(core_exports, {
   mintClientKey: () => mintClientKey,
   mintOpId: () => mintOpId,
   ok: () => ok,
+  onRecordChanged: () => onRecordChanged,
   openCaptureQueue: () => openCaptureQueue,
   optionKey: () => optionKey,
   optionLabel: () => optionLabel,
@@ -2439,6 +2444,11 @@ function highestLevel(left, right) {
   return ORDINAL[left] >= ORDINAL[right] ? left : right;
 }
 
+// src/field.ts
+function allowsOtherValues(field) {
+  return field.type === "list" && field.config?.["allow_other"] === true;
+}
+
 // src/choice.ts
 var UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 function optionKey(option) {
@@ -3813,6 +3823,7 @@ var STORE_DOORS = [
   { name: "table_declare", args: "p_organization_id uuid, p_spec jsonb", returns: "uuid", security: "definer" },
   { name: "table_decorate", args: "p_organization_id uuid, p_table_id uuid, p_path text[], p_value jsonb DEFAULT NULL::jsonb", returns: "jsonb", security: "definer" },
   { name: "table_decorations", args: "p_organization_id uuid, p_table_id uuid", returns: "jsonb", security: "definer" },
+  { name: "table_facts", args: "p_organization_id uuid", returns: "TABLE(table_id uuid, visibility text, mine boolean)", security: "definer" },
   { name: "table_from_example", args: "p_organization_id uuid, p_home_id uuid, p_example jsonb", returns: "jsonb", security: "definer" },
   { name: "table_has_a_visible_record", args: "p_user uuid, p_organization_id uuid, p_table_id uuid", returns: "boolean", security: "definer" },
   { name: "table_is_live", args: "p_organization_id uuid, p_table_id uuid", returns: "boolean", security: "invoker" },
@@ -5313,6 +5324,7 @@ var DOORS = {
   // everywhere in that organization. This is the one question the rail has to
   // ask, under the same wall and visibility gate as `portals` itself.
   portalTables: "portal_tables",
+  tableFacts: "table_facts",
   portalCard: "portal_card",
   portalDeclare: "portal_declare",
   portalInvite: "portal_invite",
@@ -5697,6 +5709,22 @@ function staleWriteDetail(error) {
   };
 }
 
+// src/core/recordChanges.ts
+var listeners = /* @__PURE__ */ new Set();
+function announceRecordChanged(recordId) {
+  for (const listener of [...listeners]) {
+    try {
+      listener(recordId);
+    } catch (thrown) {
+      console.error("[@ai-matrx/records] a record-change listener threw", thrown);
+    }
+  }
+}
+function onRecordChanged(listener) {
+  listeners.add(listener);
+  return () => listeners.delete(listener);
+}
+
 // src/core/query.ts
 var DEFAULT_PAGE_SIZE = 50;
 function planQuery(query) {
@@ -5738,12 +5766,22 @@ function intersectIds(sets) {
 
 // src/core/client.ts
 var DEFAULT_SCHEMA = "custom";
+var A_PERSONS_REFUSAL = /* @__PURE__ */ new Set([
+  "refused_by_rule",
+  "stale_write",
+  "invalid_argument",
+  "already_exists",
+  "missing_reference"
+]);
+function isAPersonsRefusal(code) {
+  return A_PERSONS_REFUSAL.has(code);
+}
 function sink(config) {
-  return config.onError ?? ((e) => (
-    // The defined degradation, stated: loud, with the store's own words, and
-    // naming where it happened. Never silence.
-    console.error(`[@ai-matrx/records] ${e.where}: ${e.code} \u2014 ${e.message}${e.hint ? ` (${e.hint})` : ""}`)
-  ));
+  return config.onError ?? ((e) => {
+    const line = `[@ai-matrx/records] ${e.where}: ${e.code} \u2014 ${e.message}${e.hint ? ` (${e.hint})` : ""}`;
+    if (isAPersonsRefusal(e.code)) console.info(line);
+    else console.error(line);
+  });
 }
 function createRecordsClient(config) {
   const schema = config.schema ?? DEFAULT_SCHEMA;
@@ -5850,21 +5888,26 @@ function createRecordsClient(config) {
         },
         "recordUpdate"
       );
+      if (result.ok) announceRecordChanged(record_id);
       return result;
     },
     async recordDelete({ record_id }) {
-      return callDoor(
+      const result = await callDoor(
         DOORS.recordDelete,
         { p_organization_id: org, p_record_id: record_id },
         "recordDelete"
       );
+      if (result.ok) announceRecordChanged(record_id);
+      return result;
     },
     async recordRestore({ record_id }) {
-      return callDoor(
+      const result = await callDoor(
         DOORS.recordRestore,
         { p_organization_id: org, p_record_id: record_id },
         "recordRestore"
       );
+      if (result.ok) announceRecordChanged(record_id);
+      return result;
     },
     async tableArchive({ table_id, chunk, includeTable }) {
       return callDoor(
@@ -5914,6 +5957,24 @@ function createRecordsClient(config) {
         })
       );
     },
+    async tableArchived({ table_id }) {
+      const kernel = await callDoor(DOORS.tableKernelId, {}, "tableArchived.kernel");
+      if (!kernel.ok) return err(kernel.error);
+      const PAGE = 200;
+      for (let page = 0; page < 25; page += 1) {
+        const answered = await this.listArchived({
+          table_id: kernel.data,
+          lane: "org",
+          limit: PAGE,
+          offset: page * PAGE
+        });
+        if (!answered.ok) return err(answered.error);
+        const hit = answered.data.rows.find((row) => row.id === table_id);
+        if (hit) return ok(hit);
+        if (answered.data.total !== null) return ok(null);
+      }
+      return ok(null);
+    },
     async listArchived({ table_id, lane = DEFAULT_ARCHIVE_LANE, limit = 50, offset = 0 }) {
       const door = await callDoor(
         DOORS.readRecordsArchived,
@@ -6079,6 +6140,23 @@ function createRecordsClient(config) {
         const { document } = unfold(row.document);
         return { ...document, id: row.id, organization_id: org };
       });
+      if (doorExists(DOORS.tableFacts)) {
+        const facts = await callDoor(
+          DOORS.tableFacts,
+          { p_organization_id: org },
+          "tableList.facts"
+        );
+        if (facts.ok) {
+          const byId = new Map((facts.data ?? []).map((f) => [f.table_id, f]));
+          const me = config.actor.user_id ?? null;
+          for (const table of tables) {
+            const fact = byId.get(table.id);
+            if (!fact) continue;
+            table.visibility = fact.visibility;
+            if (fact.mine && me) table.created_by = me;
+          }
+        }
+      }
       tables.sort((a, b) => (a.name ?? "").localeCompare(b.name ?? ""));
       return ok(tables);
     },
@@ -6115,9 +6193,11 @@ function createRecordsClient(config) {
       );
     },
     async fieldDeclare({ table_id, spec }) {
+      const { allow_other, ...rest } = spec;
+      const p_spec = allow_other === void 0 ? rest : { ...rest, config: { ...rest.config ?? {}, allow_other } };
       return callDoor(
         DOORS.fieldDeclare,
-        { p_organization_id: org, p_table_id: table_id, p_spec: spec },
+        { p_organization_id: org, p_table_id: table_id, p_spec },
         "fieldDeclare"
       );
     },
@@ -7085,14 +7165,16 @@ function createRecordsClient(config) {
       );
     },
     async restoreVersion({ record_id, version }) {
-      return callDoor(
+      const result = await callDoor(
         DOORS.restoreVersion,
         { p_organization_id: org, p_record_id: record_id, p_version: version },
         "restoreVersion"
       );
+      if (result.ok) announceRecordChanged(record_id);
+      return result;
     },
     async valueRestore({ record_id, field_key, version }) {
-      return callDoor(
+      const answered = await callDoor(
         DOORS.valueRestore,
         {
           p_organization_id: org,
@@ -7102,6 +7184,8 @@ function createRecordsClient(config) {
         },
         "valueRestore"
       );
+      if (answered.ok) announceRecordChanged(record_id);
+      return answered;
     },
     async commentThread({ record_id, include_resolved }) {
       return callDoor(
@@ -7883,12 +7967,30 @@ function ruleRefusal(field, rule, item, values) {
       }
       return null;
     case "length":
-      if (typeof item === "string" && item.length > Number(rule.value)) {
+      if (typeof item !== "string") return null;
+      if (rule.value !== void 0 && rule.value !== null && rule.value !== "" && item.length > Number(rule.value)) {
         return { ...base, message: `${label} is longer than ${rule.value} characters`, hint: "FLD-3." };
       }
+      if (typeof rule.min === "number" && item !== "" && item.length < rule.min) {
+        return {
+          ...base,
+          message: `${label} has to be at least ${rule.min} characters long`,
+          hint: "FLD-3.",
+          detail: { field_key: field.key, rule: "length", min: rule.min }
+        };
+      }
       return null;
     case "pattern":
       if (typeof item === "string" && !new RegExp(String(rule.value)).test(item)) {
+        const example = typeof rule.example === "string" ? rule.example.trim() : "";
+        if (example !== "") {
+          return {
+            ...base,
+            message: `${label} is not written the way this field expects`,
+            hint: `Enter it like ${example}.`,
+            detail: { field_key: field.key, rule: "pattern", example }
+          };
+        }
         return { ...base, message: `${label} is not written the way this field expects`, hint: "FLD-3." };
       }
       return null;
@@ -7973,12 +8075,6 @@ function predictValueRefusals(fields, values, recordType) {
             message: `${label} takes one of its choices, and it was given a ${jsonType(item)}`,
             hint: "FLD-5 / FLD-6: a list field stores the id of the option RECORD, because every pick-list is already a Table."
           });
-        } else if (!UUID2.test(item)) {
-          found.push({
-            ...base,
-            message: `${label} was given a choice that is not one of its choices`,
-            hint: `REC-51: option membership. ${label} stores the id of an option record, and what it was given is not an id at all.`
-          });
         }
       } else if (field.type === "relation") {
         if (typeof item !== "string") {