@geonosis/db 0.2.0 → 0.5.1

package/dist/index.cjs

@@ -5,9 +5,9 @@ var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;
 var __getProtoOf = Object.getPrototypeOf;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
-var __export = (target, all) => {
-  for (var name in all)
-    __defProp(target, name, { get: all[name], enumerable: true });
+var __export = (target, all2) => {
+  for (var name in all2)
+    __defProp(target, name, { get: all2[name], enumerable: true });
 };
 var __copyProps = (to, from, except, desc) => {
   if (from && typeof from === "object" || typeof from === "function") {
@@ -30,20 +30,36 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  DEFAULT_ENTITY_PAGE: () => DEFAULT_ENTITY_PAGE,
   DEFAULT_OPS_VALUE: () => DEFAULT_OPS_VALUE,
+  DEFAULT_TENANT_KEY: () => DEFAULT_TENANT_KEY,
   DbRefusal: () => DbRefusal,
+  ENTITY_PLACEHOLDERS: () => ENTITY_PLACEHOLDERS,
+  MAX_ENTITY_PAGE: () => MAX_ENTITY_PAGE,
   appConnectionString: () => appConnectionString,
   appRoleStatements: () => appRoleStatements,
+  asStatement: () => asStatement,
   concurrentTenantsConformance: () => concurrentTenantsConformance,
+  connectionsConformance: () => connectionsConformance,
   createConnections: () => createConnections,
   createSessionSeam: () => createSessionSeam,
+  defineEntity: () => defineEntity,
+  drizzleSession: () => drizzleSession,
+  drizzleTenantPolicies: () => drizzleTenantPolicies,
+  entityConformance: () => entityConformance,
+  entityMigrations: () => entityMigrations,
+  forceRowLevelSecurity: () => forceRowLevelSecurity,
   forcedRowLevelSecurityConformance: () => forcedRowLevelSecurityConformance,
+  fragment: () => fragment,
   nodePostgresDriver: () => nodePostgresDriver,
   perStepConnection: () => perStepConnection,
+  scopedQueryConformance: () => scopedQueryConformance,
   sessionConformance: () => sessionConformance,
   statementCensusConformance: () => statementCensusConformance,
   tenantIsolationConformance: () => tenantIsolationConformance,
-  tenantPolicies: () => tenantPolicies
+  tenantPolicies: () => tenantPolicies,
+  tenantPolicySet: () => tenantPolicySet,
+  undosOf: () => undosOf
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -61,7 +77,7 @@ var DbRefusal = class extends Error {
 
 // src/identifiers.ts
 var quoted = (name) => `"${name.replaceAll('"', '""')}"`;
-var literal = (value) => `'${value.replaceAll("'", "''")}'`;
+var literal = (value2) => `'${value2.replaceAll("'", "''")}'`;
 var qualified = (table, schema) => schema === void 0 ? quoted(table) : `${quoted(schema)}.${quoted(table)}`;
 
 // src/app-role.ts
@@ -106,6 +122,123 @@ var appConnectionString = (ownerConnectionString, credentials) => {
 
 // src/conformance.ts
 var import_conformance = require("@geonosis/conformance");
+
+// src/settings.ts
+var DEFAULT_OPS_VALUE = "on";
+var CUSTOM_SETTING = /^[A-Za-z_][A-Za-z0-9_]*\.[A-Za-z_][A-Za-z0-9_]*$/;
+var readSettings = (settings) => {
+  for (const named of ["opsSetting", "tenantSetting"]) {
+    const name = settings[named];
+    if (typeof name !== "string" || name === "") {
+      throw new DbRefusal(
+        `${named} is required and has no default: the name of a session setting is the one thing this package cannot pick for you, because the policies and the seam have to agree on it exactly`
+      );
+    }
+    if (!CUSTOM_SETTING.test(name)) {
+      throw new DbRefusal(
+        `${named} is "${name}", and Postgres reads a setting an application defines as \`prefix.name\` \u2014 anything else is rejected as unrecognised the first time a session sets it`
+      );
+    }
+  }
+  return { ...settings, opsValue: settings.opsValue ?? DEFAULT_OPS_VALUE };
+};
+
+// src/session.ts
+var OPS = /* @__PURE__ */ Symbol("the ops lever");
+var scopeOf = /* @__PURE__ */ new WeakMap();
+var describe = (scope) => scope === OPS ? "the ops lever" : `tenant ${JSON.stringify(scope)}`;
+var fragment = (chunks, values2 = []) => ({ chunks, values: values2 });
+var asStatement = (piece) => ({
+  params: [...piece.values],
+  text: piece.chunks.map((chunk, at) => at === 0 ? chunk : `$${at}${chunk}`).join("")
+});
+var setConfigFragment = (settings) => {
+  if (settings.length === 0) return fragment(["select 1"]);
+  const chunks = ["select set_config("];
+  for (let at = 0; at < settings.length; at += 1) {
+    chunks.push(", ", at === settings.length - 1 ? ", true)" : ", true), set_config(");
+  }
+  return fragment(
+    chunks,
+    settings.flatMap((one) => [one.name, one.value])
+  );
+};
+var executorHandles = {
+  guard: (executor, stillOpen) => ({
+    // Spread, so what a driver put on the handle BESIDES the port reaches the query that was
+    // given it: a keeper that rebuilds the object hands back less than `open()` returned.
+    ...executor,
+    execute: async (statement) => {
+      stillOpen();
+      return executor.execute(statement);
+    },
+    ...typeof executor.transaction === "function" ? {
+      transaction: async (run) => {
+        stillOpen();
+        return executor.transaction(run);
+      }
+    } : {}
+  }),
+  opens: (executor) => typeof executor.transaction === "function",
+  send: (executor, statement) => executor.execute(asStatement(statement)),
+  transaction: (executor, run) => executor.transaction(run)
+};
+var DEFAULT_TENANT_KEY = "tenantId";
+var STATEMENT_TIMEOUT = "statement_timeout";
+var createSessionSeam = (config) => {
+  const settings = readSettings(config.settings);
+  const tenantKey = config.tenantKey ?? DEFAULT_TENANT_KEY;
+  const over = config.over ?? executorHandles;
+  if (tenantKey === "") {
+    throw new DbRefusal(
+      "tenantKey is empty, and it is the property the seam reads a query\u2019s tenant out of: name the key your queries carry, or leave it out for `tenantId`"
+    );
+  }
+  const contextOf = (scope) => {
+    if (scope !== OPS) return [{ name: settings.tenantSetting, value: scope }];
+    const lever = { name: settings.opsSetting, value: settings.opsValue };
+    return config.opsStatementTimeout === void 0 ? [lever] : [lever, { name: STATEMENT_TIMEOUT, value: config.opsStatementTimeout }];
+  };
+  const opened = async (handle, scope, run) => {
+    const current = scopeOf.get(handle);
+    if (current === scope) return run(handle);
+    if (current !== void 0) {
+      throw new DbRefusal(
+        `this transaction is open for ${describe(current)} and was asked for ${describe(scope)}: a transaction names one scope, and the second query would run behind the first one's policy`
+      );
+    }
+    if (!over.opens(handle)) {
+      throw new DbRefusal(
+        `this handle is in no session and cannot open a transaction, so ${describe(scope)} has nothing to name \u2014 pass the connection, or run it inside a session already open for that scope`
+      );
+    }
+    return over.transaction(handle, async (tx) => {
+      await over.send(tx, setConfigFragment(contextOf(scope)));
+      scopeOf.set(tx, scope);
+      return run(tx);
+    });
+  };
+  const named = (params) => {
+    const carried = params[tenantKey];
+    if (typeof carried !== "string" || carried === "") {
+      throw new DbRefusal(
+        `this query is scoped by "${tenantKey}" and its parameters carry no such value: the session would name no tenant at all, which is not a refusal but a query running outside every policy. Pass the tenant under "${tenantKey}", or build the seam with the key your own queries carry`
+      );
+    }
+    return carried;
+  };
+  return {
+    inOps: (handle, run) => opened(handle, OPS, run),
+    inTenant: (handle, tenantId, run) => opened(handle, tenantId, run),
+    scoped: (query) => async (handle, params) => opened(handle, named(params), (tx) => query(tx, params)),
+    scopedAsOps: (query) => (handle, params) => opened(handle, OPS, (tx) => query(tx, params)),
+    send: (handle, statement) => over.send(handle, statement),
+    tenantKey
+  };
+};
+
+// src/conformance.ts
+var asking = (subject) => subject.run ?? ((handle, statement) => handle.execute(asStatement(statement)));
 var A = "tenant_conformance_a";
 var B = "tenant_conformance_b";
 var CONCURRENT = [
@@ -122,34 +255,45 @@ var probeSql = (probe) => {
   const on = qualified(probe.name, probe.schema);
   const tenant = quoted(probe.tenantColumn);
   return {
-    insert: (tenantId, id) => ({
-      params: [tenantId, id],
-      text: `insert into ${on} (${tenant}, ${quoted(probe.idColumn)}) values ($1, $2)`
-    }),
-    selectAll: { text: `select ${tenant} as tenant from ${on}` },
+    insert: (tenantId, id) => fragment(
+      [`insert into ${on} (${tenant}, ${quoted(probe.idColumn)}) values (`, ", ", ")"],
+      [tenantId, id]
+    ),
+    selectAll: fragment([`select ${tenant} as tenant from ${on}`]),
+    selectBound: (ids) => fragment(
+      [
+        `select ${tenant} as tenant from ${on} where ${quoted(probe.idColumn)} = any(`,
+        ") and ",
+        " > 0"
+      ],
+      [ids, ids.length]
+    ),
     tenantsOf: (answer) => (0, import_conformance.rowsOf)(answer).map((row) => row.tenant).toSorted()
   };
 };
 var written = async (subject, rows) => {
   const probe = probeSql(subject.probe);
+  const ask = asking(subject);
   for (const [tenantId, id] of rows) {
     await subject.seam.inTenant(
       subject.connection,
       tenantId,
-      (tx) => tx.execute(probe.insert(tenantId, id))
+      (tx) => ask(tx, probe.insert(tenantId, id))
     );
   }
 };
 var tenantIsolationConformance = (subject) => {
+  const ask = asking(subject);
   const probe = probeSql(subject.probe);
   return [
     {
       name: "the role the session connects as is no superuser",
       run: async () => {
         const [row] = (0, import_conformance.rowsOf)(
-          await subject.connection.execute({
-            text: `select current_setting('is_superuser') as super`
-          })
+          await ask(
+            subject.connection,
+            fragment([`select current_setting('is_superuser') as super`])
+          )
         );
         (0, import_conformance.assertIs)(
           row?.super,
@@ -169,7 +313,7 @@ var tenantIsolationConformance = (subject) => {
         const seen = await subject.seam.inTenant(
           subject.connection,
           A,
-          (tx) => tx.execute(probe.selectAll)
+          (tx) => ask(tx, probe.selectAll)
         );
         (0, import_conformance.assertSame)(
           probe.tenantsOf(seen),
@@ -187,7 +331,7 @@ var tenantIsolationConformance = (subject) => {
           [B, "row_b"]
         ]);
         (0, import_conformance.assertSame)(
-          probe.tenantsOf(await subject.connection.execute(probe.selectAll)),
+          probe.tenantsOf(await ask(subject.connection, probe.selectAll)),
           [],
           "a read outside every session answered with rows: the policy defaults to visible, so a query that forgets its session sees the whole table"
         );
@@ -201,19 +345,40 @@ var tenantIsolationConformance = (subject) => {
           () => subject.seam.inTenant(
             subject.connection,
             B,
-            (tx) => tx.execute(probe.insert(A, "row_forged"))
+            (tx) => ask(tx, probe.insert(A, "row_forged"))
           ),
           "a session naming one tenant wrote a row belonging to another \u2014 the isolation policy has a `using` clause and no `with check`, so it reads one way and writes any way"
         );
         (0, import_conformance.assertSame)(
           probe.tenantsOf(
-            await subject.seam.inOps(subject.connection, (tx) => tx.execute(probe.selectAll))
+            await subject.seam.inOps(subject.connection, (tx) => ask(tx, probe.selectAll))
           ),
           [],
           "the forged write was reported as refused and the row is there anyway"
         );
       }
     },
+    {
+      name: "a value the exam binds reaches the database as a parameter, an array included",
+      run: async () => {
+        await subject.reset();
+        await written(subject, [
+          [A, "row_a"],
+          [A, "row_b"],
+          [B, "row_c"]
+        ]);
+        const seen = await subject.seam.inTenant(
+          subject.connection,
+          A,
+          (tx) => ask(tx, probe.selectBound(["row_a", "row_b"]))
+        );
+        (0, import_conformance.assertSame)(
+          probe.tenantsOf(seen),
+          [A, A],
+          "a read whose values were BOUND did not answer with the rows they name: a handle that renders a parameter into the statement\u2019s text \u2014 an array spliced into a list, a string quoted by hand \u2014 is a handle whose queries are built by concatenation, which is the injection this port\u2019s shape exists to make impossible"
+        );
+      }
+    },
     {
       name: "the ops lever sees every tenant",
       run: async () => {
@@ -224,7 +389,7 @@ var tenantIsolationConformance = (subject) => {
         ]);
         (0, import_conformance.assertSame)(
           probe.tenantsOf(
-            await subject.seam.inOps(subject.connection, (tx) => tx.execute(probe.selectAll))
+            await subject.seam.inOps(subject.connection, (tx) => ask(tx, probe.selectAll))
           ),
           [A, B].toSorted(),
           "maintenance could not see across tenants, so every sweep, backfill and repair has to be run once per tenant or not at all"
@@ -243,6 +408,7 @@ var recorderOf = async (subject) => {
 };
 var counted = (statements, pattern) => statements.filter((one) => pattern.test(one)).length;
 var statementCensusConformance = (subject) => {
+  const ask = asking(subject);
   const probe = probeSql(subject.probe);
   return [
     {
@@ -251,7 +417,7 @@ var statementCensusConformance = (subject) => {
         await subject.reset();
         const recorded = await recorderOf(subject);
         try {
-          await subject.seam.inTenant(recorded.connection, A, (tx) => tx.execute(probe.selectAll));
+          await subject.seam.inTenant(recorded.connection, A, (tx) => ask(tx, probe.selectAll));
         } finally {
           await recorded.close();
         }
@@ -284,8 +450,8 @@ var statementCensusConformance = (subject) => {
         const recorded = await recorderOf(subject);
         try {
           await subject.seam.inTenant(recorded.connection, A, async (tx) => {
-            await tx.execute(probe.selectAll);
-            await subject.seam.inTenant(tx, A, (inner) => inner.execute(probe.selectAll));
+            await ask(tx, probe.selectAll);
+            await subject.seam.inTenant(tx, A, (inner) => ask(inner, probe.selectAll));
           });
         } finally {
           await recorded.close();
@@ -311,6 +477,7 @@ var statementCensusConformance = (subject) => {
   ];
 };
 var concurrentTenantsConformance = (subject) => {
+  const ask = asking(subject);
   const probe = probeSql(subject.probe);
   return [
     {
@@ -322,13 +489,13 @@ var concurrentTenantsConformance = (subject) => {
             (tenantId, index) => subject.seam.inTenant(
               subject.connection,
               tenantId,
-              (tx) => tx.execute(probe.insert(tenantId, `row_${index}`))
+              (tx) => ask(tx, probe.insert(tenantId, `row_${index}`))
             )
           )
         );
         (0, import_conformance.assertSame)(
           probe.tenantsOf(
-            await subject.seam.inOps(subject.connection, (tx) => tx.execute(probe.selectAll))
+            await subject.seam.inOps(subject.connection, (tx) => ask(tx, probe.selectAll))
           ),
           CONCURRENT.toSorted(),
           "writes made at the same moment did not each land under the tenant they named: the setting is not local to its transaction, so one connection carried another request's tenant"
@@ -344,13 +511,13 @@ var concurrentTenantsConformance = (subject) => {
             (tenantId, index) => subject.seam.inTenant(
               subject.connection,
               tenantId,
-              (tx) => tx.execute(probe.insert(tenantId, `row_${index}`))
+              (tx) => ask(tx, probe.insert(tenantId, `row_${index}`))
             )
           )
         );
         const seen = await Promise.all(
           CONCURRENT.map(
-            (tenantId) => subject.seam.inTenant(subject.connection, tenantId, (tx) => tx.execute(probe.selectAll)).then(probe.tenantsOf)
+            (tenantId) => subject.seam.inTenant(subject.connection, tenantId, (tx) => ask(tx, probe.selectAll)).then(probe.tenantsOf)
           )
         );
         (0, import_conformance.assertSame)(
@@ -367,7 +534,7 @@ var concurrentTenantsConformance = (subject) => {
           () => subject.seam.inTenant(
             subject.connection,
             A,
-            (tx) => subject.seam.inTenant(tx, B, (inner) => inner.execute(probe.selectAll))
+            (tx) => subject.seam.inTenant(tx, B, (inner) => ask(inner, probe.selectAll))
           ),
           "a session open for one tenant accepted a query for another: whichever setting wins, one of the two queries runs behind the wrong policy",
           // #211/#213: the SEAM's own refusal, by class — a driver that crashed throws too.
@@ -381,7 +548,7 @@ var concurrentTenantsConformance = (subject) => {
         await (0, import_conformance.assertRefuses)(
           () => subject.seam.inOps(
             subject.connection,
-            (tx) => subject.seam.inTenant(tx, A, (inner) => inner.execute(probe.selectAll))
+            (tx) => subject.seam.inTenant(tx, A, (inner) => ask(inner, probe.selectAll))
           ),
           "a tenant query reached from an ops sweep ran anyway \u2014 with no tenant named, behind the ops policy, which is every tenant",
           DbRefusal
@@ -390,16 +557,77 @@ var concurrentTenantsConformance = (subject) => {
     }
   ];
 };
+var scopedOf = (subject) => {
+  const scoped = subject.seam.scoped;
+  if (typeof scoped !== "function") {
+    throw new import_conformance.ConformanceFailure(
+      'this seam has no `scoped`, and "a query names its own tenant" is the claim that keeps every call site from naming one by hand: supply the wrapper \u2014 or this claim is untested rather than passing'
+    );
+  }
+  return scoped;
+};
+var scopedQueryConformance = (subject) => {
+  const ask = asking(subject);
+  const probe = probeSql(subject.probe);
+  const key = subject.seam.tenantKey ?? "tenantId";
+  const insert = () => scopedOf(subject)(
+    (tx, params) => ask(tx, probe.insert(params[key] ?? "", "row_scoped"))
+  );
+  return [
+    {
+      name: "a query scoped by its own parameters lands under the tenant they name",
+      run: async () => {
+        await subject.reset();
+        await insert()(subject.connection, { [key]: A });
+        (0, import_conformance.assertSame)(
+          probe.tenantsOf(
+            await subject.seam.inOps(subject.connection, (tx) => ask(tx, probe.selectAll))
+          ),
+          [A],
+          `the row a query carrying its tenant under "${key}" wrote did not land under that tenant: the seam read the key it wanted rather than the one the query carries, and what it named instead was nothing`
+        );
+      }
+    },
+    {
+      name: "a scoped query for a second tenant inside a session is refused",
+      run: async () => {
+        await subject.reset();
+        await (0, import_conformance.assertRefuses)(
+          () => subject.seam.inTenant(subject.connection, B, (tx) => insert()(tx, { [key]: A })),
+          "a scoped query naming one tenant ran inside a session open for another: the wrapper opened nothing and the write went in behind the session it found",
+          DbRefusal
+        );
+      }
+    },
+    {
+      name: "a scoped query whose parameters carry no tenant is refused by that key\u2019s name",
+      run: async () => {
+        await subject.reset();
+        await (0, import_conformance.assertRefuses)(
+          () => insert()(subject.connection, {}),
+          `a query whose parameters carry no "${key}" was run anyway \u2014 with no tenant named at all, which is a query outside every session rather than a refusal`,
+          key
+        );
+      }
+    }
+  ];
+};
 var forcedRowLevelSecurityConformance = (subject) => [
   {
     name: "every guarded table forces row level security",
     run: async () => {
       const tables = subject.guardedTables ?? [subject.probe.name];
       const rows = (0, import_conformance.rowsOf)(
-        await subject.connection.execute({
-          params: [tables],
-          text: "select relname as name, relforcerowsecurity as forced from pg_class where relname = any($1)"
-        })
+        await asking(subject)(
+          subject.connection,
+          fragment(
+            [
+              "select relname as name, relforcerowsecurity as forced from pg_class where relname = any(",
+              ")"
+            ],
+            [tables]
+          )
+        )
       );
       (0, import_conformance.assertSame)(
         rows.map((row) => row.name).toSorted(),
@@ -414,17 +642,140 @@ var forcedRowLevelSecurityConformance = (subject) => [
     }
   }
 ];
+var surfaceOf = (handle) => {
+  const found = /* @__PURE__ */ new Set();
+  for (let at = handle; at !== null && at !== Object.prototype; at = Object.getPrototypeOf(at)) {
+    for (const name of Object.getOwnPropertyNames(at)) {
+      if (name !== "constructor") found.add(name);
+    }
+  }
+  return [...found].toSorted();
+};
+var perStepOf = (subject) => {
+  const perStep = subject.perStep;
+  if (typeof perStep !== "function") {
+    throw new import_conformance.ConformanceFailure(
+      'this subject has no `perStep`, and "a step\u2019s handle is not the next step\u2019s" is a claim about a durable run that hibernates between its steps: supply the per-step scope, named \u2014 or this claim is untested rather than passing'
+    );
+  }
+  return perStep;
+};
+var connectionsConformance = (subject) => {
+  const ask = asking(subject);
+  const probe = subject.probe ?? fragment(["select 1"]);
+  const CHARGE = "charge";
+  const SHIP = "ship";
+  return [
+    {
+      name: "a handle inside its invocation answers",
+      run: () => subject.connections.withConnection(async () => {
+        await ask(subject.connections.sessionDb(), probe);
+      })
+    },
+    {
+      name: "a handle keeps everything the driver put on it, so a query reaches what open() returned",
+      run: async () => {
+        const opening = subject.connections.open;
+        if (typeof opening !== "function") {
+          throw new import_conformance.ConformanceFailure(
+            'this subject has no `open`, and "the handle a query is given is the one the driver opened" cannot be asked without the two to compare: supply it \u2014 or this claim is untested rather than passing'
+          );
+        }
+        const held = opening();
+        try {
+          const opened = surfaceOf(held.connection);
+          await subject.connections.withConnection(() => {
+            const given = surfaceOf(subject.connections.sessionDb());
+            (0, import_conformance.assertSame)(
+              opened.filter((name) => !given.includes(name)),
+              [],
+              "the handle inside the invocation answers to less than the one the driver returned: a keeper that rebuilds the handle out of the port hands a query something its own library never made, and everything the driver attached \u2014 an ORM database, a logger, a schema \u2014 is undefined from inside every scoped query"
+            );
+            return Promise.resolve();
+          });
+        } finally {
+          await held.close();
+        }
+      }
+    },
+    {
+      name: "a handle asked for outside every invocation is refused, naming what to wrap it in",
+      run: () => (0, import_conformance.assertRefuses)(
+        () => Promise.resolve(subject.connections.sessionDb()),
+        "a handle was opened for a caller in no invocation, and nothing will ever close it: one leak per call, deferred to whoever reads the comment about it",
+        DbRefusal
+      )
+    },
+    {
+      name: "a handle used after its invocation ended is refused by name",
+      run: async () => {
+        let held;
+        await subject.connections.withConnection(async () => {
+          held = subject.connections.sessionDb();
+          await ask(held, probe);
+        });
+        await (0, import_conformance.assertRefuses)(
+          () => ask(held, probe),
+          "a handle answered a query after the invocation that opened it had ended: its pool is closed or closing, and what comes back is the driver\u2019s own error at some later line rather than a refusal naming the lifetime that was crossed",
+          DbRefusal
+        );
+      }
+    },
+    {
+      name: "a step inside a run gets a handle of its own, because workerd refuses I/O on another request\u2019s socket",
+      run: () => subject.connections.withConnection(async () => {
+        const ofTheRun = subject.connections.sessionDb();
+        await perStepOf(subject)(CHARGE)(async () => {
+          const ofTheStep = subject.connections.sessionDb();
+          (0, import_conformance.assertThat)(
+            ofTheStep !== ofTheRun,
+            "a step inside a run was handed the RUN\u2019s handle: a workflow entrypoint that opens an invocation around the run body hands every step a connection opened for another request, and workerd refuses to do I/O on it \u2014 the step joined the frame it was nested in rather than opening its own"
+          );
+          await ask(ofTheStep, probe);
+        });
+        await ask(ofTheRun, probe);
+      })
+    },
+    {
+      name: "a handle from one step is refused inside another, named with the step it came from",
+      run: async () => {
+        const perStep = perStepOf(subject);
+        let charged;
+        await perStep(CHARGE)(async () => {
+          charged = subject.connections.sessionDb();
+          await ask(charged, probe);
+        });
+        await perStep(SHIP)(
+          () => (0, import_conformance.assertRefuses)(
+            () => ask(charged, probe),
+            `the handle the "${CHARGE}" step opened answered a query inside the "${SHIP}" step: a durable run hibernates between its steps, so that handle is a dead socket, and the step that leaked it has to be in the refusal or the search starts at the top of the workflow`,
+            CHARGE
+          )
+        );
+      }
+    }
+  ];
+};
 var sessionConformance = (subject) => [
   ...tenantIsolationConformance(subject),
   ...statementCensusConformance(subject),
   ...concurrentTenantsConformance(subject),
+  ...scopedQueryConformance(subject),
   ...forcedRowLevelSecurityConformance(subject)
 ];
 
 // src/connections.ts
 var import_node_async_hooks = require("async_hooks");
 var invocation = new import_node_async_hooks.AsyncLocalStorage();
+var whose = (frame) => frame.named === void 0 ? "an invocation" : `the "${frame.named}" unit of work`;
+var stillOpenIn = (frame) => () => {
+  if (frame.live) return;
+  throw new DbRefusal(
+    `this handle was opened in ${whose(frame)} and that invocation has ended: its connection is closed or closing, so a query on it now is a query on a dead socket. Open the handle inside the unit of work that uses it \u2014 a durable run hibernates between its steps, and a handle carried across one belongs to a request that is gone.`
+  );
+};
 var createConnections = (config) => {
+  const guard = config.over?.guard ?? executorHandles.guard;
   const opened = () => config.open === void 0 ? config.driver.open(config.connectionString) : config.driver.open(config.connectionString, config.open);
   return {
     inInvocation: () => invocation.getStore() !== void 0,
@@ -436,27 +787,738 @@ var createConnections = (config) => {
           "sessionDb() was called outside withConnection(), where a handle opened for it would be closed by nobody. Wrap the invocation \u2014 withConnection(() => \u2026, (closing) => ctx.waitUntil(closing)) \u2014 or call open() and close what you were given."
         );
       }
-      const known = frame.get(config.connectionString);
-      if (known !== void 0) return known.connection;
-      const held = opened();
-      frame.set(config.connectionString, held);
-      return held.connection;
+      const known = frame.held.get(config.connectionString);
+      if (known !== void 0) return known.guarded;
+      const open = opened();
+      const held = {
+        guarded: guard(open.connection, stillOpenIn(frame)),
+        open
+      };
+      frame.held.set(config.connectionString, held);
+      return held.guarded;
     },
-    withConnection: async (run, release = (closing) => void closing) => {
-      if (invocation.getStore() !== void 0) return run();
-      const held = /* @__PURE__ */ new Map();
+    withConnection: async (run, release = (closing) => void closing, options) => {
+      if (options?.own !== true && invocation.getStore() !== void 0) return run();
+      const frame = {
+        held: /* @__PURE__ */ new Map(),
+        live: true,
+        ...options?.named === void 0 ? {} : { named: options.named }
+      };
       try {
-        return await invocation.run(held, run);
+        return await invocation.run(frame, run);
       } finally {
-        release(Promise.all([...held.values()].map((one) => one.close())).then(() => void 0));
+        frame.live = false;
+        release(
+          Promise.all([...frame.held.values()].map((one) => one.open.close())).then(
+            () => void 0
+          )
+        );
       }
     }
   };
 };
 var perStepConnection = (connections) => ({
-  perStep: () => (body) => connections.withConnection(body)
+  perStep: (named) => (body) => connections.withConnection(body, void 0, {
+    own: true,
+    ...named === void 0 ? {} : { named }
+  })
 });
 
+// src/drizzle.ts
+var loadDrizzle = async () => {
+  let loaded;
+  try {
+    loaded = await import("drizzle-orm");
+  } catch (error) {
+    throw new DbRefusal(
+      "drizzle-orm is an optional peer dependency of @geonosis/db and is not installed \u2014 `npm install drizzle-orm`, or pass your own copy as `drizzleSession({ drizzleOrm })`",
+      { cause: error }
+    );
+  }
+  return loaded.default ?? loaded;
+};
+var speaking = (module2) => {
+  const sql2 = module2?.sql;
+  if (typeof sql2?.join !== "function" || typeof sql2.param !== "function") {
+    throw new DbRefusal(
+      "what was given as drizzle-orm has no `sql` with `join`, `param` and `raw` \u2014 a statement is built out of those three, and whatever answered to that name is not the library this expects"
+    );
+  }
+  return sql2;
+};
+var database = (db) => {
+  if (typeof db?.execute !== "function" || typeof db.transaction !== "function") {
+    throw new DbRefusal(
+      "what was given as a drizzle database has no `execute` and `transaction` \u2014 a session is opened through the second and named through the first"
+    );
+  }
+  return db;
+};
+var guarding = (db, stillOpen) => new Proxy(db, {
+  get: (held, property) => {
+    stillOpen();
+    const value2 = Reflect.get(held, property);
+    return typeof value2 === "function" ? value2.bind(held) : value2;
+  }
+});
+var drizzleSession = async (options = {}) => {
+  const sql2 = speaking(options.drizzleOrm ?? await loadDrizzle());
+  const built = (statement) => sql2.join(
+    statement.chunks.flatMap(
+      (chunk, at) => at === 0 ? [sql2.raw(chunk)] : [sql2.param(statement.values[at - 1]), sql2.raw(chunk)]
+    )
+  );
+  return {
+    guard: guarding,
+    opens: (db) => typeof db?.transaction === "function",
+    send: async (db, statement) => await database(db).execute(built(statement)),
+    transaction: (db, run) => database(db).transaction((tx) => run(tx))
+  };
+};
+
+// src/entity.ts
+var import_conformance2 = require("@geonosis/conformance");
+var then = (before, after2) => ({
+  chunks: [
+    ...before.chunks.slice(0, -1),
+    `${before.chunks.at(-1) ?? ""}${after2.chunks[0] ?? ""}`,
+    ...after2.chunks.slice(1)
+  ],
+  values: [...before.values, ...after2.values]
+});
+var all = (pieces) => pieces.reduce((built, piece) => then(built, piece), fragment([""]));
+var value = (held) => fragment(["", ""], [held]);
+var sql = (text) => fragment([text]);
+var DEFAULT_COLUMNS = {
+  body: "body",
+  createdAt: "created_at",
+  retiredAt: "retired_at",
+  tenant: "tenant_id",
+  updatedAt: "updated_at"
+};
+var DEFAULT_ENTITY_PAGE = 50;
+var MAX_ENTITY_PAGE = 100;
+var CURSOR = "cursor_";
+var paged = (limit) => Math.min(Math.max(limit ?? DEFAULT_ENTITY_PAGE, 1), MAX_ENTITY_PAGE);
+var stampOf = (order) => order.map((one) => `${one.column}:${one.direction ?? "asc"}`).join(",");
+var readCursor = (cursor, order) => {
+  let held;
+  try {
+    held = JSON.parse(decodeURIComponent(cursor));
+  } catch {
+    throw new DbRefusal(
+      "this cursor was not minted by this listing: a page is reached by the key of the row before it, and that key is not readable here \u2014 an unreadable cursor answered with the first page again is a caller silently reading the list twice"
+    );
+  }
+  const [stamp, ...values2] = Array.isArray(held) ? held : [];
+  if (stamp !== stampOf(order) || values2.length !== order.length) {
+    throw new DbRefusal(
+      `this cursor was minted under another ordering or another width, and the rows after it are another list's: this one is ordered by ${stampOf(order)}`
+    );
+  }
+  return values2;
+};
+var after = (order, values2) => all([
+  sql(" and ("),
+  all(
+    order.map(
+      (column, depth) => all([
+        sql(depth === 0 ? "(" : " or ("),
+        all(
+          order.slice(0, depth).map(
+            (tied, at) => all([sql(`${quoted(tied.column)} = `), value(values2[at]), sql(" and ")])
+          )
+        ),
+        sql(`${quoted(column.column)} ${column.direction === "desc" ? "<" : ">"} `),
+        value(values2[depth]),
+        sql(")")
+      ])
+    )
+  ),
+  sql(")")
+]);
+var defineEntity = (definition) => {
+  const columns = { ...DEFAULT_COLUMNS, ...definition.columns };
+  const { key, order, seam, table } = definition;
+  const on = qualified(table, definition.schema);
+  const tenantKey = seam.tenantKey;
+  const send = (handle, statement) => seam.send(handle, statement);
+  const keyed = (params) => params[key.param];
+  const withKey = (params, rest) => ({ [key.param]: params[key.param], ...rest });
+  const tenantOf = (params) => params[tenantKey];
+  const selected = [
+    `${quoted(key.column)} as "key"`,
+    `${quoted(columns.body)} as "body"`,
+    `${quoted(columns.createdAt)} as "createdAt"`,
+    `${quoted(columns.updatedAt)} as "updatedAt"`,
+    ...order.map((one, at) => `${quoted(one.column)} as ${quoted(`${CURSOR}${at}`)}`)
+  ].join(", ");
+  const alive = (tenant) => all([
+    sql(`select ${selected} from ${on} where ${quoted(columns.tenant)} = `),
+    value(tenant),
+    sql(` and ${quoted(columns.retiredAt)} is null`)
+  ]);
+  const ordered = order.map((one) => `${quoted(one.column)} ${one.direction === "desc" ? "desc" : "asc"}`).join(", ");
+  const itemsOf = (rows) => rows.map((row) => definition.item(row));
+  const cursorOf = (row) => encodeURIComponent(
+    JSON.stringify([stampOf(order), ...order.map((_, at) => row[`${CURSOR}${at}`])])
+  );
+  const get = async (handle, params) => {
+    const [row] = (0, import_conformance2.rowsOf)(
+      await send(
+        handle,
+        all([
+          alive(tenantOf(params)),
+          sql(` and ${quoted(key.column)} = `),
+          value(keyed(params)),
+          sql(" limit 1")
+        ])
+      )
+    );
+    return row === void 0 ? null : definition.item(row);
+  };
+  const listAll = async (handle, params) => itemsOf(
+    (0, import_conformance2.rowsOf)(
+      await send(handle, then(alive(tenantOf(params)), sql(` order by ${ordered}`)))
+    )
+  );
+  const list = async (handle, params) => {
+    const limit = paged(params.limit);
+    const rows = (0, import_conformance2.rowsOf)(
+      await send(
+        handle,
+        all([
+          alive(tenantOf(params)),
+          params.cursor === void 0 ? sql("") : after(order, readCursor(params.cursor, order)),
+          sql(` order by ${ordered} limit `),
+          value(limit + 1)
+        ])
+      )
+    );
+    const page = rows.slice(0, limit);
+    const last = page.at(-1);
+    return {
+      items: itemsOf(page),
+      ...rows.length > limit && last !== void 0 ? { nextCursor: cursorOf(last) } : {}
+    };
+  };
+  const upsert = async (handle, params) => {
+    const now = Date.now();
+    const indexed = definition.indexed?.(params.body) ?? {};
+    const names = Object.keys(indexed);
+    const tenant = tenantOf(params);
+    const [previous] = (0, import_conformance2.rowsOf)(
+      await send(
+        handle,
+        all([
+          sql(
+            `select ${quoted(columns.body)} as "body", ${quoted(columns.retiredAt)} as "retiredAt" from ${on} where ${quoted(columns.tenant)} = `
+          ),
+          value(tenant),
+          sql(` and ${quoted(key.column)} = `),
+          value(keyed(params)),
+          sql(" for update")
+        ])
+      )
+    );
+    const written2 = [
+      { column: columns.body, held: params.body },
+      { column: columns.updatedAt, held: now },
+      ...names.map((name) => ({ column: name, held: indexed[name] }))
+    ];
+    await send(
+      handle,
+      all([
+        sql(
+          `insert into ${on} (${[columns.tenant, key.column, columns.createdAt, columns.retiredAt, ...written2.map((one) => one.column)].map(quoted).join(", ")}) values (`
+        ),
+        value(tenant),
+        sql(", "),
+        value(keyed(params)),
+        sql(", "),
+        value(now),
+        sql(", null"),
+        all(written2.map((one) => then(sql(", "), value(one.held)))),
+        sql(
+          `) on conflict (${quoted(columns.tenant)}, ${quoted(key.column)}) do update set ${quoted(columns.retiredAt)} = null, ${written2.map((one) => `${quoted(one.column)} = excluded.${quoted(one.column)}`).join(", ")}`
+        )
+      ])
+    );
+    return withKey(params, {
+      previous: previous === void 0 || previous.retiredAt !== null ? null : previous.body
+    });
+  };
+  const retire = async (handle, params) => {
+    const now = Date.now();
+    const [row] = (0, import_conformance2.rowsOf)(
+      await send(
+        handle,
+        all([
+          sql(`update ${on} set ${quoted(columns.retiredAt)} = `),
+          value(now),
+          sql(`, ${quoted(columns.updatedAt)} = `),
+          value(now),
+          sql(` where ${quoted(columns.tenant)} = `),
+          value(tenantOf(params)),
+          sql(` and ${quoted(key.column)} = `),
+          value(keyed(params)),
+          sql(
+            ` and ${quoted(columns.retiredAt)} is null returning ${quoted(columns.body)} as "body"`
+          )
+        ])
+      )
+    );
+    return withKey(params, { retired: row === void 0 ? null : row.body });
+  };
+  const surface = {
+    get: seam.scoped(get),
+    list: seam.scoped(list),
+    listAll: seam.scoped(listAll),
+    retire: seam.scoped(retire),
+    upsert: seam.scoped(upsert)
+  };
+  const addressed = (output, tenantId) => ({ [tenantKey]: tenantId, [key.param]: output[key.param] });
+  return {
+    ...surface,
+    // A write is undone by writing what was there before it, which is what the forward verb
+    // answered with: nothing else has to be remembered anywhere.
+    undos: {
+      retire: async (handle, { output, tenantId }) => {
+        if (output.retired === null) return;
+        await surface.upsert(handle, { ...addressed(output, tenantId), body: output.retired });
+      },
+      upsert: async (handle, { output, tenantId }) => {
+        await (output.previous === null ? surface.retire(handle, addressed(output, tenantId)) : surface.upsert(handle, {
+          ...addressed(output, tenantId),
+          body: output.previous
+        }));
+      }
+    }
+  };
+};
+var undosOf = (entity) => entity.undos;
+
+// src/entity-conformance.ts
+var import_conformance3 = require("@geonosis/conformance");
+var A2 = "tenant_entity_a";
+var B2 = "tenant_entity_b";
+var asking2 = (subject) => {
+  const at = (tenantId, key) => ({
+    [subject.tenantKey]: tenantId,
+    ...key === void 0 ? {} : { [subject.keyParam]: key }
+  });
+  return {
+    at,
+    get: (tenantId, key) => subject.entity.get(subject.connection, at(tenantId, key)),
+    list: (tenantId, page = {}) => subject.entity.list(subject.connection, { ...at(tenantId), ...page }),
+    listAll: (tenantId) => subject.entity.listAll(subject.connection, at(tenantId)),
+    retire: (tenantId, key) => subject.entity.retire(subject.connection, at(tenantId, key)),
+    upsert: (tenantId, key, body) => subject.entity.upsert(subject.connection, { ...at(tenantId, key), body })
+  };
+};
+var entityConformance = (subject) => {
+  const ask = asking2(subject);
+  const [first, second] = subject.bodies;
+  const [one, two, three] = subject.keys;
+  const written2 = async (tenantId) => {
+    for (const key of subject.keys) await ask.upsert(tenantId, key, first);
+  };
+  return [
+    {
+      name: "a row written is read back by its key",
+      run: async () => {
+        await subject.reset();
+        await ask.upsert(A2, one, first);
+        const found = await ask.get(A2, one);
+        (0, import_conformance3.assertThat)(found !== null, "the row that was just written was read back as nothing");
+        (0, import_conformance3.assertSame)(
+          subject.bodyOf(found),
+          first,
+          "the row read back is not the body that was written"
+        );
+      }
+    },
+    {
+      name: "a key nothing was written under is nothing, not an empty row",
+      run: async () => {
+        await subject.reset();
+        (0, import_conformance3.assertIs)(
+          await ask.get(A2, one),
+          null,
+          "a key with no row behind it answered with something: a read that invents an empty row is a caller writing over nothing"
+        );
+      }
+    },
+    {
+      name: "an upsert answers with the body it replaced, and with nothing when it replaced nothing",
+      run: async () => {
+        await subject.reset();
+        const created = await ask.upsert(A2, one, first);
+        (0, import_conformance3.assertIs)(
+          created.previous,
+          null,
+          "a write over an empty key answered with a previous body: its undo would restore a row that never existed"
+        );
+        const replaced = await ask.upsert(A2, one, second);
+        (0, import_conformance3.assertSame)(
+          replaced.previous,
+          first,
+          "a write over a living row did not answer with what it replaced, so nothing can put it back"
+        );
+      }
+    },
+    {
+      name: "every living row of one tenant is listed, in the listing order",
+      run: async () => {
+        await subject.reset();
+        await written2(A2);
+        (0, import_conformance3.assertIs)(
+          (await ask.listAll(A2)).length,
+          3,
+          "the listing answered with a different number of rows than were written"
+        );
+      }
+    },
+    {
+      name: "a page carries a cursor while rows remain, and none on the last page",
+      run: async () => {
+        await subject.reset();
+        await written2(A2);
+        const page = await ask.list(A2, { limit: 2 });
+        (0, import_conformance3.assertIs)(page.items.length, 2, "a page of two answered with another number of rows");
+        (0, import_conformance3.assertThat)(
+          page.nextCursor !== void 0,
+          "a page with rows behind it carried no cursor, so nothing can reach them"
+        );
+        const last = await ask.list(A2, { cursor: page.nextCursor, limit: 2 });
+        (0, import_conformance3.assertIs)(last.items.length, 1, "the page after the cursor answered with the wrong rows");
+        (0, import_conformance3.assertIs)(
+          last.nextCursor,
+          void 0,
+          "the last page carried a cursor: a caller who follows it asks for a page that is not there, and a list that never ends is how a walk becomes a loop"
+        );
+      }
+    },
+    {
+      name: "a walk one row at a time visits every row exactly once",
+      run: async () => {
+        await subject.reset();
+        await written2(A2);
+        const seen = [];
+        let cursor;
+        for (let page = 0; page < subject.keys.length + 1; page += 1) {
+          const answered = await ask.list(A2, { cursor, limit: 1 });
+          seen.push(...answered.items);
+          cursor = answered.nextCursor;
+          if (cursor === void 0) break;
+        }
+        (0, import_conformance3.assertIs)(
+          seen.length,
+          subject.keys.length,
+          "the walk saw a different number of rows than the table holds: a keyset that repeats a row or skips one is a page boundary landing on a tie"
+        );
+      }
+    },
+    {
+      name: "a retired row is gone from every read",
+      run: async () => {
+        await subject.reset();
+        await ask.upsert(A2, one, first);
+        const retired = await ask.retire(A2, one);
+        (0, import_conformance3.assertSame)(retired.retired, first, "a retire did not answer with the body it took away");
+        (0, import_conformance3.assertIs)(await ask.get(A2, one), null, "a retired row was still read back by its key");
+        (0, import_conformance3.assertIs)((await ask.listAll(A2)).length, 0, "a retired row was still listed");
+      }
+    },
+    {
+      name: "the undo of an upsert puts back the body that was there",
+      run: async () => {
+        await subject.reset();
+        await ask.upsert(A2, one, first);
+        const replaced = await ask.upsert(A2, one, second);
+        await subject.entity.undos.upsert(subject.connection, {
+          output: replaced,
+          tenantId: A2
+        });
+        const found = await ask.get(A2, one);
+        (0, import_conformance3.assertSame)(
+          found === null ? null : subject.bodyOf(found),
+          first,
+          "the compensation for a write left the new body in place: a run that failed after this step is a run whose write stood"
+        );
+      }
+    },
+    {
+      name: "the undo of an upsert that created the row retires it",
+      run: async () => {
+        await subject.reset();
+        const created = await ask.upsert(A2, one, first);
+        await subject.entity.undos.upsert(subject.connection, { output: created, tenantId: A2 });
+        (0, import_conformance3.assertIs)(
+          await ask.get(A2, one),
+          null,
+          "the compensation for a write that created a row left the row behind, because it restored a body that was never there"
+        );
+      }
+    },
+    {
+      name: "the undo of a retire writes the row back",
+      run: async () => {
+        await subject.reset();
+        await ask.upsert(A2, one, first);
+        const retired = await ask.retire(A2, one);
+        await subject.entity.undos.retire(subject.connection, { output: retired, tenantId: A2 });
+        const found = await ask.get(A2, one);
+        (0, import_conformance3.assertSame)(
+          found === null ? null : subject.bodyOf(found),
+          first,
+          "the compensation for a retire did not bring the row back"
+        );
+      }
+    },
+    {
+      name: "the undo of a retire that retired nothing writes nothing",
+      run: async () => {
+        await subject.reset();
+        const retired = await ask.retire(A2, one);
+        await subject.entity.undos.retire(subject.connection, { output: retired, tenantId: A2 });
+        (0, import_conformance3.assertIs)(
+          (await ask.listAll(A2)).length,
+          0,
+          "the compensation for a retire that found no row wrote one: an undo that invents a row is worse than one that does nothing"
+        );
+      }
+    },
+    {
+      name: "a write in a session is five statements, the row it replaces locked before the insert",
+      run: async () => {
+        const recording = subject.recording;
+        if (typeof recording !== "function") {
+          throw new import_conformance3.ConformanceFailure(
+            "this subject has no `recording`, and the write census is a count of what reached the server: supply a handle that reports the statements it sends \u2014 a driver log hook is usually one line \u2014 or this claim is untested rather than passing"
+          );
+        }
+        await subject.reset();
+        const recorded = await recording();
+        try {
+          await subject.entity.upsert(recorded.connection, {
+            ...ask.at(A2, one),
+            body: first
+          });
+        } finally {
+          await recorded.close();
+        }
+        const { statements } = recorded;
+        const found = (pattern) => statements.filter((sent) => pattern.test(sent)).length;
+        (0, import_conformance3.assertIs)(
+          found(/savepoint/i),
+          0,
+          `the write opened a savepoint, which means a nested transaction per statement: ${statements.join(" | ")}`
+        );
+        (0, import_conformance3.assertIs)(
+          found(/set_config/i),
+          1,
+          `the tenant was named ${found(/set_config/i)} times for one write: ${statements.join(" | ")}`
+        );
+        (0, import_conformance3.assertThat)(
+          statements.findIndex((sent) => /for update/i.test(sent)) < statements.findIndex((sent) => /on conflict/i.test(sent)),
+          `the row was written before it was read under a lock, or never locked at all: at READ COMMITTED the pre-image is then whatever a concurrent commit left, and the undo restores a version this write never replaced \u2014 ${statements.join(" | ")}`
+        );
+        (0, import_conformance3.assertIs)(
+          statements.length,
+          5,
+          `a write in a session is the transaction, the tenant, the locked read, the write and the commit: a sixth is a round trip somebody added \u2014 ${statements.join(" | ")}`
+        );
+      }
+    },
+    {
+      name: "the wall on this entity\u2019s table reads the setting names it was rendered with",
+      run: async () => {
+        const wall = subject.wall;
+        if (wall === void 0) {
+          throw new import_conformance3.ConformanceFailure(
+            'this subject names no `wall`, and "the DDL, the policies and the session name the same two settings" is the claim a table rendered with the defaults cannot make: supply the settings, the ops lever and an unfiltered count \u2014 or this claim is untested rather than passing'
+          );
+        }
+        await subject.reset();
+        await ask.upsert(A2, one, first);
+        await ask.upsert(B2, two, second);
+        (0, import_conformance3.assertIs)(
+          (await ask.listAll(A2)).length,
+          1,
+          `a tenant saw more than its own rows on a table whose isolation policy reads "${wall.settings.tenantSetting}": the DDL was rendered with one setting name and the session names another, so the policy compares against nothing`
+        );
+        (0, import_conformance3.assertIs)(
+          await wall.inOps((tx) => wall.countAll(tx)),
+          2,
+          `the ops lever saw ${await wall.inOps((tx) => wall.countAll(tx))} of 2 rows on a table whose maintenance policy reads "${wall.settings.opsSetting}": every sweep, backfill and repair on this entity has to be run once per tenant or not at all`
+        );
+      }
+    },
+    {
+      name: "one tenant never reaches another\u2019s rows through any verb",
+      run: async () => {
+        await subject.reset();
+        await ask.upsert(A2, one, first);
+        await ask.upsert(B2, two, second);
+        (0, import_conformance3.assertIs)(await ask.get(B2, one), null, "a tenant read a row belonging to another by its key");
+        (0, import_conformance3.assertIs)(
+          (await ask.listAll(B2)).length,
+          1,
+          "a tenant listed rows belonging to another: the verbs are scoped, the wall is not, or both"
+        );
+        (0, import_conformance3.assertIs)(
+          (await ask.retire(B2, one)).retired,
+          null,
+          "a tenant retired a row belonging to another, and was told what it took away"
+        );
+        (0, import_conformance3.assertThat)(
+          await ask.get(A2, one) !== null,
+          "the row of the first tenant is gone after the second tried to retire it"
+        );
+        (0, import_conformance3.assertIs)(await ask.get(A2, three), null, "a key nobody wrote answered with a row");
+      }
+    }
+  ];
+};
+
+// src/policies.ts
+var settingRead = (name) => `(select current_setting(${literal(name)}, true))`;
+var both = (predicate) => `using (${predicate}) with check (${predicate})`;
+var DEFAULT_NAMES = {
+  freeze: "not_frozen",
+  isolation: "tenant_isolation",
+  opsMaintenance: "ops_maintenance"
+};
+var TOKEN = /^\{\{[A-Za-z][A-Za-z0-9_]*\}\}$/;
+var templated = (settings) => TOKEN.test(settings.tenantSetting) || TOKEN.test(settings.opsSetting);
+var readForDdl = (settings) => templated(settings) ? { opsValue: settings.opsValue ?? DEFAULT_OPS_VALUE, ...settings } : readSettings(settings);
+var tenantPolicySet = (options) => {
+  const settings = readForDdl(options.settings);
+  const names = { ...DEFAULT_NAMES, ...options.names };
+  const tenant = settingRead(settings.tenantSetting);
+  const opsIsOn = `${settingRead(settings.opsSetting)} = ${literal(settings.opsValue)}`;
+  const frozen = options.freeze;
+  return [
+    {
+      as: "permissive",
+      name: names.isolation,
+      predicate: `${quoted(options.tenantColumn)} = ${tenant}`
+    },
+    { as: "permissive", name: names.opsMaintenance, predicate: opsIsOn },
+    ...frozen === void 0 ? [] : [
+      {
+        as: "restrictive",
+        name: names.freeze,
+        predicate: `${opsIsOn} or not exists (select 1 from ${quoted(frozen.table)} where ${quoted(frozen.tenantColumn)} = ${tenant})`
+      }
+    ]
+  ];
+};
+var drizzleTenantPolicies = (tools, options) => tenantPolicySet(options).map(
+  (policy) => tools.pgPolicy(policy.name, {
+    as: policy.as,
+    for: "all",
+    using: tools.sql.raw(policy.predicate),
+    withCheck: tools.sql.raw(policy.predicate)
+  })
+);
+var forceRowLevelSecurity = (table, schema) => `alter table ${qualified(table, schema)} force row level security`;
+var tenantPolicies = (table, options) => {
+  const on = qualified(table, options.schema);
+  return [
+    `alter table ${on} enable row level security`,
+    forceRowLevelSecurity(table, options.schema),
+    ...tenantPolicySet(options).flatMap((policy) => [
+      `drop policy if exists ${quoted(policy.name)} on ${on}`,
+      `create policy ${quoted(policy.name)} on ${on} as ${policy.as} for all ${both(policy.predicate)}`
+    ])
+  ];
+};
+
+// src/entity-ddl.ts
+var ENTITY_PLACEHOLDERS = {
+  opsSetting: "{{opsSetting}}",
+  tenantSetting: "{{tenantSetting}}"
+};
+var DEFAULT_COLUMNS2 = {
+  body: "body",
+  createdAt: "created_at",
+  retiredAt: "retired_at",
+  tenant: "tenant_id",
+  updatedAt: "updated_at"
+};
+var NAME = /^[A-Za-z_][A-Za-z0-9_$]*$/;
+var readName = (name) => {
+  if (!NAME.test(name)) {
+    throw new DbRefusal(
+      `"${name}" is not a name this DDL can write: it is inlined into every statement inside double quotes, and a name outside \`letter_or_underscore followed by letters, digits, underscores or $\` could close them`
+    );
+  }
+  return name;
+};
+var accepted = (because, rules, statement) => `-- ${because}
+-- squawk-ignore ${rules.join(", ")}
+${statement}`;
+var TIMEOUTS_BELONG_TO_THE_DEPLOYMENT = "lock_timeout and statement_timeout are one deployment\u2019s numbers, and a value written into shipped DDL imposes that deployment\u2019s budget on every consumer: set them in the session that migrates.";
+var IN_ONE_TRANSACTION = "The migrator applies this file inside a transaction, which is also why CONCURRENTLY is not available here; the index is created in the same migration as its table, over no rows.";
+var RERUNNABLE = "This file is applied inside a transaction and every statement in it is idempotent, so a run that fails part way through leaves nothing behind and a rerun is a no-op.";
+var settingRead2 = (name) => `current_setting(${literal(name)}, true)`;
+var columnOf = (one) => typeof one === "string" ? `${quoted(readName(one))} text` : `${quoted(readName(one.column))} ${one.type}`;
+var entityTable = (options) => {
+  const columns = { ...DEFAULT_COLUMNS2, ...options.columns };
+  const table = readName(options.table);
+  const on = qualified(table, options.schema);
+  const key = readName(options.key);
+  const listing = options.order.map((one) => `${quoted(readName(one.column))} ${one.direction === "desc" ? "desc" : "asc"}`).join(", ");
+  return [
+    `create table if not exists ${on} (
+  ${quoted(columns.tenant)} text not null default ${settingRead2(options.settings.tenantSetting)},
+  ${quoted(key)} text not null,
+  ${quoted(columns.body)} jsonb not null,
+  ${quoted(columns.createdAt)} bigint not null,
+  ${quoted(columns.updatedAt)} bigint not null,
+  ${quoted(columns.retiredAt)} bigint,${(options.indexed ?? []).map((one) => `
+  ${columnOf(one)},`).join("")}
+  constraint ${quoted(`${table}_pkey`)} primary key (${quoted(columns.tenant)}, ${quoted(key)})
+)`,
+    accepted(
+      `${IN_ONE_TRANSACTION} ${TIMEOUTS_BELONG_TO_THE_DEPLOYMENT}`,
+      ["require-concurrent-index-creation", "require-lock-timeout", "require-statement-timeout"],
+      `create index if not exists ${quoted(`${table}_listing_idx`)} on ${on} (${quoted(columns.tenant)}, ${listing})`
+    )
+  ];
+};
+var both2 = (predicate) => `using (${predicate}) with check (${predicate})`;
+var entityPolicies = (options) => {
+  const columns = { ...DEFAULT_COLUMNS2, ...options.columns };
+  const on = qualified(readName(options.table), options.schema);
+  const wall = {
+    settings: options.settings,
+    tenantColumn: columns.tenant,
+    ...options.schema === void 0 ? {} : { schema: options.schema }
+  };
+  return [
+    accepted(
+      `${RERUNNABLE} ${TIMEOUTS_BELONG_TO_THE_DEPLOYMENT}`,
+      ["prefer-robust-stmts", "require-lock-timeout", "require-statement-timeout"],
+      `alter table ${on} enable row level security`
+    ),
+    accepted(RERUNNABLE, ["prefer-robust-stmts"], `alter table ${on} force row level security`),
+    ...tenantPolicySet(wall).flatMap((policy) => [
+      `drop policy if exists ${quoted(policy.name)} on ${on}`,
+      `create policy ${quoted(policy.name)} on ${on} as ${policy.as} for all ${both2(policy.predicate)}`
+    ])
+  ];
+};
+var entityMigrations = (options) => {
+  const table = readName(options.table);
+  return [
+    { name: `0001_${table}.sql`, statements: entityTable(options) },
+    { name: `0002_${table}_policies.sql`, statements: entityPolicies(options) }
+  ];
+};
+
 // src/node-postgres.ts
 var import_promises = require("fs/promises");
 var import_node_path = require("path");
@@ -482,10 +1544,10 @@ var drivingPg = (module2) => {
 };
 var values = (statement) => statement.params === void 0 ? void 0 : [...statement.params];
 var DEFAULT_MIGRATIONS_TABLE = "geonosis_db_migrations";
-var nodePostgresDriver = async (options = {}) => {
+var nodePostgresDriver = (async (options = {}) => {
   const pg = drivingPg(options.pg ?? await loadPg());
   const ledger = quoted(options.migrationsTable ?? DEFAULT_MIGRATIONS_TABLE);
-  const open = (connectionString, opened = {}) => {
+  const openPort = (connectionString, opened = {}) => {
     const say = opened.onStatement ?? (() => {
     });
     const pool = new pg.Pool({
@@ -498,31 +1560,33 @@ var nodePostgresDriver = async (options = {}) => {
       say(statement.text);
       return run(statement.text, values(statement));
     };
-    return {
-      close: () => pool.end(),
-      connection: {
-        execute: (statement) => sent((text, params) => pool.query(text, params), statement),
-        transaction: async (run) => {
-          const client = await pool.connect();
-          try {
-            say("begin");
-            await client.query("begin");
-            const result = await run({
-              execute: (statement) => sent((text, params) => client.query(text, params), statement)
-            });
-            say("commit");
-            await client.query("commit");
-            return result;
-          } catch (error) {
-            say("rollback");
-            await client.query("rollback").catch(() => void 0);
-            throw error;
-          } finally {
-            client.release();
-          }
+    const overThePort = {
+      execute: (statement) => sent((text, params) => pool.query(text, params), statement),
+      transaction: async (run) => {
+        const client = await pool.connect();
+        try {
+          say("begin");
+          await client.query("begin");
+          const result = await run({
+            execute: (statement) => sent((text, params) => client.query(text, params), statement)
+          });
+          say("commit");
+          await client.query("commit");
+          return result;
+        } catch (error) {
+          say("rollback");
+          await client.query("rollback").catch(() => void 0);
+          throw error;
+        } finally {
+          client.release();
         }
       }
     };
+    return { close: () => pool.end(), connection: overThePort, pool };
+  };
+  const open = (connectionString, opened = {}) => {
+    const held = openPort(connectionString, opened);
+    return options.drizzle === void 0 ? held : { close: held.close, connection: options.drizzle(held.pool, opened) };
   };
   return {
     /**
@@ -531,21 +1595,21 @@ var nodePostgresDriver = async (options = {}) => {
      * of their own passes their own `Driver` and this is never called.
      */
     migrate: async (connectionString, migrationsFolder) => {
-      const held = open(connectionString, { poolSize: 1 });
+      const held = openPort(connectionString, { poolSize: 1 });
       try {
         await held.connection.execute({
           text: `create table if not exists ${ledger} (name text primary key, applied_at timestamptz not null default now())`
         });
         const files = (await (0, import_promises.readdir)(migrationsFolder)).filter((name) => name.endsWith(".sql")).toSorted();
         for (const name of files) {
-          const sql = await (0, import_promises.readFile)((0, import_node_path.join)(migrationsFolder, name), "utf8");
+          const sql2 = await (0, import_promises.readFile)((0, import_node_path.join)(migrationsFolder, name), "utf8");
           await held.connection.transaction(async (tx) => {
             const applied = await tx.execute({
               params: [name],
               text: `select name from ${ledger} where name = $1`
             });
             if (applied.rows.length > 0) return;
-            await tx.execute({ text: sql });
+            await tx.execute({ text: sql2 });
             await tx.execute({ params: [name], text: `insert into ${ledger} (name) values ($1)` });
           });
         }
@@ -555,120 +1619,37 @@ var nodePostgresDriver = async (options = {}) => {
     },
     open
   };
-};
-
-// src/settings.ts
-var DEFAULT_OPS_VALUE = "on";
-var CUSTOM_SETTING = /^[A-Za-z_][A-Za-z0-9_]*\.[A-Za-z_][A-Za-z0-9_]*$/;
-var readSettings = (settings) => {
-  for (const named of ["opsSetting", "tenantSetting"]) {
-    const name = settings[named];
-    if (typeof name !== "string" || name === "") {
-      throw new DbRefusal(
-        `${named} is required and has no default: the name of a session setting is the one thing this package cannot pick for you, because the policies and the seam have to agree on it exactly`
-      );
-    }
-    if (!CUSTOM_SETTING.test(name)) {
-      throw new DbRefusal(
-        `${named} is "${name}", and Postgres reads a setting an application defines as \`prefix.name\` \u2014 anything else is rejected as unrecognised the first time a session sets it`
-      );
-    }
-  }
-  return { ...settings, opsValue: settings.opsValue ?? DEFAULT_OPS_VALUE };
-};
-
-// src/policies.ts
-var settingRead = (name) => `(select current_setting(${literal(name)}, true))`;
-var both = (predicate) => `using (${predicate}) with check (${predicate})`;
-var DEFAULT_NAMES = {
-  freeze: "not_frozen",
-  isolation: "tenant_isolation",
-  opsMaintenance: "ops_maintenance"
-};
-var tenantPolicies = (table, options) => {
-  const settings = readSettings(options.settings);
-  const names = { ...DEFAULT_NAMES, ...options.names };
-  const on = qualified(table, options.schema);
-  const tenant = settingRead(settings.tenantSetting);
-  const opsIsOn = `${settingRead(settings.opsSetting)} = ${literal(settings.opsValue)}`;
-  const policy = (name, as, predicate) => [
-    `drop policy if exists ${quoted(name)} on ${on}`,
-    `create policy ${quoted(name)} on ${on} as ${as} for all ${both(predicate)}`
-  ];
-  const frozen = options.freeze;
-  const notFrozen = frozen === void 0 ? [] : policy(
-    names.freeze,
-    "restrictive",
-    `${opsIsOn} or not exists (select 1 from ${quoted(frozen.table)} where ${quoted(frozen.tenantColumn)} = ${tenant})`
-  );
-  return [
-    `alter table ${on} enable row level security`,
-    `alter table ${on} force row level security`,
-    ...policy(names.isolation, "permissive", `${quoted(options.tenantColumn)} = ${tenant}`),
-    ...policy(names.opsMaintenance, "permissive", opsIsOn),
-    ...notFrozen
-  ];
-};
-
-// src/session.ts
-var OPS = /* @__PURE__ */ Symbol("the ops lever");
-var scopeOf = /* @__PURE__ */ new WeakMap();
-var describe = (scope) => scope === OPS ? "the ops lever" : `tenant ${JSON.stringify(scope)}`;
-var canOpen = (executor) => typeof executor.transaction === "function";
-var createSessionSeam = (config) => {
-  const settings = readSettings(config.settings);
-  const contextOf = (scope) => {
-    if (scope !== OPS) {
-      return { params: [settings.tenantSetting, scope], text: "select set_config($1, $2, true)" };
-    }
-    return config.opsStatementTimeout === void 0 ? {
-      params: [settings.opsSetting, settings.opsValue],
-      text: "select set_config($1, $2, true)"
-    } : {
-      params: [settings.opsSetting, settings.opsValue, config.opsStatementTimeout],
-      text: "select set_config($1, $2, true), set_config('statement_timeout', $3, true)"
-    };
-  };
-  const opened = async (executor, scope, run) => {
-    const current = scopeOf.get(executor);
-    if (current === scope) return run(executor);
-    if (current !== void 0) {
-      throw new DbRefusal(
-        `this transaction is open for ${describe(current)} and was asked for ${describe(scope)}: a transaction names one scope, and the second query would run behind the first one's policy`
-      );
-    }
-    if (!canOpen(executor)) {
-      throw new DbRefusal(
-        `this executor is in no session and cannot open a transaction, so ${describe(scope)} has nothing to name \u2014 pass the connection, or run it inside a session already open for that scope`
-      );
-    }
-    return executor.transaction(async (tx) => {
-      await tx.execute(contextOf(scope));
-      scopeOf.set(tx, scope);
-      return run(tx);
-    });
-  };
-  return {
-    inOps: (executor, run) => opened(executor, OPS, run),
-    inTenant: (executor, tenantId, run) => opened(executor, tenantId, run),
-    scoped: (query) => (executor, params) => opened(executor, params.tenantId, (tx) => query(tx, params)),
-    scopedAsOps: (query) => (executor, params) => opened(executor, OPS, (tx) => query(tx, params))
-  };
-};
+});
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  DEFAULT_ENTITY_PAGE,
   DEFAULT_OPS_VALUE,
+  DEFAULT_TENANT_KEY,
   DbRefusal,
+  ENTITY_PLACEHOLDERS,
+  MAX_ENTITY_PAGE,
   appConnectionString,
   appRoleStatements,
+  asStatement,
   concurrentTenantsConformance,
+  connectionsConformance,
   createConnections,
   createSessionSeam,
+  defineEntity,
+  drizzleSession,
+  drizzleTenantPolicies,
+  entityConformance,
+  entityMigrations,
+  forceRowLevelSecurity,
   forcedRowLevelSecurityConformance,
+  fragment,
   nodePostgresDriver,
   perStepConnection,
+  scopedQueryConformance,
   sessionConformance,
   statementCensusConformance,
   tenantIsolationConformance,
-  tenantPolicies
+  tenantPolicies,
+  tenantPolicySet,
+  undosOf
 });