@ai-matrx/records 0.87.31 → 0.92.0

package/dist/entity/react.cjs

@@ -0,0 +1,1024 @@
+"use client";
+"use strict";
+"use client";
+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/entity/react/index.tsx
+var react_exports = {};
+__export(react_exports, {
+  ENTITY_PORT_KEY: () => ENTITY_PORT_KEY,
+  EntityDataProvider: () => EntityDataProvider,
+  useEntityColumns: () => useEntityColumns,
+  useEntityList: () => useEntityList,
+  useEntityRow: () => useEntityRow,
+  useEntityScope: () => useEntityScope,
+  useEntityType: () => useEntityType,
+  useEntityWrite: () => useEntityWrite,
+  useOptionalEntityScope: () => useOptionalEntityScope
+});
+module.exports = __toCommonJS(react_exports);
+var import_react = require("react");
+var import_react_query = require("@tanstack/react-query");
+var import_seed = require("@ai-matrx/records/react");
+var import_react2 = require("@ai-matrx/records/data/react");
+
+// src/core/supabase.ts
+function refuse(code, message, hint) {
+  return { data: null, error: { code, message, hint, details: "" } };
+}
+function supabaseDataSource(client) {
+  if (isBound(client)) return client;
+  const supabase = client;
+  const hasSchema = typeof supabase.schema === "function";
+  const bound = {
+    // PAGE-BUNDLE: the real adapter opens a table page with one `custom.table_page_bundle` call.
+    opensInOneCall: true,
+    rpc(fn, args, options) {
+      if (!hasSchema) {
+        return Promise.resolve(
+          refuse(
+            "data_source_unbound",
+            `The records client was given something that is not a supabase client: it has no schema() method, so the door ${fn} cannot be called in the schema it lives in.`,
+            "Pass a supabase-js v2 client (createClient(...)) to supabaseDataSource()."
+          )
+        );
+      }
+      const name = options?.schema;
+      if (!name) {
+        return Promise.resolve(
+          refuse(
+            "schema_unsaid",
+            `The door ${fn} was called without saying which schema it lives in. Every door of this store is custom.${fn} and every trust door is iam.${fn}; an unqualified call reaches PostgREST's default profile (public) and is refused there.`,
+            "This is a bug in the caller, not in your data: /core says the schema on every call."
+          )
+        );
+      }
+      return supabase.schema(name).rpc(fn, args);
+    },
+    schema(name) {
+      return supabase.schema(name);
+    }
+  };
+  Object.defineProperty(bound, BOUND, { value: true, enumerable: false });
+  return bound;
+}
+var BOUND = /* @__PURE__ */ Symbol.for("@ai-matrx/records/supabaseDataSource");
+function isBound(source) {
+  return source[BOUND] === true;
+}
+function asRecordsDataSource(source) {
+  if (source === null || typeof source !== "object") return supabaseDataSource({});
+  if (isBound(source)) return source;
+  const candidate = source;
+  const looksLikeSupabaseJs = typeof candidate.schema === "function" && typeof candidate.from === "function" && candidate.auth !== null && typeof candidate.auth === "object";
+  if (looksLikeSupabaseJs || typeof candidate.rpc !== "function") return supabaseDataSource(source);
+  return source;
+}
+
+// src/core/pgError.ts
+var BY_SQLSTATE = {
+  PT409: "stale_write",
+  "42501": "door",
+  "23514": "refused_by_rule",
+  "22004": "invalid_argument",
+  "22023": "invalid_argument",
+  // MX005 — a value the store cannot take as asked: since 2026-10-06 (AP-3 U3) a word that names more than one
+  // choice or linked record raises it (it used to borrow PT409 and read as somebody else's write winning).
+  MX005: "invalid_argument",
+  // MXD01 — the held-change door tried the proposed values before filing an
+  // approval request and the store refused them. Nothing is waiting for a
+  // person to decide; correct the value before asking again, which is the same
+  // caller-side condition as the other invalid-argument refusals.
+  MXD01: "invalid_argument",
+  // 22P02 — a value does not fit the type the store holds for it. The class is
+  // real and was hit live: an organization whose copy of a package table grew
+  // `status` as a uuid-valued Field was sent the text "open", and the store
+  // answered `invalid input syntax for type uuid: "open"`. It is the CALL that
+  // is wrong for the shape the store holds, which is what `invalid_argument`
+  // already means — the store's own sentence names the value and the type.
+  "22P02": "invalid_argument",
+  // 42703 — a column that is not there. The store raises it from
+  // `custom.entity_table`, which is asked for a column by NAME, so the class is
+  // exactly "the call named something the shape does not have": the same thing
+  // `invalid_argument` already means, and the store's own sentence names the
+  // column. Added 2026-09-20 (lane FORMS) because the package's live-door suite
+  // caught it raised by a door this package did not know about — which is the
+  // suite working, and is why the map is a census rather than a guess.
+  "42703": "invalid_argument",
+  // 22007 — a date or a time the store could not read as one. It is raised by
+  // `custom.dashboard_window_sql`, which is handed a window a caller wrote
+  // ("last 30 days", a literal date), so the class is again "the call named
+  // something the shape does not accept" and the store's own sentence names the
+  // text it could not read. Added 2026-09-20 (lane SCREEN-BREAK) after the
+  // live-door census caught it — the same way 42703 arrived, which is the
+  // census working rather than a guess.
+  "22007": "invalid_argument",
+  // 22003 — a number the store could not hold at the size it was handed. It is
+  // raised by `custom.context_resolve`, which is given a window or a depth a
+  // caller wrote, so the class is the same one 22P02, 42703 and 22007 already
+  // are: the CALL named a value the shape does not accept, and the store's own
+  // sentence names the number and the range. Added 2026-09-20 (lane GRID-TWO)
+  // when the live-door census caught the release gate red on it — which is the
+  // census working, and the fourth time it has been the thing that found a new
+  // refusal class rather than a person guessing one.
+  "22003": "invalid_argument",
+  // 42883 — `custom._template_call` (the template family, 2026-10-03) was handed a step that
+  // names a door the store does not have, or an argument that door does not take. The TEMPLATE
+  // named something the shape does not have — the same class 42703 is — and the store's own
+  // sentence names the door or the argument. Caught by the live-door census on records 0.68.1's
+  // tag, the eighth time the census found a class before a person did. (A bare 42883 on a door
+  // this package itself asks for is still `door_absent`, mapped before this funnel in
+  // `owedDoor`.)
+  "42883": "invalid_argument",
+  "02000": "not_found",
+  // P0002 — `custom.inbox_snooze` / `custom.inbox_clear` (lane S5-PRIME-2, 2026-09-24): "There is
+  // nothing in your inbox with that id". An invented id, another person's item and another
+  // organization's all answer it alike, so it reads exactly as 02000 does: not found.
+  "P0002": "not_found",
+  "23503": "missing_reference",
+  "23505": "already_exists",
+  "0A000": "not_supported",
+  "53400": "store_limit",
+  "22012": "store_limit",
+  // 54001 — `custom.record_delete` stops a cascade that nests past sixty-four
+  // levels of containment, because that is a loop somebody built rather than a
+  // hierarchy, and saying so beats recursing until the server runs out of
+  // stack. It is a LIMIT of the store, and the store's own sentence names what
+  // to do about it, so it reads as one.
+  "54001": "store_limit",
+  // 54000 — the grid primitives' organization ceilings (GRID-PRIMITIVES, 2026-09-23):
+  // `custom.action_run` on a selection past its knob, `custom.table_decorate` past the
+  // rule count, `custom.table_from_example` past `custom/example_rows_max`,
+  // `custom.table_webhook_declare` past `custom/table_webhooks_max`, and
+  // `custom.hub_changed_by`. Each names its knob in the hint and writes nothing, so it
+  // reads exactly like 54001: a limit of the store, in the store's own sentence.
+  "54000": "store_limit",
+  // VIS: `custom.has_visibility_at` refuses to answer from a snapshot older
+  // than a write this reader has already seen, rather than returning something
+  // they just lost access to. It is retryable on a fresher connection, which is
+  // a different instruction from every other refusal here.
+  // 55000 — `custom.table_move` (SC-1', 2026-09-24) refuses a move the table's present state
+  // does not allow: a destination that cannot take it, a table something else holds, contents
+  // that point at themselves in a circle. The store's own sentence names the reason and nothing
+  // moves, so it reads as a refusal on the merits. Caught by the live-door census on records
+  // 0.58.3's tag, the seventh time the census found a class before a person did.
+  "55000": "refused_by_rule",
+  // 42P17 — a worked-out column that would read itself round a circle (STORE-TAILS-3,
+  // 2026-09-25): `custom._field_reads_what_it_reads` refuses the declaration or edit that would
+  // close the circle, naming every column in it, and `custom.far_value` refuses a circle stored
+  // before that rule when a lookup or rollup is worked out. Refused on its merits, in the store's
+  // own sentence, nothing written — so it reads as 55000 does.
+  "42P17": "refused_by_rule",
+  // P0001 — `custom.context_scope_write` (2026-10-03) refuses a scope whose parent breaks the
+  // parent rule in the old trigger's own class and words (manager ruling H6). Refused on its
+  // merits, nothing written. Caught by the live-door census on records 0.65.0's tag.
+  P0001: "refused_by_rule",
+  "40001": "stale_read",
+  // 57014 — the store cancelled the statement at its own timeout. Like
+  // `stale_read` and unlike every other refusal here, the call was never
+  // refused on its merits: the same call on a smaller page, or once the
+  // organization's kernel is not being rewritten, can succeed. It gets its own
+  // code so a screen can offer "try again" honestly instead of showing a
+  // failure sentence the caller cannot act on.
+  "57014": "timed_out",
+  // PostgREST's own two: the store is not being SERVED, which is a different
+  // thing from the store refusing. `custom` absent from `pgrst.db_schemas`, or
+  // the grants not copied, land here.
+  PGRST202: "store_not_served",
+  PGRST205: "store_not_served",
+  PGRST301: "door",
+  // PT428 — NOT A FAILURE, and the release gate's live census is what found it
+  // missing: the store raises it and this package answered `internal`, which is
+  // the one classification that tells a screen nothing. A stage gate whose
+  // `on_fail` is `require_approval` files the request and leaves the record
+  // where it was; the transaction is rolled back to the pipeline's own block, so
+  // "nothing was written" is a fact rather than a promise. Landed by lane
+  // STAGE-RULES; mapped here by STAGE-RULES-2 the day after, when the census
+  // caught it — the sixth time that census has been the thing that found a
+  // refusal class rather than a person guessing one.
+  PT428: "needs_approval"
+};
+var MAPPED_SQLSTATES = Object.keys(BY_SQLSTATE);
+function parseDetail(details) {
+  if (!details) return void 0;
+  const trimmed = details.trim();
+  if (!trimmed.startsWith("{") && !trimmed.startsWith("[")) return details;
+  try {
+    return JSON.parse(trimmed);
+  } catch {
+    return details;
+  }
+}
+function isNotASqlstate(code) {
+  if (!code) return true;
+  return /^[0-9]{3}$/.test(code);
+}
+function mapPgError(error, where) {
+  const raw = error.code ?? void 0;
+  const sqlstate = raw && raw !== "" ? raw : void 0;
+  const mapped = {
+    code: "internal",
+    message: error.message,
+    ...error.hint ? { hint: error.hint } : {},
+    ...sqlstate ? { sqlstate } : {}
+  };
+  if (isNotASqlstate(sqlstate)) {
+    mapped.code = "unreachable";
+  } else {
+    mapped.code = BY_SQLSTATE[sqlstate] ?? "internal";
+  }
+  const detail = parseDetail(error.details);
+  if (detail !== void 0) mapped.detail = detail;
+  if (mapped.code === "internal") {
+    mapped.unmapped = true;
+    mapped.diagnostic = `@ai-matrx/records did not recognise SQLSTATE ${sqlstate ?? "(none)"} from ${where}; the store's own message is the thing to act on.`;
+  } else if (mapped.code === "unreachable") {
+    mapped.unmapped = true;
+    mapped.diagnostic = `@ai-matrx/records never reached the store from ${where}: ${raw ? `the transport answered ${raw}` : "no response"} \u2014 ${error.message}`;
+    mapped.message = "We could not reach your data.";
+    delete mapped.hint;
+  }
+  return mapped;
+}
+
+// src/entity/core/errors.ts
+var ENTITY_REFUSALS = {
+  /** conflict_version: somebody else's write won. */
+  MX001: "stale_write",
+  /** organization_required: the call needs an organization and carried none. */
+  MX002: "organization_required",
+  /** forbidden. */
+  MX003: "door",
+  /** not_found (also: not visible to this person). */
+  MX004: "not_found",
+  /** validation_refused (detail.reason required / bad_value / ambiguous_word / constraint; `not_supported` is read apart below). */
+  MX005: "invalid_argument",
+  /** system_column: a write named a column the store owns. */
+  MX008: "invalid_argument",
+  /** unknown_identifier: a column that is not there or not usable here. */
+  MX012: "invalid_argument",
+  /** cursor_invalid: the page cursor belongs to another list; the engine restarts the page. */
+  MX013: "invalid_argument",
+  /** view_not_offered. */
+  MX015: "invalid_argument",
+  /** invalid_argument: a parameter the door refuses by name. */
+  MX016: "invalid_argument"
+};
+function mapEntityError(error, where) {
+  const mapped = mapPgError(error, where);
+  const state = mapped.sqlstate;
+  if (state && /^MX\d{3}$/.test(state)) {
+    const code = ENTITY_REFUSALS[state];
+    if (code) {
+      const reason = mapped.detail?.reason;
+      const known = { ...mapped, code: state === "MX005" && reason === "not_supported" ? "not_supported" : code };
+      delete known.unmapped;
+      delete known.diagnostic;
+      return known;
+    }
+  }
+  return mapped;
+}
+function refusal(code, message, hint) {
+  return { ok: false, error: { code, message, ...hint ? { hint } : {} } };
+}
+
+// src/entity/core/client.ts
+var OP_ID_HEADER = "x-matrx-op-id";
+var ENTITY_DOOR_SCHEMA = "platform";
+function createEntityClient(options) {
+  const source = asRecordsDataSource(options.dataSource ?? options.supabase);
+  let warnedHeaderless = false;
+  function withHeaders(pending, headers) {
+    if (!headers) return;
+    const builder = pending;
+    if (typeof builder.setHeader === "function") {
+      for (const [name, value] of Object.entries(headers)) builder.setHeader(name, value);
+      return;
+    }
+    if (!warnedHeaderless) {
+      warnedHeaderless = true;
+      console.warn(
+        `[@ai-matrx/records/entity] This data source cannot carry a per-call header (${Object.keys(headers).join(", ")}), so this browser re-reads the notice of its own writes once.`
+      );
+    }
+  }
+  async function call(fn, args, schema = ENTITY_DOOR_SCHEMA, headers) {
+    try {
+      const pending = source.rpc(fn, args, { schema });
+      withHeaders(pending, headers);
+      const answer = await pending;
+      if (answer.error) return { ok: false, error: mapEntityError(answer.error, `${schema}.${fn}`) };
+      return { ok: true, data: answer.data };
+    } catch (thrown) {
+      return {
+        ok: false,
+        error: mapEntityError({ code: "", message: thrown instanceof Error ? thrown.message : String(thrown) }, `${schema}.${fn}`)
+      };
+    }
+  }
+  return {
+    list(request) {
+      const args = {
+        p_entity_type: request.token,
+        p_scope: request.scope ?? null,
+        p_filter: request.filter ?? {},
+        p_search: request.search ?? null,
+        p_sort: request.sort ?? null,
+        p_archived: request.archived ?? "active",
+        p_page_size: request.pageSize ?? null,
+        p_after: request.after ?? null,
+        p_with_total: request.withTotal ?? true
+      };
+      return call("entity_list_scoped", args);
+    },
+    get(request) {
+      return call("entity_get", { p_entity_type: request.token, p_ids: [...request.ids] });
+    },
+    columns(request) {
+      return call("entity_columns", { p_organization_id: request.organizationId ?? null, p_token: request.token });
+    },
+    insert(request) {
+      return call(
+        "entity_insert",
+        { p_entity_type: request.token, p_organization_id: request.organizationId, p_rows: request.rows.map((r) => ({ ...r })) },
+        ENTITY_DOOR_SCHEMA,
+        opHeader(request.opId)
+      );
+    },
+    update(request) {
+      return call(
+        "entity_update",
+        { p_entity_type: request.token, p_id: request.id, p_base_version: request.baseVersion, p_patch: request.patch },
+        ENTITY_DOOR_SCHEMA,
+        opHeader(request.opId)
+      );
+    },
+    archive(request) {
+      return call("entity_archive", { p_entity_type: request.token, p_ids: [...request.ids] }, ENTITY_DOOR_SCHEMA, opHeader(request.opId));
+    },
+    unarchive(request) {
+      return call("entity_unarchive", { p_entity_type: request.token, p_ids: [...request.ids] }, ENTITY_DOOR_SCHEMA, opHeader(request.opId));
+    },
+    knob(request) {
+      return call("knob_resolve", { p_feature: "entity_data", p_key: request.key, p_organization_id: request.organizationId ?? null });
+    },
+    async memberOrganizations() {
+      const answer = await call("my_orgs", {}, "iam");
+      if (!answer.ok) return answer;
+      const rows = Array.isArray(answer.data) ? answer.data : [];
+      const ids = rows.map((row) => typeof row === "string" ? row : row && typeof row === "object" ? Object.values(row)[0] : null).filter((id) => typeof id === "string");
+      return { ok: true, data: ids };
+    }
+  };
+}
+function opHeader(opId) {
+  return opId ? { [OP_ID_HEADER]: opId } : void 0;
+}
+
+// src/entity/core/realtime.ts
+var import_realtime = require("@ai-matrx/realtime");
+
+// src/ops.ts
+var import_global_slot = require("@ai-matrx/kit/global-slot");
+var REMEMBER_MS = 3e4;
+var REMEMBER_MAX = 500;
+var ours = (0, import_global_slot.globalSlot)("ai-matrx.records.op-ledger", () => /* @__PURE__ */ new Map());
+function trim(now) {
+  for (const [id, at] of ours) {
+    if (now - at <= REMEMBER_MS) break;
+    ours.delete(id);
+  }
+  while (ours.size > REMEMBER_MAX) {
+    const oldest = ours.keys().next();
+    if (oldest.done === true) break;
+    ours.delete(oldest.value);
+  }
+}
+function mintOpId() {
+  const id = crypto.randomUUID();
+  const now = Date.now();
+  ours.set(id, now);
+  trim(now);
+  return id;
+}
+function isOwnOp(opId) {
+  if (!opId) return false;
+  const at = ours.get(opId);
+  if (at === void 0) return false;
+  if (Date.now() - at > REMEMBER_MS) {
+    ours.delete(opId);
+    return false;
+  }
+  return true;
+}
+
+// src/entity/core/realtime.ts
+var entityOrgChannel = (0, import_realtime.defineChannelNamespace)({
+  namespace: "entity-org",
+  foreignTopic: "mx:entity-org",
+  parts: ["organizationId", "token"],
+  description: "One organization's changes to one platform type (contacts, deals, projects, tasks, employees). Carries NOTICES written by platform.entity_org_notice_stmt \u2014 which ids moved, never a value. Admitted by the one RLS policy on realtime.messages to members of that organization."
+});
+var ENTITY_NOTICE_EVENT = "entity_bump";
+var DEFAULT_BATCH_MS = 150;
+var DEFAULT_MAX_WAIT_MS = 1e3;
+var DEFAULT_MAX_ORG_TOPICS = 20;
+function entityNoticeKey(notice) {
+  return notice.id ?? (notice.at ? `${notice.organization_id ?? ""}:${notice.entity_type ?? ""}:${notice.at}` : void 0);
+}
+function entityOrgTopic(organizationId, token) {
+  return entityOrgChannel.topic({ organizationId, token });
+}
+function entityOrgChannelSpec(organizationId, token, onNotice, onBackfill) {
+  return {
+    topic: entityOrgTopic(organizationId, token),
+    // Database Broadcast is authorized by RLS on realtime.messages; the manager awaits setAuth() first.
+    private: true,
+    // The sender is Postgres: no Matrx envelope. Our own write is known by the op id it carried.
+    wire: { mode: "raw", isOwnMessage: (payload) => isOwnOp(payload?.op_id) },
+    eventKey: (_source, payload) => entityNoticeKey(payload ?? {}),
+    broadcast: [
+      {
+        event: ENTITY_NOTICE_EVENT,
+        onMessage: (message) => {
+          const notice = message.data ?? {};
+          if (isOwnOp(notice.op_id)) return;
+          onNotice(notice);
+        }
+      }
+    ],
+    // Realtime has no replay: a channel back from a gap re-reads.
+    onBackfill: () => onBackfill()
+  };
+}
+function orderOrganizationTopics(input) {
+  const members = input.members ? new Set(input.members) : null;
+  const out = [];
+  const push = (org) => {
+    if (!org || out.includes(org)) return;
+    if (members && !members.has(org)) return;
+    out.push(org);
+  };
+  push(input.active);
+  push(input.filter);
+  const held = [...(input.held ?? /* @__PURE__ */ new Map()).entries()].sort((a, b) => b[1] - a[1] || (a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0));
+  for (const [org] of held) push(org);
+  for (const org of [...input.members ?? []].sort()) push(org);
+  return out.slice(0, Math.max(0, input.max));
+}
+function createEntityRealtime(options = {}) {
+  const batchMs = options.batchMs ?? DEFAULT_BATCH_MS;
+  const maxWaitMs = options.maxWaitMs ?? DEFAULT_MAX_WAIT_MS;
+  const channels = /* @__PURE__ */ new Map();
+  const open = (organizationId, token) => {
+    const channel = { listeners: /* @__PURE__ */ new Set(), stop: null };
+    const spec = entityOrgChannelSpec(
+      organizationId,
+      token,
+      (notice) => {
+        for (const listener of channel.listeners) listener.notice(notice);
+      },
+      () => {
+        for (const listener of channel.listeners) listener.backfill();
+      }
+    );
+    if (options.manager) {
+      const handle = options.manager.open(spec);
+      channel.stop = () => handle.close();
+    } else {
+      channel.stop = (0, import_realtime.subscribeToRealtimeManager)(() => spec);
+    }
+    return channel;
+  };
+  return {
+    subscribe({ token, organizationIds }, sink) {
+      let timer = null;
+      let firstAt = 0;
+      let pending = /* @__PURE__ */ new Set();
+      let wholeList = false;
+      const flush = () => {
+        if (timer !== null) clearTimeout(timer);
+        timer = null;
+        const ids = [...pending];
+        const all = wholeList;
+        pending = /* @__PURE__ */ new Set();
+        wholeList = false;
+        if (all) sink.rows(null);
+        else if (ids.length > 0) sink.rows(ids);
+      };
+      const nudge = () => {
+        const now = Date.now();
+        if (timer === null) firstAt = now;
+        else clearTimeout(timer);
+        const wait = Math.max(0, Math.min(batchMs, firstAt + maxWaitMs - now));
+        timer = setTimeout(flush, wait);
+      };
+      const listener = {
+        notice(notice) {
+          if (notice.entity_type && notice.entity_type !== token) return;
+          if (notice.ids == null) wholeList = true;
+          else for (const id of notice.ids) pending.add(id);
+          nudge();
+        },
+        backfill() {
+          wholeList = true;
+          flush();
+        }
+      };
+      const keys = [...new Set(organizationIds)].map((org) => {
+        const key = entityOrgTopic(org, token);
+        const channel = channels.get(key) ?? open(org, token);
+        channels.set(key, channel);
+        channel.listeners.add(listener);
+        return key;
+      });
+      return () => {
+        if (timer !== null) clearTimeout(timer);
+        for (const key of keys) {
+          const channel = channels.get(key);
+          if (!channel) continue;
+          channel.listeners.delete(listener);
+          if (channel.listeners.size > 0) continue;
+          channel.stop?.();
+          channels.delete(key);
+        }
+      };
+    }
+  };
+}
+
+// src/entity/port/port.ts
+var import_uuid = require("@ai-matrx/kit/uuid");
+
+// src/entity/core/wire.ts
+var IDENTITY = {
+  _id: "id",
+  _version: "version",
+  _organization_id: "organization_id"
+};
+var CUSTOM_PREFIX = "_custom.";
+function wireColumn(column, customKeys) {
+  const identity = IDENTITY[column];
+  if (identity) return identity;
+  if (column.startsWith(CUSTOM_PREFIX)) return column;
+  return customKeys.has(column) ? `${CUSTOM_PREFIX}${column}` : column;
+}
+function predicate(clause, customKeys) {
+  const column = wireColumn(clause.column, customKeys);
+  const v = clause.value;
+  switch (clause.op) {
+    case "eq":
+      return v === null || v === void 0 ? { column, op: "empty" } : { column, op: "eq", value: v };
+    case "neq":
+      return v === null || v === void 0 ? { column, op: "empty", negated: true } : { column, op: "neq", value: v };
+    case "lt":
+    case "lte":
+    case "gt":
+    case "gte":
+      return { column, op: clause.op, value: v };
+    case "in":
+      return { column, op: "in", values: Array.isArray(v) ? v : [] };
+    case "empty":
+      return v === false ? { column, op: "empty", negated: true } : { column, op: "empty" };
+    case "contains":
+      return { column, op: "contains", value: v };
+    default:
+      return { column, op: String(clause.op), value: v };
+  }
+}
+function toWire(query, customKeys = /* @__PURE__ */ new Set()) {
+  const q = query ?? {};
+  const out = {};
+  const scope = {};
+  if (q.lane) scope.kind = q.lane;
+  if (q.org && q.org !== "all") scope.organization_id = q.org;
+  if (scope.kind || scope.organization_id) out.scope = scope;
+  if (q.where && q.where.length > 0) out.filter = { all: q.where.map((c) => predicate(c, customKeys)) };
+  const search = q.search?.trim();
+  if (search) out.search = search;
+  if (q.sort && q.sort.length > 0) {
+    out.sort = q.sort.map((s) => ({
+      column: wireColumn(s.column, customKeys),
+      dir: s.direction === "desc" ? "desc" : "asc",
+      nulls: "last"
+    }));
+  }
+  if (typeof q.pageSize === "number" && Number.isFinite(q.pageSize)) out.pageSize = Math.max(1, Math.floor(q.pageSize));
+  return out;
+}
+
+// src/entity/port/rows.ts
+var IDENTITY_COLUMNS = /* @__PURE__ */ new Set(["id", "version", "organization_id"]);
+var PRESENTATION_KEYS = /* @__PURE__ */ new Set(["_state", "_k"]);
+function isRefList(value) {
+  return Array.isArray(value) && value.length > 0 && value.every((item) => item !== null && typeof item === "object" && typeof item.token === "string" && typeof item.id === "string");
+}
+function toRefs(value) {
+  if (!isRefList(value)) return [];
+  return value.map((item) => ({ token: item.token, id: item.id, label: typeof item.label === "string" ? item.label : null }));
+}
+function toRow(wire) {
+  const row = {
+    _id: wire.id,
+    _version: wire.version,
+    _organization_id: wire.organization_id,
+    _custom: wire._custom && typeof wire._custom === "object" ? { ...wire._custom } : {}
+  };
+  for (const [key, value] of Object.entries(wire)) {
+    if (IDENTITY_COLUMNS.has(key) || PRESENTATION_KEYS.has(key) || key === "_custom") continue;
+    row[key] = isRefList(value) ? toRefs(value) : value === void 0 ? null : value;
+  }
+  return row;
+}
+function toColumn(wire) {
+  const column = {
+    key: wire.key,
+    label: wire.label || wire.key,
+    type: wire.type,
+    origin: wire.origin === "custom" ? "custom" : "platform",
+    required: Boolean(wire.required),
+    readOnly: Boolean(wire.readOnly)
+  };
+  if (wire.choices && wire.choices.length > 0) column.choices = [...wire.choices];
+  if (wire.linksTo && wire.linksTo.length > 0) column.linksTo = [...wire.linksTo];
+  return column;
+}
+function toColumns(wire) {
+  return wire.filter((c) => !IDENTITY_COLUMNS.has(c.key)).map(toColumn);
+}
+
+// src/entity/port/port.ts
+function toWireValue(value) {
+  if (isRef(value)) return value.id;
+  if (Array.isArray(value) && value.length > 0 && value.every(isRef)) {
+    return value.length === 1 ? value[0].id : value.map((ref) => ref.id);
+  }
+  return value;
+}
+function isRef(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value) && typeof value.token === "string" && typeof value.id === "string";
+}
+function toWireValues(values) {
+  const out = {};
+  for (const [key, value] of Object.entries(values)) {
+    if (value === void 0) continue;
+    if (key === "_custom" && value && typeof value === "object" && !Array.isArray(value)) {
+      out._custom = Object.fromEntries(Object.entries(value).filter(([, v]) => v !== void 0).map(([k, v]) => [k, toWireValue(v)]));
+      continue;
+    }
+    out[key] = Array.isArray(value) && value.length === 0 && key !== "_custom" ? null : toWireValue(value);
+  }
+  return out;
+}
+function createEntityDataPort(options) {
+  const client = options.client ?? createEntityClient({ dataSource: options.dataSource });
+  const activeOrganization = () => (options.activeOrganizationId ? options.activeOrganizationId() : options.organization) ?? null;
+  const gets = /* @__PURE__ */ new Map();
+  const aliases = options.aliases;
+  const shapes = /* @__PURE__ */ new Map();
+  let warnedNotLive = false;
+  const held = /* @__PURE__ */ new Map();
+  const replans = /* @__PURE__ */ new Map();
+  let memberships = null;
+  let maxOrgTopics = null;
+  function hold(alias, rows) {
+    const byId = held.get(alias) ?? /* @__PURE__ */ new Map();
+    held.set(alias, byId);
+    const before = new Set(byId.values());
+    for (const r of rows) {
+      if (typeof r.id === "string" && typeof r.organization_id === "string") byId.set(r.id, r.organization_id);
+    }
+    if ([...byId.values()].some((org) => !before.has(org))) for (const replan of replans.get(alias) ?? []) replan();
+  }
+  function heldCounts(alias) {
+    const counts = /* @__PURE__ */ new Map();
+    for (const org of held.get(alias)?.values() ?? []) counts.set(org, (counts.get(org) ?? 0) + 1);
+    return counts;
+  }
+  function membershipsOnce() {
+    memberships ??= client.memberOrganizations().then((answer) => {
+      if (answer.ok) return answer.data;
+      memberships = null;
+      console.warn(`[@ai-matrx/records/entity] Could not read your organizations for live updates: ${answer.error.message}`);
+      return null;
+    });
+    return memberships;
+  }
+  function maxOrgTopicsOnce() {
+    maxOrgTopics ??= client.knob({ key: "realtime_max_org_topics", organizationId: activeOrganization() }).then((answer) => {
+      const value = answer.ok ? Number(answer.data) : Number.NaN;
+      if (Number.isFinite(value) && value >= 0) return value;
+      console.warn(`[@ai-matrx/records/entity] knob entity_data.realtime_max_org_topics did not resolve; joining at most ${DEFAULT_MAX_ORG_TOPICS} organizations.`);
+      return DEFAULT_MAX_ORG_TOPICS;
+    });
+    return maxOrgTopics;
+  }
+  const tokenBindings = /* @__PURE__ */ new Map();
+  function bindingOf(alias) {
+    if (Object.prototype.hasOwnProperty.call(aliases, alias)) return aliases[alias];
+    if (!options.tokensAreAliases || !/^[a-z][a-z0-9_]*$/.test(alias)) return null;
+    let bound = tokenBindings.get(alias);
+    if (!bound) {
+      bound = { kind: "entity", token: alias };
+      tokenBindings.set(alias, bound);
+    }
+    return bound;
+  }
+  function noSuchAlias(alias) {
+    return refusal("not_found", `This Applet has no data source called "${alias}".`, "Use one of the aliases sources() lists.");
+  }
+  function shapeOf(alias, binding) {
+    let held2 = shapes.get(alias);
+    if (!held2) {
+      held2 = client.columns({ token: binding.token, organizationId: binding.organizationId ?? null }).then((answer) => {
+        if (!answer.ok) shapes.delete(alias);
+        return answer;
+      });
+      shapes.set(alias, held2);
+    }
+    return held2;
+  }
+  function getCoalesced(alias, token, id) {
+    return new Promise((resolve) => {
+      let batch = gets.get(alias);
+      if (!batch) {
+        batch = /* @__PURE__ */ new Map();
+        gets.set(alias, batch);
+        const asked = batch;
+        queueMicrotask(() => {
+          gets.delete(alias);
+          void flushGets(alias, token, asked);
+        });
+      }
+      const waiting = batch.get(id) ?? [];
+      waiting.push(resolve);
+      batch.set(id, waiting);
+    });
+  }
+  async function flushGets(alias, token, asked) {
+    const answer = await client.get({ token, ids: [...asked.keys()] });
+    if (answer.ok) hold(alias, answer.data.rows);
+    const byId = new Map(answer.ok ? answer.data.rows.map((r) => [r.id, r]) : []);
+    for (const [id, waiting] of asked) {
+      const found = byId.get(id);
+      const wire = found && found["_state"]?.archived === true ? void 0 : found;
+      const result = answer.ok ? { ok: true, data: wire ? toRow(wire) : null } : answer;
+      for (const resolve of waiting) resolve(result);
+    }
+  }
+  function readBack(alias, answer, what) {
+    if (!answer.ok) return answer;
+    hold(alias, answer.data.rows);
+    const wire = answer.data.rows[0];
+    if (!wire) {
+      return refusal(
+        "not_found",
+        `${what} was saved, but you cannot open it now, so it is not shown here.`,
+        "The row is in the store; who may open it decides whether it appears in this list."
+      );
+    }
+    return { ok: true, data: toRow(wire) };
+  }
+  function done(answer) {
+    return answer.ok ? { ok: true, data: void 0 } : answer;
+  }
+  return {
+    async sources() {
+      const out = [];
+      for (const [alias, binding] of Object.entries(aliases)) {
+        const shape = await shapeOf(alias, binding);
+        if (!shape.ok) return shape;
+        out.push({
+          alias,
+          label: binding.label ?? shape.data.label ?? alias,
+          kind: "entity",
+          canCreate: Boolean(shape.data.can_create),
+          canUpdate: Boolean(shape.data.can_update)
+        });
+      }
+      return { ok: true, data: out };
+    },
+    async describe(alias) {
+      const binding = bindingOf(alias);
+      if (!binding) return noSuchAlias(alias);
+      const shape = await shapeOf(alias, binding);
+      if (!shape.ok) return shape;
+      return {
+        ok: true,
+        data: {
+          token: binding.token,
+          label: binding.label ?? shape.data.label ?? binding.token,
+          canCreate: Boolean(shape.data.can_create),
+          canUpdate: Boolean(shape.data.can_update)
+        }
+      };
+    },
+    async columns(alias) {
+      const binding = bindingOf(alias);
+      if (!binding) return noSuchAlias(alias);
+      const shape = await shapeOf(alias, binding);
+      return shape.ok ? { ok: true, data: toColumns(shape.data.columns) } : shape;
+    },
+    async list(alias, q = {}, cursor) {
+      const binding = bindingOf(alias);
+      if (!binding) return noSuchAlias(alias);
+      let customKeys = /* @__PURE__ */ new Set();
+      if (q.where && q.where.length > 0 || q.sort && q.sort.length > 0) {
+        const shape = await shapeOf(alias, binding);
+        if (!shape.ok) return shape;
+        customKeys = new Set(shape.data.columns.filter((c) => c.origin === "custom").map((c) => c.key));
+      }
+      const wire = toWire(q, customKeys);
+      if (binding.organizationId) wire.scope = { ...wire.scope, organization_id: binding.organizationId };
+      const answer = await client.list({ token: binding.token, ...wire, after: cursor ?? null });
+      if (!answer.ok) return answer;
+      const { data } = answer;
+      if (data.sort_ignored.length > 0) {
+        console.warn(`[@ai-matrx/records/entity] "${alias}" sorts by one column for now; ignored: ${data.sort_ignored.join(", ")}.`);
+      }
+      hold(alias, data.rows);
+      const page = {
+        rows: data.rows.map(toRow),
+        // A count that stopped at the store's cap is a floor, not a count: unknown beats a wrong number.
+        total: data.total === null || data.total === void 0 || data.total_is_capped ? null : data.total,
+        cursor: data.has_more ? data.next_after : null
+      };
+      return { ok: true, data: page };
+    },
+    async get(alias, id) {
+      const binding = bindingOf(alias);
+      if (!binding) return noSuchAlias(alias);
+      if (!(0, import_uuid.isUuidShape)(id)) return refusal("invalid_argument", `"${String(id)}" is not a row id.`);
+      return getCoalesced(alias, binding.token, id);
+    },
+    async create(alias, values) {
+      const binding = bindingOf(alias);
+      if (!binding) return noSuchAlias(alias);
+      const organizationId = binding.organizationId ?? activeOrganization();
+      if (!organizationId) {
+        return refusal(
+          "organization_required",
+          "Choose the organization this new record belongs to.",
+          "Pick an organization, then add the row again. Nothing was saved."
+        );
+      }
+      const answer = await client.insert({ token: binding.token, organizationId, rows: [toWireValues(values)], opId: mintOpId() });
+      return readBack(alias, answer, "The new row");
+    },
+    async update(alias, id, patch, baseVersion) {
+      const binding = bindingOf(alias);
+      if (!binding) return noSuchAlias(alias);
+      if (!(0, import_uuid.isUuidShape)(id)) return refusal("invalid_argument", `"${String(id)}" is not a row id.`);
+      const answer = await client.update({ token: binding.token, id, baseVersion, patch: toWireValues(patch), opId: mintOpId() });
+      return readBack(alias, answer, "The change");
+    },
+    async archive(alias, id) {
+      const binding = bindingOf(alias);
+      if (!binding) return noSuchAlias(alias);
+      if (!(0, import_uuid.isUuidShape)(id)) return refusal("invalid_argument", `"${String(id)}" is not a row id.`);
+      return done(await client.archive({ token: binding.token, ids: [id], opId: mintOpId() }));
+    },
+    async restore(alias, id) {
+      const binding = bindingOf(alias);
+      if (!binding) return noSuchAlias(alias);
+      if (!(0, import_uuid.isUuidShape)(id)) return refusal("invalid_argument", `"${String(id)}" is not a row id.`);
+      return done(await client.unarchive({ token: binding.token, ids: [id], opId: mintOpId() }));
+    },
+    subscribe(event, listener) {
+      const alias = event.startsWith("rows:") ? event.slice(5) : null;
+      const binding = alias ? bindingOf(alias) : null;
+      if (!alias || !binding) {
+        throw new Error(`DataPort.subscribe: "${event}" is not an event this Applet's port carries. Use rows:<alias>.`);
+      }
+      const realtime = options.realtime;
+      if (!realtime) {
+        if (!warnedNotLive) {
+          warnedNotLive = true;
+          console.warn("[@ai-matrx/records/entity] This host bound no realtime layer, so other people's changes appear on the next read.");
+        }
+        return () => {
+        };
+      }
+      let stopped = false;
+      let joined = [];
+      let stopLive = null;
+      const sink = { rows: (ids) => listener({ ids: ids === null ? null : [...ids] }) };
+      const plan = async () => {
+        const organizationIds = binding.organizationId ? [binding.organizationId] : orderOrganizationTopics({
+          active: activeOrganization(),
+          held: heldCounts(alias),
+          members: await membershipsOnce(),
+          max: await maxOrgTopicsOnce()
+        });
+        if (stopped) return;
+        if (organizationIds.length === joined.length && organizationIds.every((org, i) => org === joined[i])) return;
+        const previous = stopLive;
+        joined = organizationIds;
+        stopLive = realtime.subscribe({ token: binding.token, organizationIds }, sink);
+        previous?.();
+      };
+      const replan = () => void plan();
+      const set = replans.get(alias) ?? /* @__PURE__ */ new Set();
+      replans.set(alias, set);
+      set.add(replan);
+      replan();
+      return () => {
+        stopped = true;
+        set.delete(replan);
+        stopLive?.();
+        stopLive = null;
+      };
+    }
+  };
+}
+function createSeedPort(dataSource) {
+  return createEntityDataPort({ client: createEntityClient({ dataSource }), aliases: {}, tokensAreAliases: true, activeOrganizationId: () => null });
+}
+
+// src/entity/react/index.tsx
+var ENTITY_PORT_KEY = "entity-data";
+var EntityScopeContext = (0, import_react.createContext)(null);
+function EntityDataProvider({ dataSource, client, activeOrganizationId, realtime, portKey = ENTITY_PORT_KEY, children }) {
+  const active = (0, import_react.useRef)(activeOrganizationId);
+  active.current = activeOrganizationId;
+  const scope = (0, import_react.useMemo)(() => {
+    const bound = client ?? createEntityClient({ dataSource });
+    const live = realtime === false ? void 0 : realtime ?? createEntityRealtime();
+    const port = createEntityDataPort({
+      client: bound,
+      aliases: {},
+      tokensAreAliases: true,
+      activeOrganizationId: () => active.current,
+      ...live ? { realtime: live } : {}
+    });
+    return { port, portKey, events: (0, import_react2.hostEvents)(port) };
+  }, [client, dataSource, realtime, portKey]);
+  const above = (0, import_react.useContext)(import_react_query.QueryClientContext);
+  const [serverClient] = (0, import_react.useState)(() => typeof window === "undefined" && !above ? new import_react_query.QueryClient() : null);
+  const inner = (0, import_react.createElement)(EntityScopeContext.Provider, { value: scope }, children);
+  return serverClient ? (0, import_react.createElement)(import_react_query.QueryClientProvider, { client: serverClient }, inner) : inner;
+}
+function useOptionalEntityScope() {
+  return (0, import_react.useContext)(EntityScopeContext);
+}
+function useEntityScope() {
+  const scope = (0, import_react.useContext)(EntityScopeContext);
+  if (!scope) {
+    throw new Error(
+      "An entity hook was called outside <EntityDataProvider>. Mount it once, high, with the supabase client that carries this person's session and the active organization."
+    );
+  }
+  return scope;
+}
+function useEntityList(token, query = {}) {
+  const seeded = (0, import_seed.useSeededSource)(`entity:${token}:rows:${JSON.stringify(query)}`, (source) => createSeedPort(source).list(token, query));
+  return (0, import_react2.useDataRows)(token, query, useEntityScope(), seeded);
+}
+function useEntityColumns(token) {
+  const seeded = (0, import_seed.useSeededSource)(`entity:${token}:columns`, (source) => createSeedPort(source).columns(token));
+  return (0, import_react2.useDataColumns)(token, useEntityScope(), seeded);
+}
+function useEntityType(token) {
+  const scope = useEntityScope();
+  const qc = (0, import_react2.useRecordsQueryClient)();
+  const seeded = (0, import_seed.useSeededSource)(`entity:${token}:type`, (source) => createSeedPort(source).describe(token));
+  const q = (0, import_react_query.useQuery)(
+    {
+      ...seeded ? { initialData: seeded.data, initialDataUpdatedAt: seeded.at } : {},
+      queryKey: [...import_react2.dataKeys.alias(scope.portKey, token), "type"],
+      queryFn: async () => {
+        const answer = await scope.port.describe(token);
+        if (!answer.ok) throw Object.assign(new Error(answer.error.message), { error: answer.error });
+        return answer.data;
+      },
+      retry: false
+    },
+    qc
+  );
+  const failed = q.error;
+  return { data: q.data, loading: q.isPending, error: failed ? failed.error ?? { code: "internal", message: failed.message } : null, refresh: () => void q.refetch() };
+}
+function useEntityRow(token, id) {
+  return (0, import_react2.useDataRow)(token, id, useEntityScope());
+}
+function useEntityWrite(token) {
+  return (0, import_react2.useDataMutations)(token, useEntityScope());
+}
+//# sourceMappingURL=react.cjs.map