@reventlessdev/reventless-aws 3.0.0-alpha.302 → 3.0.0-alpha.303

package/CHANGELOG.md

@@ -3,6 +3,16 @@
 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.303 (2026-08-16)
+
+### 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))
+
+
 # 3.0.0-alpha.302 (2026-08-15)
 
 ### Bug Fixes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reventlessdev/reventless-aws",
-  "version": "3.0.0-alpha.302",
+  "version": "3.0.0-alpha.303",
   "description": "AWS adapters for Reventless",
   "license": "Apache-2.0",
   "dependencies": {
@@ -12,18 +12,18 @@
     "@aws-sdk/s3-request-presigner": "3.970.0",
     "sury": "11.0.0-alpha.4",
     "uuid": "^13.0.0",
-    "@reventlessdev/rescript-jest": "1.0.0-alpha.10",
+    "@reventlessdev/rescript-aws-sdk": "3.0.0-alpha.11",
     "@reventlessdev/rescript-effect": "0.1.0-alpha.32",
+    "@reventlessdev/rescript-jest": "1.0.0-alpha.10",
     "@reventlessdev/rescript-node": "2.0.0-alpha.7",
-    "@reventlessdev/rescript-aws-sdk": "3.0.0-alpha.11",
-    "@reventlessdev/rescript-pulumi-aws": "2.4.0-alpha.76",
-    "@reventlessdev/rescript-pulumi-pulumi": "2.3.0-alpha.19",
+    "@reventlessdev/rescript-pulumi-aws": "2.4.0-alpha.77",
     "@reventlessdev/rescript-uuid": "2.0.0-alpha.0",
-    "@reventlessdev/reventless-infra": "3.0.0-alpha.142",
-    "@reventlessdev/reventless-core": "3.0.0-alpha.236",
+    "@reventlessdev/reventless-core": "3.0.0-alpha.237",
+    "@reventlessdev/reventless-infra": "3.0.0-alpha.143",
     "@reventlessdev/reventless-interop": "3.0.0-alpha.31",
-    "@reventlessdev/reventless-postgres": "3.0.0-alpha.100",
-    "@reventlessdev/reventless-spec": "3.0.0-alpha.114"
+    "@reventlessdev/rescript-pulumi-pulumi": "2.3.0-alpha.19",
+    "@reventlessdev/reventless-postgres": "3.0.0-alpha.101",
+    "@reventlessdev/reventless-spec": "3.0.0-alpha.115"
   },
   "devDependencies": {
     "rescript": "12.3.0",

package/src/adapter/Api/Platform_ComponentDefinitions_Lambda_Ops.res

@@ -90,6 +90,24 @@ let mapMembers = (obj: dict<JSON.t>, key: string, f: dict<JSON.t> => unit): unit
     )
   }
 
+// Read-path shim for the `statusField` → `lifecycleField` rename. A structure
+// persisted before the rename carries only the old key, and this handler serves
+// raw JSON, so the resolver would find no `lifecycleField` and answer null until
+// the plugin re-registers. That is not a crash — the SDL declares a nullable
+// `String`, not a `[T!]!` that would null-propagate to the root — but it is a
+// silent degradation: command-menu filtering, board columns, group sections,
+// progress trackers and state diagrams go quiet while lists keep rendering.
+//
+// Delete a release later, once no structure predating the rename can be reached.
+// It closes a window; it does not support two names.
+let fillLifecycleField = (component: dict<JSON.t>): unit =>
+  switch (component->Dict.get("lifecycleField"), component->Dict.get("statusField")) {
+  | (None | Some(JSON.Null), Some(legacy)) => component->Dict.set("lifecycleField", legacy)
+  | _ => ()
+  }
+
+let readSideCollections = ["readModels", "stateViewSlices"]
+
 let healStructure = (structure: dict<JSON.t>): dict<JSON.t> => {
   let out = Dict.fromArray(structure->Dict.toArray)
   // The collections themselves are `[T!]!` too, so an absent one is the same
@@ -103,6 +121,9 @@ let healStructure = (structure: dict<JSON.t>): dict<JSON.t> => {
       )
     })
   )
+  readSideCollections->Array.forEach(collection =>
+    out->mapMembers(collection, fillLifecycleField)
+  )
   out
 }
 

package/src/adapter/Api/Platform_ComponentDefinitions_Lambda_Ops.res.mjs

@@ -148,6 +148,23 @@ function mapMembers(obj, key, f) {
   }
 }
 
+function fillLifecycleField(component) {
+  let match = component["lifecycleField"];
+  let match$1 = component["statusField"];
+  if (match !== undefined && match !== null) {
+    return;
+  }
+  if (match$1 !== undefined) {
+    component["lifecycleField"] = match$1;
+    return;
+  }
+}
+
+let readSideCollections = [
+  "readModels",
+  "stateViewSlices"
+];
+
 function healStructure(structure) {
   let out = Object.fromEntries(Object.entries(structure));
   fillLists(out, healByCollection.map(param => param[0]));
@@ -161,6 +178,7 @@ function healStructure(structure) {
       });
     });
   });
+  readSideCollections.forEach(collection => mapMembers(out, collection, fillLifecycleField));
   return out;
 }
 
@@ -483,6 +501,8 @@ export {
   healByCollection,
   fillLists,
   mapMembers,
+  fillLifecycleField,
+  readSideCollections,
   healStructure,
   isPublicQueryable,
   filterStructure,

package/src/adapter/QueryDb/PgQueryResolver_Lambda.res

@@ -68,6 +68,7 @@ type pushdowns = {
     ~capability: ReventlessCore.GraphQL_FragmentGenerator.serverCapability,
     ~labelField: string,
     ~ownerScope: (string, string)=?,
+    ~retiredScope: Reventless.OwnerScope.retiredScope=?,
   ) => promise<option<JSON.t>>,
   // Sub-id connection ({single}Items) — keyset over sub_key within a partition.
   itemsPage: (
@@ -76,6 +77,7 @@ type pushdowns = {
     ~id: string,
     ~argsDict: dict<JSON.t>,
     ~ownerScope: (string, string)=?,
+    ~retiredScope: Reventless.OwnerScope.retiredScope=?,
   ) => promise<JSON.t>,
   // Full materialisation for the list fallback (shapes listPage declines).
   scanAll: (~readModelName: string) => promise<array<JSON.t>>,
@@ -95,6 +97,8 @@ type binding = {
       from the same schema `capability` comes from, so the two cannot disagree
       about which fields this read model has. */
   ownerField: option<string>,
+  retiredField: option<string>,
+  retiredValues: option<array<string>>,
 }
 
 // -- arg helpers -------------------------------------------------------------
@@ -178,6 +182,35 @@ let dispatch = async (
       | ScopeTo(field, required) =>
         item->argStr(field)->Option.mapOr(false, v => v == required)
       }
+    // The caller's request to see the archive, honoured only where the
+    // classification says it counts.
+    let askedForRetired =
+      payload.arguments
+      ->argObj
+      ->Dict.get("includeRetired")
+      ->Option.flatMap(JSON.Decode.bool)
+      ->Option.getOr(false)
+    let retiredScope =
+      payload.identity
+      ->Reventless.OwnerScope.decideRetired(
+        ~retiredField=binding.retiredField,
+        ~retiredValues=?binding.retiredValues,
+        ~asked=askedForRetired,
+      )
+      ->Reventless.OwnerScope.retiredScopeOf
+    // Absent keeps the row, as in `QueryDbListQuery`. The two forms of `@retired`
+    // differ only inside `isRetiredValue`, so nothing here branches on which one
+    // the view declared.
+    let retiredAllows = (item: JSON.t) =>
+      switch retiredScope {
+      | None => true
+      | Some(scope) =>
+        !(
+          scope->Reventless.OwnerScope.isRetiredValue(
+            item->JSON.Decode.object->Option.flatMap(d => d->Dict.get(scope.field)),
+          )
+        )
+      }
     switch payload.kind {
     | "getById" =>
       let id = payload.arguments->argStr("id")->Option.getOr("")
@@ -199,7 +232,7 @@ let dispatch = async (
       switch found {
       // A row the caller does not own answers as "not found". Saying "not yours"
       // instead would make this door an oracle for which ids exist.
-      | Some(item) if !ownerAllows(item) => JSON.Encode.null
+      | Some(item) if !ownerAllows(item) || !retiredAllows(item) => JSON.Encode.null
       | Some(item) => binding.includeIdParam ? withId(item, resolvedKey) : item
       | None => JSON.Encode.null
       }
@@ -216,7 +249,9 @@ let dispatch = async (
       let extra = missing->Array.length > 0
         ? await binding.pushdowns.byIds(~readModelName=rm, missing)
         : []
-      JSON.Encode.array(Array.concat(found, extra)->Array.filter(ownerAllows))
+      JSON.Encode.array(
+        Array.concat(found, extra)->Array.filter(item => ownerAllows(item) && retiredAllows(item)),
+      )
 
     | "items" =>
       // Sub-id connection: {single}Items(id, filter, first/after/last/before).
@@ -233,6 +268,7 @@ let dispatch = async (
             ~id,
             ~argsDict=payload.arguments->argObj,
             ~ownerScope=?Reventless.OwnerScope.scopeOf(decision),
+            ~retiredScope?,
           )
         }
       | None => emptyConnection()
@@ -274,7 +310,7 @@ let dispatch = async (
       if authorized {
         JSON.Encode.array(
           (await binding.pushdowns.indexLookup(~readModelName=rm, field, value))->Array.filter(
-            ownerAllows,
+            item => ownerAllows(item) && retiredAllows(item),
           ),
         )
       } else {
@@ -293,6 +329,7 @@ let dispatch = async (
           ~capability=binding.capability,
           ~labelField=binding.labelField,
           ~ownerScope?,
+          ~retiredScope?,
         ) {
         | Some(conn) => conn
         | None =>
@@ -306,6 +343,7 @@ let dispatch = async (
             ~capability=binding.capability,
             ~labelField=binding.labelField,
             ~ownerScope?,
+            ~retiredScope?,
           )
         }
       }

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

@@ -80,6 +80,15 @@ async function dispatch(binding, lookupBindingOpt, payload) {
       let required = match._1;
       return Stdlib_Option.mapOr(argStr(item, match._0), false, v => v === required);
     };
+    let askedForRetired = Stdlib_Option.getOr(Stdlib_Option.flatMap(argObj(payload.arguments)["includeRetired"], Stdlib_JSON.Decode.bool), false);
+    let retiredScope = OwnerScope$Reventless.retiredScopeOf(OwnerScope$Reventless.decideRetired(payload.identity, binding.retiredField, binding.retiredValues, askedForRetired, undefined));
+    let retiredAllows = item => {
+      if (retiredScope !== undefined) {
+        return !OwnerScope$Reventless.isRetiredValue(retiredScope, Stdlib_Option.flatMap(Stdlib_JSON.Decode.object(item), d => d[retiredScope.field]));
+      } else {
+        return true;
+      }
+    };
     let other = payload.kind;
     switch (other) {
       case "byIds" :
@@ -87,7 +96,13 @@ async function dispatch(binding, lookupBindingOpt, payload) {
         let found = await binding.pushdowns.byIds(rm, ids);
         let missing = found.length < ids.length ? Stdlib_Array.filterMap(ids, Api_Ids$ReventlessCore.alternateKey) : [];
         let extra = missing.length !== 0 ? await binding.pushdowns.byIds(rm, missing) : [];
-        return found.concat(extra).filter(ownerAllows);
+        return found.concat(extra).filter(item => {
+          if (ownerAllows(item)) {
+            return retiredAllows(item);
+          } else {
+            return false;
+          }
+        });
       case "getById" :
         let id = Stdlib_Option.getOr(argStr(payload.arguments, "id"), "");
         let loadKey = async key => {
@@ -106,7 +121,7 @@ async function dispatch(binding, lookupBindingOpt, payload) {
             await loadKey(match$2)
           ];
         let found$1 = match$3[1];
-        if (found$1 !== undefined && ownerAllows(found$1)) {
+        if (found$1 !== undefined && ownerAllows(found$1) && retiredAllows(found$1)) {
           if (binding.includeIdParam) {
             return withId(found$1, match$3[0]);
           } else {
@@ -134,7 +149,13 @@ async function dispatch(binding, lookupBindingOpt, payload) {
           authorized = true;
         }
         if (authorized) {
-          return (await binding.pushdowns.indexLookup(rm, field, value)).filter(ownerAllows);
+          return (await binding.pushdowns.indexLookup(rm, field, value)).filter(item => {
+            if (ownerAllows(item)) {
+              return retiredAllows(item);
+            } else {
+              return false;
+            }
+          });
         } else {
           return [];
         }
@@ -148,7 +169,7 @@ async function dispatch(binding, lookupBindingOpt, payload) {
         if (typeof decision !== "object" && decision !== "Unscoped") {
           return emptyConnection();
         }
-        return await binding.pushdowns.itemsPage(rm, subIdField, id$1, argObj(payload.arguments), OwnerScope$Reventless.scopeOf(decision));
+        return await binding.pushdowns.itemsPage(rm, subIdField, id$1, argObj(payload.arguments), OwnerScope$Reventless.scopeOf(decision), retiredScope);
         break;
       case "list" :
         let argsDict = argObj(payload.arguments);
@@ -157,12 +178,12 @@ async function dispatch(binding, lookupBindingOpt, payload) {
           return emptyConnection();
         }
         let ownerScope = OwnerScope$Reventless.scopeOf(decision$1);
-        let conn = await binding.pushdowns.listPage(rm, argsDict, binding.capability, binding.labelField, ownerScope);
+        let conn = await binding.pushdowns.listPage(rm, argsDict, binding.capability, binding.labelField, ownerScope, retiredScope);
         if (conn !== undefined) {
           return conn;
         }
         let items$1 = await binding.pushdowns.scanAll(rm);
-        return QueryDbListQuery$ReventlessCore.run(items$1, argsDict, binding.capability, binding.labelField, undefined, ownerScope);
+        return QueryDbListQuery$ReventlessCore.run(items$1, argsDict, binding.capability, binding.labelField, undefined, ownerScope, retiredScope);
         break;
       case "resolveMany" :
         let target = Stdlib_Option.getOr(payload.target, rm);

package/src/adapter/QueryDb/QueryDbResolvers_AppSync.res

@@ -256,12 +256,12 @@ let make: ReventlessCore.QueryDb_Adapter.resolversMaker<api, role> = (
       ~view=name,
       ~ownerField,
     )
+    let isIndexed = f =>
+      indexes->Array.some(ic => ic.idField->Option.getOr(ic.index) == f) ||
+        subIdField->Option.getOr("") == f
     switch ownerField {
     | Some(f) =>
-      let indexed =
-        indexes->Array.some(ic => ic.idField->Option.getOr(ic.index) == f) ||
-          subIdField->Option.getOr("") == f
-      if !indexed {
+      if !isIndexed(f) {
         log.warn(
           ~comp="QueryDbResolvers_AppSync",
           `${name}: @owner field "${f}" is not the key of any index on this table. ` ++
@@ -271,6 +271,34 @@ let make: ReventlessCore.QueryDb_Adapter.resolversMaker<api, role> = (
       }
     | None => ()
     }
+    let retiredSpec =
+      stateSchemaOpt
+      ->Option.flatMap(Reventless.StateAnnotations.getSpec)
+      ->Option.flatMap(spec => spec.retired)
+    let retiredField = retiredSpec->Option.map(r => r.field)
+    let retiredValues = retiredSpec->Option.flatMap(r => r.values)
+    // The same class of "works, but scans" mistake as the owner warning above,
+    // and the retirement case degrades the same way: the FilterExpression is
+    // applied after the page is read, so pages shrink as the archive's share of
+    // the table grows.
+    //
+    // `@scan` deliberately does not satisfy this. It adds no index and removes
+    // no read unit — it only widens the client's filter surface — so accepting it
+    // here would make the warning dismissible by an annotation that changes
+    // nothing about the cost being warned about.
+    switch retiredField {
+    | Some(f) =>
+      if !isIndexed(f) {
+        log.warn(
+          ~comp="QueryDbResolvers_AppSync",
+          `${name}: @retired field "${f}" is not the key of any index on this table. ` ++
+          "Reads that exclude retired rows will Scan and filter, so pages shrink as " ++
+          "the archive's share of the rows grows. Add an @index on that field before " ++
+          "this read model grows.",
+        )
+      }
+    | None => ()
+    }
     let resolverAll = makeQueryResolver(
       ~resolverName=fieldNameForAll->String.capitalize,
       ~field=fieldNameForAll->Pulumi.Input.make,
@@ -283,6 +311,8 @@ let make: ReventlessCore.QueryDb_Adapter.resolversMaker<api, role> = (
           ~requireAttribute?,
           ~ownerField?,
           ~elevatedGroups=Reventless.OwnerScope.elevatedGroups(),
+          ~retiredField?,
+          ~retiredValues?,
         )
       } else {
         Resolver.Functions.listAllItems

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

@@ -9,6 +9,7 @@ import * as OwnerScope$Reventless from "@reventlessdev/reventless-spec/src/types
 import * as Adapter$ReventlessCore from "@reventlessdev/reventless-core/src/adapter/Adapter.res.mjs";
 import * as AppSync_Function$PulumiAws from "@reventlessdev/rescript-pulumi-aws/src/AppSync/AppSync_Function.res.mjs";
 import * as Util_AppSync$ReventlessAws from "../../util/Util_AppSync.res.mjs";
+import * as StateAnnotations$Reventless from "@reventlessdev/reventless-spec/src/components/StateAnnotations.res.mjs";
 import * as Util_DynamoDb$ReventlessAws from "../../util/Util_DynamoDb.res.mjs";
 import * as Util_QueryDb$ReventlessCore from "@reventlessdev/reventless-core/src/util/Util_QueryDb.res.mjs";
 import * as AppSync_DataSource$PulumiAws from "@reventlessdev/rescript-pulumi-aws/src/AppSync/AppSync_DataSource.res.mjs";
@@ -111,13 +112,23 @@ function make(name, api, apiRole, dataSourceName, indexes, subIdField, idResolve
     let requireAttribute = internalRowRequiredAttr(name$1);
     let ownerField = stateSchemaOpt !== undefined ? Owner$Reventless.fieldNames(stateSchemaOpt)[0] : undefined;
     OwnerScopeDiagnostics$ReventlessCore.warnIfNoElevatedGroups("QueryDbResolvers_AppSync", name$1, ownerField);
-    if (ownerField !== undefined) {
-      let indexed = indexes.some(ic => Stdlib_Option.getOr(ic.idField, ic.index) === ownerField) || Stdlib_Option.getOr(subIdField, "") === ownerField;
-      if (!indexed) {
-        log.warn("QueryDbResolvers_AppSync", undefined, name$1 + `: @owner field "` + ownerField + `" is not the key of any index on this table. ` + "Owner-scoped reads will Scan and filter, so pages shrink as the caller's share of the rows falls. Add an @index on that field before this read model grows.");
+    let isIndexed = f => {
+      if (indexes.some(ic => Stdlib_Option.getOr(ic.idField, ic.index) === f)) {
+        return true;
+      } else {
+        return Stdlib_Option.getOr(subIdField, "") === f;
       }
+    };
+    if (ownerField !== undefined && !isIndexed(ownerField)) {
+      log.warn("QueryDbResolvers_AppSync", undefined, name$1 + `: @owner field "` + ownerField + `" is not the key of any index on this table. ` + "Owner-scoped reads will Scan and filter, so pages shrink as the caller's share of the rows falls. Add an @index on that field before this read model grows.");
+    }
+    let retiredSpec = Stdlib_Option.flatMap(Stdlib_Option.flatMap(stateSchemaOpt, StateAnnotations$Reventless.getSpec), spec => spec.retired);
+    let retiredField = Stdlib_Option.map(retiredSpec, r => r.field);
+    let retiredValues = Stdlib_Option.flatMap(retiredSpec, r => r.values);
+    if (retiredField !== undefined && !isIndexed(retiredField)) {
+      log.warn("QueryDbResolvers_AppSync", undefined, name$1 + `: @retired field "` + retiredField + `" is not the key of any index on this table. ` + "Reads that exclude retired rows will Scan and filter, so pages shrink as the archive's share of the rows grows. Add an @index on that field before this read model grows.");
     }
-    let resolverAll = makeQueryResolver(Stdlib_String.capitalize(fieldNameForAll), fieldNameForAll, connectionSpec ? AppSync_Resolver_Functions$PulumiAws.listAllItemsConnection(labelField, filterFieldNames, rangeFieldNames, sortFieldNames, requireAttribute, ownerField, OwnerScope$Reventless.elevatedGroups()) : AppSync_Resolver_Functions$PulumiAws.listAllItems);
+    let resolverAll = makeQueryResolver(Stdlib_String.capitalize(fieldNameForAll), fieldNameForAll, connectionSpec ? AppSync_Resolver_Functions$PulumiAws.listAllItemsConnection(labelField, filterFieldNames, rangeFieldNames, sortFieldNames, requireAttribute, ownerField, OwnerScope$Reventless.elevatedGroups(), retiredField, retiredValues) : AppSync_Resolver_Functions$PulumiAws.listAllItems);
     let resolversByIndex = indexes.map(indexConfig => {
       let index = indexConfig.index;
       let stripLeadingBy = s => {

package/src/adapter/Runtime/PgQueryResolverEntryPoint_Ops.res

@@ -153,6 +153,16 @@ let registerBinding = (
       // From the same schema `capability` is derived from, one line above, so the
       // two cannot end up disagreeing about this read model's fields.
       ownerField: Reventless.Owner.fieldNames(spec.stateSchema)->Array.get(0),
+      retiredField: spec.stateSchema
+      ->Reventless.StateAnnotations.getSpec
+      ->Option.flatMap(a => a.retired)
+      ->Option.map(r => r.field),
+      // The state form's other half. Carried beside the field rather than
+      // re-derived at predicate time, so one place decides which rows are retired.
+      retiredValues: spec.stateSchema
+      ->Reventless.StateAnnotations.getSpec
+      ->Option.flatMap(a => a.retired)
+      ->Option.flatMap(r => r.values),
     },
   )
   logDebug("registered resolver binding for " ++ entry.readModelName, {comp: "PgQueryResolver"})

package/src/adapter/Runtime/PgQueryResolverEntryPoint_Ops.res.mjs

@@ -6,6 +6,7 @@ import * as Stdlib_Option from "@rescript/runtime/lib/es6/Stdlib_Option.js";
 import * as Owner$Reventless from "@reventlessdev/reventless-spec/src/components/Owner.res.mjs";
 import * as PgRuntime$ReventlessAws from "../Postgres/PgRuntime.res.mjs";
 import * as HandlerFactoryHelpersMjs from "./HandlerFactoryHelpers.mjs";
+import * as StateAnnotations$Reventless from "@reventlessdev/reventless-spec/src/components/StateAnnotations.res.mjs";
 import * as PgQueryResolver_Lambda$ReventlessAws from "../QueryDb/PgQueryResolver_Lambda.res.mjs";
 import * as ProjectionEntryPoint_Ops$ReventlessAws from "./ProjectionEntryPoint_Ops.res.mjs";
 import * as QueryEnginePostgres$ReventlessPostgres from "@reventlessdev/reventless-postgres/src/QueryEnginePostgres.res.mjs";
@@ -74,7 +75,9 @@ function registerBinding(pushdowns, pgConnection, entry, spec) {
     labelField: entry.labelField,
     includeIdParam: entry.includeIdParam,
     authorization: spec.authorization,
-    ownerField: Owner$Reventless.fieldNames(spec.stateSchema)[0]
+    ownerField: Owner$Reventless.fieldNames(spec.stateSchema)[0],
+    retiredField: Stdlib_Option.map(Stdlib_Option.flatMap(StateAnnotations$Reventless.getSpec(spec.stateSchema), a => a.retired), r => r.field),
+    retiredValues: Stdlib_Option.flatMap(Stdlib_Option.flatMap(StateAnnotations$Reventless.getSpec(spec.stateSchema), a => a.retired), r => r.values)
   });
   HandlerFactoryHelpersMjs.log.debug("registered resolver binding for " + entry.readModelName, {
     comp: "PgQueryResolver"

package/src/adapter/Runtime/StateTopicPublish.mjs

@@ -98,14 +98,43 @@ export function nextSequence() {
 // implementations. Over the size cap the state is dropped and the downgrade logged:
 // a metadata-only descriptor still tells the client to refetch, where a publish
 // rejected for size would tell it nothing.
-export function makeDescriptor({ changeKind, entityKey, state, seq }) {
+//
+// `retiredField` names the row's `@retired` flag, when the read model declares
+// one. A row whose flag is true publishes as metadata only — no state, and no
+// sortKeyValue either, since that is a timestamp off a row the subscriber may
+// not read. The channel is shared by every subscriber of the view and cannot be
+// scoped per caller, so a payload here would hand the row to exactly the callers
+// the resolvers refuse it to. `Updated` with no state is the shape an oversized
+// row already takes, and it asks the client to do the one thing that enforces
+// the rule: refetch, and let the query layer answer.
+//
+// `retiredValues` is the state form: the row is retired when the field holds any
+// of those states. Absent is the boolean form, where the flag is `true`. This
+// mirrors `OwnerScope.isRetiredValue`, which the other two implementations call
+// — this one cannot, being hand-written JS outside the ReScript graph, so the
+// three are held together by StateChangeDescriptorParityTest instead. The strict
+// readings matter and are the ones that file asserts: a non-boolean is not
+// `true`, a non-string is in no set, and an absent field is neither.
+export function makeDescriptor({ changeKind, entityKey, state, seq, retiredField, retiredValues }) {
   const descriptor = { changeKind, id: entityKey };
-  if (state !== undefined) {
+  const cell =
+    retiredField !== undefined &&
+    retiredField !== null &&
+    state !== undefined &&
+    state !== null &&
+    typeof state === "object"
+      ? state[retiredField]
+      : undefined;
+  const retired =
+    retiredValues === undefined || retiredValues === null
+      ? cell === true
+      : typeof cell === "string" && retiredValues.indexOf(cell) >= 0;
+  if (state !== undefined && !retired) {
     const sortKeyValue = pickSortKeyValue(state);
     if (sortKeyValue !== undefined) descriptor.sortKeyValue = sortKeyValue;
   }
   descriptor.seq = seq;
-  if (state !== undefined) {
+  if (state !== undefined && !retired) {
     const encoded = JSON.stringify(state);
     if (encoded.length <= MAX_STATE_CHARS) {
       descriptor.state = state;
@@ -126,12 +155,16 @@ export function makeDescriptor({ changeKind, entityKey, state, seq }) {
 // - changeKind: "Updated" (save) | "Removed" (delete).
 // - state:      the full new row for a save; omitted for a delete.
 // - dedupeId:   AppSync publish `id` (idempotency hint).
-export async function publishStateChange({ endpoint, region, topicName, entityKey, changeKind, state, dedupeId }) {
+// - retiredField: the row's `@retired` flag name, when the read model declares
+//                 one; a retired row publishes metadata-only.
+// - retiredValues: the states that retire the row, for the state form. Absent is
+//                 the boolean form, where the flag is `true`.
+export async function publishStateChange({ endpoint, region, topicName, entityKey, changeKind, state, dedupeId, retiredField, retiredValues }) {
   if (!endpoint || !topicName) return; // not live-enabled — no-op
   try {
     const url = new URL(endpoint);
     const channel = "/default/" + pathSegment(topicName) + "/" + pathSegment(entityKey);
-    const descriptor = makeDescriptor({ changeKind, entityKey, state, seq: nextSequence() });
+    const descriptor = makeDescriptor({ changeKind, entityKey, state, seq: nextSequence(), retiredField, retiredValues });
     const body = JSON.stringify({
       id: dedupeId || (topicName + ":" + entityKey + ":" + changeKind),
       channel,

package/src/adapter/StateTopic/StateTopic_AppSync.res

@@ -92,6 +92,10 @@ type streamEntry = {
   tableName: Pulumi.Output.t<string>,
   streamArn: Pulumi.Output.t<string>,
   topicName: string,
+  // The read model's `@retired` field, resolved at deploy time because the relay
+  // Lambda has no plugin registry in process to resolve it at request time.
+  retiredField: option<string>,
+  retiredValues: option<array<string>>,
 }
 
 // One registry per events API, keyed by `eventsApi.name` (the static Pulumi
@@ -134,6 +138,8 @@ let makeForTable = (
   ~streamArn: Pulumi.Output.t<string>,
   ~partitionKeyName: Pulumi.Output.t<string>,
   ~topicName: string,
+  ~retiredField: option<string>=?,
+  ~retiredValues: option<array<string>>=?,
   ~eventsApi: AppSync_EventsApi.t,
   ~opts as _: Pulumi.CustomResourceOptions.t,
 ) => {
@@ -150,7 +156,12 @@ let makeForTable = (
 
   let key = eventsApi.name
   let entries = registry->Dict.get(key)->Option.getOr([])
-  registry->Dict.set(key, entries->Array.concat([{tableName: checkedTableName, streamArn, topicName}]))
+  registry->Dict.set(
+    key,
+    entries->Array.concat([
+      {tableName: checkedTableName, streamArn, topicName, retiredField, retiredValues},
+    ]),
+  )
 }
 
 let make = (
@@ -176,6 +187,18 @@ let make = (
     // `makeForTable` and can be keyed anything.
     ~partitionKeyName=StateTopic_AppSync_Helpers.entityKeyPartitionAttribute->Pulumi.Output.make,
     ~topicName,
+    // Resolved here, where the read model's name is known and its spec is
+    // registered in this process. The relay Lambda has neither.
+    ~retiredField=?ReventlessCore.Plugin_Helpers.stateSchemaRegistry
+    ->Dict.get(readModelName)
+    ->Option.flatMap(Reventless.StateAnnotations.getSpec)
+    ->Option.flatMap(spec => spec.retired)
+    ->Option.map(r => r.field),
+    ~retiredValues=?ReventlessCore.Plugin_Helpers.stateSchemaRegistry
+    ->Dict.get(readModelName)
+    ->Option.flatMap(Reventless.StateAnnotations.getSpec)
+    ->Option.flatMap(spec => spec.retired)
+    ->Option.flatMap(r => r.values),
     ~eventsApi,
     ~opts,
   )
@@ -270,6 +293,30 @@ let finish = (
         dict->JSON.Encode.object->JSON.stringify
       })
 
+    // STATE_RETIRED_MAP env var — `{ <tableName>: {field, values?} }`, carrying
+    // only the tables that declare retirement. Built from the same awaited table
+    // names as the topic map so the two cannot describe different sets of tables.
+    // The whole predicate travels: the relay Lambda has no plugin registry, so a
+    // field without its states would leave it unable to tell the two forms apart.
+    let retiredMapJson =
+      entries
+      ->Array.map(e => e.tableName)
+      ->Pulumi.Output.all
+      ->Pulumi.Output.apply(tableNames => {
+        let dict = Dict.make()
+        tableNames->Array.forEachWithIndex((tableName, i) => {
+          let entry = entries->Array.getUnsafe(i)
+          entry.retiredField->Option.forEach(f => {
+            let obj = Dict.fromArray([("field", f->JSON.Encode.string)])
+            entry.retiredValues->Option.forEach(vs =>
+              obj->Dict.set("values", vs->Array.map(JSON.Encode.string)->JSON.Encode.array)
+            )
+            dict->Dict.set(tableName, obj->JSON.Encode.object)
+          })
+        })
+        dict->JSON.Encode.object->JSON.stringify
+      })
+
     // Shared Lambda — the compiled `_Ops` handler is identical for every
     // stream-enabled RM; routing is per-record via STATE_TOPIC_MAP env var.
     // Bundle reventless-aws (the handler + its node:crypto signer + the
@@ -325,6 +372,7 @@ let finish = (
               ("Environment", Pulumi.Pulumi.getStackName()->Pulumi.Input.make),
               ("APPSYNC_ENDPOINT", appsyncEndpoint->Pulumi.Output.asInput),
               ("STATE_TOPIC_MAP", topicMapJson->Pulumi.Output.asInput),
+              ("STATE_RETIRED_MAP", retiredMapJson->Pulumi.Output.asInput),
               ("NODE_OPTIONS", Util_Bundle.esmLoaderNodeOptions->Pulumi.Input.make),
               ("ESM_FALLBACK_DIRS", Util_Bundle.esmFallbackDirs->Pulumi.Input.make),
               Util_LambdaLogging.logLevelEntry(),