@ai-matrx/records 0.92.1 → 0.93.0

package/dist/setup/index.d.cts

@@ -1,16 +1,17 @@
 import { RealtimeManager } from '@ai-matrx/realtime';
-import { R as RecordsClient } from '../client-Cn3odIIB.cjs';
-import { C as CreateEntityDataPortOptions, E as EntityDataPort } from '../port-Drioh9al.cjs';
-import { a as RecordsConfig, b as RecordsErrorSink, c as RecordsDataSource, d as RecordsChangeSink } from '../ports-s0D2jvqn.cjs';
-import { U as Uuid, R as RecordsResult } from '../record-BwCf9wKW.cjs';
+import { R as RecordsClient } from '../client-EyD3rS0T.cjs';
+import { C as CreateEntityDataPortOptions, E as EntityDataPort } from '../port-Cx76dq-X.cjs';
+import { R as RecordOrganizationPort, O as ObjectOrganizationAnswer } from '../objectOrganization-DfjDQtDb.cjs';
+import { a as RecordsConfig, b as RowAgentPort, c as RecordsErrorSink, d as RecordsDataSource, e as RecordsChangeSink, f as RowAgentTarget } from '../ports-9BQ3zo2y.cjs';
+import { U as Uuid, R as RecordsResult } from '../record-DmmeuUrC.cjs';
 import { RecordSearchRequest, RecordSearchHit, listStoreRecordCandidates } from '../search/index.cjs';
-import '../table-kind-DzctQ7dO.cjs';
-import '../field-CCY1rG9l.cjs';
-import '../subscription-CdoI-UaB.cjs';
-import '../rule-wHI5B0Ka.cjs';
-import '../relation-8vAWCa67.cjs';
-import '../portal-DRdmZ-xv.cjs';
-import '../types-BKYEeFt4.cjs';
+import '../table-kind-C-hZxDN7.cjs';
+import '../field-6rwt4ejZ.cjs';
+import '../subscription-Drbxn-9Z.cjs';
+import '../rule-CeHg1sy1.cjs';
+import '../relation-qrb2NbHf.cjs';
+import '../portal-9sRr6cpG.cjs';
+import '../types-Dek9owBe.cjs';
 
 /** A signed-in database identity: the client every door and live change rides, and who it is. */
 interface RecordsSession {
@@ -46,6 +47,13 @@ interface CreateRecordsOptions<TAssociations = never> {
     entityAliases?: CreateEntityDataPortOptions["aliases"];
     /** The associations store (`@ai-matrx/associations/core` `createAssociationsStore`) bound by the host; handed back as-is. */
     associations?: TAssociations;
+    /**
+     * WHICH ORGANIZATION OWNS A RECORD — a port. Default: `custom.where_id_opens`, one call per ask. A host
+     * that keeps answers across remounts or seeds them from a server render binds its own.
+     */
+    organizationOf?: RecordOrganizationPort;
+    /** RUN AN AGENT ON A ROW — a port the host binds (the run belongs to `@ai-matrx/agents`). Unbound, there is none. */
+    rowAgent?: RowAgentPort;
     onError?: RecordsErrorSink;
 }
 interface RecordsSetup<TAssociations = never> {
@@ -79,6 +87,12 @@ interface RecordsSetup<TAssociations = never> {
     watch(tableId: Uuid, sink: Partial<RecordsChangeSink>, organizationId?: Uuid): () => void;
     /** The associations store the host bound, if any. */
     readonly associations: TAssociations | undefined;
+    /** Which organization owns an object (table, record, form…), read from the object — never the person's pick. */
+    organizationOf(id: Uuid): Promise<ObjectOrganizationAnswer>;
+    /** The host's agent runner, or null when none is bound (agent buttons are then not drawn). */
+    readonly rowAgent: RowAgentPort | null;
+    /** Run an agent on a row through the bound runner; refuses by name when none is bound. */
+    runAgentOnRow(target: RowAgentTarget): Promise<RecordsResult<void>>;
     /** Close live channels (a Node script calls this before it exits). */
     close(): void;
 }

package/dist/setup/index.d.ts

@@ -1,16 +1,17 @@
 import { RealtimeManager } from '@ai-matrx/realtime';
-import { R as RecordsClient } from '../client-Dzd8gtAo.js';
-import { C as CreateEntityDataPortOptions, E as EntityDataPort } from '../port-C54ykAOv.js';
-import { a as RecordsConfig, b as RecordsErrorSink, c as RecordsDataSource, d as RecordsChangeSink } from '../ports-BeOgjwYl.js';
-import { U as Uuid, R as RecordsResult } from '../record-BwCf9wKW.js';
+import { R as RecordsClient } from '../client-DsPuWFp0.js';
+import { C as CreateEntityDataPortOptions, E as EntityDataPort } from '../port--acgmxh5.js';
+import { R as RecordOrganizationPort, O as ObjectOrganizationAnswer } from '../objectOrganization-BII_K3Gm.js';
+import { a as RecordsConfig, b as RowAgentPort, c as RecordsErrorSink, d as RecordsDataSource, e as RecordsChangeSink, f as RowAgentTarget } from '../ports-DYWE1ENo.js';
+import { U as Uuid, R as RecordsResult } from '../record-DmmeuUrC.js';
 import { RecordSearchRequest, RecordSearchHit, listStoreRecordCandidates } from '../search/index.js';
-import '../table-kind-i3lZJa3f.js';
-import '../field-enufS5ry.js';
-import '../subscription-BynsG1K6.js';
-import '../rule-D9yNiorf.js';
-import '../relation-eLMgv_dV.js';
-import '../portal-or_f7BkT.js';
-import '../types-cpKY7Pjb.js';
+import '../table-kind-BZkvzBgc.js';
+import '../field-B-WaVZnS.js';
+import '../subscription-hdTaRrfK.js';
+import '../rule-tN2lxvJ1.js';
+import '../relation-Op1M67le.js';
+import '../portal-BDAqsGkg.js';
+import '../types-HVgWcZDY.js';
 
 /** A signed-in database identity: the client every door and live change rides, and who it is. */
 interface RecordsSession {
@@ -46,6 +47,13 @@ interface CreateRecordsOptions<TAssociations = never> {
     entityAliases?: CreateEntityDataPortOptions["aliases"];
     /** The associations store (`@ai-matrx/associations/core` `createAssociationsStore`) bound by the host; handed back as-is. */
     associations?: TAssociations;
+    /**
+     * WHICH ORGANIZATION OWNS A RECORD — a port. Default: `custom.where_id_opens`, one call per ask. A host
+     * that keeps answers across remounts or seeds them from a server render binds its own.
+     */
+    organizationOf?: RecordOrganizationPort;
+    /** RUN AN AGENT ON A ROW — a port the host binds (the run belongs to `@ai-matrx/agents`). Unbound, there is none. */
+    rowAgent?: RowAgentPort;
     onError?: RecordsErrorSink;
 }
 interface RecordsSetup<TAssociations = never> {
@@ -79,6 +87,12 @@ interface RecordsSetup<TAssociations = never> {
     watch(tableId: Uuid, sink: Partial<RecordsChangeSink>, organizationId?: Uuid): () => void;
     /** The associations store the host bound, if any. */
     readonly associations: TAssociations | undefined;
+    /** Which organization owns an object (table, record, form…), read from the object — never the person's pick. */
+    organizationOf(id: Uuid): Promise<ObjectOrganizationAnswer>;
+    /** The host's agent runner, or null when none is bound (agent buttons are then not drawn). */
+    readonly rowAgent: RowAgentPort | null;
+    /** Run an agent on a row through the bound runner; refuses by name when none is bound. */
+    runAgentOnRow(target: RowAgentTarget): Promise<RecordsResult<void>>;
     /** Close live channels (a Node script calls this before it exits). */
     close(): void;
 }

package/dist/setup/index.js

@@ -375,35 +375,48 @@ function sourceArchivedOf(value) {
 import { globalSlot as globalSlot2 } from "@ai-matrx/kit/global-slot";
 var REMEMBER_MS = 3e4;
 var REMEMBER_MAX = 500;
-var ours = globalSlot2("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 ledgerOver(ours) {
+  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);
+    }
   }
+  return {
+    mint() {
+      const id = crypto.randomUUID();
+      const now = Date.now();
+      ours.set(id, now);
+      trim(now);
+      return id;
+    },
+    isOwn(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;
+    },
+    clear() {
+      ours.clear();
+    },
+    get size() {
+      return ours.size;
+    }
+  };
 }
-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;
+function createOpLedger() {
+  return ledgerOver(/* @__PURE__ */ new Map());
 }
+var defaultOpLedger = ledgerOver(globalSlot2("ai-matrx.records.op-ledger", () => /* @__PURE__ */ new Map()));
 
 // src/choice.ts
 import { isUuidShape as isUuidShape2 } from "@ai-matrx/kit/uuid";
@@ -2462,6 +2475,8 @@ function createRecordsClient(given) {
   const config = { ...given, dataSource: asRecordsDataSource(given.dataSource) };
   const schema = config.schema ?? DEFAULT_SCHEMA;
   const org = config.organizationId;
+  const ledger = config.opLedger ?? defaultOpLedger;
+  const mintOp = () => ledger.mint();
   const scream = sink(config);
   const BUNDLE_TTL_MS = 1e4;
   const BUNDLE_OPENERS = /* @__PURE__ */ new Set(["applicable_fields", "views", "view_look_read", "table_decorations", "row_actions", "reverse_columns", "record_change_actions", "grid_layout", "io_imports"]);
@@ -2848,14 +2863,14 @@ function createRecordsClient(given) {
     async recordWrite({ table_id, data }) {
       const result = await callDoor(
         DOORS.recordWrite,
-        { p_organization_id: org, p_table_id: table_id, p_data: { ...data, _op_id: mintOpId() } },
+        { p_organization_id: org, p_table_id: table_id, p_data: { ...data, _op_id: mintOp() } },
         "recordWrite"
       );
       if (result.ok && typeof result.data === "string") announceRecordChanged(result.data);
       return result;
     },
     async recordWriteMany({ table_id, rows, ids }) {
-      const opId = mintOpId();
+      const opId = mintOp();
       return callDoor(
         DOORS.recordWriteMany,
         {
@@ -2868,7 +2883,7 @@ function createRecordsClient(given) {
       );
     },
     async recordChangeMany({ table_id, changes }) {
-      const opId = mintOpId();
+      const opId = mintOp();
       const result = await callDoor(
         DOORS.recordChangeMany,
         {
@@ -2891,7 +2906,7 @@ function createRecordsClient(given) {
       return result;
     },
     async recordWriteGraph({ table_id, parent, children, edges }) {
-      const opId = mintOpId();
+      const opId = mintOp();
       return callDoor(
         DOORS.recordWriteGraph,
         {
@@ -2915,7 +2930,7 @@ function createRecordsClient(given) {
         {
           p_organization_id: org,
           p_record_id: record_id,
-          p_patch: { ...patch, _op_id: mintOpId() },
+          p_patch: { ...patch, _op_id: mintOp() },
           ...expectedVersion === void 0 ? {} : { p_expected_version: expectedVersion }
         },
         "recordUpdate"
@@ -2929,7 +2944,7 @@ function createRecordsClient(given) {
         {
           p_organization_id: org,
           p_record_id: record_id,
-          p_patch: { ...patch, _op_id: mintOpId() },
+          p_patch: { ...patch, _op_id: mintOp() },
           p_add: add,
           ...expectedVersion === void 0 ? {} : { p_expected_version: expectedVersion }
         },
@@ -3954,7 +3969,7 @@ function createRecordsClient(given) {
           p_table_id: table_id,
           p_key: keys,
           // The op id rides the envelope, as `recordWrite` / `recordUpdate` send it; each door takes it off.
-          p_data: { ...data, _op_id: mintOpId() },
+          p_data: { ...data, _op_id: mintOp() },
           ...expectedVersion === void 0 ? {} : { p_expected_version: expectedVersion }
         },
         "recordUpsert"
@@ -6342,6 +6357,7 @@ function toWireValues(values) {
 }
 function createEntityDataPort(options) {
   const client = options.client ?? createEntityClient({ dataSource: options.dataSource });
+  const ledger = options.opLedger ?? defaultOpLedger;
   const activeOrganization = () => (options.activeOrganizationId ? options.activeOrganizationId() : options.organization) ?? null;
   const gets = /* @__PURE__ */ new Map();
   const aliases = options.aliases;
@@ -6532,27 +6548,27 @@ function createEntityDataPort(options) {
           "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() });
+      const answer = await client.insert({ token: binding.token, organizationId, rows: [toWireValues(values)], opId: ledger.mint() });
       return readBack(alias, answer, "The new row");
     },
     async update(alias, id, patch, baseVersion) {
       const binding = bindingOf(alias);
       if (!binding) return noSuchAlias(alias);
       if (!isUuidShape3(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() });
+      const answer = await client.update({ token: binding.token, id, baseVersion, patch: toWireValues(patch), opId: ledger.mint() });
       return readBack(alias, answer, "The change");
     },
     async archive(alias, id) {
       const binding = bindingOf(alias);
       if (!binding) return noSuchAlias(alias);
       if (!isUuidShape3(id)) return refusal("invalid_argument", `"${String(id)}" is not a row id.`);
-      return done(await client.archive({ token: binding.token, ids: [id], opId: mintOpId() }));
+      return done(await client.archive({ token: binding.token, ids: [id], opId: ledger.mint() }));
     },
     async restore(alias, id) {
       const binding = bindingOf(alias);
       if (!binding) return noSuchAlias(alias);
       if (!isUuidShape3(id)) return refusal("invalid_argument", `"${String(id)}" is not a row id.`);
-      return done(await client.unarchive({ token: binding.token, ids: [id], opId: mintOpId() }));
+      return done(await client.unarchive({ token: binding.token, ids: [id], opId: ledger.mint() }));
     },
     subscribe(event, listener) {
       const alias = event.startsWith("rows:") ? event.slice(5) : null;
@@ -6602,6 +6618,48 @@ function createEntityDataPort(options) {
   };
 }
 
+// src/objectOrganization.ts
+var WHERE_ID_OPENS_DOOR = "where_id_opens";
+function doorIsAbsent(error) {
+  if (error.code === "PGRST202" || error.code === "42883") return true;
+  return /could not find the function/i.test(error.message ?? "");
+}
+var DOOR_ABSENT_WHY = "custom.where_id_opens is missing from this database, so this page cannot tell which organization the record lives in and holds instead of guessing. Remedy: the chair applies migrations/campaign/openbyid_one_address_opens_any_id.sql and openbyid_the_resolver_can_be_reached.sql.";
+async function resolveObjectOrganization(dataSource, id) {
+  let answered;
+  try {
+    answered = await dataSource.rpc(WHERE_ID_OPENS_DOOR, { p_id: id }, { schema: "custom" });
+  } catch (thrown) {
+    return { state: "unavailable", why: thrown instanceof Error ? thrown.message : "The record store did not answer." };
+  }
+  return readObjectOrganizationAnswer(answered, id);
+}
+function readObjectOrganizationAnswer(answered, id) {
+  if (answered.error) {
+    if (doorIsAbsent(answered.error)) {
+      console.warn(`[@ai-matrx/records] ${DOOR_ABSENT_WHY}`);
+      return { state: "unavailable", why: DOOR_ABSENT_WHY };
+    }
+    return { state: "unavailable", why: answered.error.message ?? "The record store refused to say where this is." };
+  }
+  const row = answered.data;
+  if (row === null || row === void 0) return { state: "not-given" };
+  if (typeof row !== "object" || typeof row.organization_id !== "string" || typeof row.kind !== "string") {
+    return { state: "unavailable", why: "The record store answered something this page cannot read." };
+  }
+  return {
+    state: "found",
+    organizationId: row.organization_id,
+    kind: row.kind,
+    path: typeof row.path === "string" ? row.path : null,
+    live: row.live !== false,
+    resolvedId: typeof row.resolved_id === "string" ? row.resolved_id : id
+  };
+}
+function whereIdOpensPort(dataSource) {
+  return { organizationOf: (id) => resolveObjectOrganization(dataSource, id) };
+}
+
 // src/realtime/index.ts
 import {
   defineChannelNamespace as defineChannelNamespace2,
@@ -6620,7 +6678,7 @@ function noticeKey(notice) {
   const ids = notice.record_ids == null ? "*" : [...notice.record_ids].sort().join(",");
   return `${notice.table_id ?? ""}:${notice.kind ?? ""}:${notice.op ?? ""}:${notice.op_id ?? ""}:${notice.at}:${ids}`;
 }
-function storeTableChannelSpec(tableId, onNotice, onBackfill) {
+function storeTableChannelSpec(tableId, onNotice, onBackfill, ledger = defaultOpLedger) {
   return {
     topic: storeTableChannel.topic({ tableId }),
     // Database Broadcast is authorized by RLS on realtime.messages — that is what `private` means here;
@@ -6628,14 +6686,14 @@ function storeTableChannelSpec(tableId, onNotice, onBackfill) {
     // delivers nothing forever).
     private: true,
     // The sender is Postgres: no Matrx envelope. OUR OWN WRITE is known by the op id the write door carried.
-    wire: { mode: "raw", isOwnMessage: (payload) => isOwnOp(payload?.op_id) },
+    wire: { mode: "raw", isOwnMessage: (payload) => ledger.isOwn(payload?.op_id) },
     eventKey: (_source, payload) => noticeKey(payload ?? {}),
     broadcast: [
       {
         event: STORE_NOTICE_EVENT,
         onMessage: (message) => {
           const notice = message.data ?? {};
-          if (isOwnOp(notice.op_id)) return;
+          if (ledger.isOwn(notice.op_id)) return;
           onNotice(notice);
         }
       }
@@ -6655,7 +6713,8 @@ function createRecordsRealtimePort(options = {}) {
       },
       () => {
         for (const listener of channel.listeners) listener.backfill();
-      }
+      },
+      options.ledger
     );
     if (options.manager) {
       const handle = options.manager.open(spec);
@@ -6773,22 +6832,26 @@ async function createRecords(options) {
   } else if (options.live) {
     realtime = options.live;
   }
-  const realtimePort = realtime ? createRecordsRealtimePort({ manager: realtime }) : void 0;
+  const opLedger = createOpLedger();
+  const realtimePort = realtime ? createRecordsRealtimePort({ manager: realtime, ledger: opLedger }) : void 0;
   const actor = options.actor ?? { actor: "user", ...userId ? { user_id: userId } : {} };
   const records = createRecordsClient({
     dataSource,
     actor,
     organizationId,
     organizationIds,
+    opLedger,
     ...realtimePort ? { realtime: realtimePort } : {},
     ...options.onError ? { onError: options.onError } : {}
   });
   const entities = createEntityDataPort({
     dataSource,
     aliases: options.entityAliases ?? {},
+    opLedger,
     ...organizationId ? { organization: organizationId } : {}
   });
   const organizationIdChosen = organizationId;
+  const organizationPort = options.organizationOf ?? whereIdOpensPort(dataSource);
   let warnedNotLive = false;
   return {
     authKind: options.auth.kind,
@@ -6817,6 +6880,18 @@ async function createRecords(options) {
       }) });
     },
     associations: options.associations,
+    organizationOf: (id) => organizationPort.organizationOf(id),
+    rowAgent: options.rowAgent ?? null,
+    async runAgentOnRow(target) {
+      if (!options.rowAgent) {
+        return {
+          ok: false,
+          error: { code: "not_supported", message: "No agent runner is bound: pass createRecords({ rowAgent }) to run an agent on a row." }
+        };
+      }
+      await options.rowAgent.run(target);
+      return { ok: true, data: void 0 };
+    },
     close() {
       if (ownsRealtime) realtime?.dispose();
     }