makersclaw 0.5.2 → 0.7.0

package/templates/next/files/lib/brain.js

@@ -0,0 +1,413 @@
+import { claw } from "./claw";
+import { dataChanged, inTurn, useDoorRead } from "./door";
+import { surfaceOfPath } from "./platform";
+
+// The company brain, through the data door.
+//
+// The brain is the workspace's shared records (contacts, companies,
+// deals, whatever kinds the workspace keeps), each in an area: Everyone,
+// Finance… An app never reaches it with SQL: its database login holds
+// none of it. It reads and writes through _claw/data, which the Makersclaw
+// gateway answers itself under this app's path, before anything reaches
+// the app, so it works while the app's machine sleeps (claw
+// docs/brain/CONTRACTS.md §8 and §10). The door hands the app only the
+// kinds its makersclaw.json declares, and only what the member may read.
+//
+// BROWSER, in both modes: call these from "use client" files, in a server
+// app too. The grant cookie is who is asking, and it makes a write a
+// person's press: confirmed, able to overwrite a confirmed value, erase or
+// merge. A write from the app's server would be app code acting:
+// unconfirmed, skipped over a confirmed value, never an erase. So there is
+// no Server Action for the brain. A server component reads with
+// lib/brain-server.js: the same reads, over the proxy's door grant.
+//
+// Every function resolves to a plain object and never throws, like
+// lib/data.js:
+//   - a read: the door's JSON as it came, plus `error: null`;
+//   - a write: the door's JSON as it came;
+//   - a refusal: { ok: false, error, code }. A read keeps its empty values
+//     (records: [], next: null…), so a surface renders it like no rows;
+//   - a 404 that names no code, or no network: { ok: false, error,
+//     unavailable: true }. A claw with no door yet: show a quiet "not
+//     connected yet", not an error.
+// Arguments are camelCase (ifVersion); the door's keys are not (if_version).
+//
+// The door writes the activity line for every write it takes, so nothing
+// here calls logActivity. Writes go one at a time, in the order called,
+// in the same turn as lib/door.js's; one that answers ok calls
+// dataChanged(), so every hook on the page reads again: these four
+// (useRecords, useRecord, useRecordCounts, useBrainSearch) and the own
+// tables' (lib/door.js). A server app may also router.refresh().
+
+/** A value the door's path needs was not given. */
+class Missing extends Error {}
+
+/** One path segment: an id or a kind, encoded, so "a/b" stays one. */
+function segment(value, what) {
+  if (value === undefined || value === null || value === "") throw new Missing(`needs ${what}`);
+  return encodeURIComponent(String(value));
+}
+
+/** A list of names as the door reads it, "a,b"; a string is taken as it is. */
+function names(value) {
+  if (value === undefined || value === null) return undefined;
+  return Array.isArray(value) ? value.map(String).join(",") : String(value);
+}
+
+/** A filter as the door reads it: JSON in the query. A string is taken
+ *  as JSON already. */
+function filter(where) {
+  if (where === undefined || where === null) return undefined;
+  return typeof where === "string" ? where : JSON.stringify(where);
+}
+
+/** "?a=1&b=2", leaving out what was not given. */
+function query(params) {
+  const q = new URLSearchParams();
+  for (const [key, value] of Object.entries(params)) {
+    if (value === undefined || value === null || value === "") continue;
+    q.set(key, String(value));
+  }
+  const text = q.toString();
+  return text ? `?${text}` : "";
+}
+
+/** The argument off, for a flag the door turns off with "0". */
+const off = (flag) => (flag === false ? 0 : undefined);
+
+/**
+ * The door's read routes: each turns its arguments into the path under
+ * _claw/data and names what an empty answer holds. A path of null asks
+ * nothing (a blank search). lib/brain-server.js reads the same paths.
+ */
+export const BRAIN_READS = {
+  kinds: {
+    empty: { kinds: [] },
+    path: () => "kinds",
+  },
+  listRecords: {
+    empty: { records: [], next: null },
+    path: ({ kind, where, order, limit, cursor, fields, prefix, state }) =>
+      `kinds/${segment(kind, "a kind")}/records` +
+      query({ where: filter(where), order, limit, cursor, fields: names(fields), prefix, state: off(state) }),
+  },
+  getRecord: {
+    empty: { record: null, links: null },
+    path: ({ id, links = false, state }) => `records/${segment(id, "an id")}` + query({ links: links ? 1 : undefined, state: off(state) }),
+  },
+  countRecords: {
+    empty: { count: 0, by: null },
+    path: ({ kind, by, where }) => `kinds/${segment(kind, "a kind")}/counts` + query({ by, where: filter(where) }),
+  },
+  searchBrain: {
+    empty: { results: [], meaning: false },
+    path: ({ q, kinds, limit, meaning }) =>
+      String(q ?? "").trim() ? "search" + query({ q, kinds: names(kinds), limit, meaning: off(meaning) }) : null,
+  },
+  recordHistory: {
+    empty: { changes: [], next: null },
+    path: ({ id, limit, cursor }) => `records/${segment(id, "an id")}/history` + query({ limit, cursor }),
+  },
+  brainChanges: {
+    empty: { changes: [], next: null },
+    path: ({ since, kinds }) => "changes" + query({ since, kinds: names(kinds) }),
+  },
+  brainLists: {
+    empty: { lists: [] },
+    path: ({ kind }) => "lists" + query({ kind }),
+  },
+  listMembers: {
+    empty: { list: null, records: [], next: null },
+    path: ({ list, limit, cursor }) => `lists/${segment(list, "a list")}` + query({ limit, cursor }),
+  },
+};
+
+/** What went wrong before anything was sent, said as the door would. */
+function refusedHere(name, error, empty = {}) {
+  const words = error instanceof Missing ? `${name} ${error.message}` : `${name}: ${error?.message ?? error}`;
+  return { ...empty, ok: false, error: words, code: "bad_request" };
+}
+
+/** A claw()-shaped answer → the result: the door's JSON as it came (a
+ *  read's with `error: null` and its empty values under it), or the
+ *  failure in the same keys. */
+function shaped(answer, empty, read) {
+  const data = answer?.data;
+  const json = data && typeof data === "object" && !Array.isArray(data);
+  if (answer?.ok && json && data.ok !== false) return read ? { ...empty, ...data, error: null } : data;
+  const out = { ...empty, ok: false };
+  if (answer?.ok) {
+    // A 2xx that is not the door's success: its refusal, or not its JSON.
+    out.error = json ? String(data.error || "the door refused") : "the door answered something that is not its JSON";
+    if (json && typeof data.code === "string" && data.code) out.code = data.code;
+    return out;
+  }
+  out.error = String(answer?.error || "the door refused");
+  if (answer?.code) out.code = answer.code;
+  if (answer?.unavailable) out.unavailable = true;
+  if (answer?.aborted) out.aborted = true;
+  return out;
+}
+
+/**
+ * Run one of BRAIN_READS: its path from the arguments, `send(path,
+ * signal)` for a claw()-shaped answer, then the result. Never throws.
+ * The browser's reads send through claw(); lib/brain-server.js passes a
+ * `send` of its own.
+ */
+export async function brainRead(name, args, send) {
+  const { empty, path } = BRAIN_READS[name];
+  let sub;
+  try {
+    sub = path(args ?? {});
+  } catch (error) {
+    return refusedHere(name, error, empty);
+  }
+  if (sub === null) return { ok: true, ...empty, error: null };
+  let answer;
+  try {
+    answer = await send(sub, args?.signal);
+  } catch (error) {
+    answer = { ok: false, error: String(error?.message ?? error) };
+  }
+  return shaped(answer, empty, true);
+}
+
+const viaCookie = (path, signal) => claw(`data/${path}`, { signal });
+
+/** The surface the page is on, for the door's activity line. */
+function pageSurface() {
+  return typeof location === "undefined" ? undefined : surfaceOfPath(location.pathname);
+}
+
+/** POST one write route, in its turn (lib/door.js inTurn). `build(args)`
+ *  → { path, body }, or { done } when there is nothing to send. A write
+ *  the door takes calls dataChanged(). Never throws. */
+async function post(name, args, build) {
+  let built;
+  try {
+    built = build(args ?? {});
+    if (built.done) return built.done;
+    // claw() would read a body that cannot be JSON as "not reachable".
+    JSON.stringify(built.body);
+  } catch (error) {
+    return refusedHere(name, error);
+  }
+  return inTurn(async () => {
+    let answer;
+    try {
+      answer = await claw(`data/${built.path}`, { method: "POST", body: built.body });
+    } catch (error) {
+      answer = { ok: false, error: String(error?.message ?? error) };
+    }
+    const out = shaped(answer, {}, false);
+    if (out.ok !== false) dataChanged();
+    return out;
+  });
+}
+
+/** One write as the door reads it. `surface` defaults to the page's
+ *  surface key (the <key> of /s/<key>, as logActivity's lines name it);
+ *  null sends none. */
+function writeBody(write) {
+  const { kind, id, fields, area, from, ifVersion, owner, surface, detail } = write ?? {};
+  return {
+    kind,
+    id,
+    fields,
+    area,
+    from,
+    if_version: ifVersion,
+    owner,
+    surface: surface === undefined ? pageSurface() : surface,
+    detail,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Reads. Each takes an optional `signal` to abort it.
+
+/** GET _claw/data/kinds: the kinds this app declared, with the words,
+ *  fields and counts the member may see.
+ *  → { ok, brain, kinds: [{ kind, label, plural, fields, key, filters,
+ *  label_field, reads, writes, count, unconfirmed }], error }. `brain` is
+ *  false while the workspace has no brain yet (every read is empty). */
+export function kinds(args) {
+  return brainRead("kinds", args, viaCookie);
+}
+
+/** GET _claw/data/kinds/<kind>/records: one kind's records, newest first.
+ *  `where` an object (below), `order` "-updated_at" (default) |
+ *  "updated_at" | "created_at" | "-created_at" | "label" | "-label" |
+ *  "<field>" | "-<field>", `limit` 50 (at most 200), `cursor` the last
+ *  answer's `next`, `fields` ["name", "email"] only those, `prefix` the
+ *  label starts with (pickers), `state: false` leaves each field's state
+ *  out. → { ok, records, next, error } */
+export function listRecords(args) {
+  return brainRead("listRecords", args, viaCookie);
+}
+
+/** GET _claw/data/records/<id>: one record; `links: true` adds its links
+ *  both ways, to records the member may read.
+ *  → { ok, record, links: { out, in } | null, error } */
+export function getRecord(args) {
+  return brainRead("getRecord", args, viaCookie);
+}
+
+/** GET _claw/data/kinds/<kind>/counts: how many records match `where`;
+ *  `by` a field counts per value ("null" for none).
+ *  → { ok, count, by: { [value]: n } | null, error } */
+export function countRecords(args) {
+  return brainRead("countRecords", args, viaCookie);
+}
+
+/** GET _claw/data/search: records by words and meaning, across `kinds`
+ *  (default: every kind the app reads), `limit` at most 50. `meaning:
+ *  false` is keywords only: nothing is embedded or charged (a picker that
+ *  searches as the member types). A blank `q` asks nothing.
+ *  → { ok, meaning, results: [{ record: { id, kind, label, area,
+ *  updated_at }, score, matched, snippet }], error } */
+export function searchBrain(args) {
+  return brainRead("searchBrain", args, viaCookie);
+}
+
+/** GET _claw/data/records/<id>/history: who changed what, newest first
+ *  (`limit` at most 100). → { ok, changes: [{ id, at, op, fields, before,
+ *  after, by: { member, app, via } }], next, error } */
+export function recordHistory(args) {
+  return brainRead("recordHistory", args, viaCookie);
+}
+
+/** GET _claw/data/changes: what changed in the member's areas and the
+ *  app's kinds since `since` (the last answer's `next`; none: from the
+ *  start). → { ok, changes: [{ id, at, op, kind, record_id }], next, error } */
+export function brainChanges(args) {
+  return brainRead("brainChanges", args, viaCookie);
+}
+
+/** GET _claw/data/lists: the lists of records, of one `kind` or all.
+ *  → { ok, lists: [{ id, name, kind, area, count }], error } */
+export function brainLists(args) {
+  return brainRead("brainLists", args, viaCookie);
+}
+
+/** GET _claw/data/lists/<list>: a list and its records, in order.
+ *  → { ok, list, records, next, error } */
+export function listMembers(args) {
+  return brainRead("listMembers", args, viaCookie);
+}
+
+// ---------------------------------------------------------------------------
+// Writes. The member's press, through the cookie; the door logs each.
+
+/** POST _claw/data/write: make or change one record. Without `id` the
+ *  door finds the record by the kind's key, or makes one. `fields` {
+ *  name: value | null } (null clears), `area` a new record's area (or a
+ *  move), `ifVersion` refuses with `changed` when someone saved since,
+ *  `owner` { kind: "member" | "group", id } | null, `surface` (default the
+ *  page's) and `detail` (one sentence) for the activity line.
+ *  → { ok, id, created, changed, version, skipped } | { ok: false, error, code } */
+export function writeRecord(args) {
+  return post("writeRecord", args, (write) => ({ path: "write", body: writeBody(write) }));
+}
+
+/** POST _claw/data/write with { writes }: up to 100 writes, one
+ *  transaction, all or none. → { ok, results: [one writeRecord answer
+ *  each] } | { ok: false, error, code } */
+export function writeRecords(args) {
+  return post("writeRecords", args, ({ writes }) => {
+    if (!Array.isArray(writes)) throw new Missing("needs a list of writes");
+    if (!writes.length) return { done: { ok: true, results: [] } };
+    return { path: "write", body: { writes: writes.map(writeBody) } };
+  });
+}
+
+/** POST _claw/data/records/<id>/confirm: the member says these `fields`
+ *  are right (none named: every unconfirmed one).
+ *  → { ok, confirmed, version } */
+export function confirmFields(args) {
+  return post("confirmFields", args, ({ id, fields }) => ({ path: `records/${segment(id, "an id")}/confirm`, body: { fields } }));
+}
+
+/** POST _claw/data/records/<id>/erase: gone for every app, with no undo.
+ *  A person's press only. → { ok, erased } */
+export function eraseRecord(args) {
+  return post("eraseRecord", args, ({ id, reason }) => ({ path: `records/${segment(id, "an id")}/erase`, body: { reason } }));
+}
+
+/** POST _claw/data/records/<keep>/merge: `drop` folds into `keep` (its
+ *  empty fields filled, its links and lists moved) and goes.
+ *  → { ok, id, merged, filled, version } */
+export function mergeRecords(args) {
+  return post("mergeRecords", args, ({ keep, drop }) => ({ path: `records/${segment(keep, "the id to keep")}/merge`, body: { drop } }));
+}
+
+/** POST _claw/data/links { op: "add" }: link two records (`type` default
+ *  "related"). → { ok, created } */
+export function linkRecords(args) {
+  return post("linkRecords", args, ({ from, to, type }) => ({ path: "links", body: { op: "add", from, to, type } }));
+}
+
+/** POST _claw/data/links { op: "remove" }: unlink them (no `type`: every
+ *  type). → { ok, removed } */
+export function unlinkRecords(args) {
+  return post("unlinkRecords", args, ({ from, to, type }) => ({ path: "links", body: { op: "remove", from, to, type } }));
+}
+
+/** POST _claw/data/lists: a new list of one kind's records.
+ *  → { ok, id } */
+export function createList(args) {
+  return post("createList", args, ({ name, kind, area }) => ({ path: "lists", body: { name, kind, area } }));
+}
+
+/** POST _claw/data/lists/<list>/members: `add` and `remove` record ids
+ *  (at most 500), `position` where the added go. → { ok, added, removed } */
+export function changeList(args) {
+  return post("changeList", args, ({ list, add, remove, position }) => ({
+    path: `lists/${segment(list, "a list")}/members`,
+    body: { add, remove, position },
+  }));
+}
+
+// ---------------------------------------------------------------------------
+// Hooks, for "use client" components: a read on mount, again on every
+// dataChanged() (a write of this page's that answered ok, or a browser
+// app's auto-refresh), with lib/door.js's rules: `loading` until the first
+// answer for these arguments, a re-read keeps the last values until the
+// new ones land, each answer a new array, a read no longer needed
+// aborted. Each returns the read's values with `loading` and `reload`.
+
+/** A brain read, for a hook: the browser's, through the cookie. */
+const hookRead = (name) => (args) => brainRead(name, args, viaCookie);
+
+/** A read's empty values, fresh: a hook hands out a new array each time. */
+const emptyOf = (name) => () => JSON.parse(JSON.stringify(BRAIN_READS[name].empty));
+
+/** listRecords as a hook. → { records, next, error, loading, reload } */
+export function useRecords(args) {
+  return useDoorRead(hookRead("listRecords"), args, { empty: emptyOf("listRecords") });
+}
+
+/** getRecord as a hook; no id asks nothing and answers record: null.
+ *  → { record, links, error, loading, reload } */
+export function useRecord(args) {
+  return useDoorRead(hookRead("getRecord"), args, {
+    empty: emptyOf("getRecord"),
+    idle: (a) => a.id === undefined || a.id === null || a.id === "",
+  });
+}
+
+/** countRecords as a hook. → { count, by, error, loading, reload } */
+export function useRecordCounts(args) {
+  return useDoorRead(hookRead("countRecords"), args, { empty: emptyOf("countRecords") });
+}
+
+/** searchBrain as a hook; a blank `q` asks nothing. For a picker that
+ *  searches as the member types, pass `meaning: false`: each keystroke
+ *  aborts the read before it. → { results, meaning, error, loading, reload } */
+export function useBrainSearch(args) {
+  return useDoorRead(hookRead("searchBrain"), args, {
+    empty: emptyOf("searchBrain"),
+    idle: (a) => !String(a.q ?? "").trim(),
+  });
+}

package/templates/next/files/lib/claw.js

@@ -2,6 +2,8 @@
 // product's path, before it proxies anything to the app
 // (docs/ARTIFACT-CONTRACTS.md §5). It is reachable from the BROWSER only —
 // the grant cookie is the identity — so everything here is client-side.
+// One exception: the data door (lib/brain-server.js) also answers the
+// app's server, with a bearer, and clawAnswer reads its answers there.
 //
 // Every call resolves; nothing throws. A 404 that names no refusal, or a
 // network error, means the gateway has no such route yet, and comes back
@@ -199,6 +201,15 @@ export async function claw(path, { method = "GET", body, signal } = {}) {
     if (error?.name === "AbortError") return { ok: false, status: 0, error: "aborted", aborted: true };
     return { ok: false, status: 0, error: "not reachable", unavailable: true };
   }
+  return clawAnswer(res);
+}
+
+/** A gateway's response read the way claw() reads it: a 404 with or
+ *  without a code (notFound), a refusal's words and code, or the JSON.
+ *  lib/brain-server.js reaches the data door from the server, with a
+ *  bearer instead of the cookie, and reads its answers through this, so
+ *  a 404 means the same thing on both sides. */
+export async function clawAnswer(res) {
   if (res.status === 404) return notFound(res);
   if (!res.ok) return { ok: false, status: res.status, ...(await readFailure(res)), unavailable: false };
   const text = await res.text().catch(() => "");

package/templates/next/files/lib/data.js

@@ -1,5 +1,5 @@
 import { headers } from "next/headers";
-import { artifactId, ident, query } from "./db";
+import { ident, query } from "./db";
 import { markSample } from "./sample";
 
 // SERVER reads. Import from server components and server actions only —
@@ -38,21 +38,111 @@ export function plain(row) {
   return out;
 }
 
-// { column: value } → "WHERE ..." text; params is filled in place.
-// null → IS NULL, an array → = ANY, anything else → equality.
-function whereClause(filter, params) {
-  const where = [];
-  for (const [col, val] of Object.entries(filter ?? {})) {
-    if (val === null) {
-      where.push(`${ident(col)} IS NULL`);
-    } else if (Array.isArray(val)) {
-      params.push(val);
-      where.push(`${ident(col)} = ANY($${params.length})`);
-    } else {
-      params.push(val);
-      where.push(`${ident(col)} = $${params.length}`);
+// A filter is the platform data door's grammar (claw's STATIC-SPEC §1,
+// "The routes"), so a surface's filter means the same in a server app,
+// read here, and in a browser one, read by the door. Up to 0.6.x it knew
+// equals, lists and null, and any other object went to pg as a value.
+const WHERE_MAX = 20;
+const LIST_MAX = 1000;
+const BOUNDS = [
+  ["gt", ">"],
+  ["gte", ">="],
+  ["lt", "<"],
+  ["lte", "<="],
+];
+const GRAMMAR = "takes a value, [values], null, or one of {not}, {gt|gte|lt|lte}, {has}, {prefix}";
+
+/** A value a condition compares with: text, a finite number, true or
+ *  false, or a Date (JSON sends it as its ISO time). */
+function isValue(v) {
+  if (typeof v === "string" || typeof v === "boolean") return true;
+  if (typeof v === "number") return Number.isFinite(v);
+  return v instanceof Date && !Number.isNaN(v.getTime());
+}
+
+/** A prefix for LIKE: lower-cased, LIKE's own marks escaped (Postgres's
+ *  default escape is a backslash), then "%". */
+function likePrefix(text) {
+  return `${text.toLowerCase().replace(/[\\%_]/g, (m) => `\\${m}`)}%`;
+}
+
+/** One `column: condition` as SQL; `bind` adds a value and names it. */
+function condition(name, cond, bind) {
+  const refuse = (what) => {
+    throw new Error(`filter: ${name} ${what}`);
+  };
+  if (name.includes(".")) refuse("is not a column: name the column alone");
+  const col = ident(name);
+  if (cond === null) return `${col} IS NULL`;
+  if (isValue(cond)) return `${col} = ${bind(cond)}`;
+  if (Array.isArray(cond)) {
+    if (cond.length > LIST_MAX) refuse(`takes at most ${LIST_MAX.toLocaleString("en-US")} values in a list`);
+    if (!cond.every(isValue)) refuse("takes a list of values (text, numbers, true or false): filter empty ones with null");
+    return `${col} = ANY(${bind(cond)})`;
+  }
+  if (typeof cond !== "object" || cond instanceof Date) refuse(GRAMMAR);
+  // A key left undefined is not there, as JSON leaves it out on its way
+  // to the door: { gte: from, lte: to } with no `to` is one bound.
+  const keys = Object.keys(cond).filter((k) => cond[k] !== undefined);
+  if (keys.length === 1 && keys[0] === "not") {
+    if (cond.not === null) return `${col} IS NOT NULL`;
+    if (!isValue(cond.not)) refuse("takes {not: value} or {not: null}");
+    // Distinct, not <>: a row with no value is not the value either.
+    return `${col} IS DISTINCT FROM ${bind(cond.not)}`;
+  }
+  if (keys.length === 1 && keys[0] === "has") {
+    if (!isValue(cond.has)) refuse("takes {has: value}");
+    // An array column holds it. (The door also reads a jsonb column's
+    // `?`; it knows the column's type, which a filter here does not.)
+    return `${bind(cond.has)} = ANY(${col})`;
+  }
+  if (keys.length === 1 && keys[0] === "prefix") {
+    if (typeof cond.prefix !== "string" || !cond.prefix) refuse('wants {prefix: "some text"}');
+    return `lower(${col}) LIKE ${bind(likePrefix(cond.prefix))}`;
+  }
+  const bounds = BOUNDS.map(([k]) => k);
+  if (keys.length && keys.every((k) => bounds.includes(k))) {
+    const lower = keys.filter((k) => k === "gt" || k === "gte");
+    const upper = keys.filter((k) => k === "lt" || k === "lte");
+    if (lower.length > 1 || upper.length > 1) refuse("takes one lower bound (gt or gte) and one upper (lt or lte)");
+    const parts = [];
+    for (const [k, op] of BOUNDS) {
+      if (!keys.includes(k)) continue;
+      if (!isValue(cond[k])) refuse(`takes {${k}: value}: a number, a day or a time`);
+      parts.push(`${col} ${op} ${bind(cond[k])}`);
     }
+    return parts.join(" AND ");
+  }
+  return refuse(GRAMMAR);
+}
+
+/**
+ * `filter` → " WHERE …" text, "" for none; `params` is filled in place and
+ * every value is bound. An AND of `{ column: condition }`, at most 20:
+ *
+ *   value                        equals
+ *   [value, …]                   one of (at most 1,000)
+ *   null                         empty (IS NULL)
+ *   { not: value | null }        anything else (IS DISTINCT FROM), or not empty
+ *   { gt | gte | lt | lte: v }   a bound; one lower and one upper may combine
+ *   { has: value }               an array column holds it
+ *   { prefix: "text" }           starts with, case ignored
+ *
+ * A column whose condition is undefined is left out, as JSON leaves it
+ * out. Anything else throws, and the read returns it as its error.
+ */
+export function whereClause(filter, params) {
+  if (filter === undefined || filter === null) return "";
+  if (typeof filter !== "object" || Array.isArray(filter)) {
+    throw new Error('filter is an object of column names to conditions, like { stage: "won" }');
   }
+  const entries = Object.entries(filter).filter(([, cond]) => cond !== undefined);
+  if (entries.length > WHERE_MAX) throw new Error(`filter holds at most ${WHERE_MAX} conditions`);
+  const bind = (value) => {
+    params.push(value);
+    return `$${params.length}`;
+  };
+  const where = entries.map(([name, cond]) => condition(name, cond, bind));
   return where.length ? ` WHERE ${where.join(" AND ")}` : "";
 }
 
@@ -63,7 +153,8 @@ function failed(what, error) {
 }
 
 /**
- * Rows of a source table. `filter` is { column: value }; `orderBy` is
+ * Rows of a source table. `filter` is whereClause's grammar (above:
+ * { column: condition }, the data door's); `orderBy` is
  * "updated_at desc" (default: idColumn desc); `limit` caps at 5000.
  *   → { rows, error }
  */
@@ -121,37 +212,36 @@ export async function countBy({ source, column, filter }) {
 }
 
 /**
- * What happened, newest first: public.artifact_activity for this artifact
+ * What happened, newest first: this app's lines in claw_app.activity
  * (every lib/actions.js write and everything the agent recorded with the
- * sql verb). `surface` narrows to one surface key; `since` (ISO or Date)
- * to rows after that time. Rows: { id, at, action, surface, row_ref,
- * detail, data, by }. → { rows, error }
+ * sql verb). The view holds only this app's lines, so nothing here names
+ * the app. `surface` narrows to one surface key; `since` (ISO or Date) to
+ * rows after that time. Rows: { id, at, action, surface, row_ref, detail,
+ * data, by }. Outside Makersclaw there is no such view: `error` says so.
+ * → { rows, error }
  */
 export async function loadActivity({ limit = 100, surface, since } = {}) {
-  const id = artifactId();
-  if (!id) {
-    return { rows: [], error: failed("public.artifact_activity", "no CLAW_ARTIFACT_ID; product_run sets it") };
-  }
   try {
-    const params = [id];
-    let where = `WHERE artifact_id = $1`;
+    const params = [];
+    const where = [];
     if (surface) {
       params.push(String(surface));
-      where += ` AND surface = $${params.length}`;
+      where.push(`surface = $${params.length}`);
     }
     if (since) {
       params.push(since instanceof Date ? since.toISOString() : String(since));
-      where += ` AND at > $${params.length}::timestamptz`;
+      where.push(`at > $${params.length}::timestamptz`);
     }
     params.push(Math.max(1, Math.min(1000, Number(limit) || 100)));
+    const filter = where.length ? ` WHERE ${where.join(" AND ")}` : "";
     const { rows } = await query(
       `SELECT id, at, action, surface, row_ref, detail, data, by
-       FROM public.artifact_activity ${where} ORDER BY at DESC, id DESC LIMIT $${params.length}`,
+       FROM claw_app.activity${filter} ORDER BY at DESC, id DESC LIMIT $${params.length}`,
       params,
     );
     return { rows: rows.map(plain), error: null };
   } catch (error) {
-    return { rows: [], error: failed("public.artifact_activity", error) };
+    return { rows: [], error: failed("claw_app.activity", error) };
   }
 }
 
@@ -160,7 +250,7 @@ export async function loadActivity({ limit = 100, surface, since } = {}) {
  *  code keeps one import. */
 export { markSample };
 
-/** The surface key of the current request (middleware.js sets it from
+/** The surface key of the current request (proxy.js sets it from
  *  /s/<key>), unless the caller names one — a string, or the page's
  *  `surface` object. */
 export async function currentSurface(explicit) {