@reventlessdev/reventless-local 3.0.0-alpha.224 → 3.0.0-alpha.225

package/CHANGELOG.md

@@ -3,6 +3,20 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+# 3.0.0-alpha.225 (2026-08-16)
+
+### Bug Fixes
+
+* **seed:** let seed:reset take the yes it asks for ([1f646f6](https://github.com/ReventlessDev/reventless-core/commit/1f646f6ce13a4238e92b7047ee31650ccc4de4f3))
+### Features
+
+* **core:** exclude retired rows from reads a caller may not widen ([662f31a](https://github.com/ReventlessDev/reventless-core/commit/662f31abb717bda5154199d349da6dcf8e2d3e78))
+* **core:** let [@retired](https://github.com/retired) name a lifecycle state, not only a boolean ([6bb346b](https://github.com/ReventlessDev/reventless-core/commit/6bb346b4f6a5f33826fc24537953482a76067177))
+* **core:** mark the state that retires a row, and allow more than one ([cb1461f](https://github.com/ReventlessDev/reventless-core/commit/cb1461f024d3ca3b53fd9c8b010a054e3fcc4555))
+* **core:** withhold a retired row's payload from the live channel ([82c62db](https://github.com/ReventlessDev/reventless-core/commit/82c62db00b87f7135378496e36601b544d4d2b62))
+* **spec:** [@retired](https://github.com/retired) state-field annotation and its schema emission ([2d8234b](https://github.com/ReventlessDev/reventless-core/commit/2d8234b6b3dd8f479031a67eb5b4b47b5c0c2ff9))
+
+
 # 3.0.0-alpha.224 (2026-08-15)
 
 ### Features

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reventlessdev/reventless-local",
-  "version": "3.0.0-alpha.224",
+  "version": "3.0.0-alpha.225",
   "description": "Local platform for Reventless (in-memory or SQLite backend, for development and testing without AWS)",
   "license": "Apache-2.0",
   "bin": {
@@ -36,22 +36,22 @@
     "ws": "^8.18.0",
     "@reventlessdev/rescript-effect": "0.1.0-alpha.32",
     "@reventlessdev/rescript-graphql-yoga": "1.0.0-alpha.27",
-    "@reventlessdev/rescript-node": "2.0.0-alpha.7",
     "@reventlessdev/rescript-mcp-sdk": "1.0.0-alpha.21",
     "@reventlessdev/rescript-jest": "1.0.0-alpha.10",
+    "@reventlessdev/rescript-node": "2.0.0-alpha.7",
     "@reventlessdev/rescript-pulumi-pulumi": "2.3.0-alpha.19",
-    "@reventlessdev/reventless-core": "3.0.0-alpha.236",
-    "@reventlessdev/reventless-graphql-server": "1.0.0-alpha.84",
-    "@reventlessdev/reventless-infra": "3.0.0-alpha.142",
-    "@reventlessdev/reventless-gwt": "1.0.0-alpha.183",
-    "@reventlessdev/reventless-seed": "1.0.0-alpha.14",
-    "@reventlessdev/reventless-postgres": "3.0.0-alpha.100",
-    "@reventlessdev/reventless-spec": "3.0.0-alpha.114"
+    "@reventlessdev/reventless-core": "3.0.0-alpha.237",
+    "@reventlessdev/reventless-infra": "3.0.0-alpha.143",
+    "@reventlessdev/reventless-graphql-server": "1.0.0-alpha.85",
+    "@reventlessdev/reventless-gwt": "1.0.0-alpha.184",
+    "@reventlessdev/reventless-postgres": "3.0.0-alpha.101",
+    "@reventlessdev/reventless-spec": "3.0.0-alpha.115",
+    "@reventlessdev/reventless-seed": "1.0.0-alpha.15"
   },
   "devDependencies": {
     "rescript": "12.3.0",
     "sury-ppx": "11.0.0-alpha.2",
-    "@reventlessdev/reventless-ppx": "1.0.0-alpha.66"
+    "@reventlessdev/reventless-ppx": "1.0.0-alpha.67"
   },
   "peerDependencies": {
     "rescript": "12.3.0"

package/src/adapter/LocalBus.res

@@ -133,6 +133,7 @@ module type T = {
       ~capability: ReventlessCore.GraphQL_FragmentGenerator.serverCapability,
       ~labelField: string,
       ~ownerScope: (string, string)=?,
+      ~retiredScope: Reventless.OwnerScope.retiredScope=?,
     ) => option<JSON.t>,
   ) => unit
   let getQueryDbListPage: string => option<
@@ -141,6 +142,7 @@ module type T = {
       ~capability: ReventlessCore.GraphQL_FragmentGenerator.serverCapability,
       ~labelField: string,
       ~ownerScope: (string, string)=?,
+      ~retiredScope: Reventless.OwnerScope.retiredScope=?,
     ) => option<JSON.t>,
   >
 
@@ -238,6 +240,7 @@ module Impl = (C: BusConfig): T => {
         ~capability: ReventlessCore.GraphQL_FragmentGenerator.serverCapability,
         ~labelField: string,
         ~ownerScope: (string, string)=?,
+        ~retiredScope: Reventless.OwnerScope.retiredScope=?,
       ) => option<JSON.t>,
     >,
   > = ref(Dict.make())

package/src/adapter/LocalStateChangeDescriptor.res

@@ -27,6 +27,19 @@
     tell it nothing. */
 let maxStateChars = 60 * 1024
 
+/** The `@retired` field of a registered read model, or `None`.
+
+    Looked up by view name rather than passed down from the storage's
+    construction, for the reason the resolvers look it up per request: a storage
+    is built before every plugin's state schema is necessarily registered, and a
+    lookup that missed at construction would publish payloads for the rest of
+    the process. */
+let retiredSpecFor = (name: string): option<Reventless.StateAnnotations.retiredSpec> =>
+  ReventlessCore.Plugin_Helpers.stateSchemaRegistry
+  ->Dict.get(name)
+  ->Option.flatMap(Reventless.StateAnnotations.getSpec)
+  ->Option.flatMap(spec => spec.retired)
+
 let pickSortKeyValue = (state: JSON.t): option<string> =>
   switch state->JSON.Decode.object {
   | Some(obj) =>
@@ -68,16 +81,47 @@ let nextSequence = (): string => {
     - `state`: the resulting row for save(); `None` for delete(), which has no new
       row — the descriptor then omits both `state` and `sortKeyValue`.
     - `seq`: monotonic ordering token, from `nextSequence`. */
-let make = (~changeKind: string, ~id: string, ~state: option<JSON.t>, ~seq: string): JSON.t => {
+let make = (
+  ~changeKind: string,
+  ~id: string,
+  ~state: option<JSON.t>,
+  ~seq: string,
+  ~retiredField: option<string>=?,
+  ~retiredValues: option<array<string>>=?,
+): JSON.t => {
   let descriptor = Dict.make()
   descriptor->Dict.set("changeKind", JSON.Encode.string(changeKind))
   descriptor->Dict.set("id", JSON.Encode.string(id))
-  switch state->Option.flatMap(pickSortKeyValue) {
+  // Whether the row this descriptor announces has been withdrawn from ordinary
+  // reads. A publish cannot be scoped per subscriber — the channel is keyed by
+  // list field and entity, and everyone watching the view receives it — so a
+  // payload here would hand the row to exactly the callers the resolvers just
+  // refused it to.
+  // Both forms of `@retired` are the one question `isRetiredValue` answers, so
+  // nothing here branches on which the view declared.
+  let isRetired = switch (retiredField, state) {
+  | (Some(field), Some(s)) =>
+    {Reventless.OwnerScope.field, values: retiredValues}->Reventless.OwnerScope.isRetiredValue(
+      s->JSON.Decode.object->Option.flatMap(d => d->Dict.get(field)),
+    )
+  | _ => false
+  }
+  // Dropped along with the payload, not just the payload: the sort value is a
+  // timestamp off a row the subscriber may not read, and a subscriber without
+  // one is conservative rather than wrong — it refetches instead of deciding
+  // which page the row belongs on.
+  switch isRetired ? None : state->Option.flatMap(pickSortKeyValue) {
   | Some(v) => descriptor->Dict.set("sortKeyValue", JSON.Encode.string(v))
   | None => ()
   }
   descriptor->Dict.set("seq", JSON.Encode.string(seq))
   switch state {
+  // `Updated` with no payload is the shape this already emits for an oversized
+  // row, and it means the same thing to a client: refetch and let the query
+  // layer answer. Deliberately not `Removed` — the row is not gone, and saying
+  // so would be false for an elevated subscriber reading with `includeRetired`
+  // and false again the moment the row is restored.
+  | Some(_) if isRetired => ()
   | Some(s) =>
     let encoded = s->JSON.stringify
     if encoded->String.length <= maxStateChars {

package/src/adapter/LocalStateChangeDescriptor.res.mjs

@@ -2,6 +2,13 @@
 
 import * as Stdlib_JSON from "@rescript/runtime/lib/es6/Stdlib_JSON.js";
 import * as Stdlib_Option from "@rescript/runtime/lib/es6/Stdlib_Option.js";
+import * as OwnerScope$Reventless from "@reventlessdev/reventless-spec/src/types/OwnerScope.res.mjs";
+import * as StateAnnotations$Reventless from "@reventlessdev/reventless-spec/src/components/StateAnnotations.res.mjs";
+import * as Plugin_Helpers$ReventlessCore from "@reventlessdev/reventless-core/src/plugin/component/Plugin_Helpers.res.mjs";
+
+function retiredSpecFor(name) {
+  return Stdlib_Option.flatMap(Stdlib_Option.flatMap(Plugin_Helpers$ReventlessCore.stateSchemaRegistry[name], StateAnnotations$Reventless.getSpec), spec => spec.retired);
+}
 
 function pickSortKeyValue(state) {
   let obj = Stdlib_JSON.Decode.object(state);
@@ -29,16 +36,20 @@ function nextSequence() {
   return next.toString();
 }
 
-function make(changeKind, id, state, seq) {
+function make(changeKind, id, state, seq, retiredField, retiredValues) {
   let descriptor = {};
   descriptor["changeKind"] = changeKind;
   descriptor["id"] = id;
-  let v = Stdlib_Option.flatMap(state, pickSortKeyValue);
+  let isRetired = retiredField !== undefined && state !== undefined ? OwnerScope$Reventless.isRetiredValue({
+      field: retiredField,
+      values: retiredValues
+    }, Stdlib_Option.flatMap(Stdlib_JSON.Decode.object(state), d => d[retiredField])) : false;
+  let v = isRetired ? undefined : Stdlib_Option.flatMap(state, pickSortKeyValue);
   if (v !== undefined) {
     descriptor["sortKeyValue"] = v;
   }
   descriptor["seq"] = seq;
-  if (state !== undefined) {
+  if (state !== undefined && !isRetired) {
     let encoded = JSON.stringify(state);
     if (encoded.length <= 61440) {
       descriptor["state"] = state;
@@ -53,9 +64,10 @@ let maxStateChars = 61440;
 
 export {
   maxStateChars,
+  retiredSpecFor,
   pickSortKeyValue,
   lastSequence,
   nextSequence,
   make,
 }
-/* No side effect */
+/* OwnerScope-Reventless Not a pure module */

package/src/adapter/QueryDb/QueryDbResolvers_GraphQL.res

@@ -180,6 +180,54 @@ module Make = (Bus: LocalBus.T) => {
         ->Option.mapOr(false, v => v == required)
       }
 
+    // ── Retirement narrowing ─────────────────────────────────────────────────
+    // The same two forms as owner scoping above, for the same reason: a door
+    // that narrows the page and a door that hands back one row both have to ask.
+    // Read per request for the same reason too.
+    let retiredSpecOf = () =>
+      Plugin_Helpers.stateSchemaRegistry
+      ->Dict.get(name)
+      ->Option.flatMap(Reventless.StateAnnotations.getSpec)
+      ->Option.flatMap(spec => spec.retired)
+
+    // `includeRetired` is the caller asking; `decideRetired` decides whether the
+    // asking counts. Read here rather than inside the decision so the argument
+    // stays an argument — the door reports what was asked, the classifier says
+    // who may be answered.
+    let askedForRetired = (~args) =>
+      args
+      ->JSON.Decode.object
+      ->Option.flatMap(d => d->Dict.get("includeRetired"))
+      ->Option.flatMap(JSON.Decode.bool)
+      ->Option.getOr(false)
+
+    let retiredDecision = (~ctx, ~args) =>
+      extractIdentity(ctx)->Reventless.OwnerScope.decideRetired(
+        ~retiredField=retiredSpecOf()->Option.map(r => r.field),
+        ~retiredValues=?retiredSpecOf()->Option.flatMap(r => r.values),
+        ~asked=askedForRetired(~args),
+      )
+
+    let retiredScopeFor = (~ctx, ~args) =>
+      retiredDecision(~ctx, ~args)->Reventless.OwnerScope.retiredScopeOf
+
+    // Post-read form. The single-row and by-ids doors are where a filtered list
+    // would otherwise be walked around: a pasted URL, or a reference resolved
+    // from another row, reaches the entity directly.
+    let retiredAllows = (~ctx, ~args, item: JSON.t) =>
+      switch retiredScopeFor(~ctx, ~args) {
+      | None => true
+      // Absent keeps the row, matching `QueryDbListQuery`: a row written before
+      // the annotation existed is not retired. Which of the two forms decides
+      // that is `isRetiredValue`'s question, not this door's.
+      | Some(scope) =>
+        !(
+          scope->Reventless.OwnerScope.isRetiredValue(
+            item->JSON.Decode.object->Option.flatMap(d => d->Dict.get(scope.field)),
+          )
+        )
+      }
+
     let cap = s => s->String.charAt(0)->String.toUpperCase ++ s->String.slice(~start=1)
 
     // Resolve query field names: check registry first, fall back to safe defaults.
@@ -260,7 +308,8 @@ module Make = (Bus: LocalBus.T) => {
           // A row the caller does not own answers as though it were not there.
           // Distinguishing "not yours" from "not found" here would turn this door
           // into an oracle for which ids exist.
-          | Some(item) if !ownerAllows(~ctx, item) => JSON.Encode.null
+          | Some(item) if !ownerAllows(~ctx, item) || !retiredAllows(~ctx, ~args, item) =>
+            JSON.Encode.null
           | Some(item) =>
             if includeIdParam {
               // Copied — `JSON.Decode.object` hands back the stored object itself,
@@ -327,7 +376,7 @@ module Make = (Bus: LocalBus.T) => {
               loaded
               ->Array.filterMap(((id, opt)) =>
                 opt
-                ->Option.filter(item => ownerAllows(~ctx, item))
+                ->Option.filter(item => ownerAllows(~ctx, item) && retiredAllows(~ctx, ~args, item))
                 ->Option.map(item => {
                   let obj = item->JSON.Decode.object->Option.mapOr(Dict.make(), Dict.copy)
                   obj->Dict.set("id", JSON.Encode.string(id))
@@ -411,6 +460,11 @@ module Make = (Bus: LocalBus.T) => {
           | RefuseOwned => emptyConnection
           | decision =>
             let ownerScope = Reventless.OwnerScope.scopeOf(decision)
+            // Same both-arms rule as `ownerScope`, and the same reason it is
+            // spelled out: this predicate decides what the caller may see, so a
+            // push-down that did not receive it would serve the archive to
+            // everyone on the path that is hardest to notice.
+            let retiredScope = retiredScopeFor(~ctx, ~args)
             let argsDict = args->JSON.Decode.object->Option.getOr(Dict.make())
             // Prefer a backend list push-down (SQLite builds json_extract predicates
             // + ORDER BY … LIMIT so it never materialises the whole read model). When
@@ -427,7 +481,7 @@ module Make = (Bus: LocalBus.T) => {
               DomainGraphQL_Server.decodeGlobalId(id)->Option.map(((_, lid)) => lid)
             switch Bus.getQueryDbListPage(name) {
             | Some(listPage) =>
-              switch listPage(~argsDict, ~capability, ~labelField, ~ownerScope?) {
+              switch listPage(~argsDict, ~capability, ~labelField, ~ownerScope?, ~retiredScope?) {
               | Some(conn) => conn
               | None =>
                 let items = await fetchAllItems()
@@ -438,6 +492,7 @@ module Make = (Bus: LocalBus.T) => {
                   ~labelField,
                   ~decodeLocalId,
                   ~ownerScope?,
+                  ~retiredScope?,
                 )
               }
             | None =>
@@ -449,6 +504,7 @@ module Make = (Bus: LocalBus.T) => {
                 ~labelField,
                 ~decodeLocalId,
                 ~ownerScope?,
+                ~retiredScope?,
               )
             }
           }
@@ -466,7 +522,8 @@ module Make = (Bus: LocalBus.T) => {
           // The legacy shape has no push-down to reach, so the narrowing is a plain
           // filter here. `scannedCount` counts what is returned, not what was read:
           // the pre-scoping total would tell a caller how many rows they may not see.
-          let items = all->Array.filter(item => ownerAllows(~ctx, item))
+          let items =
+            all->Array.filter(item => ownerAllows(~ctx, item) && retiredAllows(~ctx, ~args, item))
           Obj.magic({"nextToken": Nullable.null, "scannedCount": items->Array.length, "items": items})
         }
       }
@@ -531,7 +588,10 @@ module Make = (Bus: LocalBus.T) => {
             // Narrowed here, before the cursor window and the sort-key filter, so
             // every page this door emits is a page of rows the caller owns. Doing
             // it after would hand back short pages with valid cursors.
-            let allItems = loaded->Array.filter(item => ownerAllows(~ctx, item))
+            let allItems =
+              loaded->Array.filter(item =>
+                ownerAllows(~ctx, item) && retiredAllows(~ctx, ~args, item)
+              )
 
             // Cursor-keyed filtering: exclude items on the cursor side of the boundary
             let cursorFiltered = if isBackward {
@@ -624,7 +684,8 @@ module Make = (Bus: LocalBus.T) => {
             // push-down and the scan are two ways to reach the same rows, and a
             // narrowing that lives in only one is a hole that appears when a
             // backend gains or loses an index.
-            let scoped = rows => rows->Array.filter(item => ownerAllows(~ctx, item))
+            let scoped = rows =>
+              rows->Array.filter(item => ownerAllows(~ctx, item) && retiredAllows(~ctx, ~args, item))
             // Prefer the pushed-down equality lookup (SQLite rides the GSI index;
             // in-memory reuses its lazy snapshot). Fall back to scan+filter only
             // if no lookup is registered for this QueryDb.

package/src/adapter/QueryDb/QueryDbResolvers_GraphQL.res.mjs

@@ -11,6 +11,7 @@ import * as Identity$Reventless from "@reventlessdev/reventless-spec/src/types/I
 import * as OwnerScope$Reventless from "@reventlessdev/reventless-spec/src/types/OwnerScope.res.mjs";
 import * as Api_Ids$ReventlessCore from "@reventlessdev/reventless-core/src/components/Api/Api_Ids.res.mjs";
 import * as Authorization$Reventless from "@reventlessdev/reventless-spec/src/types/Authorization.res.mjs";
+import * as StateAnnotations$Reventless from "@reventlessdev/reventless-spec/src/components/StateAnnotations.res.mjs";
 import * as Plugin_Helpers$ReventlessCore from "@reventlessdev/reventless-core/src/plugin/component/Plugin_Helpers.res.mjs";
 import * as SortKey_Filter$ReventlessLocal from "./SortKey_Filter.res.mjs";
 import * as QueryDbListQuery$ReventlessCore from "@reventlessdev/reventless-core/src/components/Api/QueryDbListQuery.res.mjs";
@@ -100,6 +101,17 @@ function Make(Bus) {
       let field = match._0;
       return Stdlib_Option.mapOr(Stdlib_Option.flatMap(Stdlib_Option.flatMap(Stdlib_JSON.Decode.object(item), d => d[field]), Stdlib_JSON.Decode.string), false, v => v === required);
     };
+    let retiredSpecOf = () => Stdlib_Option.flatMap(Stdlib_Option.flatMap(Plugin_Helpers$ReventlessCore.stateSchemaRegistry[name], StateAnnotations$Reventless.getSpec), spec => spec.retired);
+    let askedForRetired = args => Stdlib_Option.getOr(Stdlib_Option.flatMap(Stdlib_Option.flatMap(Stdlib_JSON.Decode.object(args), d => d["includeRetired"]), Stdlib_JSON.Decode.bool), false);
+    let retiredDecision = (ctx, args) => OwnerScope$Reventless.decideRetired(extractIdentity(ctx), Stdlib_Option.map(retiredSpecOf(), r => r.field), Stdlib_Option.flatMap(retiredSpecOf(), r => r.values), askedForRetired(args), undefined);
+    let retiredAllows = (ctx, args, item) => {
+      let scope = OwnerScope$Reventless.retiredScopeOf(retiredDecision(ctx, args));
+      if (scope !== undefined) {
+        return !OwnerScope$Reventless.isRetiredValue(scope, Stdlib_Option.flatMap(Stdlib_JSON.Decode.object(item), d => d[scope.field]));
+      } else {
+        return true;
+      }
+    };
     let cap = s => s.charAt(0).toUpperCase() + s.slice(1);
     let registryEntry = Plugin_Helpers$ReventlessCore.queryFieldNamesRegistry[name];
     let singleQueryName = registryEntry !== undefined ? registryEntry.singleFieldName : name.charAt(0).toLowerCase() + name.slice(1);
@@ -139,7 +151,7 @@ function Make(Bus) {
       if (item === undefined) {
         return null;
       }
-      if (!ownerAllows(ctx, item)) {
+      if (!ownerAllows(ctx, item) || !retiredAllows(ctx, args, item)) {
         return null;
       }
       if (!includeIdParam) {
@@ -186,7 +198,13 @@ function Make(Bus) {
         }));
         return Stdlib_Array.filterMap(loaded, param => {
           let id = param[0];
-          return Stdlib_Option.map(Stdlib_Option.filter(param[1], item => ownerAllows(ctx, item)), item => {
+          return Stdlib_Option.map(Stdlib_Option.filter(param[1], item => {
+            if (ownerAllows(ctx, item)) {
+              return retiredAllows(ctx, args, item);
+            } else {
+              return false;
+            }
+          }), item => {
             let obj = Stdlib_Option.mapOr(Stdlib_JSON.Decode.object(item), {}, prim => Object.assign({}, prim));
             obj["id"] = id;
             return obj;
@@ -242,19 +260,20 @@ function Make(Bus) {
           return emptyConnection;
         }
         let ownerScope = OwnerScope$Reventless.scopeOf(decision);
+        let retiredScope = OwnerScope$Reventless.retiredScopeOf(retiredDecision(ctx, args));
         let argsDict = Stdlib_Option.getOr(Stdlib_JSON.Decode.object(args), {});
         let decodeLocalId = id => Stdlib_Option.map(DomainGraphQL_Server$ReventlessLocal.decodeGlobalId(id), param => param[1]);
         let listPage = Bus.getQueryDbListPage(name);
         if (listPage !== undefined) {
-          let conn = listPage(argsDict, capability, labelField, ownerScope);
+          let conn = listPage(argsDict, capability, labelField, ownerScope, retiredScope);
           if (conn !== undefined) {
             return conn;
           }
           let items = await fetchAllItems();
-          return QueryDbListQuery$ReventlessCore.run(items, argsDict, capability, labelField, decodeLocalId, ownerScope);
+          return QueryDbListQuery$ReventlessCore.run(items, argsDict, capability, labelField, decodeLocalId, ownerScope, retiredScope);
         }
         let items$1 = await fetchAllItems();
-        return QueryDbListQuery$ReventlessCore.run(items$1, argsDict, capability, labelField, decodeLocalId, ownerScope);
+        return QueryDbListQuery$ReventlessCore.run(items$1, argsDict, capability, labelField, decodeLocalId, ownerScope, retiredScope);
       };
       match = [
         sdl,
@@ -272,7 +291,13 @@ function Make(Bus) {
           };
         }
         let all = await fetchAllItems();
-        let items = all.filter(item => ownerAllows(ctx, item));
+        let items = all.filter(item => {
+          if (ownerAllows(ctx, item)) {
+            return retiredAllows(ctx, args, item);
+          } else {
+            return false;
+          }
+        });
         return {
           nextToken: null,
           scannedCount: items.length,
@@ -331,7 +356,13 @@ function Make(Bus) {
           return emptyConn;
         }
         let loaded = await Effect.runPromise(Effect.catchAll(Stream.runCollect(ops.loadStream(id)), param => Effect.succeed([])));
-        let allItems = loaded.filter(item => ownerAllows(ctx, item));
+        let allItems = loaded.filter(item => {
+          if (ownerAllows(ctx, item)) {
+            return retiredAllows(ctx, args, item);
+          } else {
+            return false;
+          }
+        });
         let cursorFiltered;
         if (isBackward) {
           let beforeKey = Stdlib_Option.map(before, decodeCursor);
@@ -408,7 +439,13 @@ function Make(Bus) {
           return [];
         }
         let value = Stdlib_Option.getOr(Stdlib_Option.flatMap(Stdlib_Option.flatMap(Stdlib_JSON.Decode.object(args), d => d[index]), Stdlib_JSON.Decode.string), "");
-        let scoped = rows => rows.filter(item => ownerAllows(ctx, item));
+        let scoped = rows => rows.filter(item => {
+          if (ownerAllows(ctx, item)) {
+            return retiredAllows(ctx, args, item);
+          } else {
+            return false;
+          }
+        });
         let lookup = Bus.getQueryDbIndexLookup(name);
         if (lookup !== undefined) {
           return scoped(lookup(filterField, value));

package/src/adapter/QueryDb/QueryDbStorage_InMemory.res

@@ -198,6 +198,8 @@ module Make = (Bus: LocalBus.T) => {
         ~id=entityKeyFor(id, subKey),
         ~state=Some(state),
         ~seq=LocalStateChangeDescriptor.nextSequence(),
+        ~retiredField=?LocalStateChangeDescriptor.retiredSpecFor(name)->Option.map(r => r.field),
+      ~retiredValues=?LocalStateChangeDescriptor.retiredSpecFor(name)->Option.flatMap(r => r.values),
       )
       Bus.publishStateChange(~name, ~descriptor)
     }

package/src/adapter/QueryDb/QueryDbStorage_InMemory.res.mjs

@@ -167,11 +167,11 @@ function Make(Bus) {
     };
     let publishSaved = (changeKind, id, state) => {
       let subKey = getSubKey(state, subIdField);
-      let descriptor = LocalStateChangeDescriptor$ReventlessLocal.make(changeKind, entityKeyFor(id, subKey), state, LocalStateChangeDescriptor$ReventlessLocal.nextSequence());
+      let descriptor = LocalStateChangeDescriptor$ReventlessLocal.make(changeKind, entityKeyFor(id, subKey), state, LocalStateChangeDescriptor$ReventlessLocal.nextSequence(), Stdlib_Option.map(LocalStateChangeDescriptor$ReventlessLocal.retiredSpecFor(name), r => r.field), Stdlib_Option.flatMap(LocalStateChangeDescriptor$ReventlessLocal.retiredSpecFor(name), r => r.values));
       Bus.publishStateChange(name, descriptor);
     };
     let publishRemoved = (id, subKey) => {
-      let descriptor = LocalStateChangeDescriptor$ReventlessLocal.make("Removed", entityKeyFor(id, subKey), undefined, LocalStateChangeDescriptor$ReventlessLocal.nextSequence());
+      let descriptor = LocalStateChangeDescriptor$ReventlessLocal.make("Removed", entityKeyFor(id, subKey), undefined, LocalStateChangeDescriptor$ReventlessLocal.nextSequence(), undefined, undefined);
       Bus.publishStateChange(name, descriptor);
     };
     let save = async (id, state, _saveMode, ttl) => {

package/src/adapter/QueryDb/QueryDbStorage_Sqlite.res

@@ -147,6 +147,7 @@ type busCallbacks = {
       ~capability: GraphQL_FragmentGenerator.serverCapability,
       ~labelField: string,
       ~ownerScope: (string, string)=?,
+      ~retiredScope: Reventless.OwnerScope.retiredScope=?,
     ) => option<JSON.t>,
   ) => unit,
 }
@@ -263,6 +264,8 @@ let makeStorage = (
       ~id=entityKeyFor(id, subKey),
       ~state=Some(state),
       ~seq=LocalStateChangeDescriptor.nextSequence(),
+      ~retiredField=?LocalStateChangeDescriptor.retiredSpecFor(name)->Option.map(r => r.field),
+      ~retiredValues=?LocalStateChangeDescriptor.retiredSpecFor(name)->Option.flatMap(r => r.values),
     )
     bus.publishStateChange(~name, ~descriptor)
   }
@@ -428,6 +431,7 @@ let makeStorage = (
     ~capability: GraphQL_FragmentGenerator.serverCapability,
     ~labelField as _,
     ~ownerScope: option<(string, string)>=?,
+    ~retiredScope: option<Reventless.OwnerScope.retiredScope>=?,
   ): option<JSON.t> => {
     let filterDict =
       argsDict->Dict.get("filter")->Option.flatMap(JSON.Decode.object)->Option.getOr(Dict.make())
@@ -451,6 +455,39 @@ let makeStorage = (
         params->Array.push(JSON.Encode.string(required))
       | None => ()
       }
+      // `IS NOT 1`, not `= 0`, and on the raw extraction rather than through
+      // `jsonText`. SQLite renders a JSON true as the integer 1 and a missing
+      // path as NULL, and `IS NOT` is the comparison that treats NULL as a value
+      // rather than poisoning the predicate. Three cases have to land the way the
+      // in-memory spec lands them: absent keeps the row (a row written before the
+      // annotation is not retired), false keeps it, and a value that is not a
+      // JSON boolean keeps it too — which `= 0` would get wrong, since a string
+      // `'true'` compares unequal to 0 and the row would vanish on this backend
+      // only. `QueryDbListPushdownParityTest` is what holds the two together.
+      //
+      // The state form compares against the states' text instead of 1, and the
+      // three cases land identically: absent is NULL, a state outside the set
+      // compares unequal to every member, and a non-string value is none of them
+      // either.
+      //
+      // Written as a conjunction of `IS NOT` rather than as `NOT IN`: `IN` is
+      // ordinary equality, so a NULL path makes the predicate NULL and the row
+      // vanishes — the absent case, which has to keep the row. `IS NOT` is the
+      // comparison that treats NULL as a value, and it does not have an `IN`
+      // spelling. A set naming nothing pushes no predicate down, which is the
+      // same answer `isRetiredValue` gives it.
+      switch retiredScope {
+      | Some(scope) =>
+        let path = `json_extract(item, '$.${scope.field->String.replaceAll("'", "''")}')`
+        switch scope.values {
+        | None => whereParts->Array.push(`${path} IS NOT 1`)
+        | Some(states) =>
+          states->Array.forEach(state =>
+            whereParts->Array.push(`${path} IS NOT '${state->String.replaceAll("'", "''")}'`)
+          )
+        }
+      | None => ()
+      }
       let valString = v =>
         switch v->JSON.Decode.string {
         | Some(s) => Some(s)

package/src/adapter/QueryDb/QueryDbStorage_Sqlite.res.mjs

@@ -194,7 +194,7 @@ function makeStorage(db, bus, name, indexes, subIdField) {
   };
   let publishSaved = (changeKind, id, state) => {
     let subKey = computeSubKey(state, subIdField);
-    let descriptor = LocalStateChangeDescriptor$ReventlessLocal.make(changeKind, entityKeyFor(id, subKey), state, LocalStateChangeDescriptor$ReventlessLocal.nextSequence());
+    let descriptor = LocalStateChangeDescriptor$ReventlessLocal.make(changeKind, entityKeyFor(id, subKey), state, LocalStateChangeDescriptor$ReventlessLocal.nextSequence(), Stdlib_Option.map(LocalStateChangeDescriptor$ReventlessLocal.retiredSpecFor(name), r => r.field), Stdlib_Option.flatMap(LocalStateChangeDescriptor$ReventlessLocal.retiredSpecFor(name), r => r.values));
     bus.publishStateChange(name, descriptor);
   };
   let saveKind = (id, state) => {
@@ -209,7 +209,7 @@ function makeStorage(db, bus, name, indexes, subIdField) {
     }
   };
   let publishRemoved = (id, subKey) => {
-    let descriptor = LocalStateChangeDescriptor$ReventlessLocal.make("Removed", entityKeyFor(id, subKey), undefined, LocalStateChangeDescriptor$ReventlessLocal.nextSequence());
+    let descriptor = LocalStateChangeDescriptor$ReventlessLocal.make("Removed", entityKeyFor(id, subKey), undefined, LocalStateChangeDescriptor$ReventlessLocal.nextSequence(), undefined, undefined);
     bus.publishStateChange(name, descriptor);
   };
   let rowKeysForPartition = id => SqliteDriver$ReventlessLocal.all(selectByPartitionStmt, [id]).map(row => {
@@ -337,7 +337,7 @@ function makeStorage(db, bus, name, indexes, subIdField) {
   };
   let jsonText = field => `CAST(json_extract(item, '$.` + field.replaceAll("'", "''") + `') AS TEXT)`;
   let idExpr = "COALESCE(json_extract(item, '$.id'), partition_key)";
-  let listPage = (argsDict, capability, param, ownerScope) => {
+  let listPage = (argsDict, capability, param, ownerScope, retiredScope) => {
     let filterDict = Stdlib_Option.getOr(Stdlib_Option.flatMap(argsDict["filter"], Stdlib_JSON.Decode.object), {});
     let strNonEmpty = k => Stdlib_Option.mapOr(Stdlib_Option.flatMap(filterDict[k], Stdlib_JSON.Decode.string), false, s => s.length > 0);
     let hasIds = Stdlib_Option.mapOr(Stdlib_Option.flatMap(filterDict["ids"], Stdlib_JSON.Decode.array), false, a => a.length !== 0);
@@ -352,6 +352,17 @@ function makeStorage(db, bus, name, indexes, subIdField) {
       whereParts.push(jsonText(ownerScope[0]) + ` = ?`);
       params.push(ownerScope[1]);
     }
+    if (retiredScope !== undefined) {
+      let path = `json_extract(item, '$.` + retiredScope.field.replaceAll("'", "''") + `')`;
+      let states = retiredScope.values;
+      if (states !== undefined) {
+        states.forEach(state => {
+          whereParts.push(path + ` IS NOT '` + state.replaceAll("'", "''") + `'`);
+        });
+      } else {
+        whereParts.push(path + ` IS NOT 1`);
+      }
+    }
     let valString = v => {
       let s = Stdlib_JSON.Decode.string(v);
       if (s !== undefined) {

package/src/reset/LocalSeedReset.res

@@ -11,9 +11,20 @@
 //     unlink leaves it on the orphaned inode still serving every row it had, the
 //     delete looks like it worked, and the seed then fails against the untouched
 //     server with "the target store is not empty". Deleting ROWS through a second
-//     connection is visible to the running server immediately (its reads go to
-//     these tables; there is no in-process cache), so a reset needs no restart and
-//     no stopping of the platform.
+//     connection is what works instead — a query issued after the delete reads
+//     the emptied tables, so the platform need not be STOPPED for the reset.
+//
+//     It does need RESTARTING before the re-seed, and this comment claimed
+//     otherwise for a while on the strength of "there is no in-process cache".
+//     There is: a DCB slice's decision state is held per partition in the
+//     running process, and a delete behind its back does not invalidate it. The
+//     slice goes on refusing writes for ids whose state it still remembers, so
+//     the re-seed fails with `…AlreadyExists` naming rows the store visibly does
+//     not hold — verified by the same id being refused before a restart and
+//     accepted after, against byte-identical tables.
+//
+//     So: reset with the platform up, then restart it, then seed. Emptying the
+//     store and emptying the process are two steps, and only the first is here.
 //
 //   • It is SCOPED. Wiping domain data leaves the plugin registry intact, so a
 //     re-seed just works — the same reason the deployed default is `domain`.
@@ -543,15 +554,21 @@ let run = (~dbPath: option<string>=?): unit => {
         if total(plan) == 0 {
           Console.log("Nothing to do.")
         } else {
+          // Set at all ⇒ it is the answer, affirmative or not. Falling through to
+          // the prompt on an unrecognised value would ask for a TTY the runs this
+          // variable exists for do not have, so `SEED_RESET_CONFIRM=no` would
+          // throw where it plainly means "don't". Both arms read the reply
+          // through one predicate, which is what keeps the typed `y` and the
+          // env var speaking the same language.
           let confirmed = switch Seed.Prompt.envValue("SEED_RESET_CONFIRM") {
-          | Some("1") | Some("yes") => true
-          | _ =>
+          | Some(answer) => Seed.Prompt.isAffirmative(answer)
+          | None =>
             let answer = await Seed.Prompt.ask(
               `Empty ${total(
                   plan,
                 )->Int.toString} row(s)/object(s) in the "${plan.scope->scopeLabel}" scope? [y/N]: `,
             )
-            answer->String.trim->String.toLowerCase == "y"
+            Seed.Prompt.isAffirmative(answer)
           }
           if confirmed {
             execute(db, plan)

package/src/reset/LocalSeedReset.res.mjs

@@ -499,25 +499,8 @@ function run(dbPath) {
       if (total(plan) === 0) {
         console.log("Nothing to do.");
       } else {
-        let match$1 = Seed_Prompt$ReventlessSeed.envValue("SEED_RESET_CONFIRM");
-        let confirmed;
-        let exit = 0;
-        if (match$1 !== undefined) {
-          switch (match$1) {
-            case "1" :
-            case "yes" :
-              confirmed = true;
-              break;
-            default:
-              exit = 1;
-          }
-        } else {
-          exit = 1;
-        }
-        if (exit === 1) {
-          let answer = await Seed_Prompt$ReventlessSeed.ask(`Empty ` + total(plan).toString() + ` row(s)/object(s) in the "` + scopeLabel(plan.scope) + `" scope? [y/N]: `);
-          confirmed = answer.trim().toLowerCase() === "y";
-        }
+        let answer = Seed_Prompt$ReventlessSeed.envValue("SEED_RESET_CONFIRM");
+        let confirmed = answer !== undefined ? Seed_Prompt$ReventlessSeed.isAffirmative(answer) : Seed_Prompt$ReventlessSeed.isAffirmative(await Seed_Prompt$ReventlessSeed.ask(`Empty ` + total(plan).toString() + ` row(s)/object(s) in the "` + scopeLabel(plan.scope) + `" scope? [y/N]: `));
         if (confirmed) {
           execute(db, plan);
           console.log(`Reset complete — the "` + scopeLabel(plan.scope) + `" scope reads empty and is re-seedable.`);

package/tests/adapter/GraphQL_SchemaInspectorTest.res

@@ -109,10 +109,11 @@ let indexedStateSchemaWithAnnotations = indexedStateSchema->S.Metadata.set(
     scanSort: [],
     semantic: [],
     metric: [],
-    status: None,
+    lifecycle: None,
     groupBy: None,
     visibility: None,
     live: None,
+    retired: None,
   },
 )
 
@@ -139,10 +140,11 @@ let orderedStateSchemaWithAnnotations = orderedStateSchema->S.Metadata.set(
     scanSort: [],
     semantic: [],
     metric: [],
-    status: None,
+    lifecycle: None,
     groupBy: None,
     visibility: None,
     live: None,
+    retired: None,
   },
 )
 
@@ -170,10 +172,11 @@ let scanStateSchemaWithAnnotations = scanStateSchema->S.Metadata.set(
     scanSort: ["name"],
     semantic: [],
     metric: [],
-    status: None,
+    lifecycle: None,
     groupBy: None,
     visibility: None,
     live: None,
+    retired: None,
   },
 )
 
@@ -429,7 +432,7 @@ describe("GraphQL_SchemaInspector", () => {
       // Query field should use filter + first/after/last/before args (Phase 4)
       expect(
         sdl->String.includes(
-          "Relay_Products(filter: RelayProductFilter, first: Int, after: String, last: Int, before: String): RelayProductConnection!",
+          "Relay_Products(filter: RelayProductFilter, first: Int, after: String, last: Int, before: String, includeRetired: Boolean): RelayProductConnection!",
         ),
       )->toBe(true)
       // Connection filter input with search/searchPrefix/ids

package/tests/adapter/GraphQL_SchemaInspectorTest.res.mjs

@@ -114,10 +114,11 @@ let indexedStateSchemaWithAnnotations = S.Metadata.set(indexedStateSchema, State
   scanSort: [],
   semantic: [],
   metric: [],
-  status: undefined,
+  lifecycle: undefined,
   groupBy: undefined,
   visibility: undefined,
-  live: undefined
+  live: undefined,
+  retired: undefined
 });
 
 let orderedStateSchema = S.schema(s => ({
@@ -141,10 +142,11 @@ let orderedStateSchemaWithAnnotations = S.Metadata.set(orderedStateSchema, State
   scanSort: [],
   semantic: [],
   metric: [],
-  status: undefined,
+  lifecycle: undefined,
   groupBy: undefined,
   visibility: undefined,
-  live: undefined
+  live: undefined,
+  retired: undefined
 });
 
 let scanStateSchema = S.schema(s => ({
@@ -169,10 +171,11 @@ let scanStateSchemaWithAnnotations = S.Metadata.set(scanStateSchema, StateAnnota
   scanSort: ["name"],
   semantic: [],
   metric: [],
-  status: undefined,
+  lifecycle: undefined,
   groupBy: undefined,
   visibility: undefined,
-  live: undefined
+  live: undefined,
+  retired: undefined
 });
 
 globalThis.describe("GraphQL_SchemaInspector", () => {
@@ -350,7 +353,7 @@ globalThis.describe("GraphQL_SchemaInspector", () => {
       globalThis.expect(sdl.includes("edges: [RelayProductEdge!]!")).toBe(true);
       globalThis.expect(sdl.includes("pageInfo: PageInfo!")).toBe(true);
       globalThis.expect(sdl.includes("totalCount")).toBe(false);
-      globalThis.expect(sdl.includes("Relay_Products(filter: RelayProductFilter, first: Int, after: String, last: Int, before: String): RelayProductConnection!")).toBe(true);
+      globalThis.expect(sdl.includes("Relay_Products(filter: RelayProductFilter, first: Int, after: String, last: Int, before: String, includeRetired: Boolean): RelayProductConnection!")).toBe(true);
       globalThis.expect(sdl.includes("input RelayProductFilter")).toBe(true);
       globalThis.expect(sdl.includes("search: String")).toBe(true);
       globalThis.expect(sdl.includes("searchPrefix: String")).toBe(true);

package/tests/adapter/GraphQL_SubscriptionResolversTest.res.mjs

@@ -69,7 +69,7 @@ globalThis.describe("LocalGraphQL_SubscriptionResolvers", () => {
           "2026-05-19T12:00:00Z"
         ]
       ]);
-      let descriptor = LocalStateChangeDescriptor$ReventlessLocal.make("Updated", "prod-1", state, LocalStateChangeDescriptor$ReventlessLocal.nextSequence());
+      let descriptor = LocalStateChangeDescriptor$ReventlessLocal.make("Updated", "prod-1", state, LocalStateChangeDescriptor$ReventlessLocal.nextSequence(), undefined, undefined);
       TestBus.publishStateChange("Product", descriptor);
       let received = await consumerPromise;
       if (received !== null) {
@@ -88,7 +88,7 @@ globalThis.describe("LocalGraphQL_SubscriptionResolvers", () => {
       let foreignDescriptor = LocalStateChangeDescriptor$ReventlessLocal.make("Updated", "cat-1", Object.fromEntries([[
           "id",
           "cat-1"
-        ]]), LocalStateChangeDescriptor$ReventlessLocal.nextSequence());
+        ]]), LocalStateChangeDescriptor$ReventlessLocal.nextSequence(), undefined, undefined);
       TestBus.publishStateChange("Category", foreignDescriptor);
       let received = await consumerPromise;
       globalThis.expect(received === null ? undefined : Primitive_option.some(received)).toEqual(undefined);

package/tests/adapter/QueryDbListPushdownParityTest.res

@@ -21,13 +21,21 @@ let capability: ReventlessCore.GraphQL_FragmentGenerator.serverCapability = {
   sortFields: ["name", "qty", "status"],
 }
 
-let mk = (id, status, name, qty, owner) => {
+let mk = (id, status, name, qty, owner, archived) => {
   let o = Dict.make()
   o->Dict.set("id", JSON.Encode.string(id))
   o->Dict.set("status", JSON.Encode.string(status))
   o->Dict.set("name", JSON.Encode.string(name))
   o->Dict.set("qty", JSON.Encode.int(qty))
   o->Dict.set("owner", JSON.Encode.string(owner))
+  // `archived` is absent on p-5, not false. A row written before the annotation
+  // existed has no such attribute, and "absent means not retired" is the rule
+  // both the spec and every push-down have to land on — get it wrong and the
+  // view empties the day someone adds `@retired`.
+  switch archived {
+  | Some(b) => o->Dict.set("archived", JSON.Encode.bool(b))
+  | None => ()
+  }
   JSON.Encode.object(o)
 }
 
@@ -40,11 +48,11 @@ let mk = (id, status, name, qty, owner) => {
 // to work on a field the client-visible filter surface does not admit, which is
 // the normal case and the reason the predicate travels separately.
 let rows = [
-  ("p-1", "active", "Charlie", 3, "u-a"),
-  ("p-2", "active", "Alpha", 1, "u-b"),
-  ("p-3", "inactive", "Echo", 5, "u-a"),
-  ("p-4", "active", "Bravo", 2, "u-c"),
-  ("p-5", "inactive", "Delta", 4, "u-a"),
+  ("p-1", "active", "Charlie", 3, "u-a", Some(false)),
+  ("p-2", "active", "Alpha", 1, "u-b", Some(true)),
+  ("p-3", "inactive", "Echo", 5, "u-a", Some(false)),
+  ("p-4", "active", "Bravo", 2, "u-c", Some(true)),
+  ("p-5", "inactive", "Delta", 4, "u-a", None),
 ]
 
 type setup = {
@@ -53,6 +61,7 @@ type setup = {
     ~capability: ReventlessCore.GraphQL_FragmentGenerator.serverCapability,
     ~labelField: string,
     ~ownerScope: (string, string)=?,
+    ~retiredScope: Reventless.OwnerScope.retiredScope=?,
   ) => option<JSON.t>,
   fullScan: unit => array<JSON.t>,
 }
@@ -66,8 +75,13 @@ let build = async (): setup => {
   let s = Storage.make(~name="items", ~indexes=[], ~api=(), ~apiRole=(), ~owner=None, ~opts)
   let ops = await s.operations->TestRunner.resolve
   for i in 0 to rows->Array.length - 1 {
-    let (id, status, name, qty, owner) = rows->Array.getUnsafe(i)
-    let _ = await ops.save(id, mk(id, status, name, qty, owner), ReventlessCore.QueryDb.Any, None)
+    let (id, status, name, qty, owner, archived) = rows->Array.getUnsafe(i)
+    let _ = await ops.save(
+      id,
+      mk(id, status, name, qty, owner, archived),
+      ReventlessCore.QueryDb.Any,
+      None,
+    )
   }
   {
     listPage: TestBus.getQueryDbListPage("items")->Option.getOrThrow,
@@ -118,7 +132,7 @@ let orderBy = (f, dir) =>
 let cur = ReventlessCore.QueryDbListQuery.encodeCursor
 
 // Assert the push-down serves this shape AND matches the spec exactly.
-let checkPushed = async (~label, ~ownerScope=?, args) => {
+let checkPushed = async (~label, ~ownerScope=?, ~retiredScope=?, args) => {
   let s = await build()
   let argsDict = argsOf(args)
   let expected =
@@ -129,8 +143,9 @@ let checkPushed = async (~label, ~ownerScope=?, args) => {
       ~labelField="name",
       ~decodeLocalId=_ => None,
       ~ownerScope?,
+      ~retiredScope?,
     )->norm
-  switch s.listPage(~argsDict, ~capability, ~labelField="name", ~ownerScope?) {
+  switch s.listPage(~argsDict, ~capability, ~labelField="name", ~ownerScope?, ~retiredScope?) {
   | Some(actual) => expect(actual->norm)->toEqual(expected)
   | None => expect("push-down for " ++ label)->toBe("returned None")
   }
@@ -142,6 +157,15 @@ let checkFallback = async args => {
   expect(s.listPage(~argsDict=argsOf(args), ~capability, ~labelField="name")->Option.isSome)->toBe(false)
 }
 
+// The ids a retirement-narrowed read returns, from the push-down.
+let liveIds = async args => {
+  let s = await build()
+  switch s.listPage(~argsDict=argsOf(args), ~capability, ~labelField="name", ~retiredScope={field: "archived", values: None}) {
+  | Some(conn) => (conn->norm).edges->Array.map(e => e.id)
+  | None => []
+  }
+}
+
 // The ids a scoped read actually returns, from the push-down.
 let scopedIds = async (~owner, args) => {
   let s = await build()
@@ -218,6 +242,54 @@ describe("QueryDb list push-down parity (SQLite ≡ QueryDbListQuery spec)", ()
     checkFallback([("last", JSON.Encode.int(2)), ("before", JSON.Encode.string(cur("p-4")))])
   )
 
+  // ── Retirement narrowing ──────────────────────────────────────────────────
+  // Same parity argument as owner scoping below: the push-down is the path a
+  // deployment takes and the spec is the path the tests reach, so a predicate
+  // implemented in one of them is a hole every fallback-based test calls green.
+  describe("retirement narrowing", () => {
+    testPromise("bare page, narrowed", () =>
+      checkPushed(~label="retired-bare", ~retiredScope={field: "archived", values: None}, [])
+    )
+    testPromise("narrowed + orderBy", () =>
+      checkPushed(
+        ~label="retired-order",
+        ~retiredScope={field: "archived", values: None},
+        [("orderBy", orderBy("name", "DESC"))],
+      )
+    )
+    testPromise("narrowed + the caller's own filter", () =>
+      checkPushed(
+        ~label="retired-filter",
+        ~retiredScope={field: "archived", values: None},
+        [("filter", filterOf([("statusEq", JSON.Encode.string("active"))]))],
+      )
+    )
+    testPromise("narrowed + owner-scoped together", () =>
+      checkPushed(
+        ~label="retired-owner",
+        ~ownerScope=("owner", "u-a"),
+        ~retiredScope={field: "archived", values: None},
+        [],
+      )
+    )
+
+    // The rows, not just the parity: p-2 and p-4 are archived, p-5 carries no
+    // flag at all. Parity alone would pass if BOTH implementations were wrong
+    // the same way.
+    testPromise("drops the archived rows and keeps the one with no flag", async () => {
+      let ids = await liveIds([])
+      expect(ids)->toEqual(["p-1", "p-3", "p-5"])
+    })
+
+    // The reason the predicate is pushed into the SQL rather than applied to the
+    // page: `first: 2` must yield two LIVE rows, not two rows of which some were
+    // filtered away afterwards.
+    testPromise("a page of first:2 is two live rows, not two rows minus the archived", async () => {
+      let ids = await liveIds([("first", JSON.Encode.int(2))])
+      expect(ids)->toEqual(["p-1", "p-3"])
+    })
+  })
+
   // ── Owner scoping ─────────────────────────────────────────────────────────
   // Parity matters more here than anywhere else in this file. The push-down is
   // the path a deployment actually takes; the spec is the path the tests most

package/tests/adapter/QueryDbListPushdownParityTest.res.mjs

@@ -36,13 +36,16 @@ let capability = {
   sortFields: capability_sortFields
 };
 
-function mk(id, status, name, qty, owner) {
+function mk(id, status, name, qty, owner, archived) {
   let o = {};
   o["id"] = id;
   o["status"] = status;
   o["name"] = name;
   o["qty"] = qty;
   o["owner"] = owner;
+  if (archived !== undefined) {
+    o["archived"] = archived;
+  }
   return o;
 }
 
@@ -52,35 +55,40 @@ let rows = [
     "active",
     "Charlie",
     3,
-    "u-a"
+    "u-a",
+    false
   ],
   [
     "p-2",
     "active",
     "Alpha",
     1,
-    "u-b"
+    "u-b",
+    true
   ],
   [
     "p-3",
     "inactive",
     "Echo",
     5,
-    "u-a"
+    "u-a",
+    false
   ],
   [
     "p-4",
     "active",
     "Bravo",
     2,
-    "u-c"
+    "u-c",
+    true
   ],
   [
     "p-5",
     "inactive",
     "Delta",
     4,
-    "u-a"
+    "u-a",
+    undefined
   ]
 ];
 
@@ -96,7 +104,7 @@ async function build() {
   for (let i = 0, i_finish = rows.length; i < i_finish; ++i) {
     let match = rows[i];
     let id = match[0];
-    await ops.save(id, mk(id, match[1], match[2], match[3], match[4]), "Any", undefined);
+    await ops.save(id, mk(id, match[1], match[2], match[3], match[4], match[5]), "Any", undefined);
   }
   return {
     listPage: Stdlib_Option.getOrThrow(TestBus.getQueryDbListPage("items"), undefined),
@@ -148,11 +156,11 @@ function orderBy(f, dir) {
   ]);
 }
 
-async function checkPushed(label, ownerScope, args) {
+async function checkPushed(label, ownerScope, retiredScope, args) {
   let s = await build();
   let argsDict = Object.fromEntries(args);
-  let expected = norm(QueryDbListQuery$ReventlessCore.run(s.fullScan(), argsDict, capability, "name", param => {}, ownerScope));
-  let actual = s.listPage(argsDict, capability, "name", ownerScope);
+  let expected = norm(QueryDbListQuery$ReventlessCore.run(s.fullScan(), argsDict, capability, "name", param => {}, ownerScope, retiredScope));
+  let actual = s.listPage(argsDict, capability, "name", ownerScope, retiredScope);
   if (actual !== undefined) {
     globalThis.expect(norm(actual)).toEqual(expected);
   } else {
@@ -162,7 +170,20 @@ async function checkPushed(label, ownerScope, args) {
 
 async function checkFallback(args) {
   let s = await build();
-  globalThis.expect(Stdlib_Option.isSome(s.listPage(Object.fromEntries(args), capability, "name", undefined))).toBe(false);
+  globalThis.expect(Stdlib_Option.isSome(s.listPage(Object.fromEntries(args), capability, "name", undefined, undefined))).toBe(false);
+}
+
+async function liveIds(args) {
+  let s = await build();
+  let conn = s.listPage(Object.fromEntries(args), capability, "name", undefined, {
+    field: "archived",
+    values: undefined
+  });
+  if (conn !== undefined) {
+    return norm(conn).edges.map(e => e.id);
+  } else {
+    return [];
+  }
 }
 
 async function scopedIds(owner, args) {
@@ -170,7 +191,7 @@ async function scopedIds(owner, args) {
   let conn = s.listPage(Object.fromEntries(args), capability, "name", [
     "owner",
     owner
-  ]);
+  ], undefined);
   if (conn !== undefined) {
     return norm(conn).edges.map(e => e.id);
   } else {
@@ -179,12 +200,12 @@ async function scopedIds(owner, args) {
 }
 
 globalThis.describe("QueryDb list push-down parity (SQLite ≡ QueryDbListQuery spec)", () => {
-  globalThis.test("bare page", () => checkPushed("bare", undefined, []));
-  globalThis.test("first:2", () => checkPushed("first", undefined, [[
+  globalThis.test("bare page", () => checkPushed("bare", undefined, undefined, []));
+  globalThis.test("first:2", () => checkPushed("first", undefined, undefined, [[
       "first",
       2
     ]]));
-  globalThis.test("first:2 + after", () => checkPushed("after", undefined, [
+  globalThis.test("first:2 + after", () => checkPushed("after", undefined, undefined, [
     [
       "first",
       2
@@ -194,14 +215,14 @@ globalThis.describe("QueryDb list push-down parity (SQLite ≡ QueryDbListQuery
       QueryDbListQuery$ReventlessCore.encodeCursor("p-2")
     ]
   ]));
-  globalThis.test("statusEq active", () => checkPushed("eq", undefined, [[
+  globalThis.test("statusEq active", () => checkPushed("eq", undefined, undefined, [[
       "filter",
       Object.fromEntries([[
           "statusEq",
           "active"
         ]])
     ]]));
-  globalThis.test("statusEq active + first:2", () => checkPushed("eq+first", undefined, [
+  globalThis.test("statusEq active + first:2", () => checkPushed("eq+first", undefined, undefined, [
     [
       "filter",
       Object.fromEntries([[
@@ -214,15 +235,15 @@ globalThis.describe("QueryDb list push-down parity (SQLite ≡ QueryDbListQuery
       2
     ]
   ]));
-  globalThis.test("orderBy name ASC", () => checkPushed("order-asc", undefined, [[
+  globalThis.test("orderBy name ASC", () => checkPushed("order-asc", undefined, undefined, [[
       "orderBy",
       orderBy("name", "ASC")
     ]]));
-  globalThis.test("orderBy name DESC", () => checkPushed("order-desc", undefined, [[
+  globalThis.test("orderBy name DESC", () => checkPushed("order-desc", undefined, undefined, [[
       "orderBy",
       orderBy("name", "DESC")
     ]]));
-  globalThis.test("orderBy name DESC + first:2 + after", () => checkPushed("order-desc-after", undefined, [
+  globalThis.test("orderBy name DESC + first:2 + after", () => checkPushed("order-desc-after", undefined, undefined, [
     [
       "orderBy",
       orderBy("name", "DESC")
@@ -236,11 +257,11 @@ globalThis.describe("QueryDb list push-down parity (SQLite ≡ QueryDbListQuery
       QueryDbListQuery$ReventlessCore.encodeCursor("Delta")
     ]
   ]));
-  globalThis.test("orderBy status ASC (tiebreak by id)", () => checkPushed("order-tiebreak", undefined, [[
+  globalThis.test("orderBy status ASC (tiebreak by id)", () => checkPushed("order-tiebreak", undefined, undefined, [[
       "orderBy",
       orderBy("status", "ASC")
     ]]));
-  globalThis.test("qty range From/To (numeric-as-string)", () => checkPushed("range", undefined, [[
+  globalThis.test("qty range From/To (numeric-as-string)", () => checkPushed("range", undefined, undefined, [[
       "filter",
       Object.fromEntries([
         [
@@ -253,7 +274,7 @@ globalThis.describe("QueryDb list push-down parity (SQLite ≡ QueryDbListQuery
         ]
       ])
     ]]));
-  globalThis.test("orderBy qty ASC (numeric-as-string sort)", () => checkPushed("order-qty", undefined, [[
+  globalThis.test("orderBy qty ASC (numeric-as-string sort)", () => checkPushed("order-qty", undefined, undefined, [[
       "orderBy",
       orderBy("qty", "ASC")
     ]]));
@@ -288,22 +309,70 @@ globalThis.describe("QueryDb list push-down parity (SQLite ≡ QueryDbListQuery
       QueryDbListQuery$ReventlessCore.encodeCursor("p-4")
     ]
   ]));
+  globalThis.describe("retirement narrowing", () => {
+    globalThis.test("bare page, narrowed", () => checkPushed("retired-bare", undefined, {
+      field: "archived",
+      values: undefined
+    }, []));
+    globalThis.test("narrowed + orderBy", () => checkPushed("retired-order", undefined, {
+      field: "archived",
+      values: undefined
+    }, [[
+        "orderBy",
+        orderBy("name", "DESC")
+      ]]));
+    globalThis.test("narrowed + the caller's own filter", () => checkPushed("retired-filter", undefined, {
+      field: "archived",
+      values: undefined
+    }, [[
+        "filter",
+        Object.fromEntries([[
+            "statusEq",
+            "active"
+          ]])
+      ]]));
+    globalThis.test("narrowed + owner-scoped together", () => checkPushed("retired-owner", [
+      "owner",
+      "u-a"
+    ], {
+      field: "archived",
+      values: undefined
+    }, []));
+    globalThis.test("drops the archived rows and keeps the one with no flag", async () => {
+      let ids = await liveIds([]);
+      globalThis.expect(ids).toEqual([
+        "p-1",
+        "p-3",
+        "p-5"
+      ]);
+    });
+    globalThis.test("a page of first:2 is two live rows, not two rows minus the archived", async () => {
+      let ids = await liveIds([[
+          "first",
+          2
+        ]]);
+      globalThis.expect(ids).toEqual([
+        "p-1",
+        "p-3"
+      ]);
+    });
+  });
   globalThis.describe("owner scoping", () => {
     globalThis.test("bare page, scoped", () => checkPushed("owner-bare", [
       "owner",
       "u-a"
-    ], []));
+    ], undefined, []));
     globalThis.test("scoped + orderBy", () => checkPushed("owner-order", [
       "owner",
       "u-a"
-    ], [[
+    ], undefined, [[
         "orderBy",
         orderBy("name", "DESC")
       ]]));
     globalThis.test("scoped + client filter compose", () => checkPushed("owner-and-filter", [
       "owner",
       "u-a"
-    ], [[
+    ], undefined, [[
         "filter",
         Object.fromEntries([[
             "statusEq",
@@ -361,6 +430,7 @@ export {
   cur,
   checkPushed,
   checkFallback,
+  liveIds,
   scopedIds,
 }
 /*  Not a pure module */

package/tests/adapter/QueryDbListResolverTest.res

@@ -37,10 +37,11 @@ let rowStateSchemaWithAnnotations =
       scanSort: ["name"],
       semantic: [],
       metric: [],
-      status: None,
+      lifecycle: None,
       groupBy: None,
       visibility: None,
       live: None,
+      retired: None,
     },
   )
 

package/tests/adapter/QueryDbListResolverTest.res.mjs

@@ -45,10 +45,11 @@ let rowStateSchemaWithAnnotations = S.Metadata.set(rowStateSchema, StateAnnotati
   scanSort: ["name"],
   semantic: [],
   metric: [],
-  status: undefined,
+  lifecycle: undefined,
   groupBy: undefined,
   visibility: undefined,
-  live: undefined
+  live: undefined,
+  retired: undefined
 });
 
 let newrecord = {...Identity$Reventless.anonymous};