rowstile 0.1.0-alpha.4 → 0.1.0-alpha.6

package/README.md

@@ -1,7 +1,8 @@
 # rowstile
 
-Access rules for Postgres: a policy language that the `rowstile` command compiles into row-level security, and
-ships as migrations for your app's tool (Prisma, Drizzle Kit, Alembic, SQL files).
+Authorization for Postgres apps: access rules in a policy language that the `rowstile` command compiles into
+row-level security, and ships as migrations for your app's tool (Prisma, Drizzle Kit, Alembic, SQL files).
+Sharing, groups, nested folders and tenants, with no service to run beside the database.
 
     npx rowstile init        # a first policy from your tables, rowstile.toml, the SDK for your stack
     npx rowstile dev         # on each save: check, apply to the development database, test, write the types

package/bin/rowstile.js

@@ -64,7 +64,35 @@ function onPath() {
   return null;
 }
 
-const python = process.env.ROWSTILE_PYTHON || process.env.ROWFENCE_PYTHON || bundled() || onPath();   // ROWFENCE_PYTHON: the name before the rename
+/** On Windows, a file of the bundled Python whose path is longer than Windows loads (259 characters, unless long
+ *  paths are turned on): Python then stops with "DLL load failed ... The filename or extension is too long",
+ *  from inside node_modules. Null when every file is within the limit.
+ *  @param {string} exe @returns {string | null} */
+function tooLong(exe) {
+  if (process.platform !== "win32") return null;
+  try {
+    const dlls = path.join(path.dirname(fs.realpathSync.native(exe)), "DLLs");
+    const longest = fs.readdirSync(dlls).map((f) => path.join(dlls, f)).sort((a, b) => b.length - a.length)[0];
+    if (!longest || longest.length <= 259) return null;
+    // with long paths turned on, or when only files the command never loads are past the limit, it runs all
+    // the same: ask it for the compiled modules the command uses
+    const probe = "import unicodedata, ssl, hashlib, socket, select, zlib, decimal";
+    return spawnSync(exe, ["-E", "-s", "-c", probe]).status === 0 ? null : longest;
+  } catch {
+    return null;
+  }
+}
+
+const own = process.env.ROWSTILE_PYTHON || process.env.ROWFENCE_PYTHON ? null : bundled();   // ROWFENCE_PYTHON: the name before the rename
+const long = own && tooLong(own);
+if (long && !onPath()) {
+  console.error(`rowstile: this project's path is too long for Windows to load the Python that came with the package ` +
+    `(${long.length} characters to ${path.basename(long)}; Windows loads up to 259). Move the project to a shorter path, ` +
+    "or turn long paths on in Windows (LongPathsEnabled), or install Python 3.11 or later: rowstile then runs on that one");
+  process.exit(1);
+}
+// a Python on PATH, when the bundled one can't be loaded from here
+const python = process.env.ROWSTILE_PYTHON || process.env.ROWFENCE_PYTHON || (long ? null : own) || onPath();
 if (!python) {
   console.error(`rowstile: no Python to run on. The package for this platform (@rowstile/cli-${key}) isn't installed` +
     (PLATFORMS.includes(key) ? " (optional dependencies turned off?)" : `, and there is none for ${key}`) +

package/command/authzlib/__init__.py

@@ -12,7 +12,7 @@ class Compiler(TestMixin, DevMixin, OutputMixin):
 
 
 # set with packaging/version.py (the packages copy it); authz.policy_versions records it on each apply
-__version__ = "0.1.0-alpha.4"
+__version__ = "0.1.0-alpha.6"
 
 
 def _build() -> str:

package/command/authzlib/coverage.py

@@ -92,14 +92,15 @@ def describe(r: Report, limit: int | None = None) -> str:
     more = len(r["missing"]) - len(shown)
     return (
         head
-        + "; no test reaches:\n"
+        + '; no "can" check reaches:\n'
         + "\n".join(f"  {line}: {name}: {item}" for line, name, item in shown)
         + (f"\n  ... and {more} more" if more > 0 else "")
     )
 
 
 def summary(r: Report, limit: int = 2) -> str:
-    """For rowstile dev's line: '2 branches no test reaches (line 18: org.admin, line 40: {not locked})'."""
+    """For rowstile dev's line: '2 branches no "can" check reaches (line 18: org.admin, line 40: {not locked})'.
+    It names the checks that count: a statement run `as` someone passes and covers nothing."""
     if not r["missing"]:
         return ""
     short: Callable[[str], str] = lambda item: (
@@ -107,4 +108,4 @@ def summary(r: Report, limit: int = 2) -> str:
     )
     shown = ", ".join(f"{line}: {short(item)}" for line, _, item in r["missing"][:limit])
     n = len(r["missing"])
-    return f"{n} branch{'es' if n != 1 else ''} no test reaches ({shown}{', ...' if n > limit else ''})"
+    return f'{n} branch{"es" if n != 1 else ""} no "can" check reaches ({shown}{", ..." if n > limit else ""})'

package/command/authzlib/database.py

@@ -171,7 +171,8 @@ def may_take(db: Db, role: str | None) -> None:
             f"{me} may not switch to the app role {role} (SET ROLE), and this looks at the data as the app "
             f"does [AZ618]",
             "42501",
-            hint=f"once, as {me}: GRANT {q(role)} TO {q(me)}",
+            hint=f"once, as {me} if it made {role}, else as the role that did or a superuser: "
+            f"GRANT {q(role)} TO {q(me)}",
         )
 
 

package/command/authzlib/devtools.py

@@ -181,6 +181,13 @@ const s = (id: Id): string => Array.isArray(id)
   ? "(" + id.map((v) => '"' + String(v).replace(/["\\\\]/g, (c) => "\\\\" + c) + '"').join(",") + ")"
   : String(id);
 
+/** A key as the database writes it, for a message: 7, or (1,2) for a key of several columns. */
+const shown = (id: Id): string => Array.isArray(id)
+  ? "(" + id.map((v) => /^$|[",\\\\()\\s]/.test(String(v)) ? '"' + String(v).replace(/\\\\/g, "\\\\\\\\").replace(/"/g, '""') + '"' : String(v)).join(",") + ")"
+  : String(id);
+// who is signed in, in the words the database's own refusals use
+const WHO = "SELECT coalesce((SELECT p.principal_type || ' ' || p.principal_id FROM authz.principal() p), 'someone not signed in') AS who";
+
 /** The database refused a write (SQLSTATE 42501): its message, the table and command, and why (lines). */
 export class Refused extends Error {{
   constructor(message: string, public table?: string, public command?: string, public why: string[] = []) {{ super(message); }}
@@ -307,8 +314,9 @@ export function authz(db: Queryable) {{
         [table, command, s(id), row === undefined ? null : JSON.stringify(row)])).rows[0].e;
       // nothing there for this user, or the rule allows it (its first line says yes) and the statement matched
       // nothing for another reason, such as a WHERE with more than the key
-      if (why === null || /^\\s*yes\\b/.test(why[0] ?? "")) throw new NotFound(table, s(id));
-      throw new Refused(`permission denied: may not ${{command}} ${{table}} ${{s(id)}}`, table, command, why);
+      if (why === null || /^\\s*yes\\b/.test(why[0] ?? "")) throw new NotFound(table, shown(id));
+      const who: string = (await db.query(WHO)).rows[0].who;
+      throw new Refused(`permission denied: ${{who}} may not ${{command}} row ${{shown(id)}} of ${{table}}`, table, command, why);
     }},
     /** Which of these people (or principals of another type) hold perm: one call, for live updates. Signs each one
      *  in, so it needs what signing in needs (SET on authz.user_id). */
@@ -419,6 +427,24 @@ def _id(x: Id) -> str:
     return str(x)
 
 
+def _shown(x: Id) -> str:
+    """A key as the database writes it, for a message: 7, or (1,2) for a key of several columns."""
+    if not isinstance(x, (tuple, list)):
+        return str(x)
+
+    def field(v: object) -> str:
+        s = str(v)
+        if s == "" or any(ch in s for ch in '",\\\\()') or any(ch.isspace() for ch in s):
+            return '"' + s.replace("\\\\", "\\\\\\\\").replace('"', '""') + '"'
+        return s
+
+    return "(" + ",".join(field(v) for v in x) + ")"
+
+
+# who is signed in, in the words the database's own refusals use
+_WHO = "SELECT coalesce((SELECT p.principal_type || ' ' || p.principal_id FROM authz.principal() p), 'someone not signed in')"
+
+
 class Refused(Exception):
     """The database refused a write (SQLSTATE 42501): its message, the table and command, and why (lines)."""
 
@@ -619,8 +645,9 @@ class Authz:
             return result
         why = self.explain_rule(table, command, id_, row)
         if why is None or (why and why[0].lstrip().startswith("yes")):
-            raise NotFound(table, _id(id_))
-        raise Refused(f"permission denied: may not {{command}} {{table}} {{_id(id_)}}", table, command, why)
+            raise NotFound(table, _shown(id_))
+        who = self._one(_WHO, ())
+        raise Refused(f"permission denied: {{who}} may not {{command}} row {{_shown(id_)}} of {{table}}", table, command, why)
 
     @staticmethod
     def refusal(error: BaseException) -> Refused | None:

package/command/authzlib/draft.py

@@ -493,13 +493,17 @@ def draft(
                 "  -- no insert or delete rule: accounts are made and removed outside the app role",
             ]
         else:
-            mine = [
-                f"{{{in_sql(src)} = authz.uid()}}"
-                for rel, target, src, k in rels[n]
-                if k == "user" and not src.startswith("[")
-            ][:1]
+            # in the maker's own name: the relation, where one says it (the language page: write the relation
+            # rather than its column again)
+            mine = [rel for rel, _, src, k in rels[n] if k == "user" and not src.startswith("[")][:1]
             where = [f"{parents[0]}.edit"] if parents else []
-            insert = " and ".join(where + mine) or "signed_in"
+            # a tree of the type itself: "inside one you edit" alone lets nobody make the first row, so a row
+            # with nothing above it may be made too, in the maker's name
+            above = next((src for rel, _, src, _ in rels[n] if parents and rel == parents[0]), "")
+            if mine and parents and parent_of[n][parents[0]] == n and not above.startswith("["):
+                insert = f"{mine[0]} and ({parents[0]}.edit or {{{in_sql(above)} is null}})"
+            else:
+                insert = " and ".join(where + mine) or "signed_in"
             r += [
                 f"  insert : {insert}" + ("   -- decide: who may add one" if insert == "signed_in" or parents else ""),
                 "  update : edit",

package/command/authzlib/errors.py

@@ -141,8 +141,9 @@ CODES = {
     "AZ110": Code(
         "A dollar-quote tag in a condition",
         "The SQL in `{...}` goes into generated functions, whose bodies are quoted with tags such as `$f$`. The "
-        "same tag in a condition would end the body there. Write the text another way: `'$' || 'f$'` (`$$` is "
-        "fine).",
+        "same tag in a condition would end the body there. Write the text another way: `'$' || 'f$'`. A bare "
+        "`$$` is fine; a tag with a name between the dollars (`$changed$`, as in `$$changed$$`) is not: quote "
+        "such text with apostrophes.",
         "type folder = app.folders\n  owner : user = owner_id\n  can view = owner and {name <> '$f$'}\n",
         "type folder = app.folders\n  owner : user = owner_id\n  can view = owner and {name <> '$' || 'f$'}\n",
     ),
@@ -415,6 +416,18 @@ CODES = {
         "test \"teams\"\n  given t = {INSERT INTO app.teams (name) VALUES ('a') RETURNING id}\n  anyone cannot see team $t\n",
         when="tests",
     ),
+    "AZ503": Code(
+        "A test names a scope the policy doesn't have",
+        "`with scope` checks a line as a key or a token limited to those scopes would be. The scopes are the "
+        "policy's `scope` lines, and `read`, which is built in.",
+        "type folder = app.folders\n  owner : user = owner_id\n  can view = owner\nscope files = folder.view\n"
+        "test \"keys\"\n  given f = {INSERT INTO app.folders (owner_id, name) VALUES (1, 'a') RETURNING id}\n"
+        "  user 1 with scope file can view folder $f\n",
+        "type folder = app.folders\n  owner : user = owner_id\n  can view = owner\nscope files = folder.view\n"
+        "test \"keys\"\n  given f = {INSERT INTO app.folders (owner_id, name) VALUES (1, 'a') RETURNING id}\n"
+        "  user 1 with scope files can view folder $f\n",
+        when="tests",
+    ),
     "AZ601": Code(
         "A table or column that isn't there",
         "Applying checks the policy against the database first: each table a type or relation names, and each "
@@ -476,7 +489,9 @@ CODES = {
         "`authz.policy_versions`. This database is somewhere else: a migration was skipped, or the database was "
         "changed with `rowstile push` or `apply` since. Apply the migrations in order; a database changed by "
         "`push` takes the migrations from the start, or `rowstile apply` of the policy the previous migration "
-        "left.",
+        "left. A development database that `rowstile dev` or `push` brought to the newest policy already holds "
+        "what this migration brings: tell the migration tool it is applied (Prisma: `prisma migrate resolve "
+        "--applied <name>`; Alembic: `alembic stamp head`), or make the database again from the migrations.",
         "",
         "",
         when="deploy",
@@ -598,7 +613,8 @@ CODES = {
         "back. The role the command connects as has to hold the app role for that. A superuser always does. Since "
         "PostgreSQL 16 a role that makes another (`CREATE ROLE app_user`) only administers it, so an owner that "
         "isn't a superuser, as on managed Postgres, gives itself the role once: `GRANT app_user TO app_owner`. It "
-        "may, because it made the role. Nothing changes for the app, which connects as the app role itself.",
+        "may, because it made the role. Where another role made both (a superuser setting up by hand), that "
+        "role runs the grant. Nothing changes for the app, which connects as the app role itself.",
         "",
         "",
         when="command",
@@ -739,7 +755,8 @@ def page(code: str) -> str:
         "apply": "when the policy is applied (`rowstile push`, `apply`, a migration), against the database",
         "deploy": "when a policy migration runs",
         "command": "by the command, against a database",
-        "runtime": "to the app, by the `authz.*` functions and the policy's rules: the code is in the error's HINT (`rowstile help AZ709`), and the SDKs' errors carry it as `code`",
+        "runtime": "to the app, by the `authz.*` functions and the policy's rules: the code is in the error's HINT "
+        f"(`rowstile help {code}`), and the SDKs' errors carry it as `code`",
     }[c.when]
     out += [f"Reported {found}.", ""]
     if c.wrong:

package/command/authzlib/fmt.py

@@ -308,9 +308,12 @@ def tests_of(text: str, files: dict[str, str]) -> list[object]:
 
     pol = parse_policy(text, None, files=files)
     return [
-        *[(t.ptype, t.who, t.expect, t.perm, t.type, t.obj) for t in pol.tests],
+        *[(t.ptype, t.who, t.expect, t.perm, t.type, t.obj, t.scopes) for t in pol.tests],
         *[
-            (sc.name, [(st.kind, st.var, st.sql, st.who, st.expect, st.perm, st.type, st.obj) for st in sc.steps])
+            (
+                sc.name,
+                [(st.kind, st.var, st.sql, st.who, st.expect, st.perm, st.type, st.obj, st.scopes) for st in sc.steps],
+            )
             for sc in pol.scenarios
         ],
     ]

package/command/authzlib/grant.py

@@ -13,6 +13,7 @@ from collections.abc import Callable, Sequence
 from dataclasses import dataclass, field
 from typing import TYPE_CHECKING
 
+from .conditions import Bool, Cmp, Col, Const, In, IsNull, Node, Scalar, simple
 from .connection import Db, Value, flag, number, text
 from .parse import Expr, Loc, Ref, Relation, Source, Type
 from .sqlutil import lit, q, qt
@@ -26,6 +27,49 @@ TRIES = 40  # how many candidate changes (or combinations) it tries
 SHOWN = 5
 
 
+def settles(where: str) -> dict[str, Scalar] | None:
+    """The columns' values that make a relation's `where` true, when it says no more than that
+    ({role = 'admin'}, {active and kind in ('a', 'b')}); None for any other condition."""
+    node = simple(where)
+    out: dict[str, Scalar] = {}
+
+    def walk(n: Node) -> bool:
+        match n:
+            case Col(name=c):
+                out[c] = True
+            case Bool(op="not", items=(Col(name=c),)):
+                out[c] = False
+            case (
+                Cmp(op="=", left=Col(name=c), right=Const(value=v))
+                | Cmp(op="=", left=Const(value=v), right=Col(name=c))
+            ):
+                if v is None:
+                    return False
+                out[c] = v
+            case IsNull(item=Col(name=c), negated=False):
+                out[c] = None
+            case In(item=Col(name=c), values=values, negated=False):
+                if values[0] is None:
+                    return False
+                out[c] = values[0]
+            case Bool(op="and", items=items):
+                return all(walk(x) for x in items)
+            case _:
+                return False
+        return True
+
+    return out if node is not None and walk(node) else None
+
+
+def constant(v: Scalar) -> str:
+    """A condition's constant as SQL."""
+    if v is None:
+        return "NULL"
+    if isinstance(v, bool):
+        return "true" if v else "false"
+    return lit(v) if isinstance(v, str) else str(v)
+
+
 @dataclass
 class Held:
     objects: int  # how many objects of the type the person holds the permission on
@@ -130,20 +174,37 @@ class Grants:
                     src.loc,
                     1,
                 )
-            if (
-                src.kind == "table"
-                and src.table
-                and isinstance(src.obj_col, str)
-                and isinstance(src.subj_col, str)
-                and not src.where
-            ):
+            if src.kind == "table" and src.table and isinstance(src.obj_col, str) and isinstance(src.subj_col, str):
                 cols, vals = [src.obj_col, src.subj_col], [lit(oid), lit(sid)]
                 if src.type_col:
                     cols.append(src.type_col)
                     vals.append(lit(st))
+                # a source with a `where`: the row must also hold what the condition asks, if it says which values
+                held = settles(src.where) if src.where else {}
+                if held is None or set(held) & set(cols):
+                    self.notes.append(
+                        f"{t.name}.{r.name} wasn't tried: it reads {src.table} where {{{src.where}}}, and it isn't "
+                        "known which values make that true"
+                    )
+                    return None
+                more = ", ".join(f"{c} = {constant(v)}" for c, v in held.items())
+                if held:
+                    # the link's row may be there already, left out by the condition: then its columns change
+                    same = " AND ".join(f"{q(c)} = {v}" for c, v in zip(cols, vals, strict=True))
+                    if self.probe(f"SELECT 1 AS x FROM {qt(src.table)} WHERE {same} LIMIT 1"):
+                        sets = ", ".join(f"{q(c)} = {constant(v)}" for c, v in held.items())
+                        return Change(
+                            "link",
+                            f"set {more} on {st} {sid}'s row of {src.table} for {t.name} {oid}",
+                            f"UPDATE {qt(src.table)} SET {sets} WHERE {same}",
+                            src.loc,
+                            2,
+                        )
+                    cols += list(held)
+                    vals += [constant(v) for v in held.values()]
                 return Change(
                     "link",
-                    f"add {st} {sid} to {src.table} for {t.name} {oid}",
+                    f"add {st} {sid} to {src.table} for {t.name} {oid}" + (f", with {more}" if held else ""),
                     f"INSERT INTO {qt(src.table)} ({', '.join(q(x) for x in cols)}) VALUES ({', '.join(vals)})",
                     src.loc,
                     2,

package/command/authzlib/hardening.py

@@ -3,7 +3,7 @@
 from __future__ import annotations
 
 from .compiler import MANY_EXPANSIONS, Core
-from .parse import Loc, cols
+from .parse import KEYWORDS, Cond, Loc, cols
 from .sqlutil import POLICY_MARKS, VIEW_MARKS, lit, q, qt
 
 DEF = "SECURITY DEFINER SET search_path = pg_catalog, pg_temp"
@@ -147,7 +147,8 @@ SELECT p.oid::regprocedure::text, gw.who, a.privilege_type,
         governed = sorted({r.table for r in self.rules})
         typed_tables = sorted({t.table for t in self.types.values()})
         link_tables: set[str] = set()  # tables that hold relationships (who is in what)
-        link_cols: list[tuple[str, str, str, Loc]] = []  # (table, column, what it grants, loc) for column sources
+        # (table, column, what it grants, loc, the permission lint suggests asking for) for column sources
+        link_cols: list[tuple[str, str, str, Loc, str]] = []
         # (table, columns, relation, loc): a column placing a row under another of its type
         move_cols: list[tuple[str, tuple[str, ...], str, Loc]] = []
         index_cols: list[tuple[str, str, str]] = []  # (table, column, why) that lookups go through
@@ -173,8 +174,10 @@ SELECT p.oid::regprocedure::text, gw.who, a.privilege_type,
                         )
                     elif src.kind == "column":
                         column = cols(self.source_columns(src))
+                        # the type's own `share` where it has one: a suggestion that doesn't compile helps no one
+                        ask = "share" if "share" in self.public_perms(t) or "share" in t.relations else "nobody"
                         for c in column + ((src.type_col,) if src.type_col else ()):
-                            link_cols.append((t.table, c, f"{t.name}.{r.name}", src.loc))
+                            link_cols.append((t.table, c, f"{t.name}.{r.name}", src.loc, ask))
                         # (one that reads the row's own key is "this row", `self : user = id`: not a move)
                         if any(st == t.name for st, _ in src.subjects) and column != tuple(c for c, _ in t.key):
                             move_cols.append((t.table, column, r.name, src.loc))
@@ -183,8 +186,13 @@ SELECT p.oid::regprocedure::text, gw.who, a.privilege_type,
         # columns that grant something, on tables whose updates only need the plain 'update' rule
         guarded = {(r.table, c) for r in self.rules if r.columns and r.command != "mask" for c in r.columns}
         has_update = {r.table for r in self.rules if r.command == "update" and not r.columns}
+        # (`update : nobody` lets no one change any column: there is nothing to guard)
+        nobody = Cond("cond", KEYWORDS["nobody"])
+        open_update = {r.table for r in self.rules if r.command == "update" and not r.columns and r.expr != nobody}
         unguarded = [
-            (tb, c, what, loc) for tb, c, what, loc in link_cols if tb in has_update and (tb, c) not in guarded
+            (tb, c, what, loc, ask)
+            for tb, c, what, loc, ask in link_cols
+            if tb in open_update and (tb, c) not in guarded
         ]
         # ...and those that move a row within its tree with nothing checking where it goes (an 'after' rule)
         after = {(r.table, c) for r in self.rules if r.command == "update check" for c in r.columns}
@@ -204,16 +212,29 @@ SELECT p.oid::regprocedure::text, gw.who, a.privilege_type,
             f"({lit(qt(tb))}, {lit(c)}, {lit('; '.join(dict.fromkeys(w)))})" for (tb, c), w in whys.items()
         )
         unguarded_rows = ", ".join(
-            f"({lit(qt(tb))}, {lit(c)}, {lit(what)}, {lit(self.line_key(f'relation {what} {c}', loc))})"
-            for tb, c, what, loc in unguarded
+            f"({lit(qt(tb))}, {lit(c)}, {lit(what)}, {lit(self.line_key(f'relation {what} {c}', loc))}, {lit(ask)})"
+            for tb, c, what, loc, ask in unguarded
         )
-        # relations named like a type read, in a rule, like the type ("delete : user")
+        # relations named like a type that signs in read, alone in a rule, like the type ("delete : user" is
+        # the row's own user, not any user). One named like another type is only ever followed
+        # ("project.edit"), which reads as what it means: `project : project = project_id` is no one's mistake
         shadows = [
             (t.name, r.name, str(r.loc))
             for t in self.types.values()
             for r in t.relations.values()
-            if r.name in self.types and not r.synthetic
+            if self.is_principal(r.name) and not r.synthetic
         ]
+        # a rule for a command the app role may not run on the table at all: it never applies, and the
+        # statement fails with Postgres's own "permission denied for table", which reads like the policy's
+        # refusal. (`nobody` asks for no privilege; a rule on a column, or `after`, is an update's.)
+        asked = sorted(
+            {
+                (r.table, "update" if r.command == "update check" else r.command)
+                for r in self.rules
+                if r.command != "mask" and r.expr != nobody
+            }
+        )
+        rule_rows = ", ".join(f"({lit(qt(tb))}, {lit(cmd)})" for tb, cmd in asked)
         # principal types nobody can make keys for (they sign in only through a backend or JWTs)
         keyless = "".join(
             f"  severity := 'info'; object := {lit(t.name)};\n"
@@ -415,13 +436,13 @@ BEGIN
     END IF;
   END LOOP;
   -- columns that grant a relation, changed by anyone who may update the row
-  FOR r IN SELECT * FROM (VALUES {unguarded_rows or "(NULL::text, NULL::text, NULL::text, NULL::text)"}) v(tbl, col, what, loc)
+  FOR r IN SELECT * FROM (VALUES {unguarded_rows or "(NULL::text, NULL::text, NULL::text, NULL::text, NULL::text)"}) v(tbl, col, what, loc, ask)
            WHERE tbl IS NOT NULL LOOP
     IF EXISTS (SELECT 1 FROM pg_attribute a WHERE a.attrelid = to_regclass(r.tbl) AND a.attname = r.col
                AND a.attnum > 0 AND NOT a.attisdropped)
        AND has_column_privilege(v_role, r.tbl, r.col, 'UPDATE') THEN
       severity := 'warning'; object := to_regclass(r.tbl)::text || '.' || r.col;
-      problem := format('grants %s (%s), and anyone who may update the row may change it: add a rule such as "update %s : share"', r.what, {self.line_sql(None, None, "r.loc")}, r.col);
+      problem := format('grants %s (%s), and anyone who may update the row may change it: add a rule such as "update %s : %s"', r.what, {self.line_sql(None, None, "r.loc")}, r.col, r.ask);
       RETURN NEXT;
     END IF;
   END LOOP;
@@ -434,11 +455,25 @@ BEGIN
     problem := format('runs with JIT on: permission checks are many small subplans, and JIT can take longer to compile a read than to run it (a third of a second for a large one): ALTER ROLE %s SET jit = off', {lit(role)});
     RETURN NEXT;
   END IF;
-  -- relations named like a type
+  -- rules for a command the app role has no privilege for (one column's is enough for a read, an insert or
+  -- an update: the app may write some columns only)
+  FOR r IN SELECT to_regclass(v.tbl) AS tbl, v.cmd FROM (VALUES {rule_rows or "(NULL::text, NULL::text)"}) v(tbl, cmd)
+           WHERE v.tbl IS NOT NULL LOOP
+    CONTINUE WHEN r.tbl IS NULL;
+    IF r.cmd = 'delete' THEN
+      CONTINUE WHEN has_table_privilege(v_role, r.tbl, 'DELETE');
+    ELSE
+      CONTINUE WHEN has_any_column_privilege(v_role, r.tbl, r.cmd);
+    END IF;
+    severity := 'warning'; object := r.tbl::text;
+    problem := format('the policy has a rule for %s, but %s has no %s privilege on the table: the rule never applies, and the statement fails with Postgres''s own "permission denied for table". GRANT %s ON %s TO %s, or make the rule "%s : nobody"', r.cmd, {lit(role)}, upper(r.cmd), upper(r.cmd), r.tbl, {lit(role)}, r.cmd);
+    RETURN NEXT;
+  END LOOP;
+  -- relations named like a type that signs in
   FOR r IN SELECT * FROM (VALUES {shadow_rows or "(NULL::text, NULL::text, NULL::text)"}) v(type, rel, loc)
            WHERE type IS NOT NULL LOOP
     severity := 'info'; object := r.type || '.' || r.rel;
-    problem := format('is named like the type %s (%s), so in rules it reads like the type: a name that says what the relation is (author, member) reads better', r.rel, {self.line_sql(None, None, "r.loc")});
+    problem := format('is named like the type %s (%s), which signs in: alone in a rule it reads like any %s, and it is this row''s. A name that says what the relation is (author, owner) reads better', r.rel, {self.line_sql(None, None, "r.loc")}, r.rel);
     RETURN NEXT;
   END LOOP;
 {keyless}{heavy}  -- columns that move a row under another, with nothing checking where it moves to

package/command/authzlib/migrate.py

@@ -731,7 +731,9 @@ BEGIN
     RAISE EXCEPTION 'rowstile: this migration changes the policy the migration before it left (%), but the database has % [AZ607]',
       {sql_lit(old_hash)}, coalesce(v_lock, 'none')
       USING HINT = 'apply the migrations in order; a database changed with rowstile push or apply since needs the '
-                   'migrations from the start (or rowstile apply of the policy the previous migration left)';
+                   'migrations from the start (or rowstile apply of the policy the previous migration left). '
+                   'A development database that rowstile dev pushed the newest policy to already holds what '
+                   'this migration brings: mark it as applied in your migration tool (rowstile help AZ607)';
   END IF;
 END $authz_guard$;""")
     out.append(body)

package/command/authzlib/parse.py

@@ -211,6 +211,7 @@ class Step:
     perm: str | None = None
     type: str | None = None
     obj: str | None = None  # check: an id or a $name
+    scopes: tuple[str, ...] = ()  # check, as: `with scope a, b`: signed in limited to them, as a key with them is
 
 
 @dataclass
@@ -907,6 +908,8 @@ def parse_policy(
 
 
 VALUE = r"(\$[A-Za-z_][A-Za-z0-9_]*|'(?:[^']|'')*'|[^\s{}']+)"
+# after who a line is about: `with scope read` or `with scope read, files`
+WITH_SCOPE = rf"(?:\s+with\s+scope\s+({IDENT}(?:\s*,\s*{IDENT})*))?"
 
 
 def value(v: str) -> str:
@@ -914,17 +917,32 @@ def value(v: str) -> str:
     return v[1:-1].replace("''", "'") if v.startswith("'") else v
 
 
+def scopes_of(text: str | None) -> tuple[str, ...]:
+    return tuple(x.strip() for x in text.split(",")) if text else ()
+
+
 def parse_step(s: str, loc: Loc) -> Step:
     m = re.fullmatch(rf"given\s+(?:({IDENT})\s*=\s*)?\{{(.*)\}}", s, re.S)
     if m:
         if not m.group(2).strip():
             fail(loc, "given {...} needs a statement", "AZ106")
         return Step("given", s, loc, var=m.group(1), sql=m.group(2).strip())
-    m = re.fullmatch(rf"as\s+(?:(anyone)|({IDENT})\s+{VALUE})\s+(allowed|refused|sees\s+(\d+))\s*\{{(.*)\}}", s, re.S)
+    m = re.fullmatch(
+        rf"as\s+(?:(anyone)|({IDENT})\s+{VALUE}{WITH_SCOPE})\s+(allowed|refused|sees\s+(\d+))\s*\{{(.*)\}}", s, re.S
+    )
     if m:
-        expect: str | int = int(m.group(5)) if m.group(5) else m.group(4)
-        if not m.group(6).strip():
+        expect: str | int = int(m.group(6)) if m.group(6) else m.group(5)
+        if not m.group(7).strip():
             fail(loc, "as ... {...} needs a statement", "AZ106")
+        # `sees N` counts the rows of a query, which a write can't be put inside: at run time that was a bare
+        # "syntax error" from Postgres
+        if isinstance(expect, int) and re.match(r"\s*(insert|update|delete|merge)\b", m.group(7), re.I):
+            fail(
+                loc,
+                "`sees N` counts the rows of a SELECT, and this statement writes: for a write that must change "
+                "no row, write `as ... refused {...}` (a write that changes no row is refused)",
+                "AZ106",
+            )
         return Step(
             "as",
             s,
@@ -932,9 +950,12 @@ def parse_step(s: str, loc: Loc) -> Step:
             ptype=m.group(1) or m.group(2),
             who=None if m.group(1) else value(m.group(3)),
             expect=expect,
-            sql=m.group(6).strip(),
+            sql=m.group(7).strip(),
+            scopes=scopes_of(m.group(4)),
         )
-    m = re.fullmatch(rf"(?:(anyone)|({IDENT})\s+{VALUE})\s+(can|cannot)\s+({IDENT})\s+({IDENT})\s+{VALUE}", s)
+    m = re.fullmatch(
+        rf"(?:(anyone)|({IDENT})\s+{VALUE}{WITH_SCOPE})\s+(can|cannot)\s+({IDENT})\s+({IDENT})\s+{VALUE}", s
+    )
     if m:
         return Step(
             "check",
@@ -942,15 +963,23 @@ def parse_step(s: str, loc: Loc) -> Step:
             loc,
             ptype=m.group(1) or m.group(2),
             who=None if m.group(1) else value(m.group(3)),
-            expect=m.group(4) == "can",
-            perm=m.group(5),
-            type=m.group(6),
-            obj=value(m.group(7)),
+            expect=m.group(5) == "can",
+            perm=m.group(6),
+            type=m.group(7),
+            obj=value(m.group(8)),
+            scopes=scopes_of(m.group(4)),
+        )
+    if re.match(r"(?:as\s+)?anyone\s+with\b", s):
+        fail(
+            loc,
+            "`anyone` is nobody signed in, and a scope limits someone who is: write `user 3 with scope read ...`",
+            "AZ106",
         )
     fail(
         loc,
         "a test's lines are: given name = {INSERT ... RETURNING id}, user $name can view file $f, "
-        "or as user $name allowed|refused|sees N {SQL}",
+        "or as user $name allowed|refused|sees N {SQL} (after who: `with scope read`, to check as a key limited "
+        "to a scope)",
         "AZ106",
     )
 

package/command/authzlib/perf.py

@@ -115,7 +115,7 @@ def table_indexes(db: Db, table: str) -> list[tuple[str, ...]]:
         "SELECT array(SELECT a.attname::text FROM unnest(i.indkey::int2[]) WITH ORDINALITY k(n, o) "
         "LEFT JOIN pg_catalog.pg_attribute a ON a.attrelid = i.indrelid AND a.attnum = k.n ORDER BY k.o) AS cols "
         "FROM pg_catalog.pg_index i WHERE i.indrelid = to_regclass($1) AND i.indpred IS NULL AND i.indisvalid",
-        [table],
+        [qt(table)],  # quoted: to_regclass folds a bare name to lower case, and "TeamMember" is then not found
     )
     out: list[tuple[str, ...]] = []
     for r in rows:
@@ -354,7 +354,7 @@ def plain_column(db: Db, c: Compiler, t: Type) -> str | None:
     rows = db.rows(
         "SELECT attname::text AS a FROM pg_catalog.pg_attribute WHERE attrelid = to_regclass($1) AND attnum > 0 "
         "AND NOT attisdropped AND attgenerated = '' ORDER BY attnum",
-        [t.table],
+        [qt(t.table)],
     )
     return next((text(r, "a") for r in rows if r["a"] not in used), None)
 

package/command/authzlib/review.py

@@ -621,15 +621,17 @@ def grants_more(b: Side, h: Side, whats: list[str], worlds: int) -> dict[str, tu
                     tname, p = what.split(".")
                     more = set(sh.get((tname, p), ())) - set(sb.get((tname, p), ()))
                 if more:
-                    who = user or "nobody signed in"
-                    found[what] = (
-                        (who if ":" in who or who.startswith("nobody") else f"user {who}").replace(":", " "),
-                        f"{tname} {sorted(more)[0]}",
-                    )
+                    found[what] = (named(user), f"{tname} {sorted(more)[0]}")
                     left.remove(what)
     return found
 
 
+def named(user: str) -> str:
+    """Who an example is about, in words: user 1, service 3, nobody signed in."""
+    who = user or "nobody signed in"
+    return (who if ":" in who or who.startswith("nobody") else f"user {who}").replace(":", " ")
+
+
 def risk(b: Side, h: Side, worlds: int) -> list[Flag]:
     flags: list[Flag] = []
 
@@ -1009,11 +1011,13 @@ def summary(r: Review) -> dict[str, str]:
         loses = [g for g in loses if g["what"].startswith("permission ")] or loses
 
         def say(gs: list[Group], verb: str) -> str:
+            # "1 user gains", "2 users gain"
+            does = lambda g: verb + ("s" if g["users"] == 1 else "")
             return "; ".join(
-                f"{plural(g['users'], 'user')} {verb} `{g['what'].replace('permission ', '')}` "
+                f"{plural(g['users'], 'user')} {does(g)} `{g['what'].replace('permission ', '')}` "
                 f"on {plural(g['objects'], g['type'])}"
                 if g["what"].startswith("permission ")
-                else f"{plural(g['users'], 'user')} {verb} {g['what']} in `{g['type']}` ({plural(g['objects'], 'row')})"
+                else f"{plural(g['users'], 'user')} {does(g)} {g['what']} in `{g['type']}` ({plural(g['objects'], 'row')})"
                 for g in gs[:3]
             ) + (f"; and {len(gs) - 3} more" if len(gs) > 3 else "")
 
@@ -1214,7 +1218,9 @@ def text(r: Review) -> str:
             out.append(f"  through  {t['what']}: uses {', '.join(t['via'])}")
         ce = m.get("counterexample")
         if ce:
-            out.append(f"  not a refactor: {ce['what']} differs for {ce['user']} on {ce['object']}")
+            # as the risks name their examples: user 1 on note 1 (a rule's object is a row of its table)
+            kind = ce["what"].split(".")[0] if re.fullmatch(r"\w+\.\w+", ce["what"]) else "row"
+            out.append(f"  not a refactor: {ce['what']} differs for {named(ce['user'])} on {kind} {ce['object']}")
         if m.get("unreadable"):
             out.append(
                 f"  can't tell: {', '.join(m.get('unreadable', []))} changed only in conditions the review "

package/command/authzlib/testing.py

@@ -83,6 +83,11 @@ class TestMixin(Core):
                         f"'{st.ptype}' doesn't sign in: a test acts as anyone or as one of {', '.join(signs_in)}",
                         "AZ502",
                     )
+                for scope in st.scopes:
+                    # 'read' is built in unless the policy says its own
+                    if scope not in self.pol.scopes and scope != "read":
+                        have = sorted({*self.pol.scopes, "read"})
+                        fail(st.loc, f"no scope '{scope}' in the policy (it has: {', '.join(have)})", "AZ503")
                 if st.kind == "check":
                     known(st.obj, st.loc, bound)
                     self.check_test_perm(st.type or "", st.perm or "", st.loc)
@@ -115,7 +120,8 @@ class TestMixin(Core):
             blocks.append(f"""  -- {sc.name}{f" ({sc.loc})" if sc.loc else ""}
   v_test := {lit(sc.name)};
   BEGIN
-    PERFORM set_config('authz.user_id', '', true), set_config('authz.principal_type', '', true);
+    PERFORM set_config('authz.user_id', '', true), set_config('authz.principal_type', '', true),
+            set_config('authz.scopes', '', true);
 {steps}    RAISE EXCEPTION USING ERRCODE = 'AZT00';     -- a test's data never stays
   EXCEPTION
     WHEN SQLSTATE 'AZT00' THEN NULL;
@@ -137,7 +143,8 @@ class TestMixin(Core):
             if others:
                 who = f"CASE {others}ELSE {who} END"
             invariants = f"""  v_test := 'invariants'; v_line := ''; v_n := 0;
-  PERFORM set_config('authz.user_id', '', true), set_config('authz.principal_type', '', true);
+  PERFORM set_config('authz.user_id', '', true), set_config('authz.principal_type', '', true),
+          set_config('authz.scopes', '', true);
   FOR v_inv IN SELECT * FROM authz.check_invariants() LOOP
     v_n := v_n + 1;
     {self.add_result("''", "false", "'invariant ' || v_inv.invariant || ': ' || " + who + " || ' can reach ' || v_inv.object_ids::text", "'invariant ' || v_inv.invariant")}
@@ -157,9 +164,11 @@ DECLARE
   v_role text := current_setting('role');
   v_me text := coalesce(current_setting('authz.user_id', true), '');
   v_pt text := coalesce(current_setting('authz.principal_type', true), '');
+  v_scopes text := coalesce(current_setting('authz.scopes', true), '');
   {" ".join(variables)}
 BEGIN
-{"".join(blocks)}{invariants}  PERFORM set_config('authz.user_id', v_me, true), set_config('authz.principal_type', v_pt, true);
+{"".join(blocks)}{invariants}  PERFORM set_config('authz.user_id', v_me, true), set_config('authz.principal_type', v_pt, true),
+          set_config('authz.scopes', v_scopes, true);
   RETURN QUERY SELECT * FROM unnest(r_test, r_line, r_ok, r_detail);
 END $authz_tests$;
 """
@@ -204,16 +213,21 @@ END $authz_tests$;
     def sign_in_sql(self, st: Step, names: dict[str, str]) -> str:
         uid = "''" if st.ptype == "anyone" else self.value_sql(st.who, names)
         pt = "''" if st.ptype in ("anyone", "user") else lit(st.ptype)
+        # the scopes a key or a token would carry (`with scope read`); none: not limited
         return (
             f"    PERFORM set_config('authz.user_id', coalesce({uid}, ''), true), "
-            f"set_config('authz.principal_type', {pt}, true);\n"
+            f"set_config('authz.principal_type', {pt}, true), "
+            f"set_config('authz.scopes', {lit(','.join(st.scopes))}, true);\n"
         )
 
     def step_sql(self, st: Step, names: dict[str, str]) -> str:
         head = f"    v_line := {lit(str(st.loc))}; v_text := {lit(st.text)};\n"
         if st.kind == "given":
             stmt = self.statement_sql(self.one_statement(st.sql) if st.var else st.sql, names)
-            reset = "    PERFORM set_config('authz.user_id', '', true), set_config('authz.principal_type', '', true);\n"
+            reset = (
+                "    PERFORM set_config('authz.user_id', '', true), set_config('authz.principal_type', '', true), "
+                "set_config('authz.scopes', '', true);\n"
+            )
             if not st.var:
                 return head + reset + f"    EXECUTE {stmt};\n"
             var = names[st.var]

package/command/cli/init.py

@@ -1,4 +1,5 @@
-"""rowstile init: a first policy drafted from the database's catalog, a test file, and rowstile.toml."""
+"""rowstile init: a first policy drafted from the database's catalog, a test file, rowstile.toml, and a note for
+the coding agents that work in the app (AGENTS.md)."""
 
 from __future__ import annotations
 
@@ -10,6 +11,8 @@ if TYPE_CHECKING:
     from rowstile_cli import Config
 
 CONFIG = "rowstile.toml"
+AGENTS = "AGENTS.md"  # the file coding agents read in a repository
+BEGIN, END = "<!-- rowstile:begin -->", "<!-- rowstile:end -->"
 
 
 def write_new(path: str, text: str, written: list[str]) -> None:
@@ -22,13 +25,60 @@ def write_new(path: str, text: str, written: list[str]) -> None:
     written.append(path)
 
 
+def agents_note(policy_path: str, tests: str, role: str) -> str:
+    """What a coding agent working in the app needs to know of rowstile (llms.txt's list, with this app's paths),
+    between two markers."""
+    return f"""{BEGIN}
+## Access rules (rowstile)
+
+Who may see or change a row is decided in Postgres, by row-level security that the `rowstile` command makes
+from a policy file. For coding agents working in this repository:
+
+- The policy is `{policy_path}`, its tests `{tests}`; `{CONFIG}` names both.
+  Everything that grants access is written in the policy: no permission checks in app code, no
+  `CREATE POLICY` by hand.
+- After editing it: `rowstile check` (the first mistake, with its line and a code such as `[AZ201]`), then
+  `rowstile push` (the development database only) and `rowstile test`. `rowstile dev` does all three on each
+  save. `rowstile help AZ201` explains a code and shows the mistake fixed.
+- Production takes migrations: `rowstile migrate` writes the next one. Never `rowstile push` there.
+- The app connects as `{role}`, never as the tables' owner, and each transaction signs in first:
+  `SELECT authz.act_as('user', '42')` (the SDKs do it). Then plain queries are filtered, a refused insert
+  raises SQLSTATE 42501 with the reason, and an UPDATE or DELETE the rules don't allow changes no row.
+- Why someone holds a permission or not: `rowstile why --as user:42 TYPE ID PERMISSION`.
+- `rowstile mcp` is an MCP server with the command's tools. The language and the rest:
+  https://rowstile.dev/llms.txt
+{END}
+"""
+
+
+def write_agents_note(note: str, folder: str = ".") -> str | None:
+    """Puts the note in the app's AGENTS.md: the file is written if there is none, the note is added at the end
+    of one that doesn't have it, and one that has it (the markers) is left as it is. Returns what was done
+    ("wrote", "added"), or None."""
+    path = os.path.join(folder, AGENTS)
+    if not os.path.exists(path):
+        with open(path, "w", encoding="utf-8", newline="\n") as fh:
+            fh.write(note)
+        return "wrote"
+    with open(path, encoding="utf-8", newline="") as fh:
+        text = fh.read()
+    if BEGIN in text:
+        return None
+    eol = "\r\n" if "\r\n" in text else "\n"
+    gap = "" if not text.strip() else eol if text.endswith(("\n", "\r")) else eol * 2
+    with open(path, "w", encoding="utf-8", newline="") as fh:
+        fh.write(text + gap + note.replace("\n", eol))
+    return "added"
+
+
 def init(policy: str, opts: dict[str, str], cfg: Config) -> None:
-    """Writes the drafted policy, a first test file and rowstile.toml, keeping any that exist."""
+    """Writes the drafted policy, a first test file, rowstile.toml and the note for coding agents, keeping any
+    that exist."""
     out = opts.get("--out", "db")
     written: list[str] = []
     policy_path = os.path.join(out, "policy.authz")
     write_new(policy_path, policy, written)
-    m = re.search(r"^role (\S+)", policy, re.M)
+    m = re.search(r"^app role (\S+)", policy, re.M)
     role = m.group(1) if m else "app_user"  # a draft always has one
     first = re.search(r"^type (?!user\b)(\w+) = (\S+)", policy, re.M)
     example = first.group(1) if first else "user"
@@ -73,6 +123,14 @@ database = "{database}"     # a DSN or URL, or env:NAME for an environment varia
         print(f"using {os.path.relpath(cfg.path)} (it is there already)")
     for path in written:
         print(f"wrote {path}")
+    tests = os.path.join(out, "tests").replace(os.sep, "/") + "/*.authz"
+    noted = write_agents_note(agents_note(policy_path.replace(os.sep, "/"), tests, role))
+    if noted == "wrote":
+        print(f"wrote {AGENTS} (for coding agents: where the policy is, and the loop)")
+    elif noted == "added":
+        print(f"added   rowstile's section to {AGENTS} (for coding agents: where the policy is, and the loop)")
+    else:
+        print(f"kept {AGENTS} (it has rowstile's section already)")
     if found.tool and CONFIG in written:
         import migrations
 
@@ -88,7 +146,7 @@ database = "{database}"     # a DSN or URL, or env:NAME for an environment varia
         added = stack.add_npm(os.getcwd(), found.npm, __version__)
         if added:
             print(f"added   {', '.join(added)} to package.json (then: npm install)")
-    if found.pip:
+    if found.pip and not found.pip_there:
         req = stack.pip_requirement(found.pip, __version__)
         print(f"add     {req} to your Python dependencies (pip install '{req}', or uv add '{req}')")
     setup = ""
@@ -100,7 +158,9 @@ database = "{database}"     # a DSN or URL, or env:NAME for an environment varia
 {lines}
      The role your app connects as ({role}) must not bypass row-level security:
        CREATE ROLE {role} LOGIN PASSWORD '...' NOSUPERUSER NOBYPASSRLS;
-       ALTER ROLE {role} SET jit = off;"""
+       ALTER ROLE {role} SET jit = off;
+     The app connects as {role}, with a URL of its own: never the one this command uses, the
+     tables' owner's, which row-level security doesn't apply to."""
     else:
         setup = f"""
   2. The role your app connects as ({role}) must not bypass row-level security:

package/command/cli/lsp.py

@@ -332,7 +332,10 @@ class Server:
         name = parts[i]
         stripped = s.strip()
         # a test line: user $x can PERM TYPE ID
-        m = re.match(r"(?:anyone|\S+\s+\S+)\s+(?:can|cannot)\s+(\w+)\s+(\w+)", stripped)
+        m = re.match(
+            r"(?:anyone|\S+\s+\S+(?:\s+with\s+scope\s+\w+(?:\s*,\s*\w+)*)?)\s+(?:can|cannot)\s+(\w+)\s+(\w+)",
+            stripped,
+        )
         if m and self.block(uri, line)[0] == "test" and name in (m.group(1), m.group(2)):
             t = pol.types.get(m.group(2))
             if name == m.group(2) and t:
@@ -556,7 +559,7 @@ class Server:
             if kind == "rules"
             else TYPE_WORDS
             if kind == "type"
-            else ["given", "as", "can", "cannot", "allowed", "refused", "sees"],
+            else ["given", "as", "can", "cannot", "allowed", "refused", "sees", "with", "scope"],
             C_KEYWORD,
         )
         return dedupe(items)

package/command/cli/migrations.py

@@ -284,9 +284,17 @@ depends_on = None
 
 
 def upgrade() -> None:
+    bind = op.get_bind()
+    if bind.dialect.driver == "asyncpg":
+        # asyncpg prepares each statement, and a prepared statement is one command: said here, in a line, rather
+        # than by the driver with the whole script in its message
+        raise RuntimeError(
+            "rowstile: Alembic is connected with asyncpg, which takes one statement at a time, and this revision "
+            "is one script. Give Alembic a sync driver (postgresql+psycopg://); the app keeps asyncpg"
+        )
     sql = Path(__file__).with_suffix(".sql").read_text(encoding="utf-8")
     # as one script, straight to the driver: the SQL has % signs and colons, which are not parameters
-    op.get_bind().exec_driver_sql(sql, execution_options={{"no_parameters": True}})
+    bind.exec_driver_sql(sql, execution_options={{"no_parameters": True}})
 
 
 def downgrade() -> None:

package/command/cli/pgwire.py

@@ -131,6 +131,7 @@ class Connection:
         self.params: dict[str, str] = {}
         self.in_error = False
         self.busy = False  # a query was sent and its answer not fully read (the connection is unusable)
+        self.tag = ""  # what the last statement of query_described did, in the server's words ("DELETE 0")
         self.on_notice: Callable[[Fields], None] | None = None  # called with each NOTICE / WARNING the server sends
         self.address: tuple[str, int] | None = None  # where connect() went, for cancel()
         self.backend: tuple[int, int] | None = None  # this session's process id and key, for cancel()
@@ -318,9 +319,12 @@ class Connection:
         rows: list[tuple[Value, ...]] = []
         cols: list[tuple[str, int]] = []
         error: PgError | None = None
+        self.tag = ""
         while True:
             kind, payload = self._read_or(error)
-            if kind == b"T":
+            if kind == b"C":
+                self.tag = payload.rstrip(b"\0").decode()
+            elif kind == b"T":
                 n = struct.unpack("!h", payload[:2])[0]
                 pos, cols = 2, []
                 for _ in range(n):
@@ -351,7 +355,7 @@ class Connection:
                 if error:
                     raise error
                 return rows, [c[0] for c in cols]
-            # 1, 2, n, C, A, S: nothing to do
+            # 1, 2, n, A, S: nothing to do
 
     def execute(self, sql: str) -> list[tuple[Value, ...]]:
         """Run a statement without parameters (BEGIN, COMMIT, ...)."""

package/command/cli/rowstile_cli.py

@@ -154,6 +154,18 @@ def read_policy(path: str) -> tuple[str, dict[str, str]]:
     return text, collect_includes(text, read)
 
 
+def cant_connect(e: BaseException, dsn: str | None) -> str:
+    """What to say when the connection failed. When nothing named a database, the defaults were tried (a local
+    socket, the system's user): the message says that, and how to name one, rather than quote a host nobody
+    gave."""
+    if dsn or any(os.environ.get(v) for v in ("PGHOST", "PGPORT", "PGDATABASE", "PGUSER", "PGSERVICE")):
+        return f"can't connect: {e}"
+    return (
+        f"can't connect: no database was named, and the default failed ({e})\n"
+        f"name it with --db DSN, `database` in {CONFIG}, or DATABASE_URL"
+    )
+
+
 def fail(msg: str | None, code: int = 1) -> NoReturn:
     print(msg, file=sys.stderr)
     sys.exit(code)
@@ -552,6 +564,11 @@ class Dev:
         for line in lines[1:]:
             print(f"       {line}")
 
+    @staticmethod
+    def left(pushed: bool) -> str:
+        """What an error in a pass leaves in the database."""
+        return "the policy is applied; its tests didn't run" if pushed else "nothing applied"
+
     def cycle(self, why: str) -> bool:
         """One pass; True if everything passed."""
         print(f"{time.strftime('%H:%M:%S')} {why}")
@@ -581,14 +598,16 @@ class Dev:
         try:
             conn = self.connect()
         except (ValueError, OSError, pgwire.PgError, pgwire.ProtocolError) as e:
-            self.say("x", f"can't connect: {e}")
+            self.say("x", cant_connect(e, self.dsn))
             self.conn = None
             return False
+        pushed = False  # an error after the push leaves the policy in force: only the tests didn't run
         try:
             self.diff(conn, text, files)
             self.notices.clear()
             started = time.monotonic()
             state = transaction(conn, lambda db: database.push(db, text, files))
+            pushed = True
             took = time.monotonic() - started
             self.say(
                 "ok",
@@ -616,11 +635,11 @@ class Dev:
             self.say("x", str(e))
             return False
         except database.Error as e:
-            self.say("x", str(e) + (f"\n{e.hint}" if e.hint else "") + "\nnothing applied")
+            self.say("x", str(e) + (f"\n{e.hint}" if e.hint else "") + "\n" + self.left(pushed))
             return False
         except pgwire.PgError as e:
             detail = e.fields.get("D")
-            self.say("x", e.message + (f"\n{detail}" if detail else "") + "\nnothing applied")
+            self.say("x", e.message + (f"\n{detail}" if detail else "") + "\n" + self.left(pushed))
             return False
         except (OSError, pgwire.ProtocolError) as e:
             self.say("x", f"lost the database: {e}")
@@ -644,7 +663,7 @@ class Dev:
             self.say("~", "access: nobody gains or loses anything")
             return
         parts = [
-            f"{users} user(s) {change.rstrip('s')} {what} on {objs} of {type_}"
+            f"{users} user(s) {change.rstrip('s')} {what} on {objs} {type_}{'' if objs == 1 else 's'}"
             for change, type_, what, users, objs in rows[:8]
         ]
         more = f"\n... and {len(rows) - 8} more (rowstile diff)" if len(rows) > 8 else ""
@@ -990,7 +1009,7 @@ def main(argv: list[str]) -> None:
     try:
         conn = pgwire.connect(**pgwire.parse_dsn(dsn))
     except (ValueError, OSError, pgwire.PgError, pgwire.ProtocolError) as e:
-        fail(f"can't connect: {e}", 2)
+        fail(cant_connect(e, dsn), 2)
     conn.on_notice = lambda f: print(
         f"{f.get('V', f.get('S', 'NOTICE'))}: {f.get('M', '')}"
         + (f"\nDETAIL: {f['D']}" if f.get("D") else "")
@@ -1509,7 +1528,9 @@ def ask(conn: pgwire.Connection, cmd: str, args: list[str], opts: dict[str, str]
                 print(table(rows, cols))
                 print(f"({len(rows)} row{'s' if len(rows) != 1 else ''}, as {who}; rolled back)")
             else:
-                print(f"done, as {who}; rolled back")
+                # the server's own words for what the statement did: "DELETE 0" is a delete the rules let
+                # through for no row, which "done" would hide
+                print(f"{conn.tag or 'done'}, as {who}; rolled back")
     finally:
         try:
             q("ROLLBACK")

package/command/cli/stack.py

@@ -23,6 +23,7 @@ class Stack:
     clients: dict[str, str] = field(default_factory=dict)  # {"ts": "src/authz.gen.ts"} or {"py": "app/authz_types.py"}
     npm: list[str] = field(default_factory=list)  # @rowstile/* packages to add
     pip: str = ""  # the pip requirement to add: rowstile[fastapi]
+    pip_there: bool = False  # the project depends on rowstile already: nothing to add
     setup: list[str] = field(default_factory=list)  # the change to make, in lines to print
     setup_file: str = ""  # where to make it, if found
 
@@ -59,7 +60,8 @@ def _find(root: str, exts: tuple[str, ...], pattern: str) -> str:
 
 
 def _python_names(root: str) -> set[str]:
-    """The Python packages the project depends on: names from pyproject.toml and requirements*.txt."""
+    """The Python packages the project depends on: names from pyproject.toml and requirements*.txt, and what
+    rowstile's own extras bring (`rowstile[fastapi,asyncpg]` is how the stack pages install FastAPI's part)."""
     text = (_read(root, "pyproject.toml") or "") + "\n"
     try:
         for n in sorted(os.listdir(root)):
@@ -67,10 +69,20 @@ def _python_names(root: str) -> set[str]:
                 text += (_read(root, n) or "") + "\n"
     except OSError:
         pass
-    return {m.group(1).lower().replace("_", "-") for m in re.finditer(r'(?m)^\s*"?([A-Za-z][A-Za-z0-9_.-]*)', text)} | {
-        m.group(1).lower().replace("_", "-")
-        for m in re.finditer(r'"([A-Za-z][A-Za-z0-9_.-]*)\s*(?:\[[^\]]*\])?\s*(?:[<>=!~;][^"]*)?"', text)
+    extras = {
+        x.strip().lower()
+        for m in re.finditer(r"(?i)\browstile\s*\[([^\]]*)\]", text)
+        for x in m.group(1).split(",")
+        if x.strip()
     }
+    return (
+        {m.group(1).lower().replace("_", "-") for m in re.finditer(r'(?m)^\s*"?([A-Za-z][A-Za-z0-9_.-]*)', text)}
+        | {
+            m.group(1).lower().replace("_", "-")
+            for m in re.finditer(r'"([A-Za-z][A-Za-z0-9_.-]*)\s*(?:\[[^\]]*\])?\s*(?:[<>=!~;][^"]*)?"', text)
+        }
+        | extras
+    )
 
 
 def _object(value: object) -> dict[str, object]:
@@ -152,7 +164,8 @@ def detect(root: str = ".") -> Stack:
             s.setup = [
                 'import { PrismaPg } from "@prisma/adapter-pg";',
                 'import { authz, signedIn } from "@rowstile/prisma";',
-                "const adapter = signedIn(new PrismaPg({ connectionString: process.env.DATABASE_URL }),",
+                # the app's own connection, as the app role: DATABASE_URL is Prisma's, the owner's, for migrations
+                "const adapter = signedIn(new PrismaPg({ connectionString: process.env.ROWSTILE_APP_URL }),",
                 f"                         {{ user: {user_ts} }});",
                 "export const db = new PrismaClient({ adapter }).$extends(authz());",
             ]
@@ -194,6 +207,7 @@ def detect(root: str = ".") -> Stack:
         if "sqlalchemy" in py or "sqlmodel" in py:
             s.found.insert(1 if "fastapi" in py else 0, "SQLModel" if "sqlmodel" in py else "SQLAlchemy")
         s.pip = "rowstile" + (f"[{','.join(extras)}]" if extras else "")
+        s.pip_there = "rowstile" in py
         pkg_dir = next((d for d in ("app", "src", "backend/app") if os.path.isdir(os.path.join(root, d))), ".")
         s.clients["py"] = f"{pkg_dir}/authz_types.py".lstrip("./")
         if "fastapi" in py:

package/package.json

@@ -1,8 +1,29 @@
 {
   "name": "rowstile",
-  "version": "0.1.0-alpha.4",
-  "description": "Access rules for Postgres: the rowstile command (policies compiled to row-level security, shipped as migrations), with its own Python",
+  "version": "0.1.0-alpha.6",
+  "description": "Authorization for Postgres apps: the rowstile command (access rules compiled to row-level security, shipped as migrations), with its own Python",
   "license": "Apache-2.0",
+  "mcpName": "io.github.rowstile/rowstile",
+  "homepage": "https://rowstile.dev",
+  "keywords": [
+    "rowstile",
+    "postgres",
+    "postgresql",
+    "authorization",
+    "row-level-security",
+    "rls",
+    "permissions",
+    "access-control",
+    "rbac",
+    "rebac",
+    "multi-tenant",
+    "policy",
+    "migrations",
+    "cli",
+    "prisma",
+    "drizzle",
+    "alembic"
+  ],
   "repository": {
     "type": "git",
     "url": "git+https://github.com/rowstile/rowstile.git",
@@ -20,12 +41,12 @@
     "node": ">=18"
   },
   "optionalDependencies": {
-    "@rowstile/cli-linux-x64": "0.1.0-alpha.4",
-    "@rowstile/cli-linux-arm64": "0.1.0-alpha.4",
-    "@rowstile/cli-linux-x64-musl": "0.1.0-alpha.4",
-    "@rowstile/cli-linux-arm64-musl": "0.1.0-alpha.4",
-    "@rowstile/cli-darwin-x64": "0.1.0-alpha.4",
-    "@rowstile/cli-darwin-arm64": "0.1.0-alpha.4",
-    "@rowstile/cli-win32-x64": "0.1.0-alpha.4"
+    "@rowstile/cli-linux-x64": "0.1.0-alpha.6",
+    "@rowstile/cli-linux-arm64": "0.1.0-alpha.6",
+    "@rowstile/cli-linux-x64-musl": "0.1.0-alpha.6",
+    "@rowstile/cli-linux-arm64-musl": "0.1.0-alpha.6",
+    "@rowstile/cli-darwin-x64": "0.1.0-alpha.6",
+    "@rowstile/cli-darwin-arm64": "0.1.0-alpha.6",
+    "@rowstile/cli-win32-x64": "0.1.0-alpha.6"
   }
 }