@ai-matrx/records 0.57.0 → 0.57.1

package/CHANGELOG.md

@@ -1,5 +1,30 @@
 # Changelog — @ai-matrx/records
 
+## 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) {
@@ -5697,6 +5707,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 +5764,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 +5886,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 +5955,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,
@@ -6115,9 +6174,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 +7146,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 +7165,8 @@ function createRecordsClient(config) {
         },
         "valueRestore"
       );
+      if (answered.ok) announceRecordChanged(record_id);
+      return answered;
     },
     async commentThread({ record_id, include_resolved }) {
       return callDoor(
@@ -7883,12 +7948,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 +8056,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") {