@stonyx/orm 0.3.2-alpha.64 → 0.3.2-alpha.65

package/README.md

@@ -315,24 +315,15 @@ Access classes define models and provide custom filtering/authorization logic.
 > [Identifying the collection](#identifying-the-collection) before copying this.**
 > Every attempt to identify the collection by parsing the request target has
 > failed **open** — five distinct variants of this same example, each found only
-> after the previous was fixed, by five different people. That section is now a
-> record of what not to do, not a matching recipe: the sample below reads `model`
-> from [the access context](#the-access-context-second-argument) and never looks
-> at the mount at all, so all five variants are **unconstructible** against it
-> rather than merely handled.
+> after the previous was fixed, by five different people. The sample below does
+> not parse anything: it reads `request.baseUrl`, the mount Express actually
+> matched.
 >
 > That is still a stopgap. **The real fix is
 > [#202](https://github.com/abofs/stonyx-orm/issues/202)** — `access()` should
 > receive the model, the operation and the record, so there is nothing to
 > identify. Until it lands, prefer the array shape (`['read']`) or `false` where
 > you can: the **function** shape is the one that requires any matching at all.
->
-> The one read of argument **one** that survives is `request.path`, for the
-> `/archived` sub-path deny — and it has to. The context names which model and
-> which verb, not which route, so that deny **cannot be expressed from the
-> context alone** and a context-only rewrite would silently turn it into an
-> allow.
->
 > The same warning is repeated at the top of `src/orm-request.ts`, which ships;
 > the longer write-up in `docs/usage-patterns.md` does **not** ship, so this
 > README and that source header are the two copies a consumer sees.
@@ -346,65 +337,27 @@ Access classes define models and provide custom filtering/authorization logic.
 export default class GlobalAccess {
   models = ['owner', 'animal'];
 
-  access(request, { model, operation }) {
-    // `model` is the model this route was mounted for. It is assigned once, at
-    // mount time, and no request can influence it — not a mount prefix, not a
-    // query string, not a case-varied path, not an absolute-form request
-    // target. Nothing below parses anything, so variants 1, 2, 4 and 5 are not
-    // constructible against this predicate any more — they are history, not
-    // rules to follow. VARIANT 3 IS THE EXCEPTION AND THE CLAIM IS NARROWER
-    // THAN IT WAS: a matcher stricter than the router can still be stepped
-    // around, because the sub-path rule below is still a string comparison.
-    // Case is handled; percent-encoding is not — abofs/stonyx-orm#228.
-    //
-    // `operation` is destructured to name the whole contract at the point of
-    // use. This sample's rules are per-model and per-sub-path rather than
-    // per-verb, so it does not branch on it; the permission array at the bottom
-    // is where the verb is answered.
-
-    // FAIL CLOSED ON ARGUMENT TWO. `model` is absent for any caller that
-    // resolved this predicate without supplying the context, and a request this
-    // function cannot identify DENIES rather than falling through to the CRUD
-    // grant at the bottom. An unidentifiable input must never be the permissive
-    // path. Argument ONE is guarded at its own read, below — this guard does
-    // not cover it.
-    if (typeof model !== 'string' || model === '') return false;
-
-    if (model === 'owner') {
-      // The context names WHICH MODEL and WHICH VERB — not which route. Six
-      // distinct owner surfaces produce one identical context, so a rule that
-      // depends on the SUB-PATH still needs argument one. `request.path` is
-      // mount-relative and query-free, and it is the one read of the raw
-      // request the README sanctions. false → 403 for the whole request.
-      //
-      // THIS DENY CANNOT BE EXPRESSED FROM THE CONTEXT ALONE. Migrating it away
-      // does not remove a rule, it turns a deny into an ALLOW, silently.
-      //
-      // FAIL CLOSED ON ARGUMENT ONE TOO. The guard above covers the context;
-      // this one covers the request, and since #202 they are two different
-      // objects. A caller that resolves this predicate through the documented
-      // `Orm.instance.getAccess()` path and hand-assembles a request can supply
-      // a perfectly valid context with no usable `path` — and
-      // `String(request.path ?? '')` is then `''`, which matches no sub-path
-      // rule and falls straight through to the per-record filter below. That is
-      // a DENY becoming an ALLOW. An input this function cannot identify DENIES,
-      // whichever ARGUMENT it arrived on — which is also why the `?? ''` this
-      // file's header condemns does not appear below.
-      if (typeof request?.path !== 'string' || request.path === '') return false;
-
-      // Lower-cased because the router matched case-insensitively, so a
-      // case-sensitive rule here would be stricter than the router and could be
-      // stepped around.
-      //
-      // CASE-FOLDING ALONE IS NOT A SUFFICIENT NORMALISATION, and this line is
-      // not a recipe for one. Express sets `request.path` from the RAW pathname
-      // while the router DECODES `:id`, so `GET /owners/%61rchived` reaches this
-      // comparison as `/%61rchived`, walks past the deny, and is dispatched as
-      // the record `archived` — abofs/stonyx-orm#228. A matcher must normalise
-      // the way the router that dispatched the request does. Record ids are
-      // case-sensitive and must be compared at their real case.
-      const path = request.path.toLowerCase();
+  access(request) {
+    // `request.baseUrl` is the mount Express matched — `/owners`, or
+    // `/api/owners` under ORM_REST_ROUTE=/api. Never parse `originalUrl`: it is
+    // the raw request target and can be absolute-form.
+    const mount = request.baseUrl;
+
+    // FAIL CLOSED. If Express did not tell us what it matched we are not behind
+    // the mount we think we are, and an unidentifiable request denies rather
+    // than falling through to the CRUD grant at the bottom.
+    if (typeof mount !== 'string' || mount === '') return false;
+
+    // Lower-cased because the router matched case-INSENSITIVELY, and a matcher
+    // stricter than the router that dispatched the request can be stepped
+    // around. The PATH only — record ids stay at their real case below.
+    const collection = mount.toLowerCase();
+
+    // `request.path` is mount-relative and query-free, so sub-path rules need no
+    // prefix arithmetic either. false → 403 for the whole request.
+    const path = String(request.path ?? '').toLowerCase();
 
+    if (collection.endsWith('/owners')) {
       if (path === '/archived' || path.startsWith('/archived/')) return false;
 
       // Returning a function plugs it in as a per-record filter, and it is
@@ -420,7 +373,7 @@ export default class GlobalAccess {
     // inert. Deliberately NO `?? record.owner` fallback: accepting the raw
     // shape as well as the resolved one would absorb a resolution regression
     // silently, which is exactly what blinded this fixture before.
-    if (model === 'animal') return record => record.owner?.id !== 'restricted';
+    if (collection.endsWith('/animals')) return record => record.owner?.id !== 'restricted';
 
     // Allows full access to all calls that don't match any of the above conditions
     return ['read', 'create', 'update', 'delete'];
@@ -570,10 +523,9 @@ sample, `getAccess('owner') === getAccess('animal')`.
 #### Passing the context makes a model-correct answer *possible*
 
 It does not make the answer model-correct on its own. **The resolved predicate
-has to read the context.** Against a predicate that ignores it the failure is
-measurable. On a request Express dispatched to `GET /owners/angela`, asked about
-**animals**, the sample as it shipped before
-[#222](https://github.com/abofs/stonyx-orm/issues/222) answered:
+has to read the context.** Measured against the access class shipped with this
+repo, on a request Express dispatched to `GET /owners/angela`, asked about
+**animals**:
 
 ```
 getAccess('animal')(ownersRequest, { model: 'animal', operation: 'read' })
@@ -581,26 +533,18 @@ getAccess('animal')(ownersRequest, { model: 'animal', operation: 'read' })
 ```
 
 That is the **owners** filter, and it returns `true` for animal 21 — the record
-hidden on every animal surface. Under a mount such a predicate recognizes
-neither way it is worse still: it falls through to
-`['read', 'create', 'update', 'delete']`, a full CRUD grant. Either way the
-context was supplied and the answer is not the animal answer, and it is wrong in
-the direction that **grants** — because that predicate was single-argument and
-identified its collection from the request, so it answered about the collection
-the request was *addressed to* while being asked about another one.
-
-The sample shipped with this repo has since been migrated to read the context,
-and the same call now answers with the **animal** filter:
-
-```
-getAccess('animal')(ownersRequest, { model: 'animal', operation: 'read' })
-  ->  record => record.owner?.id !== 'restricted'
-```
-
-A single-argument predicate remains the default in every consumer tree, and a
-caller has no supported way to tell which kind it resolved. The boot-time arity
-warning that surfaces one is
-[#221](https://github.com/abofs/stonyx-orm/issues/221).
+hidden on every animal surface. Under a mount that predicate recognizes neither
+way it is worse still: it falls through to
+`['read', 'create', 'update', 'delete']`, a full CRUD grant.
+
+Either way the context was supplied and the answer is not the animal answer, and
+it is wrong in the direction that **grants**. That predicate is single-argument
+and identifies its collection from the request, so it answered about the
+collection the request is *addressed to* while being asked about another one.
+Every predicate in this repo, and in every consumer tree, is single-argument on
+the day this ships, and a caller has no supported way to tell which kind it
+resolved. The boot-time arity warning that would surface it is
+[#213](https://github.com/abofs/stonyx-orm/issues/213).
 
 So: pass the context, and do not treat a resolved predicate's answer as
 model-specific until that predicate has been migrated to read it.
@@ -637,7 +581,7 @@ a write to a *different* collection can still re-parent one. See
 | `GET /:models/:id/relationships/{relationship}` | `404` — same |
 | `PATCH /:models/:id` | `404`, no attribute is applied |
 | `DELETE /:models/:id` | `404`, the record is not removed and no SQL `DELETE` is issued |
-| `POST /:models` | `403`, and a record **this request inserted** is rolled back — see [Known limitations](#known-limitations) for the case where it did not insert one |
+| `POST /:models` | `403`, and a record **this request inserted** is rolled back — see [Known limitations](#known-limitations) for why the rollback is conditional |
 
 **Denied record-level requests return 404, not 403.** This is deliberate and it
 is the property most easily "improved" away. 403 would confirm that the record
@@ -671,23 +615,70 @@ chooses the id and learns whether the create succeeded — so under a filter the
 caller does not choose the id. The refusal happens before any store lookup, so
 neither the status nor the response time depends on whether the id exists.
 
-Let the server assign the id and read it back from the response. Callers with no
-function-style filter are unaffected: `409` on a duplicate id and `200` on a free
-one both behave exactly as before.
+Let the server assign the id and read it back from the response — and read it
+back rather than predicting it, because the value it returns is documented but
+not stable across model kinds: a numeric-id model gets `max + 1` (or, at the
+numeric ceiling, the lowest free integer), and a string-id model gets
+`<model>-<n>`. See breaking change 8.
+
+**What a server-assigned id is not.** It is not a secret. On a string-id
+collection it is dense and enumerable from `1`, where previously it inherited
+whatever entropy the last-inserted id happened to carry — a UUID-seeded store
+answered a UUID-derived key. If a collection has **no** `access` config its
+record-level routes are ungated, so the id was the only thing standing between
+an unauthenticated caller and `GET`/`PATCH`/`DELETE` on a record. That was never
+a control and must not become one; configure `access`.
+
+**And the id itself is an occupancy signal — on both model kinds.**
+`assignRecordId` reads the whole store, not the caller's filtered view — it
+never sees `state.filter` — so the id it returns is a function of records the
+caller may not be permitted to read. **This applies to numeric-id collections
+as well as string-id ones**, and the conditions differ, so read both:
+
+- **String-id collections, always.** The assigned `n` is the smallest positive
+  integer whose landing key is free, which tells the caller that every key
+  below it is taken, hidden or not.
+- **Numeric-id collections, once one record sits at the numeric ceiling.** The
+  normal answer is `max + 1`, which discloses only the maximum. But `max + 1`
+  is not representable at or above 2^53, so the walk restarts from `1` (see
+  breaking change 8) and the assigned id becomes the smallest free integer —
+  the same occupancy predicate, now over arbitrary low keys. Each subsequent
+  no-id `POST` names the next free one, so a caller can enumerate the holes in
+  a range it cannot read.
+
+**A ceiling record reaches a filter-protected collection even though `POST`
+refuses caller ids on one.** Breaking change 3 makes
+`POST /animals {"id": 9007199254740992}` answer `403`, but the same id lands
+through a *relationship write on another collection* —
+`POST /owners` carrying `attributes: { pets: [{ "id": 9007199254740992 }] }`
+creates the animal under that key
+([#207](https://github.com/abofs/stonyx-orm/issues/207), the same channel the
+**Known limitations** re-parenting note describes). So the precondition is
+reachable by an unauthenticated caller on exactly the collections `access`
+exists to protect. Measured on the sample fixture, with every animal hidden by
+the `/animals` predicate and keys 4 and 7 deleted:
 
-### Identifying the collection
+```
+GET  /animals                                       -> 200  []      (nothing visible)
+GET  /animals/4                                     -> 404          (free — indistinguishable from hidden)
+POST /animals {"id":4}                              -> 403          (breaking change 3)
+POST /owners  {... pets:[{"id":9007199254740992}]}  -> 200          (#207 plants the ceiling record)
+POST /animals (no id)                               -> 200  id=4    <- names a hole in the hidden range
+POST /animals (no id)                               -> 200  id=7    <- and the other one
+POST /animals (no id)                               -> 200  id=13
+POST /animals (no id)                               -> 200  id=14
+```
+
+Closing this requires the assignment to be filter-aware, which is a change to
+the `access` contract rather than a fix; it is stated here rather than left to
+be discovered. Callers with no function-style filter are unaffected — there are
+no hidden records to disclose.
 
-**Do not reconstruct the request path — and since
-[#202](https://github.com/abofs/stonyx-orm/issues/202) you do not have to
-identify the collection at all.** Read `model` from
-[the access context](#the-access-context-second-argument): it is fixed at mount
-time, no request can influence it, and there is nothing left to parse.
+### Identifying the collection
 
-**Everything below is the record of what happened when this sample did parse
-it.** It is kept as history, not as a recipe — none of these matching strategies
-should be written into a new predicate. Every version of this sample that tried
-to identify the collection from the request target failed **open**, and each
-variant was found only after the previous one was fixed:
+**Do not reconstruct the request path.** Every version of this sample that tried
+to has failed **open**, and each variant was found only after the previous one
+was fixed:
 
 | # | Variant | Why it fails open |
 |---|---|---|
@@ -697,24 +688,13 @@ variant was found only after the previous one was fixed:
 | 4 | hard-coded `/owners` | With `ORM_REST_ROUTE=/api` every url becomes `/api/owners/...` and the sample matches nothing — environment-specifically, which is harder to notice than failing everywhere. The remediation this document used to give was itself broken: `` `${config.orm.restServer.route}owners` `` evaluates to **`/apiowners`**, so a reader who followed the correction exactly still failed open and believed they had handled it. |
 | 5 | any match on `originalUrl` at all | HTTP/1.1 permits an **absolute-form** request-target. Express routes on `parseurl(req).pathname`, so the request dispatches normally — but `originalUrl` is the raw target. `GET http://anything.example/owners/angela` yields `originalUrl === 'http://anything.example/owners/angela'`, which has no `/owners` prefix. Measured: the record came back in full, `DELETE` succeeded, and it walked past a hard `return false` deny the same way. |
 
-**The fix is not a sixth rule, and it is not a better string to match.** It is
-to stop identifying the collection at all. That is a statement about
-**identifying the collection**, and it is not a statement about the sample as a
-whole: the `/archived` sub-path rule *is* still a string match, and
-[#228](https://github.com/abofs/stonyx-orm/issues/228) is a sixth spelling that
-gets past it. Sub-path rules are the residue this fix does not cover, which is
-why they must normalise the way the router does.
-
-An intermediate revision read **`request.baseUrl`** — the mount Express
-*actually matched*. That closed all five variants: it carries no query string
-(variant 2), it is not mount-relative (variant 1), it already contains the
-configured `ORM_REST_ROUTE` prefix (variant 4 — there is nothing left to derive,
-so `/apiowners` is unconstructible), and it is unaffected by an absolute-form
-target (variant 5). It was still a transport artifact standing in for a
-structural fact, and it is **no longer what the sample does**: the sample reads
-`model`, so all five variants are unconstructible against it rather than
-handled. The table below is retained as the measured evidence behind the five
-variants, not because any of these values should be matched on:
+**The fix is not a sixth rule.** It is to stop parsing:
+
+**Use `request.baseUrl`.** It is the mount Express *actually matched* when it
+dispatched the request. It carries no query string (variant 2), it is not
+mount-relative (variant 1), it already contains the configured `ORM_REST_ROUTE`
+prefix (variant 4 — there is nothing left to derive, so `/apiowners` is
+unconstructible), and it is unaffected by an absolute-form target (variant 5).
 
 | request | `request.url` | `request.originalUrl` | `request.baseUrl` | `request.path` |
 |---|---|---|---|---|
@@ -725,35 +705,21 @@ variants, not because any of these values should be matched on:
 | `GET http://anything.example/owners/angela` | `http://anything.example/angela` | `http://anything.example/owners/angela` | `/owners` | `/angela` |
 | `GET /api/animals/22` (`ORM_REST_ROUTE=/api`) | `/22` | `/api/animals/22` | `/api/animals` | `/22` |
 
-**One read of argument one survives, and it must: `request.path`.** It is
-mount-relative and query-free, and it is for rules that distinguish **sub-paths**
-beneath the mount — as the `/archived` deny in the sample above does. The context
-names which model and which verb, **not which route**, so that deny *cannot be
-expressed from the context alone*, and a context-only rewrite would silently turn
-it into an allow.
-
-**Normalise the way the router that dispatched the request does — and
-case-folding alone does not.** A matcher stricter than the router can be stepped
-around, so the sample lower-cases before comparing (the router matched
-case-insensitively). That closes the case gap and **it is not the whole rule**:
-Express sets `request.path` from the **raw, undecoded** pathname while the router
-**decodes** `:id`, so `GET /owners/%61rchived` reaches a `path === '/archived'`
-comparison as `/%61rchived`, walks past the deny, and is dispatched as the record
-`archived`. That gap is live in the sample above and is tracked as
-[#228](https://github.com/abofs/stonyx-orm/issues/228) — **do not read the
-`.toLowerCase()` there as a complete normalisation recipe.** Record ids are
-case-sensitive and must be compared at their real case.
-
-**Fail closed on anything you cannot identify — on *either* argument.**
-`String(request.originalUrl ?? '')` was once added here to stop a `TypeError`,
-and it traded fail-closed for fail-**open**: an empty string matched no
-collection, so `access()` fell through to the permission array and granted full
-CRUD. The same rule applies to the context — the sample returns `false` for an
-absent `model` rather than falling through. Since #202 the guard and the read can
-sit on **different objects**, and a guard on argument two does not protect a read
-of argument one: the sample therefore also returns `false` when `request.path` is
-absent or is not a string, rather than letting `?? ''` fall through to the
-per-record filter. An input you cannot identify must **deny**.
+Two rules remain, and they are the whole list:
+
+**1. Compare lower-cased.** `baseUrl` is the text the caller sent, not the
+registered mount — `GET /OwNeRs/angela` yields `/OwNeRs`. The router matched it
+case-insensitively, so a case-sensitive comparison here is stricter than the
+router and can be walked past. Lower-case the **mount and path only**; record ids
+are case-sensitive and must be compared at their real case.
+
+**2. Fail closed when `baseUrl` is absent.** `String(request.originalUrl ?? '')`
+was added to stop a `TypeError`, and it traded fail-closed for fail-**open**: an
+empty string matches no collection, so `access()` fell through to the permission
+array and granted full CRUD. An input you cannot identify must **deny**.
+
+Use `request.path` — mount-relative and query-free — if you need to distinguish
+sub-paths beneath the mount, as the `/archived` deny above does.
 
 ### Known limitations
 
@@ -776,14 +742,11 @@ per-record filter. An input you cannot identify must **deny**.
   see [The access context](#the-access-context-second-argument):
   `Orm.instance.getAccess(modelName)` makes another model's predicate
   **reachable**, and `context.model` makes a **model-correct answer possible** —
-  possible, not guaranteed: the resolved predicate has to read the context. The
-  sample shipped with this repo now does
-  ([#222](https://github.com/abofs/stonyx-orm/issues/222)), so
-  `getAccess('animal')` answers with the animal filter; a predicate that ignores
-  the second argument still answers about the collection the request is
-  addressed to, and the boot-time warning that surfaces one is
-  [#221](https://github.com/abofs/stonyx-orm/issues/221). **The mechanism
-  exists; the ORM does not yet use it on this path.** The re-parenting write above is still
+  possible, not guaranteed: the resolved predicate has to read the context, and
+  every predicate in tree is still single-argument
+  ([#213](https://github.com/abofs/stonyx-orm/issues/213)), so today it answers
+  about the collection the request is addressed to. **The mechanism exists; the
+  ORM does not yet use it on this path.** The re-parenting write above is still
   **not refused** — that enforcement is
   [#196](https://github.com/abofs/stonyx-orm/issues/196) and
   [#207](https://github.com/abofs/stonyx-orm/issues/207), which were blocked on
@@ -835,9 +798,10 @@ per-record filter. An input you cannot identify must **deny**.
   transform output differs from its lookup key is the same defect. Filtered
   collections are unaffected — breaking change 3 refuses any client-supplied id
   — so this reaches consumers with **no** function-style filter. Tracked as
-  [#205](https://github.com/abofs/stonyx-orm/issues/205), alongside
-  [#203](https://github.com/abofs/stonyx-orm/issues/203), which is the other way
-  a create can land on an id nobody named.
+  [#205](https://github.com/abofs/stonyx-orm/issues/205). Its sibling
+  [#203](https://github.com/abofs/stonyx-orm/issues/203) — a **server-assigned**
+  id landing on an occupied slot — is **fixed**; see breaking change 8. #205 is
+  the client-supplied half and is still open.
 - **`context.record` is `undefined` for an after-`create` hook when a string-id
   model is given a numeric-looking id.** The post-create lookup uses the same id
   coercion as every other surface, which resolves `'9107'` to the number `9107`,
@@ -847,15 +811,18 @@ per-record filter. An input you cannot identify must **deny**.
   [#209](https://github.com/abofs/stonyx-orm/issues/209).
 - **A denied `POST` rolls back only a record it *inserted*.** The rollback
   requires the store to have grown, because removing by id alone is a write
-  primitive keyed by a caller-supplied value. When `assignRecordId` lands a
-  **server-assigned** id on an occupied slot
-  ([#203](https://github.com/abofs/stonyx-orm/issues/203) — it returns
-  last-*inserted* + 1, not max + 1, so a store whose insertion order is not
-  ascending collides), `createRecord` updates that record **in place**: the map
-  does not grow, the rollback correctly declines to remove a record this request
-  did not create, and the `403` leaves the caller's attributes on someone else's
-  record. Narrow — it needs a non-ascending insertion order — but it is the
-  reachability condition, so it is stated rather than implied.
+  primitive keyed by a caller-supplied value. **The reachability condition this
+  bullet used to state is gone**: it was
+  [#203](https://github.com/abofs/stonyx-orm/issues/203) — `assignRecordId`
+  returned last-*inserted* + 1, so a server-assigned id could land on an
+  occupied slot and `createRecord` would update it in place — and #203 is fixed
+  (breaking change 8). A server-assigned create can no longer overwrite, so on a
+  collection whose only id channel is `createHandler` this guard has no
+  observable effect today. It is kept because a caller-supplied id reaching
+  `createRecord` from another route — a relationship write,
+  [#207](https://github.com/abofs/stonyx-orm/issues/207) — puts the condition
+  back, and without the guard a denied `403` would delete a record the request
+  did not create.
 
 ### Breaking changes
 
@@ -916,6 +883,64 @@ they are recorded here.
    population breaking changes 3 and 4 explicitly exempt. If you were relying on
    a hex-shaped or whitespace-padded id creating a second record, it never did.
 
+8. **Server-assigned ids change value on string-id models, numeric ids stop
+   being monotonic at the numeric ceiling, and the create route gains a
+   `409`.** Three consumer-visible changes from
+   [#203](https://github.com/abofs/stonyx-orm/issues/203).
+
+   **The value.** A `POST` with no `id` against a model declaring
+   `id = attr('string')` previously produced the *last-inserted* id with `1`
+   concatenated onto it — an owner store holding `['gina', 'bob']` answered
+   `'bob1'`. It now answers `'owner-1'`: the model name, a hyphen, and the
+   lowest positive integer whose landing key is free. **No test in this repo
+   pinned the old value**, so a consumer relying on it gets no failing test, no
+   deprecation and no other signal — which is why it is recorded here. Numeric
+   id models (`id = attr('number')`, the default) are unaffected in shape: they
+   still get an integer, but it is now the **maximum** existing id plus one
+   rather than the last-inserted id plus one, which is the defect #203 is about.
+   They are **not** unaffected in *sequence* — see the monotonicity half below.
+
+   The value is deliberately **not** numeric-looking, and that is not cosmetic.
+   Every id-bearing surface resolves a numeric-looking string id to a **number**
+   (`GET /owners/1` looks up `1`), while a string-id model files its records
+   under the **string** key `'1'`. A server-assigned `'1'` would therefore be a
+   record that was created successfully and could not be fetched, updated or
+   deleted by id, and whose after-`create` hook received
+   `context.record === undefined`
+   ([#209](https://github.com/abofs/stonyx-orm/issues/209)).
+
+   **Numeric ids are no longer monotonic, and deleted ids can be re-issued.**
+   The precondition is narrow but it is reachable, and there is no signal when
+   it is met: **one record filed at or above 2^53** (`9007199254740992`). `max
+   + 1` is not representable there, so assignment restarts from `1` and walks
+   up to the lowest free key — which means the id of a *deleted* record is
+   handed to the next `POST`. Both `dev` and every prior release were strictly
+   monotonic and never re-issued a numeric id, so a consumer that relied on
+   that — audit rows, cursors, cached authorization decisions, external
+   references keyed on the id — now has a stale reference that silently points
+   at a **different record, created by a different caller**, rather than at a
+   deleted one. Nothing fails; the reference simply resolves to the wrong
+   record.
+
+   The restart is deliberate and is not itself optional: without it, one record
+   at the ceiling made every subsequent server-assigned create on that
+   collection fail permanently. Re-use is the cost of keeping the collection
+   writable. **If you need monotonic ids, assign them yourself** rather than
+   letting the server assign, and note that a ceiling record can be planted by
+   an unauthenticated caller — see *And the id itself is an occupancy signal*
+   under [Filter functions](#filter-functions) for the reachability path.
+   String-id models are unaffected by this half: their keys are
+   `<model>-<n>` and were never monotonic over an integer sequence.
+
+   **The status.** `POST /{collection}` can now answer `409` for a reason other
+   than a duplicate id: the server could not derive a free id. That requires a
+   **non-injective** id transform — one that maps distinct candidates onto the
+   same store key, such as `boolean`, or anything you registered on
+   `Orm.instance.transforms` and named as an id type. It is a configuration
+   fault rather than a request fault; the message is logged through
+   `stonyx/log`. Previously this case threw out of the handler and express
+   answered `500` with a stack trace.
+
 ### Include Parameter (Sideloading Relationships)
 
 The ORM supports JSON API-compliant relationship sideloading via the `include` query parameter. This reduces the need for multiple API requests by embedding related records in a single response.