@ai-matrx/records 0.80.4 → 0.80.8

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # Changelog — @ai-matrx/records
 
+## 0.80.8
+
+Automatic changed-only republish (docs/metadata drift since the last tag — see
+`git diff npm/records/v0.80.4..npm/records/v0.80.8 -- apps/shared/records`).
+No source changes intended and no consumer action required.
+
+## 0.80.7
+
+Automatic changed-only republish (docs/metadata drift since the last tag — see
+`git diff npm/records/v0.80.4..npm/records/v0.80.7 -- apps/shared/records`).
+No source changes intended and no consumer action required.
+
+## 0.80.6
+### PAGE-BUNDLE-2: a record page opens in one call
+
+RECORD PAGE BUNDLE: the records client answers a record page's own doors (`read_record`, `record_row_controls`, `my_levels` for the record, `record_history` head, `comment_thread`, `computed_provenance`, `record_headers`) from ONE `custom.record_page_bundle(p_organization_id, p_record_id)` call (live; SECURITY INVOKER; each part equals its door's own answer, verified part by part as admin@admin.com). Same contract as the table bundle: exact door + arguments, used once, 10 s; a refusing part is asked by its own door; a write that lands on the record drops what is still held. `primeRecordPageBundle({ organizationId, recordId, answer })` hands it an answer the server render asked as the same person.
+
+**Consumer action:** none (additive). A host that seeds its record route calls `primeRecordPageBundle`.
+
+## 0.80.5
+
+Automatic changed-only republish (docs/metadata drift since the last tag — see
+`git diff npm/records/v0.80.4..npm/records/v0.80.5 -- apps/shared/records`).
+No source changes intended and no consumer action required.
 
 ## 0.80.4
 

package/README.md

@@ -278,6 +278,25 @@ const { write, update, remove, conflict } = useRecordMutation();
 `live` is never quietly false: when realtime is not bound, `liveOffReason` says
 why in a sentence a screen can show.
 
+## Drill-down — declared definitions
+
+A server drill (`platform.drill_describe` / `platform.drill_ask`) answers a standard table from
+the registry, or a **declared definition**: a `*.drill.ts` file (`declareDrillDefinition({...})`,
+shape in `scripts/drill-definitions/ai_usage.drill.ts`) compiled to one function per definition,
+`platform.drill_def__<key>()`. A Dimension may carry `level` (breakouts, show, attributes,
+records); the UI side is `useDrill` in `@ai-matrx/records-ui` and the table in
+`@ai-matrx/design-system` (its README § Drill-down).
+
+| Command (in this package) | Does |
+|---|---|
+| `pnpm drill:sync --write --lane <LANE>` | writes a campaign file (+ inverse) for every declaration whose live body differs |
+| `pnpm drill:sync --write --lane <LANE> --only <key,key>` | the same, for ONLY your definitions — never a peer's half-done one |
+| `pnpm drill:sync --check` | the census: every declaration sound and equal to its live body (exit 1 otherwise) |
+| `pnpm drill:sync --check --only <key,key>` | the census of your definitions only |
+| `... --target clone` | reads the nightly copy instead of production |
+
+`--only` naming a key no file declares fails, so a typo never passes as "nothing to do".
+
 ## The generated half
 
 `src/store.generated.ts` is written by `pnpm records:generate` from the live

package/dist/app-table/index.cjs

@@ -434,6 +434,32 @@ function takePrimedTablePageBundle(organizationId, tableId, viewId) {
   return Date.now() - held.at < PRIMED_TTL_MS ? held.answer : null;
 }
 
+// src/core/recordChanges.ts
+var listeners = /* @__PURE__ */ new Set();
+function announceRecordChanged(recordId) {
+  for (const listener of [...listeners]) {
+    try {
+      listener(recordId);
+    } catch (thrown) {
+      console.error("[@ai-matrx/records] a record-change listener threw", thrown);
+    }
+  }
+}
+function onRecordChanged(listener) {
+  listeners.add(listener);
+  return () => listeners.delete(listener);
+}
+var tableListeners = /* @__PURE__ */ new Set();
+function announceTableStructureChanged(tableId) {
+  for (const listener of [...tableListeners]) {
+    try {
+      listener(tableId);
+    } catch (thrown) {
+      console.error("[@ai-matrx/records] a table-structure listener threw", thrown);
+    }
+  }
+}
+
 // src/archive.ts
 var DEFAULT_ARCHIVE_LANE = "org";
 
@@ -1565,6 +1591,7 @@ var STORE_DOORS = [
   { name: "record_filter_sql", args: "p_organization_id uuid, p_table_id uuid, p_filter jsonb", returns: "text", security: "invoker" },
   { name: "record_headers", args: "p_organization_id uuid, p_ids uuid[]", returns: "TABLE(id uuid, table_id uuid, created_at timestamp with time zone, updated_at timestamp with time zone, version integer, deleted_at timestamp with time zone, mine boolean, created_by uuid)", security: "definer" },
   { name: "record_history", args: "p_organization_id uuid, p_record_id uuid, p_limit integer DEFAULT 200, p_offset integer DEFAULT 0", returns: "TABLE(version integer, occurred_at timestamp with time zone, operation text, operation_label text, actor jsonb, changes jsonb, migration_id uuid, undoable boolean)", security: "definer" },
+  { name: "record_page_bundle", args: "p_organization_id uuid, p_record_id uuid", returns: "jsonb", security: "invoker" },
   { name: "record_platform_keys", args: "", returns: "text[]", security: "invoker" },
   { name: "record_relation_edges", args: "p_organization_id uuid, p_id uuid, p_table_id uuid, p_data_class text, p_data jsonb, p_deleted_at timestamp with time zone", returns: "TABLE(target_id uuid, edge_role text, field_id uuid, ord integer)", security: "invoker" },
   { name: "record_reparent", args: "p_organization_id uuid, p_record_id uuid, p_parent_id uuid", returns: "void", security: "definer" },
@@ -2662,28 +2689,6 @@ var DRILL_DOORS = {
   rows: "drill_rows"
 };
 
-// src/core/recordChanges.ts
-var listeners = /* @__PURE__ */ new Set();
-function announceRecordChanged(recordId) {
-  for (const listener of [...listeners]) {
-    try {
-      listener(recordId);
-    } catch (thrown) {
-      console.error("[@ai-matrx/records] a record-change listener threw", thrown);
-    }
-  }
-}
-var tableListeners = /* @__PURE__ */ new Set();
-function announceTableStructureChanged(tableId) {
-  for (const listener of [...tableListeners]) {
-    try {
-      listener(tableId);
-    } catch (thrown) {
-      console.error("[@ai-matrx/records] a table-structure listener threw", thrown);
-    }
-  }
-}
-
 // src/core/query.ts
 var DEFAULT_PAGE_SIZE = 50;
 function planQuery(query) {
@@ -2803,8 +2808,68 @@ function createRecordsClient(given) {
     } catch {
     }
   }
+  const RECORD_OPENERS = /* @__PURE__ */ new Set(["read_record", "record_row_controls", "record_history", "comment_thread", "computed_provenance"]);
+  const recordFlights = /* @__PURE__ */ new Map();
+  const recordAsked = /* @__PURE__ */ new Map();
+  let recordChangesHeard = false;
+  function bundleRecordOf(door, args) {
+    if (RECORD_OPENERS.has(door)) return typeof args["p_record_id"] === "string" ? args["p_record_id"] : null;
+    const ids = args["p_ids"];
+    const one = Array.isArray(ids) && ids.length === 1 && typeof ids[0] === "string" ? ids[0] : null;
+    if (door === "record_headers") return one;
+    if (door === "my_levels" && args["p_type"] === "record") return one;
+    return null;
+  }
+  async function fillRecordBundle(recordId) {
+    if (!recordChangesHeard) {
+      recordChangesHeard = true;
+      onRecordChanged((changed) => {
+        recordAsked.delete(changed);
+        for (const key of [...bundleParts.keys()]) if (key.includes(changed)) bundleParts.delete(key);
+      });
+    }
+    try {
+      const usable = (r) => r !== null && !r.error && r.data !== null && typeof r.data === "object" && Array.isArray(r.data.parts);
+      const primedAnswer = takePrimedTablePageBundle(org, `record:${recordId}`, null);
+      let response = primedAnswer ? await primedAnswer : null;
+      if (!usable(response)) {
+        response = await config.dataSource.rpc("record_page_bundle", { p_organization_id: org, p_record_id: recordId }, { schema });
+      }
+      if (!usable(response)) return;
+      const now = Date.now();
+      for (const part of response.data.parts) {
+        if (part.error !== void 0 || part.data === void 0) continue;
+        bundleParts.set(bundleKey(part.door, part.args), { data: part.data, at: now });
+      }
+    } catch {
+    }
+  }
+  async function fromRecordBundle(door, args) {
+    if (!doorReady(config, "record_page_bundle")) return void 0;
+    const recordId = bundleRecordOf(door, args);
+    if (!recordId) return void 0;
+    const opener = RECORD_OPENERS.has(door);
+    if (!opener && !recordFlights.has(recordId) && !recordAsked.has(recordId)) return void 0;
+    const asked = recordAsked.get(recordId);
+    const fresh = asked !== void 0 && Date.now() - asked < BUNDLE_TTL_MS;
+    if (!fresh && opener) {
+      recordAsked.set(recordId, Date.now());
+      const flight2 = fillRecordBundle(recordId).finally(() => recordFlights.delete(recordId));
+      recordFlights.set(recordId, flight2);
+    }
+    const flight = recordFlights.get(recordId);
+    if (flight) await flight;
+    const key = bundleKey(door, args);
+    const held = bundleParts.get(key);
+    if (!held) return opener ? null : void 0;
+    bundleParts.delete(key);
+    return Date.now() - held.at < BUNDLE_TTL_MS ? { data: held.data } : null;
+  }
   async function fromBundle(door, args) {
-    if (!config.dataSource.opensInOneCall || !doorReady(config, "table_page_bundle")) return null;
+    if (!config.dataSource.opensInOneCall) return null;
+    const fromRecord = await fromRecordBundle(door, args);
+    if (fromRecord !== void 0) return fromRecord;
+    if (!doorReady(config, "table_page_bundle")) return null;
     const tableId = bundleTableOf(door, args);
     if (tableId) {
       const asked = bundleAsked.get(tableId);