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

package/README.md

@@ -629,15 +629,50 @@ 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.** `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. On
-a string-id collection the assigned `n` is the smallest positive integer whose
-key is free, which tells the caller that every key below it is taken, hidden or
-not. Closing that 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.
+**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:
+
+```
+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.
 
 ### Identifying the collection
 
@@ -848,8 +883,9 @@ 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, and the create route
-   gains a `409`.** Two consumer-visible changes from
+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
@@ -862,6 +898,7 @@ they are recorded here.
    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**
@@ -872,6 +909,29 @@ they are recorded here.
    `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

package/package.json

@@ -4,7 +4,7 @@
     "stonyx-async",
     "stonyx-module"
   ],
-  "version": "0.3.2-alpha.63",
+  "version": "0.3.2-alpha.65",
   "description": "",
   "main": "dist/index.js",
   "type": "module",