@ai-matrx/data 0.18.41 → 0.19.0

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## 0.19.0 — the one session identity
+
+- New subpath `@ai-matrx/data/session-identity`: `createSessionIdentity({ client, words, toUserId?,
+  onDiagnostic? })`, `SERVER_SESSION_IDENTITY`, `authOf`, `sessionUserId` and the session types —
+  the acting user read from the Supabase client's session, never handed in (DD-240/DD-241). Each
+  product passes its own words; messaging and meet carried a copy each until now (architecture
+  step 11).
+- New subpath `@ai-matrx/data/testing`: `fakeSession`, `withSession`, `signedInAs` for tests that
+  need a signed-in fake client.
+
+Consumer action: none (additive).
+
+## 0.18.42
+
+Automatic changed-only republish (docs/metadata drift since the last tag — see
+`git diff npm/data/v0.18.41..npm/data/v0.18.42 -- apps/shared/data`).
+No source changes intended and no consumer action required.
+
 ## 0.18.41
 
 Automatic changed-only republish (docs/metadata drift since the last tag — see

package/dist/session-identity.cjs

@@ -0,0 +1,126 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/session-identity.ts
+var session_identity_exports = {};
+__export(session_identity_exports, {
+  SERVER_SESSION_IDENTITY: () => SERVER_SESSION_IDENTITY,
+  authOf: () => authOf,
+  createSessionIdentity: () => createSessionIdentity,
+  noAuthSourceMessage: () => noAuthSourceMessage,
+  sessionUserId: () => sessionUserId,
+  unreadableSessionMessage: () => unreadableSessionMessage
+});
+module.exports = __toCommonJS(session_identity_exports);
+var RESOLVING = Object.freeze({
+  state: "resolving",
+  userId: null
+});
+var SERVER_SESSION_IDENTITY = RESOLVING;
+function authOf(client) {
+  if (client === null || typeof client !== "object" && typeof client !== "function") return null;
+  const candidate = client.auth;
+  if (candidate === null || typeof candidate !== "object") return null;
+  const auth = candidate;
+  if (typeof auth.getSession !== "function") return null;
+  if (typeof auth.onAuthStateChange !== "function") return null;
+  return auth;
+}
+function sessionUserId(session) {
+  const id = session?.user?.id;
+  return typeof id === "string" && id.length > 0 ? id : null;
+}
+function noAuthSourceMessage(words) {
+  return {
+    message: `${words.product} cannot tell who is signed in: the Supabase client it was given has no auth session source.`,
+    remedy: words.noAuthSourceRemedy
+  };
+}
+function unreadableSessionMessage(words, error) {
+  return `${words.product} could not read the signed-in session: ${String(
+    error?.message ?? error
+  )}`;
+}
+function createSessionIdentity(options) {
+  const { client, onDiagnostic, words } = options;
+  const brand = options.toUserId ?? ((id) => id);
+  const listeners = /* @__PURE__ */ new Set();
+  let current = RESOLVING;
+  let disposed = false;
+  const userIdOf = (session) => {
+    const id = sessionUserId(session);
+    return id === null ? null : brand(id);
+  };
+  const publish = (state, userId) => {
+    if (disposed) return;
+    if (current.state === state && current.userId === userId) return;
+    current = Object.freeze({ state, userId });
+    for (const listener of [...listeners]) listener();
+  };
+  const subscribeOnly = (hasAuthSource) => ({
+    hasAuthSource,
+    snapshot: () => current,
+    subscribe: (listener) => {
+      listeners.add(listener);
+      return () => {
+        listeners.delete(listener);
+      };
+    },
+    dispose: () => {
+      disposed = true;
+      listeners.clear();
+    }
+  });
+  const auth = authOf(client);
+  if (auth === null) {
+    onDiagnostic?.({ level: "error", ...noAuthSourceMessage(words) });
+    current = Object.freeze({ state: "resolved", userId: null });
+    return subscribeOnly(false);
+  }
+  void (async () => {
+    try {
+      const result = await auth.getSession();
+      publish("resolved", userIdOf(result?.data?.session));
+    } catch (error) {
+      onDiagnostic?.({
+        level: "warn",
+        message: unreadableSessionMessage(words, error),
+        remedy: words.unreadableRemedy
+      });
+      publish("resolved", null);
+    }
+  })();
+  const subscription = auth.onAuthStateChange((_event, session) => {
+    publish("resolved", userIdOf(session));
+  });
+  const base = subscribeOnly(true);
+  return {
+    hasAuthSource: true,
+    snapshot: base.snapshot,
+    subscribe: base.subscribe,
+    dispose: () => {
+      base.dispose();
+      try {
+        subscription.data.subscription.unsubscribe();
+      } catch {
+      }
+    }
+  };
+}
+//# sourceMappingURL=session-identity.cjs.map

package/dist/session-identity.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/session-identity.ts"],"sourcesContent":["/**\n * WHO IS ACTING — read from the Supabase client's session, never handed in (DD-240, DD-241).\n *\n * THE CLASS THIS CLOSES. A package that takes the acting user's id from its host (a `userId` prop\n * or option) gets the host's copy, written once when the app boots. Nothing rewrites that copy\n * when the domain-wide auth cookie rotates to another account, when the person signs out in\n * another tab, or when a refresh returns a different subject — so the package goes on issuing\n * reads (meet, DD-240) and writes (`sender_id`, `created_by` in messaging, DD-241) on behalf of\n * somebody the session no longer is. The defect is that a user id can be handed in at all.\n *\n * The rules:\n *  - The acting user is `getSession()`'s answer, then every `onAuthStateChange` after it — the\n *    same read supabase-js uses to mint the next request's JWT.\n *  - `resolving` until the first read answers; nothing user-scoped is issued on a guess.\n *  - `snapshot()` returns THE SAME REFERENCE until the acting user moves (a\n *    `useSyncExternalStore` source that returns a fresh object per call is \"Maximum update depth\n *    exceeded\", not a warning).\n *  - A client with no auth source is a named misconfiguration (`hasAuthSource: false`), never a\n *    silent fall back to \"nobody\".\n *\n * One home (architecture step 11): messaging and meet each carried a copy until data 0.19.0.\n * Each product passes its own words (`words`) and, when it brands ids, its `toUserId`.\n */\n\n/** What a session looks like to this module. Nothing else is read from it. */\nexport interface AuthSessionLike {\n  readonly user?: { readonly id?: string | null } | null | undefined;\n}\n\nexport interface AuthSubscriptionLike {\n  readonly data: { readonly subscription: { unsubscribe(): void } };\n}\n\n/** The subset of `client.auth` read here — an internal contract, never a public prop type. */\nexport interface AuthLike {\n  getSession(): PromiseLike<{\n    data: { session?: AuthSessionLike | null | undefined };\n  }>;\n  onAuthStateChange(\n    callback: (event: string, session: AuthSessionLike | null) => void,\n  ): AuthSubscriptionLike;\n}\n\nexport interface SessionIdentitySnapshot<Id extends string = string> {\n  /** `resolving` until the first `getSession()` answers. */\n  readonly state: \"resolving\" | \"resolved\";\n  /** Who the session says is acting, or `null` for nobody. */\n  readonly userId: Id | null;\n}\n\nexport interface SessionIdentity<Id extends string = string> {\n  /** False when the client has no auth source at all — a misconfiguration, not \"signed out\". */\n  readonly hasAuthSource: boolean;\n  /** Stable reference until the acting user actually changes. */\n  snapshot(): SessionIdentitySnapshot<Id>;\n  subscribe(listener: () => void): () => void;\n  dispose(): void;\n}\n\nexport interface SessionIdentityDiagnostic {\n  level: \"info\" | \"warn\" | \"error\";\n  message: string;\n  remedy?: string | undefined;\n}\n\n/** The sentences a product says about its own session. */\nexport interface SessionIdentityWords {\n  /** The product's name as the subject of a sentence, e.g. \"Messaging\". */\n  readonly product: string;\n  /** Remedy when the client has no auth source. */\n  readonly noAuthSourceRemedy: string;\n  /** Remedy when the session could not be read. */\n  readonly unreadableRemedy: string;\n}\n\nexport interface SessionIdentityOptions<Id extends string = string> {\n  /** The host's browser Supabase client (anything with `auth.getSession` / `onAuthStateChange`). */\n  readonly client: unknown;\n  readonly words: SessionIdentityWords;\n  /** Brand the raw id (default: the string itself). */\n  readonly toUserId?: ((id: string) => Id) | undefined;\n  readonly onDiagnostic?: ((event: SessionIdentityDiagnostic) => void) | undefined;\n}\n\nconst RESOLVING: SessionIdentitySnapshot<never> = Object.freeze({\n  state: \"resolving\" as const,\n  userId: null,\n});\n\n/** The snapshot every server render sees: nobody is acting on a server. */\nexport const SERVER_SESSION_IDENTITY: SessionIdentitySnapshot<never> = RESOLVING;\n\n/**\n * The one narrowing. A client whose `auth` is missing or not shaped like an auth client is a real\n * failure — the caller says so and stays `resolved` with nobody acting (inert, never wrong).\n */\nexport function authOf(client: unknown): AuthLike | null {\n  if (client === null || (typeof client !== \"object\" && typeof client !== \"function\")) return null;\n  const candidate = (client as { auth?: unknown }).auth;\n  if (candidate === null || typeof candidate !== \"object\") return null;\n  const auth = candidate as Partial<AuthLike>;\n  if (typeof auth.getSession !== \"function\") return null;\n  if (typeof auth.onAuthStateChange !== \"function\") return null;\n  return auth as AuthLike;\n}\n\n/** The session's user id, or `null` for nobody. */\nexport function sessionUserId(session: AuthSessionLike | null | undefined): string | null {\n  const id = session?.user?.id;\n  return typeof id === \"string\" && id.length > 0 ? id : null;\n}\n\n/** The named failure a client with no auth source gets. */\nexport function noAuthSourceMessage(words: SessionIdentityWords): { message: string; remedy: string } {\n  return {\n    message:\n      `${words.product} cannot tell who is signed in: the Supabase client it was given has no ` +\n      \"auth session source.\",\n    remedy: words.noAuthSourceRemedy,\n  };\n}\n\n/** The sentence for a session read that threw. */\nexport function unreadableSessionMessage(words: SessionIdentityWords, error: unknown): string {\n  return `${words.product} could not read the signed-in session: ${String(\n    (error as Error)?.message ?? error,\n  )}`;\n}\n\nexport function createSessionIdentity<Id extends string = string>(\n  options: SessionIdentityOptions<Id>,\n): SessionIdentity<Id> {\n  const { client, onDiagnostic, words } = options;\n  const brand = options.toUserId ?? ((id: string) => id as Id);\n  const listeners = new Set<() => void>();\n  let current: SessionIdentitySnapshot<Id> = RESOLVING;\n  let disposed = false;\n\n  const userIdOf = (session: AuthSessionLike | null | undefined): Id | null => {\n    const id = sessionUserId(session);\n    return id === null ? null : brand(id);\n  };\n\n  const publish = (state: \"resolving\" | \"resolved\", userId: Id | null): void => {\n    if (disposed) return;\n    // SAME REFERENCE until the fact moves.\n    if (current.state === state && current.userId === userId) return;\n    current = Object.freeze({ state, userId });\n    for (const listener of [...listeners]) listener();\n  };\n\n  const subscribeOnly = (hasAuthSource: boolean): SessionIdentity<Id> => ({\n    hasAuthSource,\n    snapshot: () => current,\n    subscribe: (listener) => {\n      listeners.add(listener);\n      return () => {\n        listeners.delete(listener);\n      };\n    },\n    dispose: () => {\n      disposed = true;\n      listeners.clear();\n    },\n  });\n\n  const auth = authOf(client);\n  if (auth === null) {\n    onDiagnostic?.({ level: \"error\", ...noAuthSourceMessage(words) });\n    current = Object.freeze({ state: \"resolved\" as const, userId: null });\n    return subscribeOnly(false);\n  }\n\n  // The first read. `getSession()` awaits auth-js's own initialization and its single-flighted\n  // refresh, so this is the same answer the next PostgREST request's JWT will carry.\n  void (async () => {\n    try {\n      const result = await auth.getSession();\n      publish(\"resolved\", userIdOf(result?.data?.session));\n    } catch (error: unknown) {\n      onDiagnostic?.({\n        level: \"warn\",\n        message: unreadableSessionMessage(words, error),\n        remedy: words.unreadableRemedy,\n      });\n      publish(\"resolved\", null);\n    }\n  })();\n\n  // …and every change after it: a sign-out, an account switch, a refresh with a different subject.\n  const subscription = auth.onAuthStateChange((_event, session) => {\n    publish(\"resolved\", userIdOf(session));\n  });\n\n  const base = subscribeOnly(true);\n  return {\n    hasAuthSource: true,\n    snapshot: base.snapshot,\n    subscribe: base.subscribe,\n    dispose: () => {\n      base.dispose();\n      try {\n        subscription.data.subscription.unsubscribe();\n      } catch {\n        // An already-torn-down subscription is not a failure worth a sentence.\n      }\n    },\n  };\n}\n"],"mappings":"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","names":[]}

package/dist/session-identity.d.cts

@@ -0,0 +1,100 @@
+/**
+ * WHO IS ACTING — read from the Supabase client's session, never handed in (DD-240, DD-241).
+ *
+ * THE CLASS THIS CLOSES. A package that takes the acting user's id from its host (a `userId` prop
+ * or option) gets the host's copy, written once when the app boots. Nothing rewrites that copy
+ * when the domain-wide auth cookie rotates to another account, when the person signs out in
+ * another tab, or when a refresh returns a different subject — so the package goes on issuing
+ * reads (meet, DD-240) and writes (`sender_id`, `created_by` in messaging, DD-241) on behalf of
+ * somebody the session no longer is. The defect is that a user id can be handed in at all.
+ *
+ * The rules:
+ *  - The acting user is `getSession()`'s answer, then every `onAuthStateChange` after it — the
+ *    same read supabase-js uses to mint the next request's JWT.
+ *  - `resolving` until the first read answers; nothing user-scoped is issued on a guess.
+ *  - `snapshot()` returns THE SAME REFERENCE until the acting user moves (a
+ *    `useSyncExternalStore` source that returns a fresh object per call is "Maximum update depth
+ *    exceeded", not a warning).
+ *  - A client with no auth source is a named misconfiguration (`hasAuthSource: false`), never a
+ *    silent fall back to "nobody".
+ *
+ * One home (architecture step 11): messaging and meet each carried a copy until data 0.19.0.
+ * Each product passes its own words (`words`) and, when it brands ids, its `toUserId`.
+ */
+/** What a session looks like to this module. Nothing else is read from it. */
+interface AuthSessionLike {
+    readonly user?: {
+        readonly id?: string | null;
+    } | null | undefined;
+}
+interface AuthSubscriptionLike {
+    readonly data: {
+        readonly subscription: {
+            unsubscribe(): void;
+        };
+    };
+}
+/** The subset of `client.auth` read here — an internal contract, never a public prop type. */
+interface AuthLike {
+    getSession(): PromiseLike<{
+        data: {
+            session?: AuthSessionLike | null | undefined;
+        };
+    }>;
+    onAuthStateChange(callback: (event: string, session: AuthSessionLike | null) => void): AuthSubscriptionLike;
+}
+interface SessionIdentitySnapshot<Id extends string = string> {
+    /** `resolving` until the first `getSession()` answers. */
+    readonly state: "resolving" | "resolved";
+    /** Who the session says is acting, or `null` for nobody. */
+    readonly userId: Id | null;
+}
+interface SessionIdentity<Id extends string = string> {
+    /** False when the client has no auth source at all — a misconfiguration, not "signed out". */
+    readonly hasAuthSource: boolean;
+    /** Stable reference until the acting user actually changes. */
+    snapshot(): SessionIdentitySnapshot<Id>;
+    subscribe(listener: () => void): () => void;
+    dispose(): void;
+}
+interface SessionIdentityDiagnostic {
+    level: "info" | "warn" | "error";
+    message: string;
+    remedy?: string | undefined;
+}
+/** The sentences a product says about its own session. */
+interface SessionIdentityWords {
+    /** The product's name as the subject of a sentence, e.g. "Messaging". */
+    readonly product: string;
+    /** Remedy when the client has no auth source. */
+    readonly noAuthSourceRemedy: string;
+    /** Remedy when the session could not be read. */
+    readonly unreadableRemedy: string;
+}
+interface SessionIdentityOptions<Id extends string = string> {
+    /** The host's browser Supabase client (anything with `auth.getSession` / `onAuthStateChange`). */
+    readonly client: unknown;
+    readonly words: SessionIdentityWords;
+    /** Brand the raw id (default: the string itself). */
+    readonly toUserId?: ((id: string) => Id) | undefined;
+    readonly onDiagnostic?: ((event: SessionIdentityDiagnostic) => void) | undefined;
+}
+/** The snapshot every server render sees: nobody is acting on a server. */
+declare const SERVER_SESSION_IDENTITY: SessionIdentitySnapshot<never>;
+/**
+ * The one narrowing. A client whose `auth` is missing or not shaped like an auth client is a real
+ * failure — the caller says so and stays `resolved` with nobody acting (inert, never wrong).
+ */
+declare function authOf(client: unknown): AuthLike | null;
+/** The session's user id, or `null` for nobody. */
+declare function sessionUserId(session: AuthSessionLike | null | undefined): string | null;
+/** The named failure a client with no auth source gets. */
+declare function noAuthSourceMessage(words: SessionIdentityWords): {
+    message: string;
+    remedy: string;
+};
+/** The sentence for a session read that threw. */
+declare function unreadableSessionMessage(words: SessionIdentityWords, error: unknown): string;
+declare function createSessionIdentity<Id extends string = string>(options: SessionIdentityOptions<Id>): SessionIdentity<Id>;
+
+export { type AuthLike, type AuthSessionLike, type AuthSubscriptionLike, SERVER_SESSION_IDENTITY, type SessionIdentity, type SessionIdentityDiagnostic, type SessionIdentityOptions, type SessionIdentitySnapshot, type SessionIdentityWords, authOf, createSessionIdentity, noAuthSourceMessage, sessionUserId, unreadableSessionMessage };

package/dist/session-identity.d.ts

@@ -0,0 +1,100 @@
+/**
+ * WHO IS ACTING — read from the Supabase client's session, never handed in (DD-240, DD-241).
+ *
+ * THE CLASS THIS CLOSES. A package that takes the acting user's id from its host (a `userId` prop
+ * or option) gets the host's copy, written once when the app boots. Nothing rewrites that copy
+ * when the domain-wide auth cookie rotates to another account, when the person signs out in
+ * another tab, or when a refresh returns a different subject — so the package goes on issuing
+ * reads (meet, DD-240) and writes (`sender_id`, `created_by` in messaging, DD-241) on behalf of
+ * somebody the session no longer is. The defect is that a user id can be handed in at all.
+ *
+ * The rules:
+ *  - The acting user is `getSession()`'s answer, then every `onAuthStateChange` after it — the
+ *    same read supabase-js uses to mint the next request's JWT.
+ *  - `resolving` until the first read answers; nothing user-scoped is issued on a guess.
+ *  - `snapshot()` returns THE SAME REFERENCE until the acting user moves (a
+ *    `useSyncExternalStore` source that returns a fresh object per call is "Maximum update depth
+ *    exceeded", not a warning).
+ *  - A client with no auth source is a named misconfiguration (`hasAuthSource: false`), never a
+ *    silent fall back to "nobody".
+ *
+ * One home (architecture step 11): messaging and meet each carried a copy until data 0.19.0.
+ * Each product passes its own words (`words`) and, when it brands ids, its `toUserId`.
+ */
+/** What a session looks like to this module. Nothing else is read from it. */
+interface AuthSessionLike {
+    readonly user?: {
+        readonly id?: string | null;
+    } | null | undefined;
+}
+interface AuthSubscriptionLike {
+    readonly data: {
+        readonly subscription: {
+            unsubscribe(): void;
+        };
+    };
+}
+/** The subset of `client.auth` read here — an internal contract, never a public prop type. */
+interface AuthLike {
+    getSession(): PromiseLike<{
+        data: {
+            session?: AuthSessionLike | null | undefined;
+        };
+    }>;
+    onAuthStateChange(callback: (event: string, session: AuthSessionLike | null) => void): AuthSubscriptionLike;
+}
+interface SessionIdentitySnapshot<Id extends string = string> {
+    /** `resolving` until the first `getSession()` answers. */
+    readonly state: "resolving" | "resolved";
+    /** Who the session says is acting, or `null` for nobody. */
+    readonly userId: Id | null;
+}
+interface SessionIdentity<Id extends string = string> {
+    /** False when the client has no auth source at all — a misconfiguration, not "signed out". */
+    readonly hasAuthSource: boolean;
+    /** Stable reference until the acting user actually changes. */
+    snapshot(): SessionIdentitySnapshot<Id>;
+    subscribe(listener: () => void): () => void;
+    dispose(): void;
+}
+interface SessionIdentityDiagnostic {
+    level: "info" | "warn" | "error";
+    message: string;
+    remedy?: string | undefined;
+}
+/** The sentences a product says about its own session. */
+interface SessionIdentityWords {
+    /** The product's name as the subject of a sentence, e.g. "Messaging". */
+    readonly product: string;
+    /** Remedy when the client has no auth source. */
+    readonly noAuthSourceRemedy: string;
+    /** Remedy when the session could not be read. */
+    readonly unreadableRemedy: string;
+}
+interface SessionIdentityOptions<Id extends string = string> {
+    /** The host's browser Supabase client (anything with `auth.getSession` / `onAuthStateChange`). */
+    readonly client: unknown;
+    readonly words: SessionIdentityWords;
+    /** Brand the raw id (default: the string itself). */
+    readonly toUserId?: ((id: string) => Id) | undefined;
+    readonly onDiagnostic?: ((event: SessionIdentityDiagnostic) => void) | undefined;
+}
+/** The snapshot every server render sees: nobody is acting on a server. */
+declare const SERVER_SESSION_IDENTITY: SessionIdentitySnapshot<never>;
+/**
+ * The one narrowing. A client whose `auth` is missing or not shaped like an auth client is a real
+ * failure — the caller says so and stays `resolved` with nobody acting (inert, never wrong).
+ */
+declare function authOf(client: unknown): AuthLike | null;
+/** The session's user id, or `null` for nobody. */
+declare function sessionUserId(session: AuthSessionLike | null | undefined): string | null;
+/** The named failure a client with no auth source gets. */
+declare function noAuthSourceMessage(words: SessionIdentityWords): {
+    message: string;
+    remedy: string;
+};
+/** The sentence for a session read that threw. */
+declare function unreadableSessionMessage(words: SessionIdentityWords, error: unknown): string;
+declare function createSessionIdentity<Id extends string = string>(options: SessionIdentityOptions<Id>): SessionIdentity<Id>;
+
+export { type AuthLike, type AuthSessionLike, type AuthSubscriptionLike, SERVER_SESSION_IDENTITY, type SessionIdentity, type SessionIdentityDiagnostic, type SessionIdentityOptions, type SessionIdentitySnapshot, type SessionIdentityWords, authOf, createSessionIdentity, noAuthSourceMessage, sessionUserId, unreadableSessionMessage };

package/dist/session-identity.js

@@ -0,0 +1,105 @@
+// src/session-identity.ts
+var RESOLVING = Object.freeze({
+  state: "resolving",
+  userId: null
+});
+var SERVER_SESSION_IDENTITY = RESOLVING;
+function authOf(client) {
+  if (client === null || typeof client !== "object" && typeof client !== "function") return null;
+  const candidate = client.auth;
+  if (candidate === null || typeof candidate !== "object") return null;
+  const auth = candidate;
+  if (typeof auth.getSession !== "function") return null;
+  if (typeof auth.onAuthStateChange !== "function") return null;
+  return auth;
+}
+function sessionUserId(session) {
+  const id = session?.user?.id;
+  return typeof id === "string" && id.length > 0 ? id : null;
+}
+function noAuthSourceMessage(words) {
+  return {
+    message: `${words.product} cannot tell who is signed in: the Supabase client it was given has no auth session source.`,
+    remedy: words.noAuthSourceRemedy
+  };
+}
+function unreadableSessionMessage(words, error) {
+  return `${words.product} could not read the signed-in session: ${String(
+    error?.message ?? error
+  )}`;
+}
+function createSessionIdentity(options) {
+  const { client, onDiagnostic, words } = options;
+  const brand = options.toUserId ?? ((id) => id);
+  const listeners = /* @__PURE__ */ new Set();
+  let current = RESOLVING;
+  let disposed = false;
+  const userIdOf = (session) => {
+    const id = sessionUserId(session);
+    return id === null ? null : brand(id);
+  };
+  const publish = (state, userId) => {
+    if (disposed) return;
+    if (current.state === state && current.userId === userId) return;
+    current = Object.freeze({ state, userId });
+    for (const listener of [...listeners]) listener();
+  };
+  const subscribeOnly = (hasAuthSource) => ({
+    hasAuthSource,
+    snapshot: () => current,
+    subscribe: (listener) => {
+      listeners.add(listener);
+      return () => {
+        listeners.delete(listener);
+      };
+    },
+    dispose: () => {
+      disposed = true;
+      listeners.clear();
+    }
+  });
+  const auth = authOf(client);
+  if (auth === null) {
+    onDiagnostic?.({ level: "error", ...noAuthSourceMessage(words) });
+    current = Object.freeze({ state: "resolved", userId: null });
+    return subscribeOnly(false);
+  }
+  void (async () => {
+    try {
+      const result = await auth.getSession();
+      publish("resolved", userIdOf(result?.data?.session));
+    } catch (error) {
+      onDiagnostic?.({
+        level: "warn",
+        message: unreadableSessionMessage(words, error),
+        remedy: words.unreadableRemedy
+      });
+      publish("resolved", null);
+    }
+  })();
+  const subscription = auth.onAuthStateChange((_event, session) => {
+    publish("resolved", userIdOf(session));
+  });
+  const base = subscribeOnly(true);
+  return {
+    hasAuthSource: true,
+    snapshot: base.snapshot,
+    subscribe: base.subscribe,
+    dispose: () => {
+      base.dispose();
+      try {
+        subscription.data.subscription.unsubscribe();
+      } catch {
+      }
+    }
+  };
+}
+export {
+  SERVER_SESSION_IDENTITY,
+  authOf,
+  createSessionIdentity,
+  noAuthSourceMessage,
+  sessionUserId,
+  unreadableSessionMessage
+};
+//# sourceMappingURL=session-identity.js.map

package/dist/session-identity.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/session-identity.ts"],"sourcesContent":["/**\n * WHO IS ACTING — read from the Supabase client's session, never handed in (DD-240, DD-241).\n *\n * THE CLASS THIS CLOSES. A package that takes the acting user's id from its host (a `userId` prop\n * or option) gets the host's copy, written once when the app boots. Nothing rewrites that copy\n * when the domain-wide auth cookie rotates to another account, when the person signs out in\n * another tab, or when a refresh returns a different subject — so the package goes on issuing\n * reads (meet, DD-240) and writes (`sender_id`, `created_by` in messaging, DD-241) on behalf of\n * somebody the session no longer is. The defect is that a user id can be handed in at all.\n *\n * The rules:\n *  - The acting user is `getSession()`'s answer, then every `onAuthStateChange` after it — the\n *    same read supabase-js uses to mint the next request's JWT.\n *  - `resolving` until the first read answers; nothing user-scoped is issued on a guess.\n *  - `snapshot()` returns THE SAME REFERENCE until the acting user moves (a\n *    `useSyncExternalStore` source that returns a fresh object per call is \"Maximum update depth\n *    exceeded\", not a warning).\n *  - A client with no auth source is a named misconfiguration (`hasAuthSource: false`), never a\n *    silent fall back to \"nobody\".\n *\n * One home (architecture step 11): messaging and meet each carried a copy until data 0.19.0.\n * Each product passes its own words (`words`) and, when it brands ids, its `toUserId`.\n */\n\n/** What a session looks like to this module. Nothing else is read from it. */\nexport interface AuthSessionLike {\n  readonly user?: { readonly id?: string | null } | null | undefined;\n}\n\nexport interface AuthSubscriptionLike {\n  readonly data: { readonly subscription: { unsubscribe(): void } };\n}\n\n/** The subset of `client.auth` read here — an internal contract, never a public prop type. */\nexport interface AuthLike {\n  getSession(): PromiseLike<{\n    data: { session?: AuthSessionLike | null | undefined };\n  }>;\n  onAuthStateChange(\n    callback: (event: string, session: AuthSessionLike | null) => void,\n  ): AuthSubscriptionLike;\n}\n\nexport interface SessionIdentitySnapshot<Id extends string = string> {\n  /** `resolving` until the first `getSession()` answers. */\n  readonly state: \"resolving\" | \"resolved\";\n  /** Who the session says is acting, or `null` for nobody. */\n  readonly userId: Id | null;\n}\n\nexport interface SessionIdentity<Id extends string = string> {\n  /** False when the client has no auth source at all — a misconfiguration, not \"signed out\". */\n  readonly hasAuthSource: boolean;\n  /** Stable reference until the acting user actually changes. */\n  snapshot(): SessionIdentitySnapshot<Id>;\n  subscribe(listener: () => void): () => void;\n  dispose(): void;\n}\n\nexport interface SessionIdentityDiagnostic {\n  level: \"info\" | \"warn\" | \"error\";\n  message: string;\n  remedy?: string | undefined;\n}\n\n/** The sentences a product says about its own session. */\nexport interface SessionIdentityWords {\n  /** The product's name as the subject of a sentence, e.g. \"Messaging\". */\n  readonly product: string;\n  /** Remedy when the client has no auth source. */\n  readonly noAuthSourceRemedy: string;\n  /** Remedy when the session could not be read. */\n  readonly unreadableRemedy: string;\n}\n\nexport interface SessionIdentityOptions<Id extends string = string> {\n  /** The host's browser Supabase client (anything with `auth.getSession` / `onAuthStateChange`). */\n  readonly client: unknown;\n  readonly words: SessionIdentityWords;\n  /** Brand the raw id (default: the string itself). */\n  readonly toUserId?: ((id: string) => Id) | undefined;\n  readonly onDiagnostic?: ((event: SessionIdentityDiagnostic) => void) | undefined;\n}\n\nconst RESOLVING: SessionIdentitySnapshot<never> = Object.freeze({\n  state: \"resolving\" as const,\n  userId: null,\n});\n\n/** The snapshot every server render sees: nobody is acting on a server. */\nexport const SERVER_SESSION_IDENTITY: SessionIdentitySnapshot<never> = RESOLVING;\n\n/**\n * The one narrowing. A client whose `auth` is missing or not shaped like an auth client is a real\n * failure — the caller says so and stays `resolved` with nobody acting (inert, never wrong).\n */\nexport function authOf(client: unknown): AuthLike | null {\n  if (client === null || (typeof client !== \"object\" && typeof client !== \"function\")) return null;\n  const candidate = (client as { auth?: unknown }).auth;\n  if (candidate === null || typeof candidate !== \"object\") return null;\n  const auth = candidate as Partial<AuthLike>;\n  if (typeof auth.getSession !== \"function\") return null;\n  if (typeof auth.onAuthStateChange !== \"function\") return null;\n  return auth as AuthLike;\n}\n\n/** The session's user id, or `null` for nobody. */\nexport function sessionUserId(session: AuthSessionLike | null | undefined): string | null {\n  const id = session?.user?.id;\n  return typeof id === \"string\" && id.length > 0 ? id : null;\n}\n\n/** The named failure a client with no auth source gets. */\nexport function noAuthSourceMessage(words: SessionIdentityWords): { message: string; remedy: string } {\n  return {\n    message:\n      `${words.product} cannot tell who is signed in: the Supabase client it was given has no ` +\n      \"auth session source.\",\n    remedy: words.noAuthSourceRemedy,\n  };\n}\n\n/** The sentence for a session read that threw. */\nexport function unreadableSessionMessage(words: SessionIdentityWords, error: unknown): string {\n  return `${words.product} could not read the signed-in session: ${String(\n    (error as Error)?.message ?? error,\n  )}`;\n}\n\nexport function createSessionIdentity<Id extends string = string>(\n  options: SessionIdentityOptions<Id>,\n): SessionIdentity<Id> {\n  const { client, onDiagnostic, words } = options;\n  const brand = options.toUserId ?? ((id: string) => id as Id);\n  const listeners = new Set<() => void>();\n  let current: SessionIdentitySnapshot<Id> = RESOLVING;\n  let disposed = false;\n\n  const userIdOf = (session: AuthSessionLike | null | undefined): Id | null => {\n    const id = sessionUserId(session);\n    return id === null ? null : brand(id);\n  };\n\n  const publish = (state: \"resolving\" | \"resolved\", userId: Id | null): void => {\n    if (disposed) return;\n    // SAME REFERENCE until the fact moves.\n    if (current.state === state && current.userId === userId) return;\n    current = Object.freeze({ state, userId });\n    for (const listener of [...listeners]) listener();\n  };\n\n  const subscribeOnly = (hasAuthSource: boolean): SessionIdentity<Id> => ({\n    hasAuthSource,\n    snapshot: () => current,\n    subscribe: (listener) => {\n      listeners.add(listener);\n      return () => {\n        listeners.delete(listener);\n      };\n    },\n    dispose: () => {\n      disposed = true;\n      listeners.clear();\n    },\n  });\n\n  const auth = authOf(client);\n  if (auth === null) {\n    onDiagnostic?.({ level: \"error\", ...noAuthSourceMessage(words) });\n    current = Object.freeze({ state: \"resolved\" as const, userId: null });\n    return subscribeOnly(false);\n  }\n\n  // The first read. `getSession()` awaits auth-js's own initialization and its single-flighted\n  // refresh, so this is the same answer the next PostgREST request's JWT will carry.\n  void (async () => {\n    try {\n      const result = await auth.getSession();\n      publish(\"resolved\", userIdOf(result?.data?.session));\n    } catch (error: unknown) {\n      onDiagnostic?.({\n        level: \"warn\",\n        message: unreadableSessionMessage(words, error),\n        remedy: words.unreadableRemedy,\n      });\n      publish(\"resolved\", null);\n    }\n  })();\n\n  // …and every change after it: a sign-out, an account switch, a refresh with a different subject.\n  const subscription = auth.onAuthStateChange((_event, session) => {\n    publish(\"resolved\", userIdOf(session));\n  });\n\n  const base = subscribeOnly(true);\n  return {\n    hasAuthSource: true,\n    snapshot: base.snapshot,\n    subscribe: base.subscribe,\n    dispose: () => {\n      base.dispose();\n      try {\n        subscription.data.subscription.unsubscribe();\n      } catch {\n        // An already-torn-down subscription is not a failure worth a sentence.\n      }\n    },\n  };\n}\n"],"mappings":"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","names":[]}

package/dist/testing.cjs

@@ -0,0 +1,68 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/testing.ts
+var testing_exports = {};
+__export(testing_exports, {
+  fakeSession: () => fakeSession,
+  signedInAs: () => signedInAs,
+  withSession: () => withSession
+});
+module.exports = __toCommonJS(testing_exports);
+function fakeSession(userId) {
+  let current = userId;
+  let reads = 0;
+  const listeners = /* @__PURE__ */ new Set();
+  const sessionOf = (id) => id === null ? null : { user: { id } };
+  return {
+    auth: {
+      getSession: async () => {
+        reads += 1;
+        return { data: { session: sessionOf(current) } };
+      },
+      onAuthStateChange: (callback) => {
+        listeners.add(callback);
+        return {
+          data: {
+            subscription: {
+              unsubscribe: () => {
+                listeners.delete(callback);
+              }
+            }
+          }
+        };
+      }
+    },
+    setUser: (next) => {
+      current = next;
+      for (const listener of [...listeners]) {
+        listener(next === null ? "SIGNED_OUT" : "SIGNED_IN", sessionOf(next));
+      }
+    },
+    reads: () => reads
+  };
+}
+function withSession(client, session) {
+  client.auth = session.auth;
+  return client;
+}
+function signedInAs(client, userId) {
+  return withSession(client, fakeSession(userId));
+}
+//# sourceMappingURL=testing.cjs.map

package/dist/testing.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/testing.ts"],"sourcesContent":["/**\n * Test helpers for packages that read the acting user from a Supabase client's session\n * (`@ai-matrx/data/session-identity`). Tests only — never imported by shipped runtime code.\n *\n * A test that wants a signed-in user says so the way the real world does: by giving the fake\n * client a session. `setUser` performs the thing that broke production — the account under the\n * tab changing while the tab stays open.\n */\nimport type { AuthSessionLike } from \"./session-identity\";\n\nexport interface FakeSession {\n  readonly auth: {\n    getSession(): Promise<{ data: { session: AuthSessionLike | null } }>;\n    onAuthStateChange(\n      callback: (event: string, session: AuthSessionLike | null) => void,\n    ): { data: { subscription: { unsubscribe(): void } } };\n  };\n  /** Change who is signed in, exactly as a cookie rotation or a switch does. */\n  setUser(userId: string | null): void;\n  /** How many times the session has actually been read. */\n  readonly reads: () => number;\n}\n\nexport function fakeSession(userId: string | null): FakeSession {\n  let current: string | null = userId;\n  let reads = 0;\n  const listeners = new Set<(event: string, session: AuthSessionLike | null) => void>();\n  const sessionOf = (id: string | null): AuthSessionLike | null => (id === null ? null : { user: { id } });\n  return {\n    auth: {\n      getSession: async () => {\n        reads += 1;\n        return { data: { session: sessionOf(current) } };\n      },\n      onAuthStateChange: (callback) => {\n        listeners.add(callback);\n        return {\n          data: {\n            subscription: {\n              unsubscribe: () => {\n                listeners.delete(callback);\n              },\n            },\n          },\n        };\n      },\n    },\n    setUser: (next) => {\n      current = next;\n      for (const listener of [...listeners]) {\n        listener(next === null ? \"SIGNED_OUT\" : \"SIGNED_IN\", sessionOf(next));\n      }\n    },\n    reads: () => reads,\n  };\n}\n\n/** Attach a session to any fake client without disturbing its other methods. */\nexport function withSession<T>(client: T, session: FakeSession): T {\n  (client as unknown as { auth: unknown }).auth = session.auth;\n  return client;\n}\n\n/** The signed-in fake in one line, for the many tests that need nothing more. */\nexport function signedInAs<T>(client: T, userId: string): T {\n  return withSession(client, fakeSession(userId));\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAuBO,SAAS,YAAY,QAAoC;AAC9D,MAAI,UAAyB;AAC7B,MAAI,QAAQ;AACZ,QAAM,YAAY,oBAAI,IAA8D;AACpF,QAAM,YAAY,CAAC,OAA+C,OAAO,OAAO,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE;AACtG,SAAO;AAAA,IACL,MAAM;AAAA,MACJ,YAAY,YAAY;AACtB,iBAAS;AACT,eAAO,EAAE,MAAM,EAAE,SAAS,UAAU,OAAO,EAAE,EAAE;AAAA,MACjD;AAAA,MACA,mBAAmB,CAAC,aAAa;AAC/B,kBAAU,IAAI,QAAQ;AACtB,eAAO;AAAA,UACL,MAAM;AAAA,YACJ,cAAc;AAAA,cACZ,aAAa,MAAM;AACjB,0BAAU,OAAO,QAAQ;AAAA,cAC3B;AAAA,YACF;AAAA,UACF;AAAA,QACF;AAAA,MACF;AAAA,IACF;AAAA,IACA,SAAS,CAAC,SAAS;AACjB,gBAAU;AACV,iBAAW,YAAY,CAAC,GAAG,SAAS,GAAG;AACrC,iBAAS,SAAS,OAAO,eAAe,aAAa,UAAU,IAAI,CAAC;AAAA,MACtE;AAAA,IACF;AAAA,IACA,OAAO,MAAM;AAAA,EACf;AACF;AAGO,SAAS,YAAe,QAAW,SAAyB;AACjE,EAAC,OAAwC,OAAO,QAAQ;AACxD,SAAO;AACT;AAGO,SAAS,WAAc,QAAW,QAAmB;AAC1D,SAAO,YAAY,QAAQ,YAAY,MAAM,CAAC;AAChD;","names":[]}

package/dist/testing.d.cts

@@ -0,0 +1,38 @@
+import { AuthSessionLike } from './session-identity.cjs';
+
+/**
+ * Test helpers for packages that read the acting user from a Supabase client's session
+ * (`@ai-matrx/data/session-identity`). Tests only — never imported by shipped runtime code.
+ *
+ * A test that wants a signed-in user says so the way the real world does: by giving the fake
+ * client a session. `setUser` performs the thing that broke production — the account under the
+ * tab changing while the tab stays open.
+ */
+
+interface FakeSession {
+    readonly auth: {
+        getSession(): Promise<{
+            data: {
+                session: AuthSessionLike | null;
+            };
+        }>;
+        onAuthStateChange(callback: (event: string, session: AuthSessionLike | null) => void): {
+            data: {
+                subscription: {
+                    unsubscribe(): void;
+                };
+            };
+        };
+    };
+    /** Change who is signed in, exactly as a cookie rotation or a switch does. */
+    setUser(userId: string | null): void;
+    /** How many times the session has actually been read. */
+    readonly reads: () => number;
+}
+declare function fakeSession(userId: string | null): FakeSession;
+/** Attach a session to any fake client without disturbing its other methods. */
+declare function withSession<T>(client: T, session: FakeSession): T;
+/** The signed-in fake in one line, for the many tests that need nothing more. */
+declare function signedInAs<T>(client: T, userId: string): T;
+
+export { type FakeSession, fakeSession, signedInAs, withSession };

package/dist/testing.d.ts

@@ -0,0 +1,38 @@
+import { AuthSessionLike } from './session-identity.js';
+
+/**
+ * Test helpers for packages that read the acting user from a Supabase client's session
+ * (`@ai-matrx/data/session-identity`). Tests only — never imported by shipped runtime code.
+ *
+ * A test that wants a signed-in user says so the way the real world does: by giving the fake
+ * client a session. `setUser` performs the thing that broke production — the account under the
+ * tab changing while the tab stays open.
+ */
+
+interface FakeSession {
+    readonly auth: {
+        getSession(): Promise<{
+            data: {
+                session: AuthSessionLike | null;
+            };
+        }>;
+        onAuthStateChange(callback: (event: string, session: AuthSessionLike | null) => void): {
+            data: {
+                subscription: {
+                    unsubscribe(): void;
+                };
+            };
+        };
+    };
+    /** Change who is signed in, exactly as a cookie rotation or a switch does. */
+    setUser(userId: string | null): void;
+    /** How many times the session has actually been read. */
+    readonly reads: () => number;
+}
+declare function fakeSession(userId: string | null): FakeSession;
+/** Attach a session to any fake client without disturbing its other methods. */
+declare function withSession<T>(client: T, session: FakeSession): T;
+/** The signed-in fake in one line, for the many tests that need nothing more. */
+declare function signedInAs<T>(client: T, userId: string): T;
+
+export { type FakeSession, fakeSession, signedInAs, withSession };

package/dist/testing.js

@@ -0,0 +1,47 @@
+// src/testing.ts
+function fakeSession(userId) {
+  let current = userId;
+  let reads = 0;
+  const listeners = /* @__PURE__ */ new Set();
+  const sessionOf = (id) => id === null ? null : { user: { id } };
+  return {
+    auth: {
+      getSession: async () => {
+        reads += 1;
+        return { data: { session: sessionOf(current) } };
+      },
+      onAuthStateChange: (callback) => {
+        listeners.add(callback);
+        return {
+          data: {
+            subscription: {
+              unsubscribe: () => {
+                listeners.delete(callback);
+              }
+            }
+          }
+        };
+      }
+    },
+    setUser: (next) => {
+      current = next;
+      for (const listener of [...listeners]) {
+        listener(next === null ? "SIGNED_OUT" : "SIGNED_IN", sessionOf(next));
+      }
+    },
+    reads: () => reads
+  };
+}
+function withSession(client, session) {
+  client.auth = session.auth;
+  return client;
+}
+function signedInAs(client, userId) {
+  return withSession(client, fakeSession(userId));
+}
+export {
+  fakeSession,
+  signedInAs,
+  withSession
+};
+//# sourceMappingURL=testing.js.map

package/dist/testing.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/testing.ts"],"sourcesContent":["/**\n * Test helpers for packages that read the acting user from a Supabase client's session\n * (`@ai-matrx/data/session-identity`). Tests only — never imported by shipped runtime code.\n *\n * A test that wants a signed-in user says so the way the real world does: by giving the fake\n * client a session. `setUser` performs the thing that broke production — the account under the\n * tab changing while the tab stays open.\n */\nimport type { AuthSessionLike } from \"./session-identity\";\n\nexport interface FakeSession {\n  readonly auth: {\n    getSession(): Promise<{ data: { session: AuthSessionLike | null } }>;\n    onAuthStateChange(\n      callback: (event: string, session: AuthSessionLike | null) => void,\n    ): { data: { subscription: { unsubscribe(): void } } };\n  };\n  /** Change who is signed in, exactly as a cookie rotation or a switch does. */\n  setUser(userId: string | null): void;\n  /** How many times the session has actually been read. */\n  readonly reads: () => number;\n}\n\nexport function fakeSession(userId: string | null): FakeSession {\n  let current: string | null = userId;\n  let reads = 0;\n  const listeners = new Set<(event: string, session: AuthSessionLike | null) => void>();\n  const sessionOf = (id: string | null): AuthSessionLike | null => (id === null ? null : { user: { id } });\n  return {\n    auth: {\n      getSession: async () => {\n        reads += 1;\n        return { data: { session: sessionOf(current) } };\n      },\n      onAuthStateChange: (callback) => {\n        listeners.add(callback);\n        return {\n          data: {\n            subscription: {\n              unsubscribe: () => {\n                listeners.delete(callback);\n              },\n            },\n          },\n        };\n      },\n    },\n    setUser: (next) => {\n      current = next;\n      for (const listener of [...listeners]) {\n        listener(next === null ? \"SIGNED_OUT\" : \"SIGNED_IN\", sessionOf(next));\n      }\n    },\n    reads: () => reads,\n  };\n}\n\n/** Attach a session to any fake client without disturbing its other methods. */\nexport function withSession<T>(client: T, session: FakeSession): T {\n  (client as unknown as { auth: unknown }).auth = session.auth;\n  return client;\n}\n\n/** The signed-in fake in one line, for the many tests that need nothing more. */\nexport function signedInAs<T>(client: T, userId: string): T {\n  return withSession(client, fakeSession(userId));\n}\n"],"mappings":";AAuBO,SAAS,YAAY,QAAoC;AAC9D,MAAI,UAAyB;AAC7B,MAAI,QAAQ;AACZ,QAAM,YAAY,oBAAI,IAA8D;AACpF,QAAM,YAAY,CAAC,OAA+C,OAAO,OAAO,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE;AACtG,SAAO;AAAA,IACL,MAAM;AAAA,MACJ,YAAY,YAAY;AACtB,iBAAS;AACT,eAAO,EAAE,MAAM,EAAE,SAAS,UAAU,OAAO,EAAE,EAAE;AAAA,MACjD;AAAA,MACA,mBAAmB,CAAC,aAAa;AAC/B,kBAAU,IAAI,QAAQ;AACtB,eAAO;AAAA,UACL,MAAM;AAAA,YACJ,cAAc;AAAA,cACZ,aAAa,MAAM;AACjB,0BAAU,OAAO,QAAQ;AAAA,cAC3B;AAAA,YACF;AAAA,UACF;AAAA,QACF;AAAA,MACF;AAAA,IACF;AAAA,IACA,SAAS,CAAC,SAAS;AACjB,gBAAU;AACV,iBAAW,YAAY,CAAC,GAAG,SAAS,GAAG;AACrC,iBAAS,SAAS,OAAO,eAAe,aAAa,UAAU,IAAI,CAAC;AAAA,MACtE;AAAA,IACF;AAAA,IACA,OAAO,MAAM;AAAA,EACf;AACF;AAGO,SAAS,YAAe,QAAW,SAAyB;AACjE,EAAC,OAAwC,OAAO,QAAQ;AACxD,SAAO;AACT;AAGO,SAAS,WAAc,QAAW,QAAmB;AAC1D,SAAO,YAAY,QAAQ,YAAY,MAAM,CAAC;AAChD;","names":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-matrx/data",
-  "version": "0.18.41",
+  "version": "0.19.0",
   "description": "The opinionated AI Matrx data layer: the /db tier's hard-won Supabase primitives — optimistic concurrency, complete-list reads, JSONB merge, session-retry, the domain-wide auth cookie, realtime channel hygiene — the /net resilience trio, and the /files lane: the Matrx file-communication client (durable-ref resolution, the mx_files_session bootstrap, authenticated blob fetch, uploads, the public-link door).",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -138,6 +138,23 @@
       "optional": true
     }
   },
+  "matrx": {
+    "charter": "The one client data and transport layer between our code, Supabase and our servers.",
+    "owns": [
+      "/db Supabase primitives",
+      "/net resilience",
+      "/files byte transport",
+      "session cookie",
+      "generated DB types (target)"
+    ],
+    "mustNotOwn": [
+      "feature state",
+      "Redux",
+      "UI",
+      "server API types (agents/generated)"
+    ],
+    "layer": 2
+  },
   "scripts": {
     "build": "pnpm clean && tsup && node ../scripts/check-node-env-not-inlined.mjs",
     "clean": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\"",