@ai-matrx/records 0.48.0 → 0.49.0

package/CHANGELOG.md

@@ -1,5 +1,35 @@
 # Changelog — @ai-matrx/records
 
+## 0.49.0
+
+**A number on a dashboard can be walked into.** (lane DRILL.)
+
+* **`custom.read_records_matching` — the store's filtered read door**, and `client.list` now
+  asks it for EVERY page, filtered or not, with `{}` when nobody asked a question. The grid,
+  the board, the record list and a dashboard drill-through are therefore one door, decided by
+  one ladder: a narrowed screen can never be a differently-judged screen. `list({ filter })`
+  and `useRecords(tableId, { filter })` are how a caller asks.
+* **`RecordFilter` — the ONE name for the store's filter shape.** It is not new and never was
+  the aggregate's private shape: `platform.saved_view` has carried exactly this object of
+  Field key → value as `definition -> 'filters'` since DOOR-18, `custom.view_declare` writes
+  it, `custom.agg_view_admits` reads it, and `custom.record_aggregate` takes it as `p_filter`.
+  A scalar is an equality, `null` is UNSET (the third state of a tick box), an object is a
+  half-open time window. `SavedViewRow.filters` and `SavedViewSpecIn.filters` were
+  `Record<string, unknown>` and are this now — an `unknown` there is a digest that quietly
+  notifies about the wrong records.
+* **One evaluator in the database, not two.** `custom.agg_sql`'s filter loop moved verbatim
+  into `custom.record_filter_sql` and the aggregate CALLS it, so the number a chart draws and
+  the rows a drill lands on are produced by the same bytes. Measured on Rincon Plumbing Co's
+  41 live jobs: the chart says Cancelled 4, the door hands back RPC-1036…1039 and nothing
+  else; the rendered choice label and the stored key both land on the same four; a window on
+  `scheduled_date` answers 5 through both doors.
+* **Why it is a new name and not a sixth argument** — the REALTIME-2 ruling, again: a defaulted
+  `p_filter` beside the live five-argument `custom.read_records` makes every existing call
+  ambiguous, and the only way to add it in place is to drop a live door.
+* **`stableFilterKey`** — key-sorted JSON of a `RecordFilter`, so a React parent that rebuilds
+  `{ status: "Cancelled" }` on every render re-reads the page when the QUESTION changes rather
+  than on every render forever.
+
 ## 0.48.0
 
 **A portal principal carries the link the office copies for them.** (lane TAILS-5.)

package/dist/core/index.cjs

@@ -124,6 +124,7 @@ __export(core_exports, {
   publicFormPath: () => publicFormPath,
   rememberedOpCount: () => rememberedOpCount,
   scopeChip: () => scopeChip,
+  stableFilterKey: () => stableFilterKey,
   staleWriteDetail: () => staleWriteDetail,
   supabaseDataSource: () => supabaseDataSource,
   toAoa: () => toAoa
@@ -484,6 +485,20 @@ function portalPath(slug) {
 function measureKey(measure) {
   return measure.op === "count" ? "count" : `${measure.op}_${measure.key ?? ""}`;
 }
+function stableFilterKey(filter) {
+  if (!filter) return "{}";
+  const keys = Object.keys(filter).sort();
+  if (keys.length === 0) return "{}";
+  const parts = keys.map((key) => {
+    const value = filter[key];
+    if (value !== null && typeof value === "object") {
+      const window2 = value;
+      return `${JSON.stringify(key)}:{"from":${JSON.stringify(window2.from ?? null)},"to":${JSON.stringify(window2.to ?? null)}}`;
+    }
+    return `${JSON.stringify(key)}:${JSON.stringify(value ?? null)}`;
+  });
+  return `{${parts.join(",")}}`;
+}
 
 // src/capture-queue.ts
 var DB_NAME = "matrx-capture";
@@ -1258,6 +1273,7 @@ var STORE_DOORS = [
   { name: "read_record", args: "p_organization_id uuid, p_record_id uuid, p_by_id boolean DEFAULT false", returns: "jsonb", security: "definer" },
   { name: "read_records", args: "p_organization_id uuid, p_table_id uuid, p_by_id boolean DEFAULT false, p_limit integer DEFAULT 200, p_offset integer DEFAULT 0", returns: "TABLE(id uuid, document jsonb, level permission_level)", security: "definer" },
   { name: "read_records_by_ids", args: "p_organization_id uuid, p_table_id uuid, p_record_ids uuid[], p_by_id boolean DEFAULT false", returns: "TABLE(id uuid, document jsonb, level permission_level)", security: "definer" },
+  { name: "read_records_matching", args: "p_organization_id uuid, p_table_id uuid, p_filter jsonb DEFAULT '{}'::jsonb, p_by_id boolean DEFAULT false, p_limit integer DEFAULT 200, p_offset integer DEFAULT 0", returns: "TABLE(id uuid, document jsonb, level permission_level)", security: "definer" },
   { name: "realtime_topic_admits", args: "p_topic text", returns: "boolean", security: "definer" },
   { name: "record_aggregate", args: "p_organization_id uuid, p_table_id uuid, p_group_by jsonb DEFAULT '[]'::jsonb, p_measures jsonb DEFAULT '[]'::jsonb, p_bucket jsonb DEFAULT NULL::jsonb, p_filter jsonb DEFAULT '{}'::jsonb, p_limit integer DEFAULT 200, p_required text DEFAULT 'viewer'::text", returns: "TABLE(groups jsonb, measures jsonb, row_count bigint)", security: "definer" },
   { name: "record_applicability", args: "p_organization_id uuid, p_record_id uuid", returns: "TABLE(rule_id uuid, rule_name text, rule_version integer, applies boolean, answer jsonb)", security: "invoker" },
@@ -2592,6 +2608,15 @@ var DOORS = {
   // live Postgres function makes every existing call ambiguous — `is not unique`. Same
   // ladder, same level, same masking, same page ceiling.
   readRecordsByIds: "read_records_by_ids",
+  // THE SAME READ DOOR, ADDRESSED BY A QUESTION. `custom.read_records_matching`
+  // takes the store's one filter shape (`RecordFilter` — the object
+  // `platform.saved_view` carries as `filters` and `custom.record_aggregate`
+  // takes as `p_filter`) and narrows the page INSIDE its own query, in the same
+  // WHERE as Visibility. A separate NAME for the same reason as above. It is
+  // what makes a number on a dashboard walkable: the filter is evaluated by
+  // `custom.record_filter_sql`, the one body `custom.agg_sql` also calls, so the
+  // rows it opens are the rows the number counted.
+  readRecordsMatching: "read_records_matching",
   // DOOR-8, the two clocks. `p_recorded_at` is what the store SAID then;
   // `p_world_on` is what was TRUE of the world on that date, read out of dated
   // values. A client that answered either one itself would be guessing.
@@ -3291,12 +3316,13 @@ function createRecordsClient(config) {
         })
       );
     },
-    async list({ table_id, limit = 50, offset = 0 }) {
+    async list({ table_id, filter, limit = 50, offset = 0 }) {
       const door = await callDoor(
-        DOORS.readRecords,
+        DOORS.readRecordsMatching,
         {
           p_organization_id: org,
           p_table_id: table_id,
+          p_filter: filter ?? {},
           p_limit: limit,
           p_offset: offset
         },