@stonyx/orm 0.3.2-alpha.74 → 0.3.2-alpha.76

package/README.md

@@ -951,7 +951,18 @@ per-record filter. An input you cannot identify must **deny**.
   `methodAccessMap[request.method]`: it would ask a different question on a
   write route than on a read route, which is the two-vocabularies failure
   `createLinkageFilter` exists to prevent. An unresolvable class
-  (`getAccess()` → `undefined`) and a predicate that throws both **deny**. A
+  (`getAccess()` → `undefined`) and a predicate that throws both **deny**.
+
+  **What the two write surfaces cost before #235, measured rather than
+  described:** one HTTP verb defeated the filter on the same record. On
+  `dev @ 8dda5d6`, seconds apart, with no query string and no relationship
+  route, `GET /animals/1` returned `owner.data: null` while `PATCH /animals/1`
+  returned **200 naming angela**. Any caller who could read a record could also
+  write it and be handed the id the read withheld. That consequence is kept here
+  after the fix, and stated as a measurement, because **naming the two handlers
+  is not a substitute for it** — a reader who is told only that `POST` and
+  `PATCH` are now covered cannot tell what was wrong, and a reviewer cannot tell
+  whether the fix addressed it. A
   filtered-out relationship is **indistinguishable from a genuinely empty one** —
   an emptied `hasMany` is `data: []` and an emptied `belongsTo` is `data: null`,
   both **keeping their `links`**, which are built from the serialized record's
@@ -983,20 +994,30 @@ per-record filter. An input you cannot identify must **deny**.
   *permitted* related record, which is recorded in the release notes as a
   breaking change.
 
-  **Not yet covered, and each one still publishes ids the surfaces above
-  withhold:**
-
-  - **`GET /:models/:id/relationships/{relationship}`**, whose *primary data* is
-    linkage, so filtering it is a **membership** decision —
-    [#232](https://github.com/abofs/stonyx-orm/issues/232), the filed child of
-    [#196](https://github.com/abofs/stonyx-orm/issues/196). This route builds
-    its `{type, id}` objects by hand and never calls `toJSON`, so it does not
-    see a `linkage` option no matter who supplies one. Measured:
-    `GET /animals/1/relationships/owner` answers
-    `{"type":"owner","id":"angela"}` while `GET /owners/angela` is `404`.
-  - **Whether a related resource appears in `included` at all** —
-    [#233](https://github.com/abofs/stonyx-orm/issues/233). #235 filters what a
-    record *already in* `included` may **name**; a hidden record is still a
+  **Not yet covered by #235. Each still publishes ids the surfaces above
+  withhold, except where its own owning issue has since closed it — the first
+  entry names an issue that is in flight as this is written:**
+
+  - **`GET /:models/:id/relationships/{relationship}`, and its state is #232's
+    to report rather than this entry's.**
+    [#232](https://github.com/abofs/stonyx-orm/issues/232) owns the
+    relationships-linkage route. Its *primary data* is linkage,
+    so filtering it is a **membership** decision — which is why it is the filed
+    child of [#196](https://github.com/abofs/stonyx-orm/issues/196) and not of
+    #234. The route builds its `{type, id}` objects by hand and never calls
+    `toJSON`, so the `linkage` **option** never reaches it; whatever that route
+    filters, it filters itself. Measured **on `dev @ 8dda5d6`**, the commit
+    #235 branched from: `GET /animals/1/relationships/owner` answered
+    `{"type":"owner","id":"angela"}` while `GET /owners/angela` was `404`. That
+    measurement is pinned to a commit on purpose, so that it does not quietly
+    become a false claim about `dev`. **PR
+    [#247](https://github.com/abofs/stonyx-orm/pull/247) is in flight against
+    this entry**; if it has landed, this route is covered and the bullet #247
+    adds above supersedes this one.
+  - **Whether a related resource appears in `included` at all.**
+    [#233](https://github.com/abofs/stonyx-orm/issues/233) owns whether a
+    related resource appears in `included`. #235 filters what a record
+    *already in* `included` may **name**; a hidden record is still a
     **member** of that array. The two are different questions and neither closes
     the other: after #235, `GET /animals/1?include=owner,owner.pets` returns
     `owner.data: null` on every permitted animal it sideloads **and still
@@ -1105,11 +1126,29 @@ read all of these.
 
 #### `Record.toJSON()` does not filter relationship linkage unless you pass a verdict
 
-**The framework owns this on four surfaces. You own it everywhere else.**
-
-`GET /:models`, `GET /:models/:id` and both `GET /:models/:id/{relationship}`
-shapes resolve a linkage verdict and pass it to `toJSON()` for you. Any other
-path to a document — `JSON.stringify(record)`, `res.json(record)`,
+**The framework resolves a verdict for you on every request-bound surface that
+serializes a record through `toJSON()`. You own it everywhere else.**
+
+Those surfaces are `GET /:models`, `GET /:models/:id`, both shapes of
+`GET /:models/:id/{relationship}`, the `POST /:models` and `PATCH /:models/:id`
+**response documents**, and every record inside an `?include=` **`included`**
+array ([#234](https://github.com/abofs/stonyx-orm/issues/234) for the four
+reads, [#235](https://github.com/abofs/stonyx-orm/issues/235) for the two
+writes and `included`). Each resolves a linkage verdict and passes it to
+`toJSON()` for you.
+
+**`GET /:models/:id/relationships/{relationship}` is not on that list, and its
+state is not this section's to report.** It builds its `{ type, id }` objects by
+hand instead of calling `toJSON()`, so the `linkage` **option** never reaches it
+— whatever that route filters, it filters itself. And because its linkage *is*
+its primary data, filtering it is a **membership** decision rather than a
+linkage one. Membership on both relationship route families is owned by
+[#232](https://github.com/abofs/stonyx-orm/issues/232) (PR
+[#247](https://github.com/abofs/stonyx-orm/pull/247), in flight as this is
+written); read that issue for its state rather than inferring it here, because
+this section describes only what `toJSON()` filters.
+
+Any other path to a document — `JSON.stringify(record)`, `res.json(record)`,
 `console.log(record)`, a custom route, a queue payload, a websocket frame —
 calls `toJSON()` with no verdict, and **the no-verdict document names every
 related id, including records hidden on every one of their own surfaces**

package/dist/orm-request.js

@@ -1333,27 +1333,46 @@ export default class OrmRequest extends Request {
             };
             // Relationship linkage route: GET /:id/relationships/{relationship}
             //
-            // NO `linkage` FILTER HERE, AND IT IS NOT AN OVERSIGHT --
-            // abofs/stonyx-orm#232 OWNS THIS ROUTE. The three sites that carry the
-            // filter (`buildResponse`'s `included`, the related-resource branch
-            // above, and the two write handlers) all call `record.toJSON()`, which is
-            // where the `linkage` option is applied. This branch builds its
-            // `{ type, id }` objects BY HAND and never calls `toJSON` at all, so it
-            // cannot see a filter no matter who passes one.
+            // NO `linkage` FILTER FROM abofs/stonyx-orm#235, AND THAT IS A SCOPE
+            // BOUNDARY RATHER THAN AN OVERSIGHT -- abofs/stonyx-orm#232 OWNS THIS
+            // ROUTE, and PR #247 is IN FLIGHT against it in this same sprint. If you
+            // are reading this after #247 landed, the filtering below is #232's and
+            // this note records why it was never #235's to add.
             //
-            // It is also a DIFFERENT QUESTION. Everywhere else, linkage is metadata
-            // ABOUT a document. Here the linkage IS the primary data, so dropping an
-            // entry is a MEMBERSHIP decision about what this route serves -- the same
-            // class as abofs/stonyx-orm#233 and #196, not the class #234/#235 close.
-            // That is why it is absent from #224 §2a's seven-site inventory.
+            // The three sites #235 does own (`buildResponse`'s `included`, the
+            // related-resource branch above, and the two write handlers) all reach
+            // the filter through `record.toJSON()`, which is where the `linkage`
+            // OPTION is applied. This branch builds its `{ type, id }` objects BY
+            // HAND and never calls `toJSON` at all, so the `linkage` option cannot
+            // reach it -- whatever this route filters, it has to filter itself, which
+            // is precisely why doing so is a separate change with a separate owner.
             //
-            // MEASURED, so the next person does not re-derive it: this route answers
-            // `GET /animals/1/relationships/owner` with
-            // `{"type":"owner","id":"angela"}` while `GET /owners/angela` is 404.
-            // Wiring the filter in here takes the suite to 993/2 and turns the
+            // It is also a DIFFERENT QUESTION. Everywhere #235 touches, linkage is
+            // metadata ABOUT a document. Here the linkage IS the primary data, so
+            // dropping an entry is a MEMBERSHIP decision about what this route
+            // serves -- the same class as abofs/stonyx-orm#233 and #196, not the
+            // class #234/#235 close. That is why it is absent from #224 §2a's
+            // seven-site inventory.
+            //
+            // MEASURED, so the next person does not re-derive it. Against this
+            // branch's baseline of 1011/0, wiring `createLinkageFilter` into the
+            // belongsTo branch below takes the suite to 1009/2, reddening
+            // `[GUARD] #235 X2` and the
             // `GET /animals/:id/relationships/owner returns relationship linkage`
-            // test red -- which is #232's own reproduction, not a regression.
-            // Pinned unchanged by `[GUARD] #235 X2` in test/integration/orm-test.ts.
+            // test -- the latter is #232's own reproduction, not a regression.
+            //
+            // THE BASELINE IS QUOTED WITH THE RESULT BECAUSE AN EARLIER REVISION OF
+            // THIS COMMENT SAID 993/2 AND SHIPPED IT. This file lands in consumers'
+            // `node_modules`, so a wrong number here is a wrong number in the
+            // published package. 993+2 = 995 is the DEV baseline, carried over from
+            // a branch on which `[GUARD] #235 X2` does not exist. A pass/fail pair
+            // with no baseline beside it cannot be checked by reading, which is how
+            // it survived three artifacts and a review; the qualitative claim was
+            // right the whole time and only the count was wrong.
+            //
+            // `[GUARD] #235 X2` in test/integration/orm-test.ts pins the OWNERSHIP
+            // BOUNDARY here rather than this route's current answer, so that it
+            // survives #247 landing. Read its comment before changing it.
             routes[`/:id/relationships/${dasherizedName}`] = async (request, { filter } = {}) => {
                 const record = await store.find(model, getId(request.params));
                 if (!record)

package/package.json

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

package/src/orm-request.ts

@@ -1454,27 +1454,46 @@ export default class OrmRequest extends Request {
 
       // Relationship linkage route: GET /:id/relationships/{relationship}
       //
-      // NO `linkage` FILTER HERE, AND IT IS NOT AN OVERSIGHT --
-      // abofs/stonyx-orm#232 OWNS THIS ROUTE. The three sites that carry the
-      // filter (`buildResponse`'s `included`, the related-resource branch
-      // above, and the two write handlers) all call `record.toJSON()`, which is
-      // where the `linkage` option is applied. This branch builds its
-      // `{ type, id }` objects BY HAND and never calls `toJSON` at all, so it
-      // cannot see a filter no matter who passes one.
+      // NO `linkage` FILTER FROM abofs/stonyx-orm#235, AND THAT IS A SCOPE
+      // BOUNDARY RATHER THAN AN OVERSIGHT -- abofs/stonyx-orm#232 OWNS THIS
+      // ROUTE, and PR #247 is IN FLIGHT against it in this same sprint. If you
+      // are reading this after #247 landed, the filtering below is #232's and
+      // this note records why it was never #235's to add.
       //
-      // It is also a DIFFERENT QUESTION. Everywhere else, linkage is metadata
-      // ABOUT a document. Here the linkage IS the primary data, so dropping an
-      // entry is a MEMBERSHIP decision about what this route serves -- the same
-      // class as abofs/stonyx-orm#233 and #196, not the class #234/#235 close.
-      // That is why it is absent from #224 §2a's seven-site inventory.
+      // The three sites #235 does own (`buildResponse`'s `included`, the
+      // related-resource branch above, and the two write handlers) all reach
+      // the filter through `record.toJSON()`, which is where the `linkage`
+      // OPTION is applied. This branch builds its `{ type, id }` objects BY
+      // HAND and never calls `toJSON` at all, so the `linkage` option cannot
+      // reach it -- whatever this route filters, it has to filter itself, which
+      // is precisely why doing so is a separate change with a separate owner.
       //
-      // MEASURED, so the next person does not re-derive it: this route answers
-      // `GET /animals/1/relationships/owner` with
-      // `{"type":"owner","id":"angela"}` while `GET /owners/angela` is 404.
-      // Wiring the filter in here takes the suite to 993/2 and turns the
+      // It is also a DIFFERENT QUESTION. Everywhere #235 touches, linkage is
+      // metadata ABOUT a document. Here the linkage IS the primary data, so
+      // dropping an entry is a MEMBERSHIP decision about what this route
+      // serves -- the same class as abofs/stonyx-orm#233 and #196, not the
+      // class #234/#235 close. That is why it is absent from #224 §2a's
+      // seven-site inventory.
+      //
+      // MEASURED, so the next person does not re-derive it. Against this
+      // branch's baseline of 1011/0, wiring `createLinkageFilter` into the
+      // belongsTo branch below takes the suite to 1009/2, reddening
+      // `[GUARD] #235 X2` and the
       // `GET /animals/:id/relationships/owner returns relationship linkage`
-      // test red -- which is #232's own reproduction, not a regression.
-      // Pinned unchanged by `[GUARD] #235 X2` in test/integration/orm-test.ts.
+      // test -- the latter is #232's own reproduction, not a regression.
+      //
+      // THE BASELINE IS QUOTED WITH THE RESULT BECAUSE AN EARLIER REVISION OF
+      // THIS COMMENT SAID 993/2 AND SHIPPED IT. This file lands in consumers'
+      // `node_modules`, so a wrong number here is a wrong number in the
+      // published package. 993+2 = 995 is the DEV baseline, carried over from
+      // a branch on which `[GUARD] #235 X2` does not exist. A pass/fail pair
+      // with no baseline beside it cannot be checked by reading, which is how
+      // it survived three artifacts and a review; the qualitative claim was
+      // right the whole time and only the count was wrong.
+      //
+      // `[GUARD] #235 X2` in test/integration/orm-test.ts pins the OWNERSHIP
+      // BOUNDARY here rather than this route's current answer, so that it
+      // survives #247 landing. Read its comment before changing it.
       routes[`/:id/relationships/${dasherizedName}`] = async (request: OrmRequest$, { filter }: { [key: string]: unknown } = {}) => {
         const record = await store.find(model, getId(request.params)) as OrmRecord | undefined;
         if (!record) return 404;