makersclaw 0.6.0 → 0.8.0

package/templates/next/files/components/ui/index.js

@@ -48,6 +48,7 @@ export { Stat, StatGroup, Delta, StatusDot, Legend, Meter } from "./stat";
 export { Steps } from "./steps";
 export { Separator, Kbd, KbdGroup, AspectRatio } from "./separator";
 export { ScrollArea } from "./scroll-area";
+export { AppLayout, DocumentLayout } from "./layout";
 export { Slider } from "./slider";
 export { InputGroup, PasswordInput } from "./input-group";
 export { Image } from "./image";

package/templates/next/files/components/ui/item.jsx

@@ -17,7 +17,7 @@ import { Icon } from "./icon";
 //   meta        a count, a date, a Badge — muted, on the right
 //   actions     buttons on the far right (IconButton, Menu); they sit above
 //               the row's target, so they click on their own
-//   href        a next/link row · `onClick` a button row · neither: static
+//   href        a next/link row · `onClick` a button row · neither: a plain row
 //   size        default (56px) · sm (44px, for dense lists and rails) ·
 //               lg (64px, roomier: a pipeline's runs, a list read at leisure)
 //   variant     plain (no fill) · outline (a bordered card) · muted (a filled panel)
@@ -58,7 +58,7 @@ const STACKED = {
 
 const TARGET = "outline-none after:absolute after:inset-0";
 
-// The row filled while its target (or a static row itself) is current.
+// The row filled while its target (or a plain row itself) is current.
 const CURRENT =
   "has-[[data-item-target][aria-current]:not([aria-current=false])]:bg-accent " +
   "[&[aria-current]:not([aria-current=false])]:bg-accent";

package/templates/next/files/components/ui/layout.jsx

@@ -0,0 +1,307 @@
+"use client";
+
+import { createContext, useContext, useEffect, useRef, useState } from "react";
+import { cx } from "./cx";
+import { Button, IconButton } from "./button";
+import { Sheet } from "./sheet";
+
+// Layouts — who owns the window's height, and who scrolls.
+//
+// Every design-first build of 2026-10-07 shipped a shell of `min-h-dvh`
+// that grew with its content: the page itself scrolled, no pane scrolled
+// on its own, and a footer, an inspector or a button below a long
+// article sat past the end of the iframe, where nothing could reach it.
+// So the kit owns the window's height, once, and the app's code never
+// sizes anything by the window (`npm run check` refuses min-h-dvh,
+// h-screen, 100vh, h-[80vh]… outside the kit, rule 12).
+//
+// AppLayout — the app frame. Exactly one owns the viewport: the
+// outermost. A layout inside another fills the slot it is in instead,
+// whatever `height` says, so there is never a second viewport owner. The
+// shell (app/shell.jsx) is the outermost one in every app the template
+// lays; a surface that needs an inspector or a fill of its own returns
+// an AppLayout as its outermost element, and it fills the shell's
+// content edge to edge (the content's padding drops for it).
+//
+//   header         the top bar, always in view (title, the surface's
+//                  commands). The bar draws its own bottom border
+//   navigation     the surfaces, a page tree: a rail beside the content
+//                  from md (768px); below md a Sheet from the leading
+//                  edge, opened by the menu button in the top bar. A
+//                  press on a link or a button inside closes it
+//   navigationLabel  the Sheet's title and the menu button's words
+//                  ("Navigation")
+//   navigationWidth  the rail, in px (176; 160 to 320)
+//   children       the content. It scrolls inside its own region
+//   contentMode    scroll (the default): the content region scrolls ·
+//                  fill: the region is a bounded flex column and the
+//                  child owns its own scrolling (a canvas, a grid, a
+//                  spreadsheet, an editor that scrolls itself)
+//   contentLabel   the content region's name for a screen reader ("Content")
+//   contentClassName  spacing and token backgrounds for the content
+//                  region (p-4 sm:p-6, bg-card). Never a height or an
+//                  overflow: the layout owns those
+//   scrollKey      when it changes the content scrolls back to its top
+//                  and the navigation Sheet closes: pass the route
+//                  (usePathname()), since the frame stays mounted while
+//                  the surfaces change inside it
+//   inspector      the details, review or feedback panel beside the
+//                  content, scrolling on its own
+//   inspectorLabel the inspector region's name ("Details")
+//   inspectorWidth in px (360; 240 to 560). Builds have needed 300 and 440
+//   inspectorAt    md · lg (the default) · xl: the width from which the
+//                  inspector sits beside the content
+//   footer         under the content, always in view (the save state,
+//                  the composer, the commands for what is above)
+//   height         viewport (the default): the frame is the window's
+//                  height · parent: it fills a bounded parent. Nested,
+//                  it is parent whatever this says
+//   className      the frame's own tokens; never a height or an overflow
+//
+// Below `inspectorAt`, where there is no room for two columns:
+//   - contentMode scroll: the content and the inspector share ONE scroll
+//     region, the inspector after the content. Everything is reachable
+//     by scrolling, and nothing is hidden behind a button.
+//   - contentMode fill: the content keeps the room and the inspector is
+//     a bounded pane under it (at most 45% of the height), scrolling on
+//     its own. A fill child has no flow to stack into, and a pane with
+//     no bound under it is cut off (workspace-layout's fault, 2026-10-07).
+//   The footer stays under both, in view.
+//
+// In print the frame lets go: no bound, no overflow, no navigation, no
+// header, inspector or footer; the content flows onto pages. A page meant
+// for print or export is a DocumentLayout inside the content.
+
+const Nested = createContext(false);
+
+const px = (value, fallback, min, max) => {
+  const n = Number(value);
+  return `${Number.isFinite(n) && n > 0 ? Math.min(max, Math.max(min, Math.round(n))) : fallback}px`;
+};
+
+// Tailwind reads class names whole from the source, so every breakpoint
+// is written out.
+const BESIDE = {
+  md: {
+    main: "md:grid md:grid-cols-[minmax(0,1fr)_var(--app-inspector)] md:grid-rows-[minmax(0,1fr)_auto]",
+    flow: "md:contents",
+    content: "md:col-start-1 md:row-start-1",
+    scrolls: "md:min-h-0 md:overflow-y-auto md:overscroll-contain",
+    inspector: "md:col-start-2 md:row-span-2 md:row-start-1 md:max-h-none md:min-h-0 md:overflow-y-auto md:border-l md:border-t-0",
+    footer: "md:col-start-1 md:row-start-2",
+  },
+  lg: {
+    main: "lg:grid lg:grid-cols-[minmax(0,1fr)_var(--app-inspector)] lg:grid-rows-[minmax(0,1fr)_auto]",
+    flow: "lg:contents",
+    content: "lg:col-start-1 lg:row-start-1",
+    scrolls: "lg:min-h-0 lg:overflow-y-auto lg:overscroll-contain",
+    inspector: "lg:col-start-2 lg:row-span-2 lg:row-start-1 lg:max-h-none lg:min-h-0 lg:overflow-y-auto lg:border-l lg:border-t-0",
+    footer: "lg:col-start-1 lg:row-start-2",
+  },
+  xl: {
+    main: "xl:grid xl:grid-cols-[minmax(0,1fr)_var(--app-inspector)] xl:grid-rows-[minmax(0,1fr)_auto]",
+    flow: "xl:contents",
+    content: "xl:col-start-1 xl:row-start-1",
+    scrolls: "xl:min-h-0 xl:overflow-y-auto xl:overscroll-contain",
+    inspector: "xl:col-start-2 xl:row-span-2 xl:row-start-1 xl:max-h-none xl:min-h-0 xl:overflow-y-auto xl:border-l xl:border-t-0",
+    footer: "xl:col-start-1 xl:row-start-2",
+  },
+};
+
+const REGION = "outline-none focus-visible:ring-2 focus-visible:ring-inset focus-visible:ring-ring";
+const LETS_GO = "print:block print:h-auto print:min-h-0 print:overflow-visible";
+
+export function AppLayout({
+  header,
+  navigation,
+  navigationLabel = "Navigation",
+  navigationWidth,
+  children,
+  contentMode = "scroll",
+  contentLabel = "Content",
+  contentClassName,
+  scrollKey,
+  inspector,
+  inspectorLabel = "Details",
+  inspectorWidth,
+  inspectorAt = "lg",
+  footer,
+  height = "viewport",
+  className,
+}) {
+  const nested = useContext(Nested);
+  const bounded = nested || height === "parent";
+  const fill = contentMode === "fill";
+  const at = BESIDE[inspectorAt] ?? BESIDE.lg;
+  const hasInspector = inspector != null && inspector !== false;
+  const hasNavigation = navigation != null && navigation !== false;
+  const shared = hasInspector && !fill; // below `at`: content and inspector in one scroll region
+  const [open, setOpen] = useState(false);
+  const flowRef = useRef(null);
+  const contentRef = useRef(null);
+
+  useEffect(() => {
+    if (flowRef.current) flowRef.current.scrollTop = 0;
+    if (contentRef.current) contentRef.current.scrollTop = 0;
+    setOpen(false);
+  }, [scrollKey]);
+
+  return (
+    <Nested.Provider value={true}>
+      <div
+        data-app-layout={bounded ? "parent" : "viewport"}
+        style={{ "--app-nav": px(navigationWidth, 176, 160, 320), "--app-inspector": px(inspectorWidth, 360, 240, 560) }}
+        className={cx(
+          "flex min-w-0 flex-col overflow-hidden bg-background text-foreground",
+          bounded ? "h-full min-h-0 flex-1" : "h-dvh",
+          LETS_GO,
+          className,
+        )}
+      >
+        {header != null && header !== false ? (
+          <div data-layout-header className="flex shrink-0 items-center gap-1 border-b border-border print:hidden">
+            {hasNavigation ? (
+              <IconButton icon="menu" label={`Open ${navigationLabel.toLowerCase()}`} onClick={() => setOpen(true)} className="ml-1 md:hidden" />
+            ) : null}
+            <div className="min-w-0 flex-1">{header}</div>
+          </div>
+        ) : hasNavigation ? (
+          <div data-layout-header className="flex shrink-0 items-center border-b border-border px-1 py-1 md:hidden print:hidden">
+            <Button variant="quiet" size="sm" icon="menu" onClick={() => setOpen(true)}>
+              {navigationLabel}
+            </Button>
+          </div>
+        ) : null}
+
+        {hasNavigation ? (
+          <Sheet open={open} onClose={() => setOpen(false)} title={navigationLabel} side="start">
+            {open ? (
+              <div
+                onClick={(e) => {
+                  if (e.target instanceof Element && e.target.closest("a,button")) setOpen(false);
+                }}
+              >
+                {navigation}
+              </div>
+            ) : null}
+          </Sheet>
+        ) : null}
+
+        <div data-layout-body className={cx("flex min-h-0 min-w-0 flex-1", LETS_GO)}>
+          {hasNavigation ? (
+            <div
+              data-layout-navigation
+              className="hidden shrink-0 flex-col overflow-y-auto overscroll-contain border-r border-border md:flex md:w-(--app-nav) print:hidden"
+            >
+              {navigation}
+            </div>
+          ) : null}
+
+          <div data-layout-main className={cx("flex min-h-0 min-w-0 flex-1 flex-col", hasInspector && at.main, LETS_GO)}>
+            <div
+              ref={flowRef}
+              data-layout-flow
+              className={cx(
+                "flex min-h-0 min-w-0 flex-1 flex-col",
+                shared && "overflow-y-auto overscroll-contain",
+                hasInspector && at.flow,
+                LETS_GO,
+              )}
+            >
+              <div
+                ref={contentRef}
+                data-layout-content
+                role="region"
+                aria-label={contentLabel}
+                tabIndex={0}
+                className={cx(
+                  "flex min-w-0 flex-col",
+                  REGION,
+                  fill
+                    ? "min-h-0 flex-1 overflow-hidden"
+                    : shared
+                      ? cx("shrink-0", at.scrolls)
+                      : "min-h-0 flex-1 overflow-y-auto overscroll-contain",
+                  hasInspector && at.content,
+                  LETS_GO,
+                  contentClassName,
+                  // A surface that is a frame of its own runs to the edges.
+                  "has-[>[data-app-layout]]:p-0",
+                )}
+              >
+                {children}
+              </div>
+              {hasInspector ? (
+                <div
+                  data-layout-inspector
+                  role="region"
+                  aria-label={inspectorLabel}
+                  tabIndex={0}
+                  className={cx(
+                    "min-w-0 shrink-0 border-t border-border print:hidden",
+                    REGION,
+                    fill && "max-h-[45%] overflow-y-auto overscroll-contain",
+                    at.inspector,
+                  )}
+                >
+                  {inspector}
+                </div>
+              ) : null}
+            </div>
+            {footer != null && footer !== false ? (
+              <div data-layout-footer className={cx("shrink-0 border-t border-border print:hidden", hasInspector && at.footer)}>
+                {footer}
+              </div>
+            ) : null}
+          </div>
+        </div>
+      </div>
+    </Nested.Provider>
+  );
+}
+
+// DocumentLayout — a page that flows: a report, an invoice, an article
+// meant for print or export. It owns no height and scrolls nothing; it
+// sits in the AppLayout's content (contentMode scroll), which scrolls it,
+// and in print the frame lets go and it flows onto pages.
+//
+//   children   the document
+//   toolbar    a bar held at the top while the document scrolls under it
+//              (Print, Export, the zoom); never printed
+//   width      prose (the default: a measure for reading) · page (A4,
+//              210mm) · letter (8.5in) · full. In print it is the paper's
+//   paper      true: drawn as a sheet on the desk on screen (bg-card, a
+//              hairline, padding); plain in print
+//   align      start (the default) · center
+//   label      the document's name for a screen reader ("Document")
+//   className  the document's own spacing and tokens; never a height
+const WIDTHS = {
+  prose: "max-w-prose",
+  page: "max-w-[210mm]",
+  letter: "max-w-[8.5in]",
+  full: "max-w-none",
+};
+
+export function DocumentLayout({ children, toolbar, width = "prose", paper = false, align = "start", label = "Document", className }) {
+  return (
+    <div data-document-layout className="flex min-w-0 flex-col">
+      {toolbar != null && toolbar !== false ? (
+        <div data-document-toolbar className="sticky top-0 z-10 border-b border-border bg-background print:hidden">
+          {toolbar}
+        </div>
+      ) : null}
+      <article
+        aria-label={label}
+        className={cx(
+          "w-full min-w-0 print:max-w-none",
+          WIDTHS[width] ?? WIDTHS.prose,
+          align === "center" && "mx-auto",
+          paper && "my-6 rounded-lg border border-border bg-card p-8 text-card-foreground shadow-sm print:my-0 print:rounded-none print:border-0 print:p-0 print:shadow-none",
+          className,
+        )}
+      >
+        {children}
+      </article>
+    </div>
+  );
+}

package/templates/next/files/components/ui/notice.jsx

@@ -2,7 +2,7 @@ import { cx } from "./cx";
 import { IconButton } from "./button";
 import { Icon } from "./icon";
 
-// Static parts: a card, a notice, a badge, a kicker, the empty state.
+// Plain parts: a card, a notice, a badge, a kicker, the empty state.
 // Server-safe (no hooks), so a server surface can use them directly.
 
 const TONES = {

package/templates/next/files/components/ui/separator.jsx

@@ -1,6 +1,6 @@
 import { cx } from "./cx";
 
-// Small static parts that shape a layout: a separator, a key cap, a box
+// Small plain parts that shape a layout: a separator, a key cap, a box
 // that keeps its ratio. Server-safe (no hooks).
 
 /**

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

@@ -2,13 +2,22 @@
 
 import { headers } from "next/headers";
 import { revalidatePath } from "next/cache";
-import { ident, logActivity, query } from "./db";
+import { ident, logActivity, query, requestMember, transaction } from "./db";
 
 // Every write the app makes. Callable from server and client components
 // alike (they are server actions). Each one goes through lib/db.js,
 // records an activity row, and re-renders the app. Table and column names
 // are quoted through ident(), which refuses anything that is not a plain
-// identifier. Returns { ok } or { ok: false, error }; never throws.
+// identifier. Returns { ok } or { ok: false, error, code }; never throws.
+// `code` is the one the platform's data door answers a browser app with
+// (lib/door.js), so a surface branches on it the same way in both modes.
+//
+// Each write runs in its own transaction that first tells the database
+// who is asking (transaction() in lib/db.js: claw.member_id and
+// claw.member_email, local to it), so a trigger or an action function
+// reads the member here as it does in a browser app, behind the platform's
+// door. The activity line is written after the COMMIT, never inside it:
+// a line that fails must not undo the write it describes.
 //
 // `surface` is optional: proxy.js stamps the current surface key on
 // the request, so a surface rarely needs to pass it.
@@ -20,13 +29,12 @@ import { ident, logActivity, query } from "./db";
 // words. Pass a detail when the surface can say what changed in plain
 // words; leave it out and the tab shows the action word alone.
 
+/** The line's `by`, as the door writes it: the member's email, else
+ *  their id, else unknown (a local run). */
 async function actor() {
-  try {
-    const email = (await headers()).get("x-claw-user-email");
-    return email ? `user:${email}` : "user:unknown";
-  } catch {
-    return "user:unknown";
-  }
+  const { id, email } = await requestMember();
+  if (email) return `user:${email}`;
+  return id ? `user:${id}` : "user:unknown";
 }
 
 async function surfaceOf(explicit) {
@@ -97,36 +105,88 @@ async function setClause(source, cols) {
   return cols.map((c, i) => `${ident(c)} = $${i + 2}`).join(", ") + (await stampFor(source, cols));
 }
 
-function fail(error) {
+// Postgres's raise_exception: what a plpgsql `raise exception` says.
+const REFUSED = "P0001";
+
+// The data door's codes for Postgres's errors (claw's STATIC-SPEC §1,
+// "Errors reach the Builder"). Up to 0.6.x a failure here had no code, so
+// a surface that branched on the door's `code` in a browser app fell
+// through to its generic path after `makersclaw mode server`.
+const CODES = new Map([
+  [REFUSED, "action_refused"],
+  ["23505", "conflict"], // unique
+  ["23503", "conflict"], // foreign key
+  ["23502", "bad_request"], // not null
+  ["22P02", "bad_request"], // not a value of the column's type
+  ["22007", "bad_request"], // not a date or time
+  ["22008", "bad_request"], // a date or time out of range
+  ["57014", "too_slow"],
+  ["40001", "try_again"], // serialization
+  ["40P01", "try_again"], // deadlock
+  ["55P03", "try_again"], // lock not available
+]);
+const SQLSTATE = /^[0-9A-Z]{5}$/;
+
+/** A failure's code, as the door gives it. `missing` names the one error
+ *  that means the statement's own table or function is not there: 42P01
+ *  no_such_table for a table's write, 42883 no_such_action for an
+ *  action. Postgres raises it with no `where` (the context an error from
+ *  inside a function or a trigger carries); from inside, it is the
+ *  code's fault, bad_request, as the rest of class 42. ident()'s refusal
+ *  is bad_request; a connection that failed is failed. */
+function codeOf(error, missing) {
+  const state = typeof error?.code === "string" && SQLSTATE.test(error.code) ? error.code : "";
+  if (!state) return /^invalid identifier: /.test(error?.message ?? "") ? "bad_request" : "failed";
+  if (missing?.[state] && !error.where) return missing[state];
+  if (CODES.has(state)) return CODES.get(state);
+  return state.startsWith("42") ? "bad_request" : "failed";
+}
+
+function fail(error, missing) {
   const message = error?.message ?? String(error);
-  console.error(`[actions] write failed: ${message}`);
-  return { ok: false, error: message };
+  const code = codeOf(error, missing);
+  // A trigger's own raise exception is a deliberate no, as an action's is
+  // (runAction): a warning, or the log tail sends the platform agent after it.
+  if (code === "action_refused") console.warn(`[actions] refused: ${message}`);
+  else console.error(`[actions] write failed: ${message}`);
+  return { ok: false, error: message, code };
 }
 
+/** A write refused here, with the door's code for it. */
+const refused = (error, code) => ({ ok: false, error, code });
+
+/** What the door reads a table's write failing with, when the table is not there. */
+const NO_TABLE = { "42P01": "no_such_table" };
+
 /** Change columns of one row. `patch` is { column: value }; updated_at
- *  becomes now() when the table has one (above). */
-export async function updateRow({ source, idColumn = "id", id, patch, surface, action = "edited", detail, data }) {
+ *  becomes now() when the table has one (above). `log: false` writes no
+ *  activity line: for a save that is typing, not a decision (an autosave
+ *  every few keystrokes would flood the Activity tab). */
+export async function updateRow({ source, idColumn = "id", id, patch, surface, action = "edited", detail, data, log }) {
   try {
+    const table = ident(source);
+    const key = ident(idColumn);
     const cols = Object.keys(patch ?? {}).filter((c) => patch[c] !== undefined);
-    if (!cols.length) return { ok: false, error: "nothing to change" };
+    if (!cols.length) return refused("nothing to change", "bad_request");
     const sets = await setClause(source, cols);
-    const { rowCount } = await query(
-      `UPDATE ${ident(source)} SET ${sets} WHERE ${ident(idColumn)} = $1`,
-      [id, ...cols.map((c) => patch[c])],
+    const { rowCount } = await transaction((q) =>
+      q(`UPDATE ${table} SET ${sets} WHERE ${key} = $1`, [id, ...cols.map((c) => patch[c])]),
     );
-    if (!rowCount) return { ok: false, error: "row not found" };
-    await logActivity({
-      action,
-      surface: await surfaceOf(surface),
-      row_ref: id,
-      detail: detail ?? `${cols.join(", ")} changed`,
-      data: data ?? patch,
-      by: await actor(),
-    });
+    if (!rowCount) return refused("row not found", "not_found");
+    if (log !== false) {
+      await logActivity({
+        action,
+        surface: await surfaceOf(surface),
+        row_ref: id,
+        detail: detail ?? `${cols.join(", ")} changed`,
+        data: data ?? patch,
+        by: await actor(),
+      });
+    }
     done();
     return { ok: true };
   } catch (error) {
-    return fail(error);
+    return fail(error, NO_TABLE);
   }
 }
 
@@ -148,12 +208,10 @@ export async function moveRow({ source, idColumn = "id", id, stateColumn, to, su
 export async function insertRow({ source, idColumn = "id", values, surface, action = "added", detail }) {
   try {
     const cols = Object.keys(values ?? {}).filter((c) => values[c] !== undefined);
-    if (!cols.length) return { ok: false, error: "nothing to add" };
+    if (!cols.length) return refused("nothing to add", "bad_request");
     const placeholders = cols.map((_, i) => `$${i + 1}`).join(", ");
-    const { rows } = await query(
-      `INSERT INTO ${ident(source)} (${cols.map(ident).join(", ")}) VALUES (${placeholders}) RETURNING ${ident(idColumn)}`,
-      cols.map((c) => values[c]),
-    );
+    const text = `INSERT INTO ${ident(source)} (${cols.map(ident).join(", ")}) VALUES (${placeholders}) RETURNING ${ident(idColumn)}`;
+    const { rows } = await transaction((q) => q(text, cols.map((c) => values[c])));
     const id = rows[0]?.[idColumn];
     await logActivity({
       action,
@@ -166,14 +224,15 @@ export async function insertRow({ source, idColumn = "id", values, surface, acti
     done();
     return { ok: true, id };
   } catch (error) {
-    return fail(error);
+    return fail(error, NO_TABLE);
   }
 }
 
 export async function deleteRow({ source, idColumn = "id", id, surface, detail }) {
   try {
-    const { rowCount } = await query(`DELETE FROM ${ident(source)} WHERE ${ident(idColumn)} = $1`, [id]);
-    if (!rowCount) return { ok: false, error: "row not found" };
+    const text = `DELETE FROM ${ident(source)} WHERE ${ident(idColumn)} = $1`;
+    const { rowCount } = await transaction((q) => q(text, [id]));
+    if (!rowCount) return refused("row not found", "not_found");
     await logActivity({
       action: "removed",
       surface: await surfaceOf(surface),
@@ -184,7 +243,7 @@ export async function deleteRow({ source, idColumn = "id", id, surface, detail }
     done();
     return { ok: true };
   } catch (error) {
-    return fail(error);
+    return fail(error, NO_TABLE);
   }
 }
 
@@ -195,7 +254,8 @@ export async function deleteRow({ source, idColumn = "id", id, surface, detail }
  * has a plain `key text` column and Postgres rejects ON CONFLICT without a
  * unique index on it. JSON mode sets the key inside the jsonb `column` of
  * the row `id` in `source`. An update stamps updated_at as updateRow's
- * does; the insert leaves it to the column's default.
+ * does; the insert leaves it to the column's default. The UPDATE and the
+ * INSERT run in one transaction (up to 0.6.x they were two).
  */
 export async function saveSetting({
   mode = "table",
@@ -210,24 +270,21 @@ export async function saveSetting({
   surface,
 }) {
   try {
-    if (!key) return { ok: false, error: "no key" };
+    if (!key) return refused("no key", "bad_request");
     if (mode === "json") {
+      const col = ident(column);
       const stamp = await stampFor(source, [column]);
-      const { rowCount } = await query(
-        `UPDATE ${ident(source)} SET ${ident(column)} = jsonb_set(COALESCE(${ident(column)}, '{}'::jsonb), $2::text[], $3::jsonb, true)${stamp} WHERE ${ident(idColumn)} = $1`,
-        [id, [key], JSON.stringify(value ?? null)],
-      );
-      if (!rowCount) return { ok: false, error: "row not found" };
+      const text = `UPDATE ${ident(source)} SET ${col} = jsonb_set(COALESCE(${col}, '{}'::jsonb), $2::text[], $3::jsonb, true)${stamp} WHERE ${ident(idColumn)} = $1`;
+      const { rowCount } = await transaction((q) => q(text, [id, [key], JSON.stringify(value ?? null)]));
+      if (!rowCount) return refused("row not found", "not_found");
     } else {
       const stored = typeof value === "object" && value !== null ? JSON.stringify(value) : value;
+      const [table, keyCol, valueCol] = [ident(source), ident(keyColumn), ident(valueColumn)];
       const stamp = await stampFor(source, [valueColumn]);
-      const { rowCount } = await query(
-        `UPDATE ${ident(source)} SET ${ident(valueColumn)} = $2${stamp} WHERE ${ident(keyColumn)} = $1`,
-        [key, stored],
-      );
-      if (!rowCount) {
-        await query(`INSERT INTO ${ident(source)} (${ident(keyColumn)}, ${ident(valueColumn)}) VALUES ($1, $2)`, [key, stored]);
-      }
+      await transaction(async (q) => {
+        const { rowCount } = await q(`UPDATE ${table} SET ${valueCol} = $2${stamp} WHERE ${keyCol} = $1`, [key, stored]);
+        if (!rowCount) await q(`INSERT INTO ${table} (${keyCol}, ${valueCol}) VALUES ($1, $2)`, [key, stored]);
+      });
     }
     await logActivity({
       action: "edited",
@@ -240,6 +297,68 @@ export async function saveSetting({
     done();
     return { ok: true };
   } catch (error) {
-    return fail(error);
+    return fail(error, NO_TABLE);
+  }
+}
+
+// An action's name as the door takes it: one bare, lower-case name. The
+// door calls only a function of the app's own schema, so a name with a
+// schema (`app_x.fn`) or capitals (`CloseCycle`), which ident() quotes
+// and Postgres would find, worked here and is no_such_action there.
+// Refused here too, so a surface that works in one mode works in the
+// other.
+const ACTION_NAME = /^[a-z_][a-z0-9_]{0,62}$/;
+
+/**
+ * Run an action: a function in the app's own schema, `(args jsonb)
+ * returns jsonb`, for any write of more than one row, or one that decides
+ * something. The screen calls it here; the app's agent runs the same
+ * function with `sql` (`select close_cycle($1::jsonb)`), so the two never
+ * drift. It runs inside transaction(), after the member is set, so it
+ * reads who is asking from `current_setting('claw.member_email', true)`.
+ * It says no with `raise exception '<sentence>'`: the sentence comes back
+ * as `error`, code action_refused, and the log says it was refused, not
+ * that the app failed. A name that is not one bare lower-case name, or no
+ * function of it that takes jsonb, is no_such_action, as at the door.
+ *
+ * The activity line is this call's: `action` defaults to the function's
+ * name, `row_ref` is `rowRef` or the result's `id`. The function never
+ * writes claw_app.activity itself. `log: false` writes no line (an
+ * autosave). `args` defaults to {}.
+ *   → { ok: true, result } | { ok: false, error, code }
+ */
+export async function runAction({ name, args, surface, action, detail, rowRef, log } = {}) {
+  if (typeof name !== "string" || !ACTION_NAME.test(name)) {
+    const error = `no action ${JSON.stringify(name ?? null)}: an action is named in lower case, a-z, 0-9 and _, with no schema (close_cycle)`;
+    console.error(`[actions] ${error}`);
+    return refused(error, "no_such_action");
+  }
+  try {
+    const text = `SELECT ${ident(name)}($1::jsonb) AS result`;
+    const json = JSON.stringify(args === undefined ? {} : args);
+    const { rows } = await transaction((q) => q(text, [json]));
+    const result = rows[0]?.result ?? null;
+    if (log !== false) {
+      const returned = result && typeof result === "object" && !Array.isArray(result) ? result.id : undefined;
+      await logActivity({
+        action: action || name,
+        surface: await surfaceOf(surface),
+        row_ref: rowRef ?? returned ?? null,
+        detail: detail ?? null,
+        by: await actor(),
+      });
+    }
+    done();
+    return { ok: true, result };
+  } catch (error) {
+    // P0001 is the function's own raise exception: a deliberate no ("that
+    // cycle is already closed"), which the member acts on. Logged as an
+    // error, the log tail would send the platform agent chasing it as a
+    // bug, which the door avoids by not recording it either.
+    if (error?.code === REFUSED) {
+      console.warn(`[actions] ${name} refused: ${error.message}`);
+      return refused(error.message, "action_refused");
+    }
+    return fail(error, { "42883": "no_such_action" });
   }
 }