@ai-matrx/data 0.18.35 → 0.18.37

package/dist/db.d.cts

@@ -10,7 +10,7 @@ import './net.cjs';
  * direct-Supabase writes.
  *
  * Cross-repo system-of-record:
- * common-docs/systems/platform/optimistic-concurrency/FEATURE.md — read it
+ * common-docs/systems/architecture/optimistic-concurrency/FEATURE.md — read it
  * before touching this feature in ANY repo.
  *
  * The revision token is the canonical `version` int column (bumped by the
@@ -761,4 +761,54 @@ type WriteOneRowResult<Row> = {
  */
 declare function writeOneRow<Row>(write: PromiseLike<RowsResponse<Row>>, options: Pick<WriteOneOptions, "action" | "noun" | "compareAndSet">): Promise<WriteOneRowResult<Row>>;
 
-export { type ActiveOrgCookie, type ActiveOrgCookieOptions, type ActiveOrgSelection, type AuthRetryableResult, BulkWriteError, type CreateActiveOrgCookieArgs, type CreateOAuthRefreshFetchArgs, type CreateSessionRetryOptions, DEFAULT_ACTIVE_ORG_COOKIE_MAX_AGE, DEFAULT_ACTIVE_ORG_COOKIE_NAME, type GuardedUpdateArgs, type GuardedUpdateResult, IncompleteReadError, type JsonObject, type MergeJsonColumnArgs, type MergeJsonColumnResult, type OAuthRefreshStorage, type PagedReadQuery, type PagedReadResult, type ReadAllRowsOptions, type ReadAllRowsRestOptions, type SessionSource, SessionUnavailableError, type TryWriteOneResult, type VersionedRow, WriteDidNotLandError, type WriteDidNotLandReason, type WriteFailureWords, type WriteOneAction, type WriteOneOptions, type WriteOneRowResult, WriteRefusedError, asJsonObject, assertWriteLanded, createActiveOrgCookie, createOAuthRefreshFetch, createSessionRetry, decodeActiveOrgSelection, decodeOAuthRefreshClaims, describeWriteFailure, encodeActiveOrgSelection, guardedUpdate, isMissingSessionError, mergeJsonColumn, personSentence, readAllRows, readAllRowsRest, serverMessageFromBody, tryReadAllRows, tryReadAllRowsRest, tryWriteOne, writeFailureStatus, writeOne, writeOneRow };
+/**
+ * @ai-matrx/data/db — record-unavailable: THE one shape for "a single-record
+ * read came back with zero rows".
+ *
+ * Ported from matrx-frontend `lib/records/recordUnavailable.ts`, which keeps
+ * its capture helpers (`recordUnavailable`, `resolveRecordUnavailableCapture`)
+ * and re-exports this class — so `RecordUnavailableError` is ONE class across
+ * the app and `@ai-matrx/chat`, and every `instanceof` keeps working.
+ *
+ * Zero rows is at least three different situations: the row was soft-deleted,
+ * the row is alive but this reader's access (org membership / permission
+ * grant) does not reach it, or the id is stale/wrong. Asserting deletion for
+ * all three is what D133 cost — two agent-review items were rejected as "site
+ * deleted or is no longer accessible" while the brand AND site were live and
+ * un-deleted; the null was RLS.
+ *
+ * So `deleted` is claimed ONLY when a probe proved it. Everything else is
+ * `unknown` and says both possibilities out loud. Never construct the error
+ * directly at a read site: the host's `recordUnavailable(...)` builds it AND
+ * captures it — the capture is the loud half of the contract.
+ */
+/** `deleted` is PROVEN (a probe read the row and saw `deleted_at`). */
+type RecordUnavailableReason = "deleted" | "unknown";
+/** The truth an access resolver can add after the initial ambiguous read failure. */
+type RecordUnavailableResolution = "denied" | "deleted" | "missing" | "signed-out" | "ok";
+declare class RecordUnavailableError extends Error {
+    readonly entity: string;
+    readonly reason: RecordUnavailableReason;
+    readonly recordId?: string | undefined;
+    /**
+     * Canonical entity token, when the read site knows it. With a token AND a
+     * recordId the renderer stops describing the ambiguity and ASKS the platform
+     * instead — an access gate resolves which of the four it really is.
+     * Without one, honest ambiguity is still the best available answer.
+     */
+    readonly token?: string | undefined;
+    /** Diagnostics identity for reconciling this exact capture in place. */
+    captureId?: string | undefined;
+    /** Last truth written to diagnostics; avoids duplicate reconciliation. */
+    captureResolution: RecordUnavailableReason | RecordUnavailableResolution;
+    constructor(input: {
+        entity: string;
+        reason: RecordUnavailableReason;
+        recordId?: string | undefined;
+        token?: string | undefined;
+    });
+}
+declare function recordUnavailableMessage(entity: string, reason: RecordUnavailableReason): string;
+declare function isRecordUnavailableError(value: unknown): value is RecordUnavailableError;
+
+export { type ActiveOrgCookie, type ActiveOrgCookieOptions, type ActiveOrgSelection, type AuthRetryableResult, BulkWriteError, type CreateActiveOrgCookieArgs, type CreateOAuthRefreshFetchArgs, type CreateSessionRetryOptions, DEFAULT_ACTIVE_ORG_COOKIE_MAX_AGE, DEFAULT_ACTIVE_ORG_COOKIE_NAME, type GuardedUpdateArgs, type GuardedUpdateResult, IncompleteReadError, type JsonObject, type MergeJsonColumnArgs, type MergeJsonColumnResult, type OAuthRefreshStorage, type PagedReadQuery, type PagedReadResult, type ReadAllRowsOptions, type ReadAllRowsRestOptions, RecordUnavailableError, type RecordUnavailableReason, type RecordUnavailableResolution, type SessionSource, SessionUnavailableError, type TryWriteOneResult, type VersionedRow, WriteDidNotLandError, type WriteDidNotLandReason, type WriteFailureWords, type WriteOneAction, type WriteOneOptions, type WriteOneRowResult, WriteRefusedError, asJsonObject, assertWriteLanded, createActiveOrgCookie, createOAuthRefreshFetch, createSessionRetry, decodeActiveOrgSelection, decodeOAuthRefreshClaims, describeWriteFailure, encodeActiveOrgSelection, guardedUpdate, isMissingSessionError, isRecordUnavailableError, mergeJsonColumn, personSentence, readAllRows, readAllRowsRest, recordUnavailableMessage, serverMessageFromBody, tryReadAllRows, tryReadAllRowsRest, tryWriteOne, writeFailureStatus, writeOne, writeOneRow };

package/dist/db.d.ts

@@ -10,7 +10,7 @@ import './net.js';
  * direct-Supabase writes.
  *
  * Cross-repo system-of-record:
- * common-docs/systems/platform/optimistic-concurrency/FEATURE.md — read it
+ * common-docs/systems/architecture/optimistic-concurrency/FEATURE.md — read it
  * before touching this feature in ANY repo.
  *
  * The revision token is the canonical `version` int column (bumped by the
@@ -761,4 +761,54 @@ type WriteOneRowResult<Row> = {
  */
 declare function writeOneRow<Row>(write: PromiseLike<RowsResponse<Row>>, options: Pick<WriteOneOptions, "action" | "noun" | "compareAndSet">): Promise<WriteOneRowResult<Row>>;
 
-export { type ActiveOrgCookie, type ActiveOrgCookieOptions, type ActiveOrgSelection, type AuthRetryableResult, BulkWriteError, type CreateActiveOrgCookieArgs, type CreateOAuthRefreshFetchArgs, type CreateSessionRetryOptions, DEFAULT_ACTIVE_ORG_COOKIE_MAX_AGE, DEFAULT_ACTIVE_ORG_COOKIE_NAME, type GuardedUpdateArgs, type GuardedUpdateResult, IncompleteReadError, type JsonObject, type MergeJsonColumnArgs, type MergeJsonColumnResult, type OAuthRefreshStorage, type PagedReadQuery, type PagedReadResult, type ReadAllRowsOptions, type ReadAllRowsRestOptions, type SessionSource, SessionUnavailableError, type TryWriteOneResult, type VersionedRow, WriteDidNotLandError, type WriteDidNotLandReason, type WriteFailureWords, type WriteOneAction, type WriteOneOptions, type WriteOneRowResult, WriteRefusedError, asJsonObject, assertWriteLanded, createActiveOrgCookie, createOAuthRefreshFetch, createSessionRetry, decodeActiveOrgSelection, decodeOAuthRefreshClaims, describeWriteFailure, encodeActiveOrgSelection, guardedUpdate, isMissingSessionError, mergeJsonColumn, personSentence, readAllRows, readAllRowsRest, serverMessageFromBody, tryReadAllRows, tryReadAllRowsRest, tryWriteOne, writeFailureStatus, writeOne, writeOneRow };
+/**
+ * @ai-matrx/data/db — record-unavailable: THE one shape for "a single-record
+ * read came back with zero rows".
+ *
+ * Ported from matrx-frontend `lib/records/recordUnavailable.ts`, which keeps
+ * its capture helpers (`recordUnavailable`, `resolveRecordUnavailableCapture`)
+ * and re-exports this class — so `RecordUnavailableError` is ONE class across
+ * the app and `@ai-matrx/chat`, and every `instanceof` keeps working.
+ *
+ * Zero rows is at least three different situations: the row was soft-deleted,
+ * the row is alive but this reader's access (org membership / permission
+ * grant) does not reach it, or the id is stale/wrong. Asserting deletion for
+ * all three is what D133 cost — two agent-review items were rejected as "site
+ * deleted or is no longer accessible" while the brand AND site were live and
+ * un-deleted; the null was RLS.
+ *
+ * So `deleted` is claimed ONLY when a probe proved it. Everything else is
+ * `unknown` and says both possibilities out loud. Never construct the error
+ * directly at a read site: the host's `recordUnavailable(...)` builds it AND
+ * captures it — the capture is the loud half of the contract.
+ */
+/** `deleted` is PROVEN (a probe read the row and saw `deleted_at`). */
+type RecordUnavailableReason = "deleted" | "unknown";
+/** The truth an access resolver can add after the initial ambiguous read failure. */
+type RecordUnavailableResolution = "denied" | "deleted" | "missing" | "signed-out" | "ok";
+declare class RecordUnavailableError extends Error {
+    readonly entity: string;
+    readonly reason: RecordUnavailableReason;
+    readonly recordId?: string | undefined;
+    /**
+     * Canonical entity token, when the read site knows it. With a token AND a
+     * recordId the renderer stops describing the ambiguity and ASKS the platform
+     * instead — an access gate resolves which of the four it really is.
+     * Without one, honest ambiguity is still the best available answer.
+     */
+    readonly token?: string | undefined;
+    /** Diagnostics identity for reconciling this exact capture in place. */
+    captureId?: string | undefined;
+    /** Last truth written to diagnostics; avoids duplicate reconciliation. */
+    captureResolution: RecordUnavailableReason | RecordUnavailableResolution;
+    constructor(input: {
+        entity: string;
+        reason: RecordUnavailableReason;
+        recordId?: string | undefined;
+        token?: string | undefined;
+    });
+}
+declare function recordUnavailableMessage(entity: string, reason: RecordUnavailableReason): string;
+declare function isRecordUnavailableError(value: unknown): value is RecordUnavailableError;
+
+export { type ActiveOrgCookie, type ActiveOrgCookieOptions, type ActiveOrgSelection, type AuthRetryableResult, BulkWriteError, type CreateActiveOrgCookieArgs, type CreateOAuthRefreshFetchArgs, type CreateSessionRetryOptions, DEFAULT_ACTIVE_ORG_COOKIE_MAX_AGE, DEFAULT_ACTIVE_ORG_COOKIE_NAME, type GuardedUpdateArgs, type GuardedUpdateResult, IncompleteReadError, type JsonObject, type MergeJsonColumnArgs, type MergeJsonColumnResult, type OAuthRefreshStorage, type PagedReadQuery, type PagedReadResult, type ReadAllRowsOptions, type ReadAllRowsRestOptions, RecordUnavailableError, type RecordUnavailableReason, type RecordUnavailableResolution, type SessionSource, SessionUnavailableError, type TryWriteOneResult, type VersionedRow, WriteDidNotLandError, type WriteDidNotLandReason, type WriteFailureWords, type WriteOneAction, type WriteOneOptions, type WriteOneRowResult, WriteRefusedError, asJsonObject, assertWriteLanded, createActiveOrgCookie, createOAuthRefreshFetch, createSessionRetry, decodeActiveOrgSelection, decodeOAuthRefreshClaims, describeWriteFailure, encodeActiveOrgSelection, guardedUpdate, isMissingSessionError, isRecordUnavailableError, mergeJsonColumn, personSentence, readAllRows, readAllRowsRest, recordUnavailableMessage, serverMessageFromBody, tryReadAllRows, tryReadAllRowsRest, tryWriteOne, writeFailureStatus, writeOne, writeOneRow };

package/dist/db.js

@@ -855,12 +855,49 @@ async function writeOneRow(write, options) {
     })
   };
 }
+
+// src/db/record-unavailable.ts
+var RecordUnavailableError = class extends Error {
+  entity;
+  reason;
+  recordId;
+  /**
+   * Canonical entity token, when the read site knows it. With a token AND a
+   * recordId the renderer stops describing the ambiguity and ASKS the platform
+   * instead — an access gate resolves which of the four it really is.
+   * Without one, honest ambiguity is still the best available answer.
+   */
+  token;
+  /** Diagnostics identity for reconciling this exact capture in place. */
+  captureId;
+  /** Last truth written to diagnostics; avoids duplicate reconciliation. */
+  captureResolution;
+  constructor(input) {
+    super(recordUnavailableMessage(input.entity, input.reason));
+    this.name = "RecordUnavailableError";
+    this.entity = input.entity;
+    this.reason = input.reason;
+    this.recordId = input.recordId;
+    this.token = input.token;
+    this.captureResolution = input.reason;
+  }
+};
+function recordUnavailableMessage(entity, reason) {
+  if (reason === "deleted") {
+    return `This ${entity} was deleted, so it can no longer be opened.`;
+  }
+  return `We couldn't open this ${entity}. It may have been deleted, or it may belong to an organization you don't have access to.`;
+}
+function isRecordUnavailableError(value) {
+  return value instanceof RecordUnavailableError;
+}
 export {
   BulkWriteError,
   DEFAULT_ACTIVE_ORG_COOKIE_MAX_AGE,
   DEFAULT_ACTIVE_ORG_COOKIE_NAME,
   DEFAULT_AUTH_COOKIE_NAME,
   IncompleteReadError,
+  RecordUnavailableError,
   SessionUnavailableError,
   WriteDidNotLandError,
   WriteRefusedError,
@@ -876,11 +913,13 @@ export {
   encodeActiveOrgSelection,
   guardedUpdate,
   isMissingSessionError,
+  isRecordUnavailableError,
   mergeJsonColumn,
   parseCookieHeader,
   personSentence,
   readAllRows,
   readAllRowsRest,
+  recordUnavailableMessage,
   serverMessageFromBody,
   tryReadAllRows,
   tryReadAllRowsRest,