@geonosis/db 0.2.0 → 0.5.1

package/CHANGELOG.md

@@ -0,0 +1,151 @@
+# @geonosis/db
+
+## 0.5.1
+
+### Patch Changes
+
+- d15a654: The tarball carries `CHANGELOG.md`, so `geonosis update` can read what a db bump changed (#268) instead of naming the floor as unreadable — the line the other four floors already had.
+- Updated dependencies [d15a654]
+  - @geonosis/conformance@0.2.1
+
+## 0.5.0
+
+### Minor Changes
+
+- 5bc2eed: **`entityMigrations`: an entity's table and its wall, as the two files a consumer applies.** Four
+  exports added, none removed; the db door goes 78 → 82. `entityMigrations(options)` renders them;
+  `ENTITY_PLACEHOLDERS` is the pair a consumer whose migrator templates fills in, and is on the door
+  because passing it is how the token form is asked for; `EntityDdlOptions` and `EntityMigration` are
+  that call's argument and answer.
+  
+  The tenant column DEFAULTS to the session setting, so a write that names no tenant still lands under
+  the one its transaction is open for — the column and the policy then say the same thing, and neither
+  depends on a caller remembering. RLS is enabled AND forced, and the policies are the same
+  `tenantPolicySet` the DDL and drizzle doors both render, so a table has one wall however it was
+  created. Rendered with `ENTITY_PLACEHOLDERS` it is the same DDL carrying `{{tenantSetting}}` and
+  `{{opsSetting}}`, for a migrator that templates: a `{{token}}` is a hole a migrator fills rather than
+  a name Postgres is ever handed, so policy DDL accepts one where `createSessionSeam` still refuses it.
+  Every finding squawk 2.63.0 has on the rendered DDL is accepted on the statement it belongs to, with
+  the reason beside the rule names — 0 issues over both files, and the findings come back the moment an
+  acceptance is taken off. `geonosis-release schema` reads an entity's migrations with no change to
+  the gate. The exam's own entity table is this renderer's output, so the DDL and the generated verbs
+  are proven against each other on both Postgres majors — under this suite's own setting names and
+  under a second pair belonging to nothing else, so a default leaking into the renderer, the policies
+  or the session shows up as a wall that lets nothing through.
+- ccf04d8: **`defineEntity`: one payload table, one business key, every verb and both undos written once
+  (#251).** A payload table with a business key got the same ten things hand-written for it every
+  time — `get` / `list` / `listAll` / `upsert` / `retire`, the two compensations, a page envelope and a
+  keyset cursor — and every copy of that was a chance to forget the lock, the soft delete or the
+  tenant.
+  
+  Sixteen exports added, none removed; the db door goes 62 → 78. Each of them, and why it is on the
+  door rather than inside:
+  
+  - `defineEntity` — the declaration itself, and `undosOf(entity)`, the compensation registry as plain
+    data an engine reads by name (`@geonosis/db` and an engine are sibling foundations, so what
+    crosses between them is the shape).
+  - `EntityDefinition` — the argument, for a repo that builds one in a helper of its own; and
+    `EntityColumns`, `EntityOrdering`, `EntityRow` with it, because each is named inside it and a type
+    reachable from an exported one has to be reachable from the door.
+  - `Entity` — the return, for a signature that takes an entity; `EntityPage` — what `list` answers;
+    `EntityUndo`, `UpsertOutput`, `RetireOutput` — what an engine's registry names when it reads the
+    undos.
+  - `DEFAULT_ENTITY_PAGE`, `MAX_ENTITY_PAGE` — the bounds `list` clamps to, for an API layer that
+    validates its own page size against the same two numbers rather than restating them.
+  - `entityConformance`, `EntitySubject`, `EntityUnderTest` — the exam a consumer runs against their
+    own implementation.
+  
+  `SessionSeam` gains `send`, so a generated query is written over the seam alone and runs on
+  whichever kind of handle that seam was built for.
+  
+  Every verb goes through `scoped`, so a tenant is named before any of them runs and there is no door
+  on the entity that skips one (D-014). `list` is keyset on the listing index and reads one row more
+  than the page, because that extra row is the only honest way to know there is a next page;
+  `nextCursor` is absent on the last page rather than empty, and a cursor minted under another
+  ordering or another width is a `DbRefusal` rather than the first page served twice. The exam counts
+  what a WRITE costs, too — five statements, the row locked before the insert — so a round trip cannot
+  be added to an entity's write path silently, and it checks that the table's DDL, its policies and its
+  session all name the SAME two settings, which a table rendered with the defaults cannot show. `upsert` reads
+  the row it is about to replace under `for update` — at READ COMMITTED a plain select names the row
+  as it was before a concurrent commit, and the undo would then restore a version the write never
+  replaced — and calls a retired row's previous state nothing, so its undo retires again rather than
+  reviving. The exam runs over the executor port AND over a drizzle database, on Postgres 17.10 and
+  18.4.
+
+## 0.4.0
+
+### Minor Changes
+
+- 9d76504: **Drizzle-native: the seam, the driver, the handle and the wall (#250, #266, #267, #273).** A repo
+  whose queries are drizzle builders wrote an adapter for every one of those four, and now writes
+  none.
+  
+  Sixteen exports added, none removed. `drizzleSession(options?)` — a `SessionHandles<Db>` whose
+  `send` hands each of a statement's chunks to `sql.raw` and each of its values to `sql.param`, and
+  whose `transaction` hands the query drizzle's own `tx`, so no text with placeholders in it is
+  written for something else to read back out; the `SessionHandles<Handle>` and `SqlFragment` types a
+  consumer implements that port with, and `fragment` / `asStatement`, which are what implementing it
+  for a third library takes and are exported for that alone (the port's own default and the
+  `set_config` builder are NOT: nothing outside this package calls either); `drizzleTenantPolicies(tools,
+  options)` and `tenantPolicySet(options)`, the one policy source rendered as `pgPolicy` declarations
+  drizzle-kit generates a migration from; `forceRowLevelSecurity(table, schema?)`, the statement no
+  drizzle declaration can say (neither drizzle-orm 0.45.2 nor drizzle-kit 0.31.10 contains `FORCE ROW
+  LEVEL SECURITY` anywhere, measured 2026-09-02); the `DrizzleDatabase`, `DrizzleModuleLike`,
+  `DrizzleSql`, `DrizzleSessionOptions`, `DrizzlePolicyTools`, `TenantPolicy` and `DrizzleFactory`
+  types.
+  
+  CHANGED shapes, every one of them: `Driver<Handle = Connection>`, `OpenConnection<Handle>`,
+  `Connections<Handle>`, `ConnectionsConfig<Handle>` (new `over`) and `createConnections<Handle>` take
+  the handle a driver returns as a type parameter — a default-only change for the executor port, and
+  what lets `sessionDb()` answer with the database itself. `SessionSeam<Key, Handle>`,
+  `SessionSeamConfig<Key, Handle>` (new `over`) and `Query<Params, Result, Handle>` likewise; the seam
+  now also exposes `tenantKey`. `SessionSubject<Handle>`, `SeamUnderTest<Handle>`,
+  `RecordingConnection<Handle>`, `ConnectionsUnderTest<Handle>` and `ConnectionsSubject<Handle>` are
+  generic and take an optional `run` — the exam's own SQL now carries no parameters, so a handle of
+  any kind can be asked it as the text it is. `nodePostgresDriver({ drizzle })` returns
+  `Driver<Db>`. The ops lever's statement binds `statement_timeout` as a parameter rather than
+  inlining the name.
+  
+  #266, held by a new `connectionsConformance` case: `sessionDb()` used to rebuild the handle out of
+  the port, so everything a driver attached — the ORM database, its schema, its logger — was
+  `undefined` inside every scoped query (17 names dropped, measured). A handle now keeps everything
+  `open()` returned; the drizzle guard is a Proxy, because a database's surface is its builders.
+  `sessionConformance`, `connectionsConformance` and `tenantIsolationConformance` run over a drizzle
+  subject on Postgres 17.10 and 18.4, and a table whose policies were DECLARED is walled there too.
+  drizzle-orm is an OPTIONAL peer; a bundle importing only the seam carries no byte of it or of `pg`.
+
+## 0.3.0
+
+### Minor Changes
+
+- 91e1b2d: **`connectionsConformance`, and two handles that were nobody's (#246, #248).** The handle discipline
+  had no exam: a handle used after its invocation ended answered with the DRIVER's error at whatever
+  line the query sat on — `Cannot use a pool after calling end on the pool`, measured on Postgres 17
+  and 18 — which reads as a bug in the query. It is a `DbRefusal` now, naming the unit of work the
+  handle came from. And a step nested inside a run JOINED the run's invocation, so a Cloudflare
+  Workflows entrypoint that wrapped its run body in `withConnection` handed every step a socket opened
+  for another request, which workerd refuses: `perStepConnection` opens its own frame regardless of
+  nesting, and `perStep(name)` takes the step's name so a leak is named with the step that leaked it.
+  `withConnection` takes `InvocationOptions` (`named`, `own`) for a caller who needs the same; nested
+  reuse stays the default. The exam runs over `nodePostgresDriver` on both majors.
+- cb21027: **`scoped` reads the tenant under the key your queries carry (#245).** It could only read
+  `tenantId`, so a repo whose 200 queries say `{ orgId }` reached the seam through `inTenant` with a
+  wrapper per call site — the hand-written scope the seam exists to remove. `createSessionSeam` takes
+  `tenantKey`, default `tenantId` and exported as `DEFAULT_TENANT_KEY`, and the key stays in the type:
+  `scoped` on a seam built with `ownerId` will not compile a query whose parameters carry `tenantId`.
+  A key name rather than a selector, measured: under `tenantOf: (params) => string` a query carrying
+  no tenant at all compiles clean. Parameters that carry the key as nothing are now a `DbRefusal`
+  naming it — before, the seam named `undefined`, matched the executor's own empty scope, and ran the
+  query outside every session with no transaction and no `set_config` at all. `sessionConformance`
+  gains `scopedQueryConformance`, run here under a non-default key on Postgres 17 and 18.
+
+## 0.2.0
+
+### Minor Changes
+
+- 54fba77: **`DbRefusal`: everything this seam refuses, it refuses as a class (#211).** `session.ts` and `connections.ts` threw a bare `Error` — and the config validators threw `TypeError`, which is what a broken driver throws — so a caller could only recognise a refusal by matching its prose, and a conformance case could not tell one from a crash (#213). Every refusal in the package is now a `DbRefusal`, exported from the root, and the two conformance cases about the SEAM's own refusals assert the class.
+
+### Patch Changes
+
+- Updated dependencies [bb5e84b]
+  - @geonosis/conformance@0.2.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
@@ -114,7 +121,10 @@ const records = createConnections({
 
 export default {
   fetch: (request, env, ctx) =>
-    records.withConnection(() => handle(request), (closing) => ctx.waitUntil(closing)),
+    records.withConnection(
+      () => handle(request),
+      (closing) => ctx.waitUntil(closing),
+    ),
 }
 ```
 
@@ -125,6 +135,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 +172,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.
 
@@ -163,24 +190,160 @@ its own transaction, each recorded in `migrationsTable` so the next run skips it
 thing that can apply a folder. A consumer with a migrator of their own implements `Driver` around
 it, which is two methods.
 
+### On drizzle
+
+A repo whose queries are drizzle builders keeps them, and writes no adapter. Three doors, one for
+each thing it would otherwise have had to translate:
+
+```ts
+import { createConnections, createSessionSeam, drizzleSession, nodePostgresDriver } from '@geonosis/db'
+import * as drizzleOrm from 'drizzle-orm'
+import { drizzle } from 'drizzle-orm/node-postgres'
+
+const over = await drizzleSession<Database>({ drizzleOrm })
+const seam = createSessionSeam({ settings, tenantKey: 'orgId', over })
+const driver = await nodePostgresDriver({
+  drizzle: (pool, { onStatement }) =>
+    drizzle(pool, { schema, logger: { logQuery: (query) => onStatement?.(query) } }),
+})
+const records = createConnections({ connectionString, driver, over })
+
+const listInvoices = seam.scoped((db, params: { orgId: string }) =>
+  db.select().from(invoices),
+)
+```
+
+`over` is a `SessionHandles<Handle>`: how a session is opened on ONE kind of handle — `send`,
+`opens`, `transaction`, and the `guard` that holds a handle to its invocation. A seam given none
+drives the executor port's own.
+
+What `send` takes is a `SqlFragment`: the SQL between the values and the values themselves, one more
+chunk than there are values — a template literal's own shape, because that is what every library
+that places values already speaks. The executor port renders it to numbered placeholders with `asStatement`;
+`drizzleSession` hands each chunk to `sql.raw` and each value to `sql.param`, which places it as ONE
+parameter — drizzle's `sql` TAG spreads an array into a tuple, which is not the query anybody wrote.
+Nothing in the middle writes text with placeholders in it for something else to read back out.
+`fragment(chunks, values)` builds one; the two of them are what implementing `SessionHandles` for a
+third library takes, and are exported for that and nothing else.
+
+The driver's `drizzle` option is a factory rather than a flag, because a repo's database carries its
+own schema and options and a flag could only hand back one with neither. `open()` returns the
+DATABASE itself, unwrapped — so `sessionDb()` inside an invocation answers with what drizzle
+returned, builders and all (#266: a keeper that rebuilt the handle out of the port left every ORM
+handle `undefined` inside every scoped query, and `connectionsConformance` now holds it). The
+factory is handed this `open`'s `onStatement`, because drizzle sends its own `begin` and `commit`
+through the database where the driver cannot see them.
+
+The lifetime guard for a database is a Proxy: its surface is its builders, and a keeper that copies
+two methods off it hands the query something that cannot write a query.
+
+The tenant wall has ONE source and two doors. `tenantPolicySet` is the policies themselves — name,
+mode, predicate; `tenantPolicies` renders them as the DDL above, and `drizzleTenantPolicies` renders
+the same set as declarations for a table's own definition, so drizzle-kit generates the migration
+and a repo on drizzle applies the kit's wall rather than keeping a second one:
+
+```ts
+import { drizzleTenantPolicies, forceRowLevelSecurity } from '@geonosis/db'
+import { sql } from 'drizzle-orm'
+import { pgPolicy, pgTable, text } from 'drizzle-orm/pg-core'
+
+export const invoices = pgTable('invoices', { … }, () =>
+  drizzleTenantPolicies({ pgPolicy, sql }, { settings, tenantColumn: 'org_id' }),
+).enableRLS()
+```
+
+`DrizzlePolicyTools` is handed in rather than imported, so the door costs nothing to a consumer who
+never installed drizzle. FORCE is not among the declarations — neither drizzle-orm 0.45.2 nor
+drizzle-kit 0.31.10 contains the string `FORCE ROW LEVEL SECURITY` anywhere (measured 2026-09-02) —
+so `forceRowLevelSecurity(table)` is the one statement to apply beside the generated migration, and
+without it ENABLE alone exempts the table's owner.
+
+Hand drizzle-orm IN, as above: a repo reaching this door already holds the library, `drizzleOrm` is
+the copy its own queries are built with, and passing it means no resolver decides which copy the
+seam speaks through. `nodePostgresDriver({ pg })` takes the same form for the same reason. Leave
+either out and the module is imported on demand — the fallback for a composition root that has none
+in hand, and the reason both of these are `async` at all.
+
+drizzle-orm is an OPTIONAL peer, and `pg` is another: a consumer who imports only the seam bundles
+neither.
+
 Connection POOLING and caching belong to the deployment, not to this package. A managed pooler in
 front of Postgres is reached the same way any other connection string is; if that pooler caches
 query results, turn the caching OFF — this seam's correctness rests on `set_config` being local to
 the transaction that a cached result never re-enters.
 
+## An entity
+
+A payload table with one business key gets the same ten things written for it every time: five verbs,
+two undos, a page envelope and a cursor. `defineEntity` is that declaration, and every verb it
+generates goes through the seam's `scoped`, so a tenant is named before any of them runs and there is
+no door on the entity that skips one:
+
+```ts
+import { defineEntity, undosOf } from '@geonosis/db'
+
+export const products = defineEntity({
+  indexed: (body: Product) => ({ name: body.name, sku: body.sku }),
+  item: (row) => ({ ...row.body, id: row.key }),
+  key: { column: 'product_id', param: 'productId' },
+  order: [{ column: 'name' }, { column: 'product_id' }],
+  seam,
+  table: 'products',
+})
+
+await products.upsert(db, { orgId, productId, body })
+const page = await products.list(db, { orgId, limit: 20 })
+```
+
+`get` / `list` / `listAll` / `upsert` / `retire`, and both undos. `EntityColumns` names the columns
+beside the key — `body`, `created_at`, `updated_at`, `retired_at`, `tenant_id` — and defaults to the
+DDL this package renders. `indexed` reads the columns kept beside the body OFF the body on every
+write: the body is the only source, and a column a caller could set separately is a second answer to
+what the entity says. `item` is what a read answers with, from an `EntityRow<Body>`.
+
+`list` answers an `EntityPage<Item>`: `{ items, nextCursor }`, keyset on the listing index, never an
+offset — an offset re-counts rows somebody is still inserting. The page is read one row longer than
+it was asked for, because that extra row is the only honest way to know there is a next page.
+`nextCursor` is absent on the last page rather than empty. `DEFAULT_ENTITY_PAGE` is 50 and
+`MAX_ENTITY_PAGE` caps it. A cursor minted under another ordering, or of another width, is a
+`DbRefusal` — answering it with the first page again is a caller silently reading the list twice.
+
+`undosOf(entity)` is the compensation registry as plain data: `upsert` and `retire`, each an
+`EntityUndo` taking `{ output, tenantId }` — what the forward verb answered and the tenant it ran
+for. A write is undone by writing what was there before it, which is exactly what the forward verb
+returned, so nothing has to be remembered anywhere else. An upsert that created the row is undone by
+retiring it; a retire that found nothing is undone by doing nothing. A retired row's previous state
+is "retired", so its undo retires again rather than reviving.
+
+`entityMigrations` renders the table and its wall as the two files a consumer applies:
+`0001_<table>.sql` and `0002_<table>_policies.sql`. The tenant column DEFAULTS to the session
+setting, so a write that names no tenant still lands under the one its transaction is open for — the
+column and the policy then say the same thing, and neither depends on a caller remembering. The
+listing index is the `order` the entity declares, under the tenant. RLS is enabled AND forced, and
+the policies are the same `tenantPolicySet` both other doors render. Rendered with
+`ENTITY_PLACEHOLDERS` it is the same DDL carrying `{{tenantSetting}}` and `{{opsSetting}}`, for a
+migrator that templates; `geonosis-release schema` reads either. Every finding squawk has on it is
+accepted on the statement it belongs to, with the reason beside the rule names.
+
+`entityConformance` is the exam: the verbs, an upsert answering with what it replaced, a keyset walk
+one row at a time that must visit every row exactly once, both undos, and one tenant reaching none of
+another's rows through any verb. It runs here over both kinds of handle on both Postgres majors.
+
 ## The exam
 
 The four proofs that made this worth extracting ship as runner-agnostic functions a consumer runs
 against THEIR session — no test framework rides along; a case fails by throwing a
 `ConformanceFailure` from [`@geonosis/conformance`](../conformance):
 
-| Export | What it asks |
-| --- | --- |
-| `tenantIsolationConformance` | what a query with no predicate can still see, and who is a superuser |
-| `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 |
+| Export                              | What it asks                                                                                                                                                          |
+| ----------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `tenantIsolationConformance`        | what a query with no predicate can still see, and who is a superuser                                                                                                  |
+| `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                                                                                                   |
+| `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 +351,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.