@geonosis/db 0.2.0 → 0.3.0

package/README.md

@@ -42,6 +42,13 @@ const listInvoices = seam.scoped(async (executor, params: { tenantId: string })
 const sweep = seam.scopedAsOps(async (executor, params: { since: number }) => …)
 ```
 
+`scoped` reads the tenant out of a query's own parameters, under `DEFAULT_TENANT_KEY` — `tenantId`
+— or under the `tenantKey` the seam was built with, so a repo whose queries carry `{ orgId }` names
+the key once instead of wrapping every call site in `inTenant` by hand. The key is part of the
+type: parameters that do not carry it do not compile, and parameters that carry it as nothing at
+runtime are a `DbRefusal` naming the key rather than a query that quietly runs outside every
+session.
+
 `tenantSetting` and `opsSetting` have NO defaults. The name of a session setting is the one thing
 this package cannot pick for you: the seam and the policies must agree on it exactly, and a default
 here would be one repo's name compiled into every other repo's wall. `opsValue` defaults to
@@ -125,6 +132,17 @@ instead of something every caller threads through. `sessionDb()` resolves the in
 and REFUSES outside a frame, where a handle it opened would be closed by nobody — the repo this
 came from returns one there and says so in a comment. `open()` is for a caller who will close it.
 
+A handle does not outlive its invocation: used after the frame that opened it has ended, it answers
+with a `DbRefusal` naming the unit of work it came from. Without that, the answer is the driver's,
+at whatever line the query sits on — `Cannot use a pool after calling end on the pool` from
+node-postgres, and on workerd a refusal to do I/O on behalf of another request — which reads as a
+bug in the query rather than as a lifetime that was crossed.
+
+A nested `withConnection` JOINS the invocation it is inside, so a request that reaches two
+databases still has one lifetime. A caller that needs its own frame regardless passes
+`InvocationOptions`: `withConnection(run, release, { named: 'charge', own: true })`. `named` is what
+a leaked handle is named with; `own` is what a durable step needs.
+
 `onStatement` reports every statement a handle sends, the transaction's own `begin` and `commit`
 included — a count of round trips that leaves those out is not a count of round trips. It is what
 the statement census reads.
@@ -151,6 +169,12 @@ outside on the runner's connection.
 createRuntime({ journal, scope: perStepConnection(records) })
 ```
 
+Each step opens its OWN frame, even when the entrypoint has already wrapped the whole run in one.
+A Cloudflare Workflows entrypoint that does that would otherwise hand every step the RUN's handle,
+and workerd refuses I/O on a socket opened for another request. `perStep(name)` takes the step's
+name where the caller has one — `RunScope` calls it with none — so a handle that leaked out of a
+step is refused naming the step it came from.
+
 The type is not imported in either direction. `@geonosis/db` and a workflow engine are sibling
 foundations, and what crosses between them is the shape.
 
@@ -180,7 +204,9 @@ against THEIR session — no test framework rides along; a case fails by throwin
 | `statementCensusConformance` | a read in a session is four statements: no savepoint, one `set_config`, and the tenant named before the read |
 | `concurrentTenantsConformance` | eight tenants at once on one pool, and the two refusals |
 | `forcedRowLevelSecurityConformance` | every guarded table forces RLS, so the owner is behind the wall too |
-| `sessionConformance` | all four |
+| `scopedQueryConformance` | a query that names its own tenant lands under it, refuses a second one, and refuses parameters carrying no tenant at all |
+| `sessionConformance` | all five |
+| `connectionsConformance` | the handle discipline: alive inside its invocation, refused outside one, refused after it, a frame of its own per step, and the leak named with the step it came from |
 
 ```ts
 for (const { name, run } of sessionConformance(subject)) {
@@ -188,4 +214,10 @@ for (const { name, run } of sessionConformance(subject)) {
 }
 ```
 
+`SeamUnderTest` carries `scoped` and the `tenantKey` those queries use — a seam with no `scoped` is
+REFUSED by name rather than passing a claim nothing was asked of. A `ConnectionsSubject` is
+`{ connections, perStep?, probe? }`: the `ConnectionsUnderTest` is `sessionDb` and `withConnection`,
+`perStep` is the per-step scope BY NAME, and `probe` is any statement the role may run (`select 1`
+when nothing is named).
+
 This package sits its own exam over `nodePostgresDriver` against a real Postgres, on both majors.

package/dist/index.cjs

@@ -31,15 +31,18 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var index_exports = {};
 __export(index_exports, {
   DEFAULT_OPS_VALUE: () => DEFAULT_OPS_VALUE,
+  DEFAULT_TENANT_KEY: () => DEFAULT_TENANT_KEY,
   DbRefusal: () => DbRefusal,
   appConnectionString: () => appConnectionString,
   appRoleStatements: () => appRoleStatements,
   concurrentTenantsConformance: () => concurrentTenantsConformance,
+  connectionsConformance: () => connectionsConformance,
   createConnections: () => createConnections,
   createSessionSeam: () => createSessionSeam,
   forcedRowLevelSecurityConformance: () => forcedRowLevelSecurityConformance,
   nodePostgresDriver: () => nodePostgresDriver,
   perStepConnection: () => perStepConnection,
+  scopedQueryConformance: () => scopedQueryConformance,
   sessionConformance: () => sessionConformance,
   statementCensusConformance: () => statementCensusConformance,
   tenantIsolationConformance: () => tenantIsolationConformance,
@@ -390,6 +393,60 @@ 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 probe = probeSql(subject.probe);
+  const key = subject.seam.tenantKey ?? "tenantId";
+  const insert = () => scopedOf(subject)(
+    (tx, params) => tx.execute(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) => tx.execute(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",
@@ -414,16 +471,114 @@ var forcedRowLevelSecurityConformance = (subject) => [
     }
   }
 ];
+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 probe = subject.probe ?? { text: "select 1" };
+  const CHARGE = "charge";
+  const SHIP = "ship";
+  return [
+    {
+      name: "a handle inside its invocation answers",
+      run: () => subject.connections.withConnection(async () => {
+        await subject.connections.sessionDb().execute(probe);
+      })
+    },
+    {
+      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 held.execute(probe);
+        });
+        await (0, import_conformance.assertRefuses)(
+          () => held.execute(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 ofTheStep.execute(probe);
+        });
+        await ofTheRun.execute(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 charged.execute(probe);
+        });
+        await perStep(SHIP)(
+          () => (0, import_conformance.assertRefuses)(
+            () => charged.execute(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 guarded = (frame, connection) => {
+  const stillOpen = () => {
+    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.`
+    );
+  };
+  return {
+    execute: async (statement) => {
+      stillOpen();
+      return connection.execute(statement);
+    },
+    transaction: async (run) => {
+      stillOpen();
+      return connection.transaction(run);
+    }
+  };
+};
 var createConnections = (config) => {
   const opened = () => config.open === void 0 ? config.driver.open(config.connectionString) : config.driver.open(config.connectionString, config.open);
   return {
@@ -436,25 +591,38 @@ 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: guarded(frame, open.connection), 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/node-postgres.ts
@@ -615,8 +783,15 @@ 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 DEFAULT_TENANT_KEY = "tenantId";
 var createSessionSeam = (config) => {
   const settings = readSettings(config.settings);
+  const tenantKey = config.tenantKey ?? DEFAULT_TENANT_KEY;
+  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 { params: [settings.tenantSetting, scope], text: "select set_config($1, $2, true)" };
@@ -648,25 +823,37 @@ var createSessionSeam = (config) => {
       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: (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)),
+    scoped: (query) => async (executor, params) => opened(executor, named(params), (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_OPS_VALUE,
+  DEFAULT_TENANT_KEY,
   DbRefusal,
   appConnectionString,
   appRoleStatements,
   concurrentTenantsConformance,
+  connectionsConformance,
   createConnections,
   createSessionSeam,
   forcedRowLevelSecurityConformance,
   nodePostgresDriver,
   perStepConnection,
+  scopedQueryConformance,
   sessionConformance,
   statementCensusConformance,
   tenantIsolationConformance,

package/dist/index.d.cts

@@ -68,6 +68,13 @@ type RecordingConnection = {
 type SeamUnderTest = {
     inOps: <Result>(executor: Executor, run: (tx: Executor) => Promise<Result>) => Promise<Result>;
     inTenant: <Result>(executor: Executor, tenantId: string, run: (tx: Executor) => Promise<Result>) => Promise<Result>;
+    /**
+     * The wrapper that reads the tenant out of a query's own parameters. Spelled here rather than
+     * imported: what the exam asks about is the behaviour, and a consumer's seam is their own type.
+     */
+    scoped?: <Params extends Readonly<Record<string, string>>, Result>(query: (executor: Executor, params: Params) => Promise<Result>) => (executor: Executor, params: Params) => Promise<Result>;
+    /** The key those parameters carry the tenant under. `tenantId` when the seam names none. */
+    tenantKey?: string;
 };
 /**
  * A table under the policies under test, whose only required columns are these two.
@@ -113,14 +120,58 @@ declare const statementCensusConformance: (subject: SessionSubject) => Conforman
  * and the one a pooled connection carrying a stale setting would fail.
  */
 declare const concurrentTenantsConformance: (subject: SessionSubject) => ConformanceCase[];
+/**
+ * A query that names its own tenant, under the key the CONSUMER's queries carry it in (#245).
+ *
+ * A seam that reads only `tenantId` sends every repo whose queries say something else back through
+ * `inTenant` with a wrapper per call site, which is the hand-written scope the seam exists to
+ * remove — and a wrapper that reads a key nobody carries names `undefined`, which is not a tenant
+ * and, before this, was not a refusal either.
+ */
+declare const scopedQueryConformance: (subject: SessionSubject) => ConformanceCase[];
 /**
  * ENABLE alone exempts the table's OWNER, and the owner is the role that migrates and the role an
  * ops sweep connects as. A wall only the application is behind is a wall with a door in it.
  */
 declare const forcedRowLevelSecurityConformance: (subject: SessionSubject) => ConformanceCase[];
+/** As much of a handle keeper as the exam asks about. */
+type ConnectionsUnderTest = {
+    sessionDb: () => Connection;
+    withConnection: <Result>(run: () => Promise<Result>, release?: (closing: Promise<void>) => void) => Promise<Result>;
+};
+type ConnectionsSubject = {
+    connections: ConnectionsUnderTest;
+    /**
+     * A unit of work, by name. A durable step's handle is the one that outlives its step, and a
+     * refusal that cannot say WHICH step leaked sends a reader through every step in the workflow.
+     */
+    perStep?: (named: string) => <Output>(body: () => Promise<Output>) => Promise<Output>;
+    /** Something any role may run. The exam asks a handle a question rather than assuming a table. */
+    probe?: Statement;
+};
+/**
+ * The handle discipline: a connection belongs to the invocation that opened it and to no other.
+ *
+ * A serverless invocation hibernates and dies, so a handle held across one is a socket nobody is on
+ * the other end of. Held inside the process that opened it, the failure is a driver's own error at
+ * some later line — "Cannot use a pool after calling end on the pool" — which reads as a bug in the
+ * query rather than as a handle used out of its lifetime.
+ */
+declare const connectionsConformance: (subject: ConnectionsSubject) => ConformanceCase[];
 /** The whole exam: what a consumer runs against their own session before depending on it. */
 declare const sessionConformance: (subject: SessionSubject) => ConformanceCase[];
 
+/** What one invocation may be told about itself, for the refusal a handle that outlives it raises. */
+type InvocationOptions = {
+    /** The unit of work this frame is, so a leaked handle is named with what leaked it. */
+    named?: string;
+    /**
+     * A frame of its own even when this call is nested inside one. A durable step needs it: an
+     * entrypoint that wraps the whole run in an invocation would otherwise hand every step the RUN's
+     * handle, and workerd refuses I/O on a socket opened for another request.
+     */
+    own?: boolean;
+};
 type OpenOptions = {
     /**
      * Every statement this handle sends, as it is sent — the transaction's own begin and commit
@@ -157,7 +208,7 @@ type Connections = {
     open: () => OpenConnection;
     /** The handle this invocation is using, opened on first ask. */
     sessionDb: () => Connection;
-    withConnection: <Result>(run: () => Promise<Result>, release?: (closing: Promise<void>) => void) => Promise<Result>;
+    withConnection: <Result>(run: () => Promise<Result>, release?: (closing: Promise<void>) => void, invocation?: InvocationOptions) => Promise<Result>;
 };
 type ConnectionsConfig = {
     connectionString: string;
@@ -177,14 +228,18 @@ declare const createConnections: (config: ConnectionsConfig) => Connections;
  * The `scope.perStep` hook a workflow engine asks for, answered with a connection per unit of work.
  *
  * A durable run hibernates between steps, so the handle its first step opened is dead by the fifth:
- * each step body and each undo opens its own. The engine's own writes — the trail, the closing
- * batch — are not units of work and stay outside, on whatever connection the runner holds.
+ * each step body and each undo opens its own — its OWN frame, even when the entrypoint has already
+ * wrapped the whole run in one, because a step handed the run's handle is a step doing I/O for a
+ * request that has gone. The engine's own writes — the trail, the closing batch — are not units of
+ * work and stay outside, on whatever connection the runner holds.
  *
  * The type is not imported. `@geonosis/workflows` is a sibling foundation and the floors forbid an
- * edge between two of them in either direction; what crosses is the shape.
+ * edge between two of them in either direction; what crosses is the shape. `perStep` takes the
+ * step's name where the caller has one — `RunScope` calls it with none, and a frame with no name
+ * refuses by lifetime alone.
  */
 declare const perStepConnection: (connections: Pick<Connections, "withConnection">) => {
-    perStep: () => <Output>(body: () => Promise<Output>) => Promise<Output>;
+    perStep: (named?: string) => <Output>(body: () => Promise<Output>) => Promise<Output>;
 };
 
 /**
@@ -307,15 +362,14 @@ declare const tenantPolicies: (table: string, options: TenantPolicyOptions) => s
 
 /** A query that takes its session as an argument: what the seam wraps and what a provider writes. */
 type Query<Params, Result> = (executor: Executor, params: Params) => Promise<Result>;
-type SessionSeam = {
+declare const DEFAULT_TENANT_KEY = "tenantId";
+type SessionSeam<Key extends string = typeof DEFAULT_TENANT_KEY> = {
     inOps: <Result>(executor: Executor, run: (tx: Executor) => Promise<Result>) => Promise<Result>;
     inTenant: <Result>(executor: Executor, tenantId: string, run: (tx: Executor) => Promise<Result>) => Promise<Result>;
-    scoped: <Params extends {
-        tenantId: string;
-    }, Result>(query: Query<Params, Result>) => Query<Params, Result>;
+    scoped: <Params extends Readonly<Record<Key, string>>, Result>(query: Query<Params, Result>) => Query<Params, Result>;
     scopedAsOps: <Params, Result>(query: Query<Params, Result>) => Query<Params, Result>;
 };
-type SessionSeamConfig = {
+type SessionSeamConfig<Key extends string = typeof DEFAULT_TENANT_KEY> = {
     /**
      * How long a statement may run under the ops lever, as Postgres reads it. No default: a sweep's
      * budget is a fact about one deployment's data, and the value that fits belongs to whoever runs
@@ -323,6 +377,15 @@ type SessionSeamConfig = {
      */
     opsStatementTimeout?: string;
     settings: SessionSettings;
+    /**
+     * The key a query's own parameters carry its tenant under (#245). A repo whose queries say
+     * `{ orgId }` names it here instead of wrapping every call site in `inTenant` by hand.
+     *
+     * A key name rather than a selector, measured: under `tenantOf: (params) => string` nothing ties
+     * the selector's shape to the query's, and a query whose parameters carry no tenant at all
+     * compiles clean — which is the one thing `scoped` is here to make impossible.
+     */
+    tenantKey?: Key;
 };
 /**
  * The seam every query crosses: one transaction, the scope named as its first statement.
@@ -331,6 +394,6 @@ type SessionSeamConfig = {
  * the name is gone when the transaction ends, and a connection handed to the next request carries
  * nothing. Naming it second would leave the statements before it running under no tenant at all.
  */
-declare const createSessionSeam: (config: SessionSeamConfig) => SessionSeam;
+declare const createSessionSeam: <Key extends string = typeof DEFAULT_TENANT_KEY>(config: SessionSeamConfig<Key>) => SessionSeam<Key>;
 
-export { type AppRoleOptions, type ConformanceCase, type Connection, type Connections, type ConnectionsConfig, DEFAULT_OPS_VALUE, DbRefusal, type Driver, type Executor, type FreezeRegister, type NodePostgresOptions, type OpenConnection, type OpenOptions, type PgClientLike, type PgModuleLike, type PgPoolLike, type ProbeTable, type Query, type RecordingConnection, type SeamUnderTest, type SessionSeam, type SessionSeamConfig, type SessionSettings, type SessionSubject, type Statement, type TenantPolicyNames, type TenantPolicyOptions, appConnectionString, appRoleStatements, concurrentTenantsConformance, createConnections, createSessionSeam, forcedRowLevelSecurityConformance, nodePostgresDriver, perStepConnection, sessionConformance, statementCensusConformance, tenantIsolationConformance, tenantPolicies };
+export { type AppRoleOptions, type ConformanceCase, type Connection, type Connections, type ConnectionsConfig, type ConnectionsSubject, type ConnectionsUnderTest, DEFAULT_OPS_VALUE, DEFAULT_TENANT_KEY, DbRefusal, type Driver, type Executor, type FreezeRegister, type InvocationOptions, type NodePostgresOptions, type OpenConnection, type OpenOptions, type PgClientLike, type PgModuleLike, type PgPoolLike, type ProbeTable, type Query, type RecordingConnection, type SeamUnderTest, type SessionSeam, type SessionSeamConfig, type SessionSettings, type SessionSubject, type Statement, type TenantPolicyNames, type TenantPolicyOptions, appConnectionString, appRoleStatements, concurrentTenantsConformance, connectionsConformance, createConnections, createSessionSeam, forcedRowLevelSecurityConformance, nodePostgresDriver, perStepConnection, scopedQueryConformance, sessionConformance, statementCensusConformance, tenantIsolationConformance, tenantPolicies };

package/dist/index.d.ts

@@ -68,6 +68,13 @@ type RecordingConnection = {
 type SeamUnderTest = {
     inOps: <Result>(executor: Executor, run: (tx: Executor) => Promise<Result>) => Promise<Result>;
     inTenant: <Result>(executor: Executor, tenantId: string, run: (tx: Executor) => Promise<Result>) => Promise<Result>;
+    /**
+     * The wrapper that reads the tenant out of a query's own parameters. Spelled here rather than
+     * imported: what the exam asks about is the behaviour, and a consumer's seam is their own type.
+     */
+    scoped?: <Params extends Readonly<Record<string, string>>, Result>(query: (executor: Executor, params: Params) => Promise<Result>) => (executor: Executor, params: Params) => Promise<Result>;
+    /** The key those parameters carry the tenant under. `tenantId` when the seam names none. */
+    tenantKey?: string;
 };
 /**
  * A table under the policies under test, whose only required columns are these two.
@@ -113,14 +120,58 @@ declare const statementCensusConformance: (subject: SessionSubject) => Conforman
  * and the one a pooled connection carrying a stale setting would fail.
  */
 declare const concurrentTenantsConformance: (subject: SessionSubject) => ConformanceCase[];
+/**
+ * A query that names its own tenant, under the key the CONSUMER's queries carry it in (#245).
+ *
+ * A seam that reads only `tenantId` sends every repo whose queries say something else back through
+ * `inTenant` with a wrapper per call site, which is the hand-written scope the seam exists to
+ * remove — and a wrapper that reads a key nobody carries names `undefined`, which is not a tenant
+ * and, before this, was not a refusal either.
+ */
+declare const scopedQueryConformance: (subject: SessionSubject) => ConformanceCase[];
 /**
  * ENABLE alone exempts the table's OWNER, and the owner is the role that migrates and the role an
  * ops sweep connects as. A wall only the application is behind is a wall with a door in it.
  */
 declare const forcedRowLevelSecurityConformance: (subject: SessionSubject) => ConformanceCase[];
+/** As much of a handle keeper as the exam asks about. */
+type ConnectionsUnderTest = {
+    sessionDb: () => Connection;
+    withConnection: <Result>(run: () => Promise<Result>, release?: (closing: Promise<void>) => void) => Promise<Result>;
+};
+type ConnectionsSubject = {
+    connections: ConnectionsUnderTest;
+    /**
+     * A unit of work, by name. A durable step's handle is the one that outlives its step, and a
+     * refusal that cannot say WHICH step leaked sends a reader through every step in the workflow.
+     */
+    perStep?: (named: string) => <Output>(body: () => Promise<Output>) => Promise<Output>;
+    /** Something any role may run. The exam asks a handle a question rather than assuming a table. */
+    probe?: Statement;
+};
+/**
+ * The handle discipline: a connection belongs to the invocation that opened it and to no other.
+ *
+ * A serverless invocation hibernates and dies, so a handle held across one is a socket nobody is on
+ * the other end of. Held inside the process that opened it, the failure is a driver's own error at
+ * some later line — "Cannot use a pool after calling end on the pool" — which reads as a bug in the
+ * query rather than as a handle used out of its lifetime.
+ */
+declare const connectionsConformance: (subject: ConnectionsSubject) => ConformanceCase[];
 /** The whole exam: what a consumer runs against their own session before depending on it. */
 declare const sessionConformance: (subject: SessionSubject) => ConformanceCase[];
 
+/** What one invocation may be told about itself, for the refusal a handle that outlives it raises. */
+type InvocationOptions = {
+    /** The unit of work this frame is, so a leaked handle is named with what leaked it. */
+    named?: string;
+    /**
+     * A frame of its own even when this call is nested inside one. A durable step needs it: an
+     * entrypoint that wraps the whole run in an invocation would otherwise hand every step the RUN's
+     * handle, and workerd refuses I/O on a socket opened for another request.
+     */
+    own?: boolean;
+};
 type OpenOptions = {
     /**
      * Every statement this handle sends, as it is sent — the transaction's own begin and commit
@@ -157,7 +208,7 @@ type Connections = {
     open: () => OpenConnection;
     /** The handle this invocation is using, opened on first ask. */
     sessionDb: () => Connection;
-    withConnection: <Result>(run: () => Promise<Result>, release?: (closing: Promise<void>) => void) => Promise<Result>;
+    withConnection: <Result>(run: () => Promise<Result>, release?: (closing: Promise<void>) => void, invocation?: InvocationOptions) => Promise<Result>;
 };
 type ConnectionsConfig = {
     connectionString: string;
@@ -177,14 +228,18 @@ declare const createConnections: (config: ConnectionsConfig) => Connections;
  * The `scope.perStep` hook a workflow engine asks for, answered with a connection per unit of work.
  *
  * A durable run hibernates between steps, so the handle its first step opened is dead by the fifth:
- * each step body and each undo opens its own. The engine's own writes — the trail, the closing
- * batch — are not units of work and stay outside, on whatever connection the runner holds.
+ * each step body and each undo opens its own — its OWN frame, even when the entrypoint has already
+ * wrapped the whole run in one, because a step handed the run's handle is a step doing I/O for a
+ * request that has gone. The engine's own writes — the trail, the closing batch — are not units of
+ * work and stay outside, on whatever connection the runner holds.
  *
  * The type is not imported. `@geonosis/workflows` is a sibling foundation and the floors forbid an
- * edge between two of them in either direction; what crosses is the shape.
+ * edge between two of them in either direction; what crosses is the shape. `perStep` takes the
+ * step's name where the caller has one — `RunScope` calls it with none, and a frame with no name
+ * refuses by lifetime alone.
  */
 declare const perStepConnection: (connections: Pick<Connections, "withConnection">) => {
-    perStep: () => <Output>(body: () => Promise<Output>) => Promise<Output>;
+    perStep: (named?: string) => <Output>(body: () => Promise<Output>) => Promise<Output>;
 };
 
 /**
@@ -307,15 +362,14 @@ declare const tenantPolicies: (table: string, options: TenantPolicyOptions) => s
 
 /** A query that takes its session as an argument: what the seam wraps and what a provider writes. */
 type Query<Params, Result> = (executor: Executor, params: Params) => Promise<Result>;
-type SessionSeam = {
+declare const DEFAULT_TENANT_KEY = "tenantId";
+type SessionSeam<Key extends string = typeof DEFAULT_TENANT_KEY> = {
     inOps: <Result>(executor: Executor, run: (tx: Executor) => Promise<Result>) => Promise<Result>;
     inTenant: <Result>(executor: Executor, tenantId: string, run: (tx: Executor) => Promise<Result>) => Promise<Result>;
-    scoped: <Params extends {
-        tenantId: string;
-    }, Result>(query: Query<Params, Result>) => Query<Params, Result>;
+    scoped: <Params extends Readonly<Record<Key, string>>, Result>(query: Query<Params, Result>) => Query<Params, Result>;
     scopedAsOps: <Params, Result>(query: Query<Params, Result>) => Query<Params, Result>;
 };
-type SessionSeamConfig = {
+type SessionSeamConfig<Key extends string = typeof DEFAULT_TENANT_KEY> = {
     /**
      * How long a statement may run under the ops lever, as Postgres reads it. No default: a sweep's
      * budget is a fact about one deployment's data, and the value that fits belongs to whoever runs
@@ -323,6 +377,15 @@ type SessionSeamConfig = {
      */
     opsStatementTimeout?: string;
     settings: SessionSettings;
+    /**
+     * The key a query's own parameters carry its tenant under (#245). A repo whose queries say
+     * `{ orgId }` names it here instead of wrapping every call site in `inTenant` by hand.
+     *
+     * A key name rather than a selector, measured: under `tenantOf: (params) => string` nothing ties
+     * the selector's shape to the query's, and a query whose parameters carry no tenant at all
+     * compiles clean — which is the one thing `scoped` is here to make impossible.
+     */
+    tenantKey?: Key;
 };
 /**
  * The seam every query crosses: one transaction, the scope named as its first statement.
@@ -331,6 +394,6 @@ type SessionSeamConfig = {
  * the name is gone when the transaction ends, and a connection handed to the next request carries
  * nothing. Naming it second would leave the statements before it running under no tenant at all.
  */
-declare const createSessionSeam: (config: SessionSeamConfig) => SessionSeam;
+declare const createSessionSeam: <Key extends string = typeof DEFAULT_TENANT_KEY>(config: SessionSeamConfig<Key>) => SessionSeam<Key>;
 
-export { type AppRoleOptions, type ConformanceCase, type Connection, type Connections, type ConnectionsConfig, DEFAULT_OPS_VALUE, DbRefusal, type Driver, type Executor, type FreezeRegister, type NodePostgresOptions, type OpenConnection, type OpenOptions, type PgClientLike, type PgModuleLike, type PgPoolLike, type ProbeTable, type Query, type RecordingConnection, type SeamUnderTest, type SessionSeam, type SessionSeamConfig, type SessionSettings, type SessionSubject, type Statement, type TenantPolicyNames, type TenantPolicyOptions, appConnectionString, appRoleStatements, concurrentTenantsConformance, createConnections, createSessionSeam, forcedRowLevelSecurityConformance, nodePostgresDriver, perStepConnection, sessionConformance, statementCensusConformance, tenantIsolationConformance, tenantPolicies };
+export { type AppRoleOptions, type ConformanceCase, type Connection, type Connections, type ConnectionsConfig, type ConnectionsSubject, type ConnectionsUnderTest, DEFAULT_OPS_VALUE, DEFAULT_TENANT_KEY, DbRefusal, type Driver, type Executor, type FreezeRegister, type InvocationOptions, type NodePostgresOptions, type OpenConnection, type OpenOptions, type PgClientLike, type PgModuleLike, type PgPoolLike, type ProbeTable, type Query, type RecordingConnection, type SeamUnderTest, type SessionSeam, type SessionSeamConfig, type SessionSettings, type SessionSubject, type Statement, type TenantPolicyNames, type TenantPolicyOptions, appConnectionString, appRoleStatements, concurrentTenantsConformance, connectionsConformance, createConnections, createSessionSeam, forcedRowLevelSecurityConformance, nodePostgresDriver, perStepConnection, scopedQueryConformance, sessionConformance, statementCensusConformance, tenantIsolationConformance, tenantPolicies };

package/dist/index.js

@@ -348,6 +348,60 @@ var concurrentTenantsConformance = (subject) => {
     }
   ];
 };
+var scopedOf = (subject) => {
+  const scoped = subject.seam.scoped;
+  if (typeof scoped !== "function") {
+    throw new 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 probe = probeSql(subject.probe);
+  const key = subject.seam.tenantKey ?? "tenantId";
+  const insert = () => scopedOf(subject)(
+    (tx, params) => tx.execute(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 });
+        assertSame(
+          probe.tenantsOf(
+            await subject.seam.inOps(subject.connection, (tx) => tx.execute(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 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 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",
@@ -372,16 +426,114 @@ var forcedRowLevelSecurityConformance = (subject) => [
     }
   }
 ];
+var perStepOf = (subject) => {
+  const perStep = subject.perStep;
+  if (typeof perStep !== "function") {
+    throw new 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 probe = subject.probe ?? { text: "select 1" };
+  const CHARGE = "charge";
+  const SHIP = "ship";
+  return [
+    {
+      name: "a handle inside its invocation answers",
+      run: () => subject.connections.withConnection(async () => {
+        await subject.connections.sessionDb().execute(probe);
+      })
+    },
+    {
+      name: "a handle asked for outside every invocation is refused, naming what to wrap it in",
+      run: () => 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 held.execute(probe);
+        });
+        await assertRefuses(
+          () => held.execute(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();
+          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 ofTheStep.execute(probe);
+        });
+        await ofTheRun.execute(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 charged.execute(probe);
+        });
+        await perStep(SHIP)(
+          () => assertRefuses(
+            () => charged.execute(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
 import { AsyncLocalStorage } from "async_hooks";
 var invocation = new AsyncLocalStorage();
+var whose = (frame) => frame.named === void 0 ? "an invocation" : `the "${frame.named}" unit of work`;
+var guarded = (frame, connection) => {
+  const stillOpen = () => {
+    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.`
+    );
+  };
+  return {
+    execute: async (statement) => {
+      stillOpen();
+      return connection.execute(statement);
+    },
+    transaction: async (run) => {
+      stillOpen();
+      return connection.transaction(run);
+    }
+  };
+};
 var createConnections = (config) => {
   const opened = () => config.open === void 0 ? config.driver.open(config.connectionString) : config.driver.open(config.connectionString, config.open);
   return {
@@ -394,25 +546,38 @@ 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: guarded(frame, open.connection), 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/node-postgres.ts
@@ -573,8 +738,15 @@ 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 DEFAULT_TENANT_KEY = "tenantId";
 var createSessionSeam = (config) => {
   const settings = readSettings(config.settings);
+  const tenantKey = config.tenantKey ?? DEFAULT_TENANT_KEY;
+  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 { params: [settings.tenantSetting, scope], text: "select set_config($1, $2, true)" };
@@ -606,24 +778,36 @@ var createSessionSeam = (config) => {
       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: (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)),
+    scoped: (query) => async (executor, params) => opened(executor, named(params), (tx) => query(tx, params)),
     scopedAsOps: (query) => (executor, params) => opened(executor, OPS, (tx) => query(tx, params))
   };
 };
 export {
   DEFAULT_OPS_VALUE,
+  DEFAULT_TENANT_KEY,
   DbRefusal,
   appConnectionString,
   appRoleStatements,
   concurrentTenantsConformance,
+  connectionsConformance,
   createConnections,
   createSessionSeam,
   forcedRowLevelSecurityConformance,
   nodePostgresDriver,
   perStepConnection,
+  scopedQueryConformance,
   sessionConformance,
   statementCensusConformance,
   tenantIsolationConformance,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@geonosis/db",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "types": "./dist/index.d.ts",
   "description": "The consumer side of the executor port: a query-in-a-session type a domain provider imports, a tenant session seam whose set_config is the first statement of its transaction, an RLS policy generator, an app role whose password never enters logged DDL, and one handle per invocation.",
   "keywords": [