@ai-matrx/records 0.46.0 → 0.47.0

package/CHANGELOG.md

@@ -1,5 +1,35 @@
 # Changelog — @ai-matrx/records
 
+## 0.47.0
+
+**A refusal this package does not recognise no longer becomes a sentence about this package.**
+(lane TAILS-6.)
+
+* **`mapPgError` wrote its own note ONTO `hint` — and `hint` is what every screen treats as
+  THE REMEDY.** So when the client met a code it did not know, the person acting on the screen
+  was handed this to act on:
+
+  > `@ai-matrx/records did not recognise SQLSTATE  from checklistTemplates`
+
+  Watched on the live seat by the GUIDE lane on 2026-09-21, on the Checklists tab of a table's
+  rail, under the title "Something went wrong at our end". Reproduced here from the shapes
+  supabase-js actually returns.
+* **The note moves to `RecordsError.diagnostic`, with `unmapped: true` beside it.** It is still
+  said out loud — nobody reads the silence as "handled" — but it is said to whoever debugs
+  this and to nobody else. `hint` is the STORE's own words or it is absent.
+* **New code `unreachable`, and it is how the bug got out.** A SQLSTATE is five characters;
+  supabase-js puts `""` in `code` for a `FetchError` and the HTTP status (`"404"`, `"502"`) when
+  the gateway answers with no body. Neither is a SQLSTATE, both used to land in `internal`, and
+  `""` is not nullish so it was carried as one. They now classify as `unreachable` — the call
+  never reached the store, nothing was written, and the same call can simply be made again,
+  which is a thing a screen can honestly offer. `TypeError: Failed to fetch` is the browser
+  talking to itself, so the message becomes "We could not reach your data." and the raw text
+  goes to `diagnostic`.
+
+**Consumer action:** none required. A host that reads `error.hint` gets the store's hint or
+nothing, never this package's commentary; a host that switches on `error.code` should add
+`unreachable` beside `internal` (`@ai-matrx/records-ui` 0.66.0 already has its title and remedy).
+
 ## 0.46.0
 
 **A portal can say which Tables it shows.**

package/dist/core/index.cjs

@@ -3070,19 +3070,34 @@ function parseDetail(details) {
     return details;
   }
 }
+function isNotASqlstate(code) {
+  if (!code) return true;
+  return /^[0-9]{3}$/.test(code);
+}
 function mapPgError(error, where) {
-  const sqlstate = error.code ?? void 0;
-  const code = (sqlstate ? BY_SQLSTATE[sqlstate] : void 0) ?? "internal";
+  const raw = error.code ?? void 0;
+  const sqlstate = raw && raw !== "" ? raw : void 0;
   const mapped = {
-    code,
+    code: "internal",
     message: error.message,
     ...error.hint ? { hint: error.hint } : {},
     ...sqlstate ? { sqlstate } : {}
   };
+  if (isNotASqlstate(sqlstate)) {
+    mapped.code = "unreachable";
+  } else {
+    mapped.code = BY_SQLSTATE[sqlstate] ?? "internal";
+  }
   const detail = parseDetail(error.details);
   if (detail !== void 0) mapped.detail = detail;
-  if (code === "internal") {
-    mapped.hint = (mapped.hint ? `${mapped.hint} ` : "") + `(@ai-matrx/records did not recognise SQLSTATE ${sqlstate ?? "(none)"} from ${where}; the message above is the store's own and is the thing to act on.)`;
+  if (mapped.code === "internal") {
+    mapped.unmapped = true;
+    mapped.diagnostic = `@ai-matrx/records did not recognise SQLSTATE ${sqlstate ?? "(none)"} from ${where}; the store's own message is the thing to act on.`;
+  } else if (mapped.code === "unreachable") {
+    mapped.unmapped = true;
+    mapped.diagnostic = `@ai-matrx/records never reached the store from ${where}: ${raw ? `the transport answered ${raw}` : "no response"} \u2014 ${error.message}`;
+    mapped.message = "We could not reach your data.";
+    delete mapped.hint;
   }
   return mapped;
 }