letopis 1.3.0 → 1.4.1

package/README.en.md

@@ -1,4 +1,4 @@
-# letopis 1.3
+# letopis 1.4
 
 **letopis** is a Node.js library: a store of versioned entities on PostgreSQL 18. Every change is saved as a version
 in a journal. So every object has a history, a state as of any date and a change subscription. The database itself
@@ -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,11 +370,21 @@ 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.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
+updating the package: `up()` from the older version would bring the old functions back. A new package version without
+SQL changes keeps the stamp, and there is no warning.
 
 The first `up()` after moving to 1.2 builds the journal index `log_class_tenant_at (class, tenant, at)` instead of
 `log_class_at`: an `asOf` and `withDeleted` slice by class no longer reads the journal of other tenants with the same
@@ -377,8 +394,9 @@ 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
 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. Both schemas are
+upgraded with `up({ upgrade: true })`: 1.1.0 (revision 6) with migration `0007`, 1.0.1 (revision 5) with migrations
+`0006` and `0007`.
 
 ### Development without PostgreSQL: PGlite
 
@@ -567,13 +585,21 @@ const Movement = link('Movement', { amount: z.number().int() }, { ends: { Wallet
   key; the `via` end is single and accepts the target class; the `sum` field is a number; aggregates do not form a
   cycle; the target and the source are not system or derived classes. A source class is described before the
   aggregate: an aggregate over a class that does not exist yet is refused. For a tenant class, the source is looked up
-  among the tenant's classes. `syncModels` describes sources before targets itself. The `of` class is not deleted while
-  an aggregate of a class of the same tenant names it: first the aggregate is removed from the target's description.
+  among the tenant's classes. `syncModels` describes sources before targets itself, and models in a circle (an
+  aggregate over the class's own descendant, a cycle of aggregates) it refuses before writing (`invalid_class` naming
+  the circle). The `of` class is not deleted while an aggregate of a class of the same tenant names it: first the
+  aggregate is removed from the target's description.
 - Rows get into an aggregate only with the knowledge of someone who reads them all: the field also counts rows that
   the author cannot see. Only someone who reads all rows of the source and its descendants without conditions can
   describe or change an aggregate. Only someone who reads all rows of a class and its descendants without conditions,
   both before the change and after it, can make the class a source (a new descendant of a source, a `parent` change).
   Otherwise `acl_denied`.
+- A new source is also checked against whoever described the aggregate: they too must read all rows of the class
+  without conditions. The describer is the author of the version of the target's `Class` row from which the aggregate
+  description became the current one. If they cannot read those rows, the class does not become a source
+  (`acl_denied`) until someone who can read them describes the aggregate again. For an aggregate of a System class, the
+  describer is checked against System classes, as at description time. A tenant class under a System aggregate is
+  checked only for whoever creates it.
 - The option is inherited, and a descendant replaces it as a whole. Adding or changing an aggregate is a tightening:
   writes to the target and to the sources wait while the field is recalculated for all rows.
 - `db.rebuildAggregates(class)` recalculates the field from the current rows, for repair. A version is written only
@@ -608,9 +634,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
@@ -664,8 +691,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`
 
@@ -800,8 +828,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
 
@@ -846,7 +881,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 |
@@ -917,7 +952,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
 
@@ -950,9 +987,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);
@@ -1416,8 +1454,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()
 ```
 
@@ -1430,6 +1470,16 @@ 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
@@ -1542,7 +1592,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
 
@@ -1712,7 +1770,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
 }
 ```
@@ -1731,10 +1789,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
 
@@ -1821,6 +1883,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
@@ -1873,17 +1938,23 @@ 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 })`.
 - `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).
   Otherwise a transaction of any tenant holding a total row or an end target would hold the batch of all tenants.
   Longer than that, the batch rolls back, the cursor stays, and `run()` does not reject but skips the pass
-  (`skipped`) and repeats it.
+  (`skipped`) and repeats it. The report names the tenant whose row stopped the batch (`locked`).
+  `rebuild({ tenant, chunked: true })` waits such a lock out.
+- `lockRetries` is how many passes in a row the writes of one tenant may run into `lockTimeout` before it drops out
+  (0 by default — it never drops out). The dropped tenant gets the code `55P03`, and the batch goes on for the others;
+  its changes are skipped until `rebuild({ tenant })`. The process keeps the count, and a successful write of the
+  tenant resets it. Note: a long exclusive lock on the family of a System class (a tightening of its description) will
+  hit every tenant in turn.
 - Every edit that `out` sends to the database is a separate edit of a row, and the speed of a projector is set by the
   number of edits, not by the number of changes. The folding of `inc` brings the edits of a row down to one per batch,
   so the handle from the example above (`out.inc` for every change) caught up with 6 thousand changes per second with
@@ -1965,8 +2036,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`
@@ -1987,10 +2060,17 @@ 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, — 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
@@ -2201,6 +2281,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
@@ -2320,17 +2404,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
 
@@ -2340,14 +2426,14 @@ give `invalid_data`.
 
 | Member | What it does |
 |---|---|
-| options `ProjectorOptions` | `from`, `into`: classes with descendants; `version`: an integer from 1; `handle(changes, out)`; `withBefore`; `onExpired: 'rebuild' \| 'error'` (`'rebuild'` rebuilds in batches); `batch`: changes in a batch (500, from 1 to 10,000); `pollMs`: fallback polling (1000 ms); `lockTimeout`: waiting for another transaction's row lock (5000 ms, 0 — no limit); `tenants`: ids of the participant tenants |
+| options `ProjectorOptions` | `from`, `into`: classes with descendants; `version`: an integer from 1; `handle(changes, out)`; `withBefore`; `onExpired: 'rebuild' \| 'error'` (`'rebuild'` rebuilds in batches); `batch`: changes in a batch (500, from 1 to 10,000); `pollMs`: fallback polling (1000 ms); `lockTimeout`: waiting for another transaction's row lock (5000 ms, 0 — no limit); `lockRetries`: passes in a row before a tenant with another transaction's lock drops out (0 — never); `tenants`: ids of the participant tenants |
 | `run({ once })` | catch up with the journal (`once`) or follow it until `stop()` → `ProjectorReport` |
 | `rebuild({ chunked, tenant })` | rebuild from the current state: atomically, in batches or for one tenant → `ProjectorReport` |
 | `status()` | → `ProjectorStatus`: `{ name, state, version, cursor, at, lag, failed, rebuildingTenants }`; `failed` is `{ [tenant id]: ProjectorFailure }`, where `ProjectorFailure` is `{ cursor, code, message }` |
 | `stop()`, `close()` | stop `run()` after the current batch; the same plus unsubscribing from signals |
-| `ProjectorReport` | `{ batches, changes, created, updated, deleted, unchanged, skipped, rebuilds }` |
+| `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
 
@@ -2364,9 +2450,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`,
@@ -2423,7 +2511,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 |
@@ -2493,7 +2581,7 @@ runs) showed no write or read regressions against 1.1: two outliers did not repe
 
 ## 18. Limitations
 
-This section lists what letopis 1.3 deliberately does not do or does with caveats, and where you need to watch the
+This section lists what letopis 1.4 deliberately does not do or does with caveats, and where you need to watch the
 behavior.
 
 **Platform**
@@ -2558,8 +2646,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**
 
@@ -2758,7 +2846,7 @@ This section is for those who develop letopis itself. Run: `cd lib && npm test`.
 # 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)
 # 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.1.0 (upgrade: true, migration 0007) and from 1.0.1 (upgrade: true, migrations 0006 and 0007) 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, 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)