letopis 1.4.0 → 1.4.2

package/README.en.md

@@ -130,7 +130,7 @@ What happened here:
   from the journal.
 
 Calling `up()` again is safe: it re-applies the same revision and does not touch the data, and it does not issue the
-service key again while the installation still has a valid API key. Next, section 2 explains the design, and sections
+service key again while the installation still has at least one API key that is not revoked. Next, section 2 explains the design, and sections
 3–13 go through the tasks in order.
 
 ## 2. How letopis works
@@ -243,11 +243,16 @@ functions and the system seed. On the first installation, it issues a service ke
 | `owner`, `app` | the names of the owner and application roles (`letopis_owner`, `letopis_app` by default) |
 
 Result: `schema` (the full name), `serviceKey` (on the first installation, and on a re-run when the installation has no
-valid API key left; otherwise `null`), `created`, `upgraded`, `revision`, `migrations`, `analyzed`, `owner`, `app`,
+API key left except revoked ones: an expired or disabled key counts too; otherwise `null`), `created`, `upgraded`, `revision`, `migrations`, `analyzed`, `owner`, `app`,
 `signals` (the signal mode of the installation), `warnings` (without `quiet` they are printed), and also `tenant` and
 `pglite` if they were requested. On PostgreSQL below 18.2, `up()` warns: such a server could truncate CLOG that unread
 signals still need — upgrade it.
 
+Several instances of a service may call `up()` for the same schema at the same time: the installation runs under a lock
+on the schema. The first `up()` installs or upgrades it, the others wait and re-apply the ready schema
+(`created: false`, `upgraded: false`); one of them creates the first `tenant`, the others find it by name. `up()` calls
+for different schemas of one database do not wait for each other.
+
 To hide class names from signals, use the `opaque` mode (or `tenant` if the names are not secret but you want the
 cache to be precise per tenant); after changing the mode, restart the application processes — they read the mode on
 connect:
@@ -291,7 +296,9 @@ A repeat with the same name and login duplicates nothing and does not change the
 session. The login goes into the id as is: `Anna@shop.ru` and `anna@shop.ru` would give two accounts, and the second one
 would have no password, so write logins in one case. The `created` field in the result tells whether this call created
 the tenant: for an existing tenant with a new user it is `false`. The roles are set by `user.roles`, a non-empty list
-of names (not masks), otherwise `invalid_data`. A repeat does not change the roles of an existing membership: they are
+of names (not masks), otherwise `invalid_data`. The password kind `user.kind` (`PASSWORD` by default) follows the rule
+for a credential kind, as in `auth.setPassword` ([API reference](#dbauth)), otherwise it is `invalid_data` too. A
+repeat does not change the roles of an existing membership: they are
 changed by editing the membership ([Granting a permission](#granting-a-permission)). A repeat does not bring back
 what was deleted: if the tenant, the user account or the membership is deleted (the row is gone but its history is in
 the journal), `createTenant` answers `invalid_data` and writes nothing. The error text names what was deleted and
@@ -363,13 +370,16 @@ const adm = await connect({ dsn: ADMIN, schema: r.schema, token: r.tenant!.token
 
 ### Upgrading the package and schema
 
-The schema has an engine revision (currently 6). If a new package version brings a new revision, `connect()` only warns
+The schema has an engine revision (currently 7). If a new package version brings a new revision, `connect()` only warns
 and names the command. It is `up()` that refuses: a lagging schema without `upgrade: true`, and a schema newer than the
-package. So a startup script that calls `up()` on every start will stop after a package update until it gets
+package. To a schema newer than the package (a newer package has already upgraded it, and old application instances
+are still running) `connect()` connects anyway and warns that the letopis package should be updated. So a startup script that calls `up()` on every start will stop after a package update until it gets
 `upgrade: true`. `up({ dsn, schema, upgrade: true })` applies the migrations from `sql/migrate/` and re-applies the
-functions; the data is kept.
+functions; the data is kept. Revision 7 (1.4.1) adds the foreign key `secret.account`: migration `0007` first erases
+the `secret` rows whose accounts are already gone (the credentials of accounts deleted earlier were kept with the
+`deleted_at` mark), and then sets the key.
 
-The revision does not change with every version: 1.1–1.4 share one, while their functions differ. So `up()` also writes
+The revision does not change with every version: 1.1–1.4.0 share one (6), while their functions differ. So `up()` also writes
 an engine stamp into the schema comment: the package version and a hash of its SQL files. If the stamp does not match
 the package files, `connect()` warns. When the schema was applied by an older version (or by a version before 1.4,
 which has no stamp), it suggests `up({ schema })`. When a newer version has already upgraded the schema, it suggests
@@ -382,10 +392,30 @@ class name. While the index is being built, writes to the journal wait. On a lar
 without stopping writes: `create index concurrently log_class_tenant_at on "v2.<schema>".log (class, tenant, at)` as
 the owner role — then `up()` only drops the old one.
 
-The `upgrade` test checks upgrading 1.1.0 and 1.0.1 schemas. The old package installs the schema and the old engine
+The `upgrade` test checks upgrading 1.4.1, 1.1.0 and 1.0.1 schemas; every release checks the upgrade from the previous
+release. The old package installs the schema and the old engine
 writes the data, then the current version's `up()` runs. After it, the versions and hashes written by the old engine
-are in place, `verify({ data: true })` is clean, and the schema catalog matches a clean installation. A 1.1.0 schema is
-upgraded with a plain `up()`, since its revision is the same. A 1.0.1 schema is upgraded with `up({ upgrade: true })`.
+are in place, `verify({ data: true })` is clean, and the schema catalog matches a clean installation. A 1.4.1 schema of the
+same revision 7 is upgraded with a plain `up()`, without migrations; 1.1.0 (revision 6) and 1.0.1 (revision 5) — with
+`up({ upgrade: true })`: with migration `0007` and with migrations `0006` and `0007`.
+
+### Versions and compatibility
+
+letopis versions follow semver. What each version step promises:
+
+- **Patch** (1.4.1 → 1.4.2) — fixes only. The engine revision stays the same: a plain `up({ schema })` re-applies the
+  fixed functions, there are no migrations; until it runs, `connect()` warns about the stamp mismatch. Working code gets
+  no new refusals, and no methods, options, exports or error codes disappear.
+- **Minor** (1.4 → 1.5) — new features: methods, options, error codes; behavior changes that do not break working code;
+  a new engine revision. `up({ schema, upgrade: true })` applies the new revision. Nothing is removed or renamed.
+- **Major** (1.x → 2.0) — removed and renamed methods, options, exports and error codes, changed signatures and types,
+  new refusals for everyone. `MIGRATION.md` describes what to change in your code.
+
+The text of an error message is not part of the API: a patch may make it more precise. Rely on `err.code`.
+
+Before every release the `check:semver` script checks the version step: it compares the API contract
+(`docs/api-contract.json`) and the engine revision with the previous release and requires at least the matching step.
+Every release checks the schema upgrade from the previous release (the `upgrade` test).
 
 ### Development without PostgreSQL: PGlite
 
@@ -623,9 +653,10 @@ ends type is `InferLinks<typeof Product>`. Your own `meta` shape is typed by ext
 
 ### Class names
 
-A chain step is named after a class, its alias or a role name. The Proxy parses the names of chain and root methods
-(`count`, `sort`, `set`, `sql`, `auth` and others) before classes. So a class with such a name cannot be reached as a
-step, and the database does not accept a link with such a name. The full list is in the
+A chain step is named after a class, its alias or a role name. Where a chain or root method exists, the library parses
+its name (`count`, `sort`, `set`, `sql`, `auth` and others) before classes: a class `count` is reachable as the first
+step `db.count(…)`, but not after another step. The database does not accept a link with such a name. Do not give
+classes these names; the full list is in the
 ["Reserved names"](#reserved-names) section.
 
 ## 5. Writing
@@ -679,8 +710,9 @@ fields are not lost. If the step has no filter of its own, the target is taken f
 `data.id` all entities of the step are edited: `db.Product().update(…)` edits all products of the tenant. If the step
 found nothing, the result is empty and there is no error, so check the length of the result. If `update` affected fewer
 rows than the step found, the whole plan is rolled back: a row deleted in the meantime gives `target_not_found`, and a
-row that is visible but may not be edited gives `acl_denied`. The `.tags(…)` modifier before `update` both selects the
-rows and replaces their tags entirely.
+row that is visible but may not be edited gives `acl_denied`. The `.tags(…)` modifier before `update` selects the rows;
+a string or a list also replaces their tags entirely, while an operator (`has`, `hasAny`, `hasAll`) only selects — the
+tags stay as they are.
 
 ### Create or replace: `upsert`
 
@@ -815,8 +847,15 @@ await db.Order(order).line().create({ qty: 1, price: 900 }).Product.set(sencha).
   journal conflict, the library retries the whole plan, up to three times.
 - An error in any part rolls back the whole plan. `exists` and `conflict` are not retried: they are answers for the
   application.
-- Modifiers before a verb (`limit`, `sort`) narrow its targets.
+- Modifiers before a verb (`limit`, `offset`, `sort`) narrow its targets.
+- A modifier after a verb applies to what follows it: a class step, `versions()`, `diff()`, `blame()` and aggregates,
+  or the targets of the next verb. If a `rows`, `first`, `ids`, `count` or `paths` terminal follows right away, there is
+  nothing left to narrow — the verb has gone through all targets of the step — so
+  `db.Product().update(…).limit(1).rows()` gives `invalid_query` and writes nothing. In a batch, `run()` refuses the
+  same way.
 - A verb right after a verb writes to the same entities.
+- The result rows of a verb come in the order of its targets: by `sort()` before the verb, otherwise by id; `first()`
+  after a verb is the first one in that order.
 
 ## 6. Reading
 
@@ -861,7 +900,7 @@ const roots = await db.Category({ Parent: null }).rows()       // root categorie
 | `ne(v)`, `gt(v)`, `gte(v)`, `lt(v)`, `lte(v)` | ≠ (taking `null` into account), >, ≥, <, ≤ |
 | `between(a, b)`, `inList([…])` | a ≤ x ≤ b; a value from the list |
 | `like(s)`, `ilike(s)`, `starts(s)`, `ends(s)` | a pattern with `%` and `_`; case-insensitive; starts with; ends with |
-| `has(v)`, `hasAny([…])`, `hasAll([…])` | an array field contains the value; at least one; all |
+| `has(v)`, `hasAny([…])`, `hasAll([…])` | an array field contains the value; at least one; all (`hasAll([])` matches every row, `hasAny([])` matches none) |
 | `exists(true \| false)`, `isNull()` | the field is present or not; the field is `null` or missing |
 | `not(v)` | negation of an operator; for a scalar, "not equal" |
 | `or(f1, f2, …)` | any of the step filters |
@@ -897,8 +936,8 @@ const page2 = await db.Product().sort('data.price', 'desc')
 
 `sort(field, 'asc' | 'desc')` sorts by `'at'`, `'rev'`, `'id'` or `'data.<path>'`. `after(cursorOf(row, field))` is
 pagination "after this row"; it requires `sort()`. Such pagination withstands inserts and deletes between pages, but a
-row whose sort field has changed may drop out or repeat. A cursor is an object `{ v, id }` (the field value and the row
-id): it survives JSON, so you can hand it to a client. The field in `cursorOf` must match the `sort` field. The cursor
+row whose sort field has changed may drop out or repeat. A cursor is an object `{ v, id, rev }` (the field value, the
+row id and its version number): it survives JSON, so you can hand it to a client. The field in `cursorOf` must match the `sort` field. The cursor
 value is checked against the type of the `sort` field before the query, and a wrong one is `invalid_query`: a numeric
 field needs a finite number, `rev` an integer, a boolean field `true` or `false`, a text field a string, uuid fields
 and `id` a uuid, time fields and `at` an ISO string with a time zone, a date field `YYYY-MM-DD`, a field without a
@@ -906,6 +945,12 @@ description a string, a number or `true`/`false`. `null` fits only data fields,
 The check cannot tell apart a cursor of the same type taken from another field. `limit` and `offset` are available
 too.
 
+`after()` also pages `versions()`: the cursor of a version carries its `rev`, so versions of one object with an equal
+sort field are not lost. In `paths()` the cursor comes from `cursorOf(path, field)`: the field and the id are those of
+the last node of the path, and `path` holds the ids of all nodes, so paths to the same node are not lost. A cursor
+`cursorOf(path.Node, field)` taken from a single node skips the other paths to that node. `count()`, aggregates,
+`diff()` and `blame()` ignore the cursor.
+
 A data field may be `null` or missing. `sort` places such rows the way `order by` in PostgreSQL does: last when
 ascending, first when descending, and `after()` treats `null` as a value after all others (ascending) or before them
 (descending). So pages go through such rows without gaps or repeats, and a cursor with the value `null` gives the next
@@ -932,7 +977,9 @@ const byStatus = await db.Order().countBy('data.status')          // { new: 1 }
 ```
 
 The database computes aggregates over the entities of the last step. `limit(n)` and `offset(n)` before `countBy()`
-apply to the groups: `db.Order().limit(3).countBy('data.status')` gives the three most frequent values.
+apply to the groups: `db.Order().limit(3).countBy('data.status')` gives the three most frequent values. For a boolean
+field, `min()` is `false` if there is at least one `false` (whether all values are `true`), and `max()` is `true` if
+there is at least one `true`; `sum()` and `avg()` do not work on a boolean field — PostgreSQL returns an error.
 
 ### Paths
 
@@ -942,7 +989,8 @@ const orderPaths = await db.Order(order).line().Product().paths()   // [{ Order:
 ```
 
 `paths()` returns the nodes of every variant of the path; the key of a node is the step name or the name from
-`.alias(name)`. Repeating a link in the chain returns to its node: this way you can go from one link in several
+`.alias(name)`. The keys follow the order of the steps; if the chain ends by returning to an earlier node, that node
+comes last. Repeating a link in the chain returns to its node: this way you can go from one link in several
 directions. `db.entity(row | chain)` inserts a ready node into the path.
 
 ## 7. Deleting and restoring
@@ -965,9 +1013,10 @@ try {
 `delete()` without `{ confirm: true }` is only a preview: the whole cascade closure. Every preview row has `$action`
 (`delete`, `unset` or `restrict`) and `$depth`, the cascade level (0 is the target itself; `unset` and `restrict` rows
 do not have it). With the confirmation, all targets of the step are deleted in one statement, and the cascade applies
-the rules of the ends. The preview does not take permissions into account: a row with `$action: 'delete'` may fail to
-be deleted for a user without the permission (`acl_denied`), so a user interface should ask
-`acl.checkData(class, 'DELETE')`. The rules of the ends:
+the rules of the ends. The result is the tombstones level by level, by id within a level (the journal has them in the
+same order); targets of classes without a journal (`history: false`) come last. The preview does not take permissions
+into account: a row with `$action: 'delete'` may fail to be deleted for a user without the permission (`acl_denied`),
+so a user interface should ask `acl.checkData(class, 'DELETE')`. The rules of the ends:
 
 - `restrict`: deletion is forbidden while the target is referenced (`delete_restricted` with a list of the visible rows
   and the number of the others);
@@ -1254,7 +1303,7 @@ const changed = await adm.load({ Shop: [{ name: 'Cornflower', city: 'Samara' }]
 | Option | Values |
 |---|---|
 | `duplicates`: a repeated id within the load | `'error'` (default): cancel; `'first'` or `'last'`: keep the first or the last row |
-| `existing`: the object already exists in the database | `'error'` (default): cancel; `'skip'`: skip, do not resurrect deleted objects; `'update'`: a new version if the content differs (unchanged objects are counted in `skipped`), deleted objects are created again |
+| `existing`: the object already exists in the database | `'error'` (default): cancel; `'skip'`: skip, do not resurrect deleted objects; `'update'`: a new version if the content differs (unchanged objects are counted in `skipped`), deleted objects are created again; an object of another class with the same id (a class without a key after `reclass`) is `exists` |
 
 ### Portions, history and verification
 
@@ -1431,8 +1480,10 @@ denial that the identifier is taken ([section 18](#18-limitations)).
 <!-- run: guide -->
 ```ts
 const shortToken = await svc.auth.sessionFor(BORIS, { ttl: 600 })   // a session for 10 minutes of idle time for another process
+const whose = await svc.auth.session(shortToken)                     // { account, tenant, member, expiresAt, loginAt, methods }
 const boris = await connect({ dsn: APP, schema: r.schema, token: shortToken })
 await boris.auth.revoke()                                            // sign-out: the session is revoked
+const ended = await svc.auth.session(shortToken)                     // null
 await boris.close()
 ```
 
@@ -1445,14 +1496,25 @@ account is deleted. Deleting a credential revokes the other sessions of the acco
 "key + secret" pair revokes only the sessions opened by that key (and old sessions of the same sign-in method without
 a key mark); the current session stays unless you pass `keepCurrent: false`.
 
+A service that holds a user's token (for example, in a cookie) learns about the session with `svc.auth.session(token)`:
+no connection is opened with that token, and the session is not extended. The answer tells whose session it is
+(`account`), which tenant it works in (`tenant`: the one chosen by `auth.switch()` or the account's own tenant),
+whether the membership there is intact (`member`; always `true` in the own tenant), when it expires (`expiresAt`), and
+when and how the sign-in happened (`loginAt`, `methods`: `PASSWORD`, `APIKEY`, `SERVICE`, `TOTP` …). A wrong, revoked
+or expired token and a disabled account give `null`; the reason is not told apart. This is how a web service checks the
+session at the start of every request: reading under a revoked session gives no error, the answers are simply empty.
+The method is called by the service or the system administrator (the `auth.session` permission); a user gets
+`acl_denied`.
+
 ### Working in another tenant
 
 A service acts on behalf of a user through `svc.as(account, { tenant, owner })`. The database checks the service's
 `auth.impersonate` permission (by System rules), that the user exists and is enabled, and that the tenant is available
 to the user, either their own or through membership. You cannot act on behalf of System, services, system
 administrators or disabled accounts. The user's visibility under the access rules is not checked. In the journal,
-`author` is the user and `agent` is the service. A user's connection by their own token switches between tenants like
-this:
+`author` is the user and `agent` is the service. The class registry of `db.as()` is one per tenant, and a connection
+keeps at most 1000 of them: a long unused one is evicted, and a facade whose registry was evicted keeps working — the
+registry is re-read. A user's connection by their own token switches between tenants like this:
 
 <!-- run: guide -->
 ```ts
@@ -1557,7 +1619,15 @@ Fields of the system permission classes:
 
 `db.auth.purgeAccount(account)` deletes an account and the data of its tenant. The system administrator or the owner of
 its tenant can call it; you cannot delete yourself or the last owner of a tenant. Ownership of rows in other tenants
-passes to those tenants, sessions are revoked, credentials are deleted.
+passes to those tenants, sessions are revoked, credentials are deleted. An owner can also delete the tenant they are
+working in right now: their session returns to their personal tenant.
+
+The system administrator can also delete the account row itself — `db.Account(id).delete({ confirm: true })` in the
+System tenant; the data of the account's tenant stays then. Either way, the account's rows in `secret` are erased at
+once: sessions, password and key hashes, TOTP secrets, external accounts (the foreign key `secret.account` with a
+cascade, revision 7). Before that, the sessions are revoked with a signal, and processes drop the cached answers of
+these sessions. The System account cannot be deleted (`acl_denied`): the service rows of the installation in `secret`
+belong to it.
 
 ## 11. History and point-in-time reads
 
@@ -1579,6 +1649,12 @@ Without `sort()`, versions go by id and version number (with `follow`, by time).
 too, and `limit()` limits them in the query itself: `db.Product(kettle).sort('at', 'desc').limit(5).versions()` gives
 the five latest versions, newest first.
 
+`follow: true` gives the history of the object across all its ids: before a move, the versions of the former id;
+after it, of the new one. An object created later on the former id (the same key after `rekey`) is a different one,
+and its versions are not in this history; its own history with `follow` starts at its creation. `diff({ follow: true
+})` and `blame()` work the same way. Without `follow`, `versions()` gives every version of the id, whoever it
+belonged to.
+
 ### Point-in-time read
 
 <!-- run: guide -->
@@ -1681,7 +1757,8 @@ none.
   single-valued end, every id of a multi-valued end (`['links', role, id]`), every tag (`['tags', tag]`), `owner` and
   `class`. `rev`, `at`, `author`, `agent`, `op` and `reason` come from the version that changed the leaf last. Empty
   `agent` and `reason` are omitted; `id` is present only if it is a version of the former id (the history went
-  through `reclass` or `rekey`).
+  through `reclass` or `rekey`). `blame()` does not look at versions of another object on the same id — one that
+  lived there before a move or was created after it.
 - `exact: false` means there are gaps between the current version and the found one (the history is thinned,
   trimmed or partly invisible): a missing version may have changed the leaf too. `complete: true` means the whole
   history was scanned without gaps; by default at most the 1000 latest versions are scanned.
@@ -1727,7 +1804,7 @@ const sub = db.watch({ from: 'start', classes: ['Product'] })   // the whole jou
 await db.Product(kettle).update({ price: 2100 }).rows()
 let cursor = ''
 for await (const ev of sub) {             // ev: { cursor, row, id, class, op, rev, at }
-  cursor = ev.cursor                      // save the cursor: watch({ from: cursor }) continues after it
+  cursor = sub.cursor!                    // the subscription cursor: watch({ from: cursor }) continues after this event
   if (ev.id === kettle.id && ev.row.data.price === 2100) break   // break (or sub.close()) stops the subscription
 }
 ```
@@ -1746,10 +1823,14 @@ for await (const ev of sub) {             // ev: { cursor, row, id, class, op, r
   within a transaction in the order of writing. This is not the commit order: compare versions of one object by `rev`.
 - A long write transaction in any database of the cluster delays the stream: `await sub.lag()` shows the lag in ms.
 - A cursor older than the `all` tier of the retention policy gives `cursor_expired`: read the current state again and
-  subscribe with `'now'`.
+  subscribe with `'now'`. The time in the subscription cursor `sub.cursor` is the time of the last event, and once the
+  subscription has caught up with the journal, the time of the poll, so a subscription that got no events for a day
+  does not expire. The event cursor `ev.cursor` keeps the time of the event itself.
 - Without `LISTEN` (`connect({ listen: false })`), the subscription polls the journal.
-- A subscription without losses is a saved cursor: store `ev.cursor` of the last processed event and resume from it
-  after a restart.
+- A subscription without losses is a saved cursor: after processing an event, store `sub.cursor` (the position after
+  the last delivered event) and resume from it after a restart. `ev.cursor` also continues the stream, but after a
+  quiet period longer than the `all` tier such a cursor is older than the tier, and resuming from it gives
+  `cursor_expired`.
 
 ### Projectors
 
@@ -1836,6 +1917,9 @@ sales.close()                                    // stop() after the current bat
   `out.inc(class, row, deltas, { tenant })` creates a row or completes it and adds the numbers without reading the row
   (missing fields count from 0). `out.delete(class, key or id, { tenant })` deletes a row and does nothing if there is
   none. `await out.get(class, key or id, { tenant })` reads the current row together with the writes of the batch.
+  `delete` and `get` find a row of a class with a key by the key fields (`{ day: '2026-10-29' }`), and by id (a string
+  or `{ $id }`) only a row of a class without a key; an id alone for a class with a key is `invalid_data`, and the
+  batch is rolled back.
   `out` writes only to the `into` classes and only to the tenant of the changes passed to `handle`; otherwise you get
   `derived_class` or `tenant_denied`, and the batch is rolled back.
 - `out` adds up the increments of a row given by key fields only (or by `$id` alone) before sending them to the
@@ -1888,11 +1972,15 @@ sales.close()                                    // stop() after the current bat
   at all — `derived_class`. Only an administrator may mark the classes of a tenant, so it is the administrator who
   chooses the participants: a tenant user cannot join a projector on their own. The option `tenants: [id, …]`
   is an explicit list of participants: the projector works only with these tenants (their `into` classes must be
-  marked too) and ignores the marks of the others. The sources are the `from` families of these tenants; a class
-  cannot be a source and a result at the same time. A projector does not see the changes of a class with
-  `history: false`: it has no journal. So a tenant with such a class among the sources drops out with the code
-  `invalid_class`, and the projector does not build its derived rows. Turn the journal of the class on and rebuild the
-  tenant with `rebuild({ tenant })`.
+  marked too) and ignores the marks of the others. The sources are the `from` families of these tenants; an `into`
+  class is never a source, even if it falls into `from`: a projector does not read its own results. A projector does
+  not see the changes of a class with `history: false`: it has no journal. So a tenant with such a class among the
+  sources drops out with the code `invalid_class`, and the projector does not build its derived rows. Turn the journal
+  of the class on and rebuild the tenant with `rebuild({ tenant })`.
+- A tenant that became a participant after the first projection (the administrator marked its classes later) gets an
+  initial batch rebuild: the rows created before it joined get into the projection too. A projector re-reads its
+  participants on a class signal, and on a connection without LISTEN (`listen: false`) at the start of `run()` and at
+  least every 5 seconds.
 - `batch` is how many changes go into a batch (500), `pollMs` is fallback polling (1000 ms): source signals wake the
   projector earlier.
 - `lockTimeout` is how long a projector transaction waits for another transaction's row lock (5000 ms; 0 — no limit).
@@ -1986,8 +2074,10 @@ stays correct:
 - changes of permissions and classes, writes through `db.sql`, a revoked session and a listener reconnect clear the
   whole cache or the results of the session;
 - the default term is 60 seconds; the cache does not work inside `db.begin()`;
-- without `LISTEN` and in the `none` mode the cache is off, and `connect({ cache: { ttlOnly: true } })` enables it by
-  term only.
+- without `LISTEN` and in the `none` mode the cache is off, and `connect({ cache: { ttlOnly: true } })` enables it: an
+  answer lives until its term ends unless a write of this connection resets it;
+- `db.load()`, the projector and `db.rebuildAggregates()` reset the cache, even of this connection, only by a database
+  signal.
 
 A process re-reads the class registry right away on a class change signal (one re-read at a time), and the registry
 and the signal key on `*`, on an unknown token and on a payload of another mode (and without the key in the `opaque`
@@ -2008,10 +2098,18 @@ Between processes, the cache goes stale for the signal sending interval (`notify
 const report = await adm.maintain()     // { sessions, codes, thinned, batches, more, queue, skipped }
 ```
 
-`maintain()` deletes expired sessions and one-time codes, thins the journal by the retention policy and checks the
-PostgreSQL signal queue: if it is more than half full, you get a warning. The system administrator, a role with the
-`letopis.maintain` permission or an admin connection can call it. An external scheduler runs it (`letopis maintain`),
-or the library itself does: `connect({ maintain: '1h' })`. Of several processes, only one works: each batch is its own
+`maintain()` deletes sessions and one-time codes of all kinds (`OTP` and custom `OTP_<NAME>` from `issueOtp({ kind })`)
+from the `secret` table — expired ones, as well as
+revoked sessions and codes that were used, replaced by a new one or ran out of attempts, — and the lock rows of deleted
+classes (two per class; a row held by a transaction goes on the next call), thins the journal by the
+retention policy and checks the PostgreSQL signal queue: if it is more than half full, you get a warning. You do not
+need `maintain()` for the rows of a deleted account: the deletion itself erases them ([Deleting an account](#deleting-an-account)).
+The system administrator, a role with the `letopis.maintain` permission or an admin connection can call it. An external scheduler
+runs it (`letopis maintain`), or the library itself does: `connect({ maintain: '1h' })`. The interval is a number of
+milliseconds or a string (`'500ms'`, `'30s'`, `'15m'`, `'1h'`, `'1d'`) from 1 ms to 2³¹−1 ms (about 24 days):
+`connect()` rejects any other value, including zero, a negative number or `NaN`, with `invalid_data` without opening
+connections. `close()` waits for a scheduled run in progress: it finishes the current batch and does not start the
+next one. Of several processes, only one works: each batch is its own
 transaction, and the first thing it does is take the maintenance lock — a row of the `secret` table that neither the
 application role nor any other database role can take; the lock is released when the batch commits. If another
 process holds the lock, the call answers `skipped: true` before the first batch, and between batches it stops (that
@@ -2222,6 +2320,10 @@ letopis mcp --dsn <dsn> --schema <v2.name> --token <user token> [--write]
   (or LETOPIS_DSN, LETOPIS_SCHEMA, LETOPIS_TOKEN; the service key --api-key is not accepted)
 ```
 
+`letopis types` and `letopis describe` build their output from the session's classes, so without a valid session (the
+token expired, was revoked, is wrong or not given, or the API key is wrong) they exit with code 1 and the `no_session`
+error and leave the `--out` file untouched.
+
 ### Monitoring
 
 - `connect({ onQuery, slowMs })`: for every chain query, the hook gets the mode, the classes, the duration, the row
@@ -2341,17 +2443,19 @@ Removed 0.21 names (`uuidv7`, `LETOPIS_NS` and the methods listed below) throw `
 | `link`, `lookup` | `{ account, kind, identifier, meta?, confirmed? }` → id; `{ kind, identifier, requireConfirmed?, ttl?, totp? }` → sign-in or `null` |
 | `credentials`, `revokeCredential`, `setFlags` | `(account)` → credentials without secrets; `(id, { keepCurrent? })`; `(id, { confirmed?, enabled? })` |
 | `sessionFor`, `refresh`, `revoke`, `revokeAll` | `(account, { ttl? })` → token; `({ ttl? })` → the new expiration time (the token stays the same); `()`; `(account?)` → number of sessions |
+| `session` | `(token)` → `{ account, tenant, member, expiresAt, loginAt, methods }` or `null` |
 | `tenants`, `switch` | `()` → `[{ tenant, roles }]`; `(tenant)` |
 | `purgeAccount` | `(account)` → `{ account, rows, versions, memberships, owned }` |
 
-Password, code and TOTP checks, session issuing and credential confirmation are called by the service (`auth.*`
-permissions); a regular user gets `acl_denied`. The credentials of System, services and system administrators can be
-changed only by the account itself after a recent interactive sign-in, or by the system administrator. The exception is
-the service's keys: the service issues and revokes its own API keys and "key + secret" pairs itself with a session of
-its own key, but not its other credentials; nobody can revoke the last active key of a service (`acl_denied`). With
-`totp`, `verifyPassword` and `lookup` also check the TOTP code (the `auth.totp` permission) and issue a session with the
-`TOTP` method. The credential kind `kind` is `^[A-Z][A-Z0-9_]{1,31}$` (`PASSWORD`, `EMAIL`,
-`TELEGRAM` …); `SESSION`, `APIKEY`, `KEYSECRET`, `OTP`, `TOTP` and `KEY` are taken.
+Password, code and TOTP checks, session issuing, session details by token and credential confirmation are called by the
+service (`auth.*` permissions); a regular user gets `acl_denied`. The credentials of System, services and system
+administrators can be changed only by the account itself after a recent interactive sign-in, or by the system
+administrator. The exception is the service's keys: the service issues and revokes its own API keys and "key + secret"
+pairs itself with a session of its own key, but not its other credentials; nobody can revoke the last active key of a
+service (`acl_denied`). With `totp`, `verifyPassword` and `lookup` also check the TOTP code (the `auth.totp` permission)
+and issue a session with the `TOTP` method. The credential kind `kind` is `^[A-Z][A-Z0-9_]{1,31}$` (`PASSWORD`, `EMAIL`,
+`TELEGRAM` …); `SESSION`, `APIKEY`, `KEYSECRET`, `OTP`, `TOTP`, `KEY`, `PROJECTOR` and `LOCK` are taken. The same rule
+applies to the password kind `user.kind` in `createTenant` and `up({ tenant })`.
 
 ### Projector
 
@@ -2368,7 +2472,7 @@ give `invalid_data`.
 | `stop()`, `close()` | stop `run()` after the current batch; the same plus unsubscribing from signals |
 | `ProjectorReport` | `{ batches, changes, created, updated, deleted, unchanged, skipped, rebuilds, locked }` |
 | `ProjectorChange` | `{ cursor, id, class, tenant, op, rev, at, author, row }` and, when present, `agent`, `reason`, `moved`, `before`, `rebuild` |
-| `ProjectorOut` | `upsert(class, row, { tenant })`, `inc(class, row, deltas, { tenant })`, `delete(class, key or id, { tenant })`, `get(class, key or id, { tenant })` → `Row \| null`; a row is a `ProjectorRow` in the loader format |
+| `ProjectorOut` | `upsert(class, row, { tenant })`, `inc(class, row, deltas, { tenant })`, `delete(class, key or id, { tenant })`, `get(class, key or id, { tenant })` → `Row \| null`; a row is a `ProjectorRow` in the loader format; for a class with a key `delete` and `get` go by the key, an id only for a class without a key |
 
 ### Result row
 
@@ -2385,9 +2489,11 @@ give `invalid_data`.
 
 ### Reserved names
 
-The Proxy parses the names below before classes, so a class with such a name cannot be reached as a step, and the
-database does not accept a link with such a name (`reserved_names()`; the installer fills in the list from
-`RESERVED_CLASS_NAMES`).
+A method name hides a class only where that method exists: after a step — chain methods, at the root `db` — its
+methods, in a batch — its own. So a hub named like a chain-only method (for example, `count`) is reachable as the first
+step `db.count(…)` but not after another step, and a hub named like a root method cannot be the first step. The
+database does not accept a link with any of these names (`reserved_names()`; the installer fills in the list from
+`RESERVED_CLASS_NAMES`). Do not give classes these names.
 
 - chain methods: `then`, `entity`, `paths`, `rows`, `first`, `ids`, `count`, `limit`, `offset`, `sort`, `asOf`,
   `withDeleted`, `deep`, `exact`, `sum`, `avg`, `min`, `max`, `countBy`, `after`, `versions`, `create`, `update`,
@@ -2444,7 +2550,7 @@ Library codes:
 | `tx_rolled_back` | PostgreSQL answered `ROLLBACK` to `COMMIT`: the error was caught inside `tr.transaction(fn)` |
 | `no_key` | `upsert`, `rekey` or `idOf` on a class without a key |
 | `no_path` | there is no hop between the classes of neighboring steps |
-| `invalid_query` | the chain or the API is used incorrectly (a step modifier `deep`, `exact`, `alias`, `tags` or `owner` after a verb, a slot not after a verb, an `after()` cursor with a value of a different type than the `sort` field, without `v` or with an `id` that is not a uuid, and so on) |
+| `invalid_query` | the chain or the API is used incorrectly (a step modifier `deep`, `exact`, `alias`, `tags` or `owner` after a verb, a selection modifier between a verb and a `rows`, `first`, `ids`, `count` or `paths` terminal, a slot not after a verb, an `after()` cursor with a value of a different type than the `sort` field, without `v` or with an `id` that is not a uuid, and so on) |
 | `admin_required` | the loader, a projector and `rebuildAggregates` need an admin connection |
 | `rebuild_required` | the projection was built by another version of the projector (`version`): a rebuild with `rebuild()` is needed; `rebuild({ tenant })` while there is no projection or a batch rebuild is in progress |
 | `projector_busy` | a rebuild cannot start: the projector is running in another process right now |
@@ -2520,7 +2626,7 @@ behavior.
 **Platform**
 
 - PostgreSQL 18 or newer is required; there are no workarounds for 15–17. AWS RDS, Google Cloud SQL, Azure Flexible
-  Server and Neon support 18, while Supabase, as of October 2026, offers only 15 and 17, so 1.0 will not work there.
+  Server and Neon support 18, while Supabase, as of October 2026, offers only 15 and 17, so letopis will not work there.
 - The database must be in UTF8 encoding (`casefold()` and the `pg_unicode_fast` collation). If a new major PostgreSQL
   version updates the Unicode tables, the unique index of credential identifiers is rebuilt with the `reindex` command.
 - PGlite has one superuser connection: no concurrent writers and no `LISTEN`, and RLS does not apply
@@ -2579,8 +2685,8 @@ behavior.
 - Hot reference targets (an organization that almost everything references) accumulate `for key share` locks and
   MultiXact, as with regular foreign keys; this needs monitoring. Operations on one wallet go one after another under a
   lock of its row ([section 8](#8-transactions-batches-and-money), "Recipe: wallet").
-- A link cannot have a reserved name, and a hub with such a name cannot be reached as a step
-  (["Reserved names"](#reserved-names)).
+- A link cannot have a reserved name, and a hub with such a name is not reachable everywhere: for example, `count` —
+  only as the first step (["Reserved names"](#reserved-names)).
 
 **Access**
 
@@ -2731,6 +2837,12 @@ behavior.
 This section is for those who develop letopis itself. Run: `cd lib && npm test`. The harness starts the
 `letopis-pg18` container (`postgres:18`, port 15433) by itself if the database does not respond; each test file works in its own schema `v2.t_<name>`.
 
+CI runs no tests: before a push and a release, everything that checks behavior runs as one command,
+`cd lib && npm run prerelease` — typecheck, the documentation check, all tests, the site examples against snapshots, the
+sandbox, the service scenarios, a quick soak run (15 minutes of mixed load) and the package check with a live run, in
+order; the first red step stops the run. The same load for a day: `cd lib && npm run soak` (duration — `SOAK_HOURS`,
+24 hours by default). A test for a fix is named after its test-plan item ("plan 2.0, 7.3 No. 1") and fails without the fix.
+
 ```
 # connect — connecting under a session, refusing roles that bypass RLS, the registry, the deferred signal, error translation (stage 2)
 # context — sessions, service sign-in by key, the RLS policies of stage 1 (stage 1)
@@ -2777,9 +2889,9 @@ This section is for those who develop letopis itself. Run: `cd lib && npm test`.
 # retention — retention policy: tiers, a finite term, special versions, deleted rows, asOf, cursor_expired, time zone, catch-up run, inheritance and default — versus a reference in TypeScript (stage 6)
 # watch — cursor subscription: commit order, a long transaction, resuming, listener drop, two tenants (stage 6)
 # cache — result cache: hits, own and others' writes, the key with the user, permissions, revoked sessions, listener drop, ttl, class marking, without LISTEN, a race, db.sql, the limit of signal counters (stage 6; plan 1.1, checkpoint A)
-# maintain — maintenance: expired sessions and codes, permissions, one process under a lock, schedule (stage 6)
+# maintain — maintenance: expired sessions and codes, permissions, one process under a lock, schedule (stage 6), lock rows of deleted classes
 # up — the full installer: fresh installation, re-apply, custom seeds, automatic database creation, UTF8, version 17, upgrade with migrations, PGlite, the first tenant and user (up({ tenant }), createTenant) (stages 6, 8)
-# upgrade — schema upgrade from 1.1.0 (re-apply) and from 1.0.1 (upgrade: true, migration 0006) with the letopis-11 and letopis-1 packages: versions and hashes written by the old engine, verify(), the catalog against a clean installation, lock rows, the application, a subscription and a projector over old data, a repeated up() (work after 1.2.0, stage 1)
+# upgrade — schema upgrade from 1.4.1 (a plain up() without migrations, plan 2.0, 7.8 No. 2), from 1.1.0 (upgrade: true, migration 0007) and from 1.0.1 (upgrade: true, migrations 0006 and 0007) with the letopis-141, letopis-11 and letopis-1 packages: versions and hashes written by the old engine, verify(), the catalog against a clean installation, lock rows, secret rows without an account erased, the application, a subscription and a projector over old data, a repeated up() (work after 1.2.0, stage 1; revision 7)
 # scenario-salon — end-to-end salon scenario: 21 acts from 0.21 (salon) with a coverage matrix of the 1.0 API (stage 6)
 # telemetry — onQuery and slowMs, describe() and class metadata with inheritance, describeText (stage 6)
 # history — diff and blame over the log, the reason of a change for verbs, db.begin() and batches; a version hidden by an ACL condition, the changed column, a missing version, row_changes over 20 thousand targets (plan 1.1, stage 1 and checkpoint A)
@@ -2789,4 +2901,10 @@ This section is for those who develop letopis itself. Run: `cd lib && npm test`.
 # mcp — MCP tools: the model and meta only in results, tenant rights, the JSON chain and hints of similar names, row and byte limits with a cursor, the untrusted-data wrapper, writing only with write, update only with rev, deletion with a human confirmation (elicitation in revisions 2025 and 2026-07-28), the reason in blame, credentials, tool schemas, letopis without the SDK; letopis mcp over stdio, the HTTP handler; the confirmation window without the alias and meta, countBy and versions limited in the query itself, limits of steps and $or conditions; the permission classes only with allowAclWrite, a session in the System tenant only with allowSystemAdmin; structuredContent with a note, a requestState signature of the server user with an expiry (plan 1.1, stage 5; security review No. 2; checkpoint B and the work after it)
 # import — import from 0.21 with a fixture of a real 0.21: key violation, --keyless, per-class counters, verify, self-reference, repeat, ids without a key, a dangling reference, $$strict and fields starting with $, update, credentials, CLI (stage 7)
 # security-final — the final security review (stage 8, §7.10 No. 8.4): a family lock by the tenant of the root, account_purge without permission and restore/purge of a foreign id give neither a leak nor a lock; the functions of stage 6, log_refs_at, journal-based find_* reads and watch_read stay within their own tenant; NOTIFY carries only names or mode tokens; the cache key distinguishes the token, the actor and the tenant (stage 8)
+# semver — version rules: check:semver requires at least the matching version step — a major for a removed method or error code, a minor for a new method and a new engine revision, a patch for texts only (plan 2.0, 7.8 No. 1)
+# prerelease — the pre-release check: steps run strictly in order, the first red one stops the run and the following ones do not start (plan 2.0, 7.8 No. 3)
+# write-contract — README promises about writes (plan 2.0, 7.2): a repeated key in a batch gives exists and a rollback, the row order of reclass, restore and rekey responses, a chain with a verb as a slot value, the loader with existing: update does not edit a row of another class, a cached answer is not spoiled by editing an earlier answer
+# watch-contract — README promises about subscriptions and connections (plan 2.0, 7.4): an idle subscription polls the journal once per pollMs, close() of the connection closes live subscriptions, a reclass without a key resets the cache of the old class, a new projector participant gets an initial rebuild, a projector without LISTEN re-reads its participants, at most a limit of db.as() registries
+# model-contract — README promises about models, types, the CLI and errors (plan 2.0, 7.5): letopis types gives valid TypeScript for Cyrillic names, a class without fields and anyOf, the full form of hub() with z.object, clear errors instead of raw ones, CLI exit codes
+# read-contract — README promises about reads and history (plan 2.0, 7.1): an asOf slice by class and by ends after a class change without an id change, versions, diff and blame with follow after rekey, the after() cursor in versions() and paths(), a field name with @S@
 ```