@colixsystems/widget-sdk 0.87.0 → 0.88.0

package/README.md

@@ -61,7 +61,41 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
-`v0.87.0` — pre-publish. The package surface (types, function names, export paths) is the v1 contract; runtime behaviour for some hooks is stubbed (each hook documents what's wired and what isn't). It is **not yet published to npm**.
+`v0.88.0` — pre-publish. The package surface (types, function names, export paths) is the v1 contract; runtime behaviour for some hooks is stubbed (each hook documents what's wired and what isn't). It is **not yet published to npm**.
+
+### What's new in 0.88.0 (contract 1.62.0)
+
+**A refused datastore / directory / permission call now reaches the widget as its real reason (sc-4986).**
+
+- **The reason was being thrown away.** Each `@colixsystems/*-client` throws typed
+  errors carrying `.code` / `.status` / `.details` (the parsed envelope) and **no
+  `.response`** — but `toDatastoreError`, `toDirectoryError` and
+  `toPermissionError` read `err.response.*` only. Every typed client rejection
+  fell through every branch and arrived as `code: "INTERNAL"`, so a 403 the
+  workspace owner has to lift was indistinguishable from a dropped socket, and
+  `DatastoreError.fieldErrors` never populated at all. `toPaymentError` was fixed
+  for exactly this in 0.83.0; these three were not.
+- **All three mappers now read both shapes**, preferring the envelope's own
+  `message` (the canonical `{ statusCode, message, code }` field — the old code
+  read a `.error` key the envelope has never carried). The documented `code`
+  vocabularies are unchanged, so a widget already branching on
+  `code === "FORBIDDEN"` starts working rather than having to change.
+- **`DatastoreError` / `DirectoryError` / `PermissionError` gain `retryable`**
+  (and `status`). `retryable === false` for a refusal only the caller, the record
+  or the workspace can clear — 403 / 404 / 400 / 422 / 409 — and `true` for a
+  timeout, a rate limit, a 5xx or a dropped socket. Branch on it instead of
+  offering a blanket "try again". This is deliberately *not* the payments rule:
+  a 402 `DECLINED` card IS worth another attempt, so that contract differs.
+- **`fieldErrors` works again** — a 400/422 carrying
+  `errors: [{ field, code, message }]` becomes the flat `{ field: message }` map
+  the type has always advertised, so a form can mark the offending input.
+- **New soft lint rule `datastore-error-not-branched`** (severity `warning`,
+  never blocks a publish): a widget that writes with `useDatastoreMutation` but
+  never reads `retryable`, branches on `code ===`, or renders the error's own
+  `.message` is flagged, so the AI widget agent's repair loop closes the gap.
+- `CONTRACT.version` → `1.62.0`: the three hooks' `returnShape` entries now name
+  the `{ code, message, retryable }` triple. No export or signature changed —
+  additive fields on three error classes.
 
 ### What's new in 0.87.0 (contract 1.61.1)
 

package/dist/contract.cjs

@@ -714,7 +714,7 @@ const HOOKS = [
       signedAt: "string | null",
       verdict: "{ valid, checks, content_status, ... } | null",
       loading: "boolean",
-      error: "PermissionError | null",
+      error: "PermissionError | null  // { code, message, retryable }",
       initiate: "() => Promise<{ signature_id, qr, auto_start_token, status }>",
       refresh: "() => Promise<void>",
       cancel: "() => Promise<void>",
@@ -824,9 +824,12 @@ const HOOKS = [
     name: "useDatastoreMutation",
     signature: "useDatastoreMutation(tableId)",
     returnShape: {
-      create: "(record) => Promise<Record>  // rejects with DatastoreError",
-      update: "(id, partial) => Promise<Record>  // rejects with DatastoreError",
-      delete: "(id) => Promise<void>  // rejects with DatastoreError",
+      create:
+        "(record) => Promise<Record>  // rejects with DatastoreError { code, message, retryable } — render the message when retryable is false, never 'try again'",
+      update:
+        "(id, partial) => Promise<Record>  // rejects with DatastoreError { code, message, retryable } — render the message when retryable is false, never 'try again'",
+      delete:
+        "(id) => Promise<void>  // rejects with DatastoreError { code, message, retryable } — render the message when retryable is false, never 'try again'",
     },
     requiredContextSlice: ["datastore.records"],
     scopes: ["datastore.write:*"],
@@ -942,7 +945,7 @@ const HOOKS = [
     returnShape: {
       users: "Array<{ id, name, email?, role, is_active }>  // snake_case rows; unwrapped from { data, meta }",
       loading: "boolean",
-      error: "DirectoryError | null",
+      error: "DirectoryError | null  // { code, message, retryable }",
       refetch: "() => Promise<void>",
       invite:
         "({ email, name, group_ids? }) => Promise<Invite>  // rejects with DirectoryError",
@@ -971,7 +974,7 @@ const HOOKS = [
     returnShape: {
       groups: "Array<{ id, name, member_count }>  // snake_case rows; unwrapped from { data, meta }",
       loading: "boolean",
-      error: "DirectoryError | null",
+      error: "DirectoryError | null  // { code, message, retryable }",
       refetch: "() => Promise<void>",
       create:
         "({ name }) => Promise<Group>  // rejects with DirectoryError",
@@ -1010,7 +1013,7 @@ const HOOKS = [
       message: "string | null",
       loading: "boolean",
       statusLoading: "boolean",
-      error: "DirectoryError | null",
+      error: "DirectoryError | null  // { code, message, retryable }",
       startLink: "() => Promise<{ order_ref, qr, auto_start_token, status }>",
       refresh: "() => Promise<void>",
       cancel: "() => Promise<void>",
@@ -1092,7 +1095,7 @@ const HOOKS = [
       permissions:
         "Array<{ id, user_id, group_id, can_read, can_write, can_delete, can_grant }>  // snake_case rows; unwrapped from { data, meta }",
       loading: "boolean",
-      error: "PermissionError | null",
+      error: "PermissionError | null  // { code, message, retryable }",
       grant:
         "({ user_id?, group_id?, can_read?, can_write?, can_delete?, can_grant? }) => Promise<RecordPermission>  // rejects with PermissionError",
       revoke:
@@ -2784,7 +2787,7 @@ const CONTRACT = deepFreeze({
   //    Naming one widget is strictly more specific than restyling a scope, and
   //    the Properties Panel stays the final word. Additive throughout: a theme
   //    that sets none of it resolves exactly as before.
-  version: "1.61.1",
+  version: "1.62.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/contract.js

@@ -714,7 +714,7 @@ const HOOKS = [
       signedAt: "string | null",
       verdict: "{ valid, checks, content_status, ... } | null",
       loading: "boolean",
-      error: "PermissionError | null",
+      error: "PermissionError | null  // { code, message, retryable }",
       initiate: "() => Promise<{ signature_id, qr, auto_start_token, status }>",
       refresh: "() => Promise<void>",
       cancel: "() => Promise<void>",
@@ -824,9 +824,12 @@ const HOOKS = [
     name: "useDatastoreMutation",
     signature: "useDatastoreMutation(tableId)",
     returnShape: {
-      create: "(record) => Promise<Record>  // rejects with DatastoreError",
-      update: "(id, partial) => Promise<Record>  // rejects with DatastoreError",
-      delete: "(id) => Promise<void>  // rejects with DatastoreError",
+      create:
+        "(record) => Promise<Record>  // rejects with DatastoreError { code, message, retryable } — render the message when retryable is false, never 'try again'",
+      update:
+        "(id, partial) => Promise<Record>  // rejects with DatastoreError { code, message, retryable } — render the message when retryable is false, never 'try again'",
+      delete:
+        "(id) => Promise<void>  // rejects with DatastoreError { code, message, retryable } — render the message when retryable is false, never 'try again'",
     },
     requiredContextSlice: ["datastore.records"],
     scopes: ["datastore.write:*"],
@@ -942,7 +945,7 @@ const HOOKS = [
     returnShape: {
       users: "Array<{ id, name, email?, role, is_active }>  // snake_case rows; unwrapped from { data, meta }",
       loading: "boolean",
-      error: "DirectoryError | null",
+      error: "DirectoryError | null  // { code, message, retryable }",
       refetch: "() => Promise<void>",
       invite:
         "({ email, name, group_ids? }) => Promise<Invite>  // rejects with DirectoryError",
@@ -971,7 +974,7 @@ const HOOKS = [
     returnShape: {
       groups: "Array<{ id, name, member_count }>  // snake_case rows; unwrapped from { data, meta }",
       loading: "boolean",
-      error: "DirectoryError | null",
+      error: "DirectoryError | null  // { code, message, retryable }",
       refetch: "() => Promise<void>",
       create:
         "({ name }) => Promise<Group>  // rejects with DirectoryError",
@@ -1010,7 +1013,7 @@ const HOOKS = [
       message: "string | null",
       loading: "boolean",
       statusLoading: "boolean",
-      error: "DirectoryError | null",
+      error: "DirectoryError | null  // { code, message, retryable }",
       startLink: "() => Promise<{ order_ref, qr, auto_start_token, status }>",
       refresh: "() => Promise<void>",
       cancel: "() => Promise<void>",
@@ -1092,7 +1095,7 @@ const HOOKS = [
       permissions:
         "Array<{ id, user_id, group_id, can_read, can_write, can_delete, can_grant }>  // snake_case rows; unwrapped from { data, meta }",
       loading: "boolean",
-      error: "PermissionError | null",
+      error: "PermissionError | null  // { code, message, retryable }",
       grant:
         "({ user_id?, group_id?, can_read?, can_write?, can_delete?, can_grant? }) => Promise<RecordPermission>  // rejects with PermissionError",
       revoke:
@@ -2784,7 +2787,7 @@ const CONTRACT = deepFreeze({
   //    Naming one widget is strictly more specific than restyling a scope, and
   //    the Properties Panel stays the final word. Additive throughout: a theme
   //    that sets none of it resolves exactly as before.
-  version: "1.61.1",
+  version: "1.62.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/hooks.js

@@ -941,11 +941,29 @@ export function useGeolocation(options) {
  * error message, populated when the datastore returned a structured
  * 400/422 payload with `errors: [{ field, code }, ...]`.
  */
+// sc-4986 — the datastore refusals retrying the same call can never clear.
+// The default for a hand-constructed error; the mappers pass the status-derived
+// answer explicitly (see isRetryableDomainStatus).
+const NON_RETRYABLE_DATASTORE_CODES = new Set([
+  "CONSTRAINT_VIOLATION",
+  "FORBIDDEN",
+  "NOT_FOUND",
+  "VALIDATION",
+]);
+
 export class DatastoreError extends Error {
   constructor(code, message, opts) {
     super(message);
     this.name = "DatastoreError";
     this.code = code;
+    // sc-4986 — the HTTP status behind the code, when there was one. null for a
+    // transport failure or a locally-raised wiring error.
+    this.status =
+      opts && typeof opts.status === "number" ? opts.status : null;
+    this.retryable =
+      opts && opts.retryable !== undefined
+        ? Boolean(opts.retryable)
+        : !NON_RETRYABLE_DATASTORE_CODES.has(code);
     if (opts && opts.fieldErrors && typeof opts.fieldErrors === "object") {
       this.fieldErrors = opts.fieldErrors;
     }
@@ -960,50 +978,113 @@ export class DatastoreError extends Error {
  * a DatastoreError with a stable `.code`. Reads `error.response.status` if
  * present (axios shape) and falls back to inspecting the message string.
  */
+/* ===========================================================================
+ * sc-4986 — reading a refusal's real reason off a rejected domain-client call
+ * ==========================================================================*/
+
+/**
+ * The one envelope read the three data-domain mappers share.
+ *
+ * A rejected call arrives in one of TWO shapes and both have to be read, which
+ * is the whole bug this exists to fix:
+ *
+ *   - the `@colixsystems/*-client` packages throw their own typed errors
+ *     (`ForbiddenError`, `ValidationError`, …) carrying `.code` / `.status` /
+ *     `.details` — the parsed envelope — and **no `.response`**;
+ *   - the older host path throws an axios-shaped error with `.response`.
+ *
+ * Reading only `.response` (what these mappers used to do) meant every typed
+ * client rejection fell through every branch and became `INTERNAL`, so a 403
+ * was indistinguishable from a dropped socket.
+ *
+ * `status` is the signal the code is derived from, never the client's own
+ * `.code`: an axios transport failure carries `code: "ECONNABORTED"`, which is
+ * not a domain code and must never be mistaken for one. The typed client errors
+ * always set a numeric `.status`, and axios keeps its status on `.response`, so
+ * the two reads together cover both shapes.
+ */
+function readDomainErrorEnvelope(err) {
+  const response = (err && err.response) || null;
+  const body = (response && response.data) || (err && err.details) || null;
+  const status =
+    response && typeof response.status === "number"
+      ? response.status
+      : err && typeof err.status === "number" && err.status
+        ? err.status
+        : null;
+  // `message` is the canonical envelope's field (REQ-GEN-05, errorResponse.ts
+  // emits `{ statusCode, message, ...extras }`); `error` is the ad-hoc key a
+  // few older surfaces still emit. The envelope has never carried BOTH.
+  const envelopeMessage = body && (body.message || body.error);
+  return {
+    status,
+    code: body && typeof body.code === "string" && body.code ? body.code : null,
+    message: typeof envelopeMessage === "string" ? envelopeMessage : null,
+    fieldErrors: readEnvelopeFieldErrors(body),
+  };
+}
+
+/**
+ * A flat `field -> message` map from an envelope's `errors: [{ field, code,
+ * message }]` array (the shape `errorResponse(res, 4xx, msg, { errors })`
+ * emits). Returns undefined when the body carries none, so the caller can leave
+ * the property off the error entirely.
+ */
+function readEnvelopeFieldErrors(body) {
+  if (!body || !Array.isArray(body.errors)) return undefined;
+  const map = {};
+  for (const entry of body.errors) {
+    if (entry && typeof entry.field === "string") {
+      map[entry.field] = entry.message || entry.code || "Invalid value";
+    }
+  }
+  return Object.keys(map).length > 0 ? map : undefined;
+}
+
+/**
+ * Whether retrying the SAME data call could plausibly succeed.
+ *
+ * A timeout, a rate limit, a 5xx or a dropped socket is worth another attempt;
+ * a refusal (403), a missing row (404), a bad body (400/422) or a conflict
+ * (409) never clears until the caller, the record or the workspace changes.
+ * An absent status is a transport failure, so it counts as transient.
+ *
+ * Deliberately NOT shared with `NON_RETRYABLE_PAYMENT_CODES`: a payment's 402
+ * DECLINED IS worth another attempt with a different card, so the payments
+ * contract genuinely differs here (CLAUDE.md §3 — the divergence is the point,
+ * not an accident).
+ */
+function isRetryableDomainStatus(status) {
+  if (status === null) return true;
+  if (status === 408 || status === 429) return true;
+  return status >= 500;
+}
+
 function toDatastoreError(err) {
+  // An already-mapped SDK error passes straight through. NOTE: the datastore
+  // CLIENT exports its own class of the same name, so a client rejection does
+  // NOT match here — it is handled by the envelope read below, which is exactly
+  // what used to be missing (sc-4986).
   if (err instanceof DatastoreError) return err;
-  const status =
-    err && err.response && typeof err.response.status === "number"
-      ? err.response.status
-      : null;
-  const bodyMessage =
-    err &&
-    err.response &&
-    err.response.data &&
-    typeof err.response.data.error === "string"
-      ? err.response.data.error
-      : null;
-  const fallbackMessage =
-    bodyMessage ||
-    (err && typeof err.message === "string"
-      ? err.message
-      : "Datastore call failed");
+  const { status, message, fieldErrors } = readDomainErrorEnvelope(err);
   let code = "INTERNAL";
   if (status === 400 || status === 422) code = "VALIDATION";
   else if (status === 409) code = "CONSTRAINT_VIOLATION";
   else if (status === 403) code = "FORBIDDEN";
   else if (status === 404) code = "NOT_FOUND";
-  // Surface a structured fieldErrors map when the server emitted one
-  // (record.controller.js shapes 422 bodies as `{ errors: [{ field, code }] }`).
-  let fieldErrors;
-  if (
-    err &&
-    err.response &&
-    err.response.data &&
-    Array.isArray(err.response.data.errors)
-  ) {
-    const map = {};
-    for (const entry of err.response.data.errors) {
-      if (entry && typeof entry.field === "string") {
-        map[entry.field] = entry.message || entry.code || "Invalid value";
-      }
-    }
-    if (Object.keys(map).length > 0) fieldErrors = map;
-  }
-  return new DatastoreError(code, fallbackMessage, {
-    cause: err,
-    fieldErrors,
-  });
+  return new DatastoreError(
+    code,
+    message ||
+      (err && typeof err.message === "string"
+        ? err.message
+        : "Datastore call failed"),
+    {
+      cause: err,
+      status,
+      retryable: isRetryableDomainStatus(status),
+      fieldErrors,
+    },
+  );
 }
 
 // sc-1579 — consecutive renders with a different serialized query before
@@ -1422,43 +1503,54 @@ export function useDatastoreMutation(table) {
  *   - "CONFLICT"   — 409 (e.g. trying to edit a template-derived row).
  *   - "INTERNAL"   — anything else (network, 5xx).
  */
+// sc-4986 — the permission refusals retrying the same call can never clear.
+// This mapper's code set is OPEN (the server's own code wins), so the status is
+// the primary signal and this set only backstops a hand-constructed error.
+const NON_RETRYABLE_PERMISSION_CODES = new Set([
+  "CONFLICT",
+  "FORBIDDEN",
+  "NOT_FOUND",
+  "TEMPLATE_DERIVED",
+  "VALIDATION",
+]);
+
 export class PermissionError extends Error {
   constructor(code, message, opts) {
     super(message);
     this.name = "PermissionError";
     this.code = code;
     if (opts && opts.status !== undefined) this.status = opts.status;
+    // sc-4986 — lets a widget tell "this will never work" from "try again".
+    this.retryable =
+      opts && opts.retryable !== undefined
+        ? Boolean(opts.retryable)
+        : !NON_RETRYABLE_PERMISSION_CODES.has(code);
     if (opts && opts.cause) this.cause = opts.cause;
   }
 }
 
 function toPermissionError(err) {
+  // See the note in toDatastoreError — a client rejection is read from the
+  // envelope below rather than matching this instanceof.
   if (err instanceof PermissionError) return err;
-  const status =
-    err && err.response && typeof err.response.status === "number"
-      ? err.response.status
-      : null;
-  const bodyCode =
-    err && err.response && err.response.data && err.response.data.code;
-  const bodyMessage =
-    err && err.response && err.response.data && err.response.data.error;
+  const { status, code: envelopeCode, message } = readDomainErrorEnvelope(err);
   let code = "INTERNAL";
   if (status === 403) code = "FORBIDDEN";
   else if (status === 404) code = "NOT_FOUND";
   else if (status === 409) code = "CONFLICT";
   else if (status === 400 || status === 422) code = "VALIDATION";
-  if (typeof bodyCode === "string" && bodyCode) {
-    // Preserve the server's stable code over the status-derived one when
-    // the server volunteered it (e.g. TEMPLATE_DERIVED on edit/delete of
-    // an inherit/template row).
-    code = bodyCode;
-  }
-  const message =
-    (typeof bodyMessage === "string" && bodyMessage) ||
-    (err && typeof err.message === "string"
-      ? err.message
-      : "Record permission call failed");
-  return new PermissionError(code, message, { status, cause: err });
+  // Preserve the server's stable code over the status-derived one when the
+  // server volunteered it (e.g. TEMPLATE_DERIVED on edit/delete of an
+  // inherit/template row) — this mapper's documented code set is open.
+  if (envelopeCode) code = envelopeCode;
+  return new PermissionError(
+    code,
+    message ||
+      (err && typeof err.message === "string"
+        ? err.message
+        : "Record permission call failed"),
+    { cause: err, status, retryable: isRetryableDomainStatus(status) },
+  );
 }
 
 const _NOOP_PERMISSIONS_RESULT = Object.freeze({
@@ -2727,41 +2819,53 @@ export function useFolderPermissions(folderId, options = {}) {
  *                     is invite-only and the email is not on the list.
  *   - "INTERNAL"    — anything else (network, 5xx).
  */
+// sc-4986 — the directory refusals retrying the same call can never clear.
+const NON_RETRYABLE_DIRECTORY_CODES = new Set([
+  "FORBIDDEN",
+  "INVITE_ONLY",
+  "NOT_FOUND",
+  "VALIDATION",
+]);
+
 export class DirectoryError extends Error {
   constructor(code, message, opts) {
     super(message);
     this.name = "DirectoryError";
     this.code = code;
+    // sc-4986 — the HTTP status behind the code, when there was one.
+    this.status =
+      opts && typeof opts.status === "number" ? opts.status : null;
+    this.retryable =
+      opts && opts.retryable !== undefined
+        ? Boolean(opts.retryable)
+        : !NON_RETRYABLE_DIRECTORY_CODES.has(code);
     if (opts && opts.cause) this.cause = opts.cause;
   }
 }
 
 function toDirectoryError(err) {
+  // See the note in toDatastoreError: the directory CLIENT has a same-named
+  // class, so a client rejection is read from the envelope below, not here.
   if (err instanceof DirectoryError) return err;
-  const status =
-    err && err.response && typeof err.response.status === "number"
-      ? err.response.status
-      : null;
-  const bodyCode =
-    err && err.response && err.response.data && err.response.data.code;
-  const bodyMessage =
-    err && err.response && err.response.data && err.response.data.error;
+  const { status, code: envelopeCode, message } = readDomainErrorEnvelope(err);
   let code = "INTERNAL";
-  if (bodyCode === "INVITE_ONLY") code = "INVITE_ONLY";
+  if (envelopeCode === "INVITE_ONLY") code = "INVITE_ONLY";
   else if (status === 403) code = "FORBIDDEN";
   else if (status === 404) code = "NOT_FOUND";
   else if (status === 400 || status === 422) code = "VALIDATION";
   else if (status === 409) {
     // 409 is invite-only on the invite endpoints; treat the rest as
     // validation conflicts (duplicate email, etc.).
-    code = bodyCode === "INVITE_ONLY" ? "INVITE_ONLY" : "VALIDATION";
+    code = envelopeCode === "INVITE_ONLY" ? "INVITE_ONLY" : "VALIDATION";
   }
-  const message =
-    (typeof bodyMessage === "string" && bodyMessage) ||
-    (err && typeof err.message === "string"
-      ? err.message
-      : "Directory call failed");
-  return new DirectoryError(code, message, { cause: err });
+  return new DirectoryError(
+    code,
+    message ||
+      (err && typeof err.message === "string"
+        ? err.message
+        : "Directory call failed"),
+    { cause: err, status, retryable: isRetryableDomainStatus(status) },
+  );
 }
 
 /**

package/dist/index.d.ts

@@ -1275,11 +1275,22 @@ export class DatastoreError extends Error {
     | "NOT_FOUND"
     | "INTERNAL";
   fieldErrors?: Record<string, string>;
+  /** sc-4986 — the HTTP status behind the code; null for a transport failure. */
+  status: number | null;
+  /**
+   * sc-4986 — whether retrying the SAME call could plausibly succeed. False
+   * for a refusal only the caller, the record or the workspace can clear
+   * (403/404/400/422/409); true for a timeout, a rate limit, a 5xx or a
+   * dropped socket. Branch on this instead of offering a blanket retry.
+   */
+  retryable: boolean;
   constructor(
     code: DatastoreError["code"],
     message: string,
     opts?: {
       fieldErrors?: Record<string, string>;
+      status?: number | null;
+      retryable?: boolean;
       cause?: unknown;
     },
   );
@@ -1297,10 +1308,18 @@ export class DirectoryError extends Error {
     | "NOT_FOUND"
     | "INVITE_ONLY"
     | "INTERNAL";
+  /** sc-4986 — the HTTP status behind the code; null for a transport failure. */
+  status: number | null;
+  /** sc-4986 — whether retrying the SAME call could plausibly succeed. */
+  retryable: boolean;
   constructor(
     code: DirectoryError["code"],
     message: string,
-    opts?: { cause?: unknown },
+    opts?: {
+      status?: number | null;
+      retryable?: boolean;
+      cause?: unknown;
+    },
   );
 }
 
@@ -1620,10 +1639,16 @@ export class PermissionError extends Error {
     | "INTERNAL"
     | string;
   status?: number;
+  /** sc-4986 — whether retrying the SAME call could plausibly succeed. */
+  retryable: boolean;
   constructor(
     code: PermissionError["code"],
     message: string,
-    opts?: { status?: number; cause?: unknown },
+    opts?: {
+      status?: number | null;
+      retryable?: boolean;
+      cause?: unknown;
+    },
   );
 }
 

package/dist/linter.cjs

@@ -845,6 +845,37 @@ function _paymentErrorHandlingRules(source) {
   ];
 }
 
+// sc-4986 — soft warning, the datastore twin of `payment-error-not-branched`.
+// A write can be refused for reasons a retry never clears (the table's grants,
+// a validation failure, a row that is gone), and the server sends a user-safe
+// sentence saying which. A widget that collapses every rejection into one
+// generic "something went wrong" throws that sentence away and leaves the user
+// pressing the button again. Reading `DatastoreError.retryable`, branching on
+// `code ===`, or rendering the error's own `.message` all satisfy it; strings
+// and comments are blanked so prose about errors never does.
+function _datastoreErrorHandlingRules(source) {
+  const code = _stripNonCode(source);
+  const call = /\buseDatastoreMutation\s*\(/.exec(code);
+  if (!call) return [];
+  if (/\bretryable\b/.test(code)) return [];
+  if (/\bcode\s*===/.test(code)) return [];
+  if (/\.message\b/.test(code)) return [];
+  const line = code.slice(0, call.index).split(/\r?\n/).length;
+  return [
+    {
+      rule: "datastore-error-not-branched",
+      severity: "warning",
+      label:
+        `writes with useDatastoreMutation() but never reports why a write ` +
+        `failed — read DatastoreError.retryable (or err.message) and show the ` +
+        `server's reason, so a refusal the user cannot clear is not offered ` +
+        `as "try again".`,
+      line,
+      snippet: (source.split(/\r?\n/)[line - 1] || "").trim().slice(0, 200),
+    },
+  ];
+}
+
 function _imagePercentHeightRules(source) {
   const findings = [];
   const code = _stripNonCode(source, { keepStrings: true });
@@ -1012,6 +1043,7 @@ function lintSource(source, options) {
   findings.push(..._paymentCurrencyRules(source));
   findings.push(..._hardcodedCurrencyLabelRules(source));
   findings.push(..._paymentErrorHandlingRules(source));
+  findings.push(..._datastoreErrorHandlingRules(source));
   findings.push(
     ..._scopeRules(source, options && options.manifest).map((f) => ({
       ...f,

package/dist/linter.js

@@ -977,6 +977,37 @@ function _paymentErrorHandlingRules(source) {
   ];
 }
 
+// sc-4986 — soft warning, the datastore twin of `payment-error-not-branched`.
+// A write can be refused for reasons a retry never clears (the table's grants,
+// a validation failure, a row that is gone), and the server sends a user-safe
+// sentence saying which. A widget that collapses every rejection into one
+// generic "something went wrong" throws that sentence away and leaves the user
+// pressing the button again. Reading `DatastoreError.retryable`, branching on
+// `code ===`, or rendering the error's own `.message` all satisfy it; strings
+// and comments are blanked so prose about errors never does.
+function _datastoreErrorHandlingRules(source) {
+  const code = _stripNonCode(source);
+  const call = /\buseDatastoreMutation\s*\(/.exec(code);
+  if (!call) return [];
+  if (/\bretryable\b/.test(code)) return [];
+  if (/\bcode\s*===/.test(code)) return [];
+  if (/\.message\b/.test(code)) return [];
+  const line = code.slice(0, call.index).split(/\r?\n/).length;
+  return [
+    {
+      rule: "datastore-error-not-branched",
+      severity: "warning",
+      label:
+        `writes with useDatastoreMutation() but never reports why a write ` +
+        `failed — read DatastoreError.retryable (or err.message) and show the ` +
+        `server's reason, so a refusal the user cannot clear is not offered ` +
+        `as "try again".`,
+      line,
+      snippet: (source.split(/\r?\n/)[line - 1] || "").trim().slice(0, 200),
+    },
+  ];
+}
+
 function _imagePercentHeightRules(source) {
   const findings = [];
   // Comments are blanked (string contents kept) so a commented-out example —
@@ -1174,6 +1205,7 @@ export function lintSource(source, options) {
   findings.push(..._paymentCurrencyRules(source));
   findings.push(..._hardcodedCurrencyLabelRules(source));
   findings.push(..._paymentErrorHandlingRules(source));
+  findings.push(..._datastoreErrorHandlingRules(source));
   // REQ-USERMGMT / REQ-ACL-SYS M3 — scope-aware rules. Run after the
   // line-by-line scan so banned-identifier findings stay first in the
   // output.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@colixsystems/widget-sdk",
-  "version": "0.87.0",
+  "version": "0.88.0",
   "description": "Common widget interface for AppStudio. Implements WidgetManifest, WidgetContext, property schema, and helper hooks.",
   "type": "module",
   "main": "./dist/index.js",
@@ -48,7 +48,7 @@
   ],
   "scripts": {
     "build": "node scripts/build.js",
-    "test": "node --test src/__tests__/contract.test.js src/__tests__/hooks-users.test.js src/__tests__/hooks-groups.test.js src/__tests__/hooks-schema.test.js src/__tests__/hooks-assets-by-tag.test.js src/__tests__/hooks-filestore-upload.test.js src/__tests__/hooks-filestore-file.test.js src/__tests__/hooks-mutation.test.js src/__tests__/hooks-payments.test.js src/__tests__/hooks-record-permissions.test.js src/__tests__/hooks-geolocation.test.js src/__tests__/hooks-section-empty.test.js src/__tests__/hooks-widget-event.test.js src/__tests__/hooks-widget-input.test.js src/__tests__/hooks-identification.test.js src/__tests__/hooks-subscription.test.js src/__tests__/hooks-volatile-query-key.test.js src/__tests__/linter-users-scope.test.js src/__tests__/linter-comments.test.js src/__tests__/linter-translation-api.test.js src/__tests__/linter-image-height.test.js src/__tests__/linter-measured-padding.test.js src/__tests__/linter-payment-error.test.js src/__tests__/linter-platform.test.js src/__tests__/linter-react-import.test.js src/__tests__/lucide-icon-names.test.js src/__tests__/lucideIconName.test.js src/__tests__/manifest-actions.test.js src/__tests__/widget-translations.test.js src/__tests__/hooks-translate.test.js src/__tests__/devserver.test.js src/__tests__/host-externals.test.js src/__tests__/datetimepicker.test.js src/__tests__/property-schema-resolve.test.js src/__tests__/theme-components-parity.test.js src/__tests__/theme-depth-tokens.test.js src/__tests__/toast-host.test.js"
+    "test": "node --test src/__tests__/contract.test.js src/__tests__/hooks-users.test.js src/__tests__/hooks-groups.test.js src/__tests__/hooks-schema.test.js src/__tests__/hooks-assets-by-tag.test.js src/__tests__/hooks-filestore-upload.test.js src/__tests__/hooks-filestore-file.test.js src/__tests__/hooks-mutation.test.js src/__tests__/hooks-payments.test.js src/__tests__/hooks-record-permissions.test.js src/__tests__/hooks-geolocation.test.js src/__tests__/hooks-section-empty.test.js src/__tests__/hooks-widget-event.test.js src/__tests__/hooks-widget-input.test.js src/__tests__/hooks-identification.test.js src/__tests__/hooks-subscription.test.js src/__tests__/hooks-volatile-query-key.test.js src/__tests__/linter-users-scope.test.js src/__tests__/linter-comments.test.js src/__tests__/linter-translation-api.test.js src/__tests__/linter-image-height.test.js src/__tests__/linter-measured-padding.test.js src/__tests__/linter-payment-error.test.js src/__tests__/linter-platform.test.js src/__tests__/linter-react-import.test.js src/__tests__/lucide-icon-names.test.js src/__tests__/lucideIconName.test.js src/__tests__/manifest-actions.test.js src/__tests__/widget-translations.test.js src/__tests__/hooks-translate.test.js src/__tests__/devserver.test.js src/__tests__/host-externals.test.js src/__tests__/datetimepicker.test.js src/__tests__/property-schema-resolve.test.js src/__tests__/theme-components-parity.test.js src/__tests__/theme-depth-tokens.test.js src/__tests__/toast-host.test.js src/__tests__/hooks-domain-error-mapping.test.js src/__tests__/linter-datastore-error.test.js"
   },
   "engines": {
     "node": ">=18"