fix(rest): fold the switched-off action names into the cached object read's ETag

.changeset/28044-object-read-etag-folds-disabled-actions.md

@@ -0,0 +1,15 @@
+---
+'@objectstack/rest': patch
+'@objectstack/spec': patch
+---
+
+fix(rest): a cached `GET /meta/object/:name` that carries `disabledActions` is answered `304 Not Modified` again when nothing changed
+
+Clause-②: no
+Metadata-protocol: none
+
+The default cached object read serves `disabledActions` beside the item: the names in `item.actions` that the deployment's activation ledger switches off. That list used to be kept out of the ETag, so every such read was answered `200` with the full body and never `304`, and on a default deployment, where the ledger is attached, revalidating an object definition saved nothing.
+
+The switched-off list is now part of the object read's ETag. An unchanged object with an unchanged set of switched-off actions is answered `304` on revalidation. When an administrator turns an action off or on under Setup › Packaged automation, the ETag changes and the next revalidation is answered `200` with the new list. `[]` and an absent key give different ETags, so a ledger being attached or detached also changes it. An object with no `disabledActions` key keeps exactly the ETag it had before. The response body is unchanged.
+
+The published description of `disabledActions` on the object read response now says the list is folded into the ETag, instead of saying it is never part of it.

content/docs/references/api/protocol.mdx

@@ -1332,7 +1332,7 @@ This schema accepts one of the following structures:
 | **notModified** | `boolean` | optional (default: `false`) | True if resource has not been modified (304 response) |
 | **version** | `string` | optional | Metadata version identifier |
 | **registration** | `{ state: 'registered' } \| { state: 'refused'; reason: object } \| { state: 'unregistered' }` | optional | The automation engine's verdict on the flow in `data`, read live on every call and never part of `etag` (see `FlowRegistrationSchema`). Present only for a `flow` read answered by a process that runs an automation service; a read that carries it is never answered `notModified`. Absent otherwise, and absence means no engine judged it, never `registered`. |
-| **disabledActions** | `string[]` | optional | The names in the `actions` of the object in `data` that this deployment's activation ledger switches off (a call to any of them is refused 409 `ACTION_DISABLED`), read live on every call and never part of `etag`. Present only for an `object` read answered by a process whose data engine has an activation ledger attached, `[]` when none is switched off; a read that carries it is never answered `notModified`. Absent otherwise, and absence means no ledger answered, never that nothing is switched off. |
+| **disabledActions** | `string[]` | optional | The names in the `actions` of the object in `data` that this deployment's activation ledger switches off (a call to any of them is refused 409 `ACTION_DISABLED`), read live on every call and never part of `etag`. Present only for an `object` read answered by a process whose data engine has an activation ledger attached, `[]` when none is switched off; this method never answers `notModified` for a read that carries it (the REST door folds the served list into the ETag it checks instead, so its 304 comes back only while the switched-off set is unchanged). Absent otherwise, and absence means no ledger answered, never that nothing is switched off. |
 
 ### Nested Shape: `GetMetaItemCachedResponse.etag`
 
@@ -1459,7 +1459,7 @@ This schema accepts one of the following structures:
 | **resettable** | `boolean` | optional | Whether the item can be reset to its packaged default — true iff it is artifact-backed, i.e. there is a baseline to reset TO. |
 | **version** | `string \| null` | optional | ADR-0008 version token of the STORED row a save to this item compares against, at this read's scope (the environment's partition and `?package=`) and lifecycle (`?state=draft` reads the draft row, the plain read the active row). The same keyed token a save receipt's `version` serves for that row: send it back as the `If-Match` request header on `PUT /meta/:type/:name` (with `?mode=draft` for the draft) and a concurrent edit is refused 409 `METADATA_CONFLICT` instead of overwritten. `null` when no stored row is there — an item served from code or a package artifact, or from a row in another scope (a package-less row a package read falls back to) — so the next save creates one: pin it with `If-None-Match: *`. A `null` beside `editable: false` is no such invitation: that item takes no save at this address, so no pin is prescribed for it. ABSENT on the cached published-value branch and on a `?preview=draft` read, which publish no version: absence means "not published here", never "no row". Opaque — echo it verbatim, never parse it. |
 | **registration** | `{ state: 'registered' } \| { state: 'refused'; reason: object } \| { state: 'unregistered' }` | optional | The automation engine's verdict on this flow (see `FlowRegistrationSchema`): `registered`, or `refused` with the engine's `reason` verbatim, or `unregistered`. Present only on a `flow` read answered by a process that runs an automation service; absent otherwise, and absence means no engine judged it, never `registered`. Unlike the protection keys it is published by the cached branch too, read live and never part of the ETag, so a cached read that carries it is never answered 304; it is absent on a draft read, whose pending body no engine holds. The verdict is the answering process's engine. Beside `item`, never inside it: the item's `status` stays what its author declared. |
-| **disabledActions** | `string[]` | optional | The names in `item.actions` that this deployment's activation ledger switches off (an administrator turned them off under Setup › Packaged automation): a call to any of them is refused 409 `ACTION_DISABLED`. Present only on an `object` read answered by a process whose data engine has an activation ledger attached, and then `[]` when none of this object's actions is switched off. Absent otherwise, and absence means no ledger answered, never that nothing is switched off. Unlike the protection keys it is published by the cached branch too, read live and never part of the ETag, so a cached read that carries it is never answered 304; it is absent on a draft read. The ledger is the answering process's engine's. Beside `item`, never inside it: `item.actions` is served as declared, a switched-off action included. |
+| **disabledActions** | `string[]` | optional | The names in `item.actions` that this deployment's activation ledger switches off (an administrator turned them off under Setup › Packaged automation): a call to any of them is refused 409 `ACTION_DISABLED`. Present only on an `object` read answered by a process whose data engine has an activation ledger attached, and then `[]` when none of this object's actions is switched off. Absent otherwise, and absence means no ledger answered, never that nothing is switched off. Unlike the protection keys it is published by the cached branch too, read live and folded into the ETag, so a cached read revalidates to 304 only while the switched-off set is unchanged; it is absent on a draft read. The ledger is the answering process's engine's. Beside `item`, never inside it: `item.actions` is served as declared, a switched-off action included. |
 | **draftChanges** | `{ path: string[]; by: Enum<'copilot' \| 'mcp' \| 'studio' \| 'api'>; actor: string \| null; client?: object; … }[]` | optional | Per-key provenance of the pending draft: which authoring surface last changed each key path of `item`, under which actor, and when. The draft save records it: each draft save is compared with the body that save replaced (the previous draft, or the stored published row for the draft's first save; a draft of an item with no stored published row is recorded as `[]`, the whole body). A `migrate-stored` rewrite of a draft row records nothing, since it is not authoring. The entries are kept from the first recorded save until the draft is published or discarded, which remove the draft row and the entries with it; and no two entries share a path: a save replaces every entry at or under each path it changes, so the last write to change a key is the entry whose `path` is the longest prefix of that key's path, and entries under a key's path are changes inside it. The entries name which writes changed what; they are not a list of every difference from the published body (compare the two bodies for that). Served only on a `?state=draft` read that answers a stored draft row. ABSENT on the active read, the cached branch and a `?preview=draft` read, and for a draft row whose saves recorded none: absence means "not recorded", never "no changes". |
 
 ### Nested Shape: `GetMetaItemResponse.sortability`

packages/rest/src/meta-item-read-routes.ts

@@ -88,7 +88,8 @@
  *
  * The two module-level helpers only this body called moved with it, verbatim,
  * and sit at the end of this file: the reference sweep's declared-refusal
- * re-dresser and the intake reasons' ETag dimension. Five names declared in
+ * re-dresser and the intake reasons' ETag dimension. [#28044] A third, the
+ * switched-off actions' ETag dimension, was born here. Five names declared in
  * `rest-server.ts` stay there and are imported from it: the reference sweep's
  * closed query set (its tests import it from there), the package binding and
  * the draft admission (both already exported), and the absence answer and the
@@ -767,18 +768,23 @@ export function registerMetaItemReadRoutes(this: MetaItemReadRouteHost, scope: M
                             : {};
                         // [#27842] The action twin, for an OBJECT: the
                         // packaged actions the activation ledger switches
-                        // off, beside the document on the same terms. This
-                        // branch is the default door of
+                        // off, beside the document, read live on every call.
+                        // This branch is the default door of
                         // `GET /meta/object/:name`. An object's validator is
-                        // folded and judged HERE (`audienceFolds`), so the
-                        // 304 below stands down for a read that carries the
-                        // key, as the protocol's does for `registration`: the
-                        // switch moves no byte the validator hashes.
+                        // folded and judged HERE (`audienceFolds`), so unlike
+                        // `registration` the key need not stand the 304
+                        // down: [#28044] the served list is folded into the
+                        // validator below (`disabledActionsFingerprint`), so
+                        // an administrator's switch moves the ETag and an
+                        // unchanged switch set still revalidates to 304.
                         const cachedDisabledActions = metaType === 'object' && result.disabledActions !== undefined
                             ? { disabledActions: result.disabledActions }
                             : {};
                         const cachedBeside = { ...cachedRegistration, ...cachedDisabledActions };
-                        const besideJudged = Object.keys(cachedBeside).length > 0;
+                        // Only what is beside the document and in NO
+                        // validator stands the 304 down — `registration`.
+                        const besideJudged = Object.keys(cachedRegistration).length > 0;
+                        const disabledActionsFingerprint = cachedDisabledActionsFingerprint(cachedDisabledActions.disabledActions);
 
                         if (result.notModified) {
                             res.status(304).send();
@@ -870,16 +876,22 @@ export function registerMetaItemReadRoutes(this: MetaItemReadRouteHost, scope: M
                             // [#22639] …and so does what the read gate
                             // withheld: a caller who no longer holds a list
                             // view's capability is never answered a `304`
-                            // for the body that carried it.
+                            // for the body that carried it. [#28044] …and so
+                            // does the switched-off list served beside an
+                            // object: a switch flipped off or on is never
+                            // answered a `304` for the list it replaced.
                             const value = foldVisibilityFingerprintIntoEtag(
                                 foldVisibilityFingerprintIntoEtag(
                                     foldVisibilityFingerprintIntoEtag(
-                                        foldVisibilityFingerprintIntoEtag(result.etag.value, visibilityFingerprint),
-                                        runtimeView.fingerprint,
+                                        foldVisibilityFingerprintIntoEtag(
+                                            foldVisibilityFingerprintIntoEtag(result.etag.value, visibilityFingerprint),
+                                            runtimeView.fingerprint,
+                                        ),
+                                        intakeFingerprint,
                                     ),
-                                    intakeFingerprint,
+                                    audienceFingerprint,
                                 ),
-                                audienceFingerprint,
+                                disabledActionsFingerprint,
                             );
                             const etagValue = result.etag.weak
                                 ? `W/"${value}"`
@@ -1228,3 +1240,14 @@ function notImplementedRefusalAnswer(
 function anonymousFormIntakeFingerprint(warnings: ReadonlyArray<{ path: string; message: string }>): string {
     return objectFieldVisibilityFingerprint(warnings.map((w) => JSON.stringify([w.path, w.message])));
 }
+
+/**
+ * [#28044] The ETag dimension of the `disabledActions` served beside an object
+ * (#27842), hashed over the list exactly as served, so the validator describes
+ * the representation sent. Absent (no ledger answered) folds nothing and keeps
+ * the ETag byte-identical; `[]` (a ledger that switches none of them off) folds
+ * a fingerprint of its own, so a ledger attaching or detaching moves it too.
+ */
+function cachedDisabledActionsFingerprint(disabledActions: readonly string[] | undefined): string {
+    return disabledActions === undefined ? '' : objectFieldVisibilityFingerprint([JSON.stringify(disabledActions)]);
+}

packages/rest/src/meta-object-cached-disabled-actions.test.ts

@@ -11,10 +11,11 @@
 // live on exactly the door that matters.
 //
 // An object's validator is folded and judged HERE (`audienceFolds`), not in the
-// protocol, so this file also pins the 304 half: a read that carries the key is
-// answered in full whatever `If-None-Match` says, because an administrator's
-// switch moves no byte the validator hashes; and the unjudged control still is
-// answered 304.
+// protocol, so this file also pins the 304 half (#28044): the served
+// `disabledActions` is folded into that validator, so an unchanged object under
+// an unchanged switch set is answered 304, a switch flipped off or on answers
+// 200 under a new ETag, and an object no ledger answered for keeps the ETag it
+// had before.
 //
 // The protocol double answers `getMetaItemCached` the way `metadata-protocol`'s
 // producer does: the document under `data`, its ETag, and — where a ledger
@@ -112,20 +113,62 @@ describe('the default cached `GET /meta/object/:name` carries `disabledActions`
         expect(res.body.item.actions).toHaveLength(2);
     });
 
-    it('a read that carries the key is never answered 304; control: the unjudged read still is', async () => {
-        // The validator this door issues for the document, read off a first
-        // answer and sent back as `If-None-Match`.
-        const first = await getItem(setup(undefined).rest, 'object', 'showcase_task');
-        const etag = first.headers.ETag;
+});
+
+// #28044 — the switched-off names are folded into the validator this door
+// issues, so a cached object read that carries `disabledActions` revalidates
+// like any other: `304` while neither the document nor the switch set moved,
+// `200` under a new ETag once an administrator switches an action off or on.
+describe('the cached `GET /meta/object/:name` folds `disabledActions` into its ETag (#28044)', () => {
+    /** Read once, then revalidate with the ETag that answer issued — against `next` as the ledger then answers. */
+    async function revalidate(first: string[] | undefined, next: string[] | undefined) {
+        const served = await getItem(setup(first).rest, 'object', 'showcase_task');
+        expect(served.statusCode).toBe(200);
+        const etag = served.headers.ETag;
         expect(typeof etag).toBe('string');
+        const again = await getItem(setup(next).rest, 'object', 'showcase_task', { 'if-none-match': etag });
+        return { etag, again };
+    }
+
+    it('an unchanged object under an unchanged switch set is answered 304', async () => {
+        const { again } = await revalidate(['showcase_mark_done'], ['showcase_mark_done']);
+        expect(again.statusCode).toBe(304);
+        expect(again.body).toBeUndefined();
+    });
+
+    it('an action switched OFF moves the ETag: 200 with the new list under a new validator', async () => {
+        const { etag, again } = await revalidate(['showcase_mark_done'], ['showcase_mark_done', 'showcase_snooze']);
+        expect(again.statusCode).toBe(200);
+        expect(again.body.disabledActions).toEqual(['showcase_mark_done', 'showcase_snooze']);
+        expect(again.headers.ETag).not.toBe(etag);
+    });
+
+    it('an action switched back ON moves the ETag: 200 with `[]` under a new validator', async () => {
+        const { etag, again } = await revalidate(['showcase_mark_done'], []);
+        expect(again.statusCode).toBe(200);
+        expect(again.body.disabledActions).toEqual([]);
+        expect(again.headers.ETag).not.toBe(etag);
+    });
+
+    it('absent and `[]` fold differently: a ledger attaching (or detaching) moves the ETag', async () => {
+        const attached = await revalidate(undefined, []);
+        expect(attached.again.statusCode).toBe(200);
+        expect(attached.again.body.disabledActions).toEqual([]);
+        expect(attached.again.headers.ETag).not.toBe(attached.etag);
+
+        const detached = await revalidate([], undefined);
+        expect(detached.again.statusCode).toBe(200);
+        expect(detached.again.body).not.toHaveProperty('disabledActions');
+        expect(detached.again.headers.ETag).not.toBe(detached.etag);
+    });
 
-        const judged = await getItem(setup(['showcase_mark_done']).rest, 'object', 'showcase_task', { 'if-none-match': etag });
-        expect(judged.statusCode).toBe(200);
-        expect(judged.body.disabledActions).toEqual(['showcase_mark_done']);
-        // The validator itself is unchanged by the key: the same document, the same ETag.
-        expect(judged.headers.ETag).toBe(etag);
+    it('control: an object with no switched-off action keeps its 304, under the validator it had before', async () => {
+        const none = await revalidate(undefined, undefined);
+        expect(none.again.statusCode).toBe(304);
+        // No ledger answered → nothing folds: the ETag is the document's own.
+        expect(none.etag).toBe('"etag_task"');
 
-        const unjudged = await getItem(setup(undefined).rest, 'object', 'showcase_task', { 'if-none-match': etag });
-        expect(unjudged.statusCode).toBe(304);
+        const empty = await revalidate([], []);
+        expect(empty.again.statusCode).toBe(304);
     });
 });