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

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(),

package/src/adapter/StateTopic/StateTopic_AppSync.res.mjs

@@ -10,6 +10,8 @@ import * as AWS_Tags$ReventlessAws from "../AWS_Tags.res.mjs";
 import * as QueryDb$ReventlessCore from "@reventlessdev/reventless-core/src/components/QueryDb/QueryDb.res.mjs";
 import * as PolicyDocument$PulumiAws from "@reventlessdev/rescript-pulumi-aws/src/IAM/PolicyDocument.res.mjs";
 import * as Util_Bundle$ReventlessAws from "../../util/Util_Bundle.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 Util_ReadModel$ReventlessCore from "@reventlessdev/reventless-core/src/util/Util_ReadModel.res.mjs";
 import * as AppSync_EventsApi$ReventlessAws from "../Api/AppSync_EventsApi.res.mjs";
 import * as Util_LambdaLogging$ReventlessAws from "../../util/Util_LambdaLogging.res.mjs";
@@ -18,7 +20,7 @@ import * as StateTopic_AppSync_Helpers$ReventlessAws from "./StateTopic_AppSync_
 
 let registry = {};
 
-function makeForTable(tableName, streamArn, partitionKeyName, topicName, eventsApi, param) {
+function makeForTable(tableName, streamArn, partitionKeyName, topicName, retiredField, retiredValues, eventsApi, param) {
   let checkedTableName = Pulumi.all([
     tableName,
     partitionKeyName
@@ -32,13 +34,15 @@ function makeForTable(tableName, streamArn, partitionKeyName, topicName, eventsA
   registry[key] = entries.concat([{
       tableName: checkedTableName,
       streamArn: streamArn,
-      topicName: topicName
+      topicName: topicName,
+      retiredField: retiredField,
+      retiredValues: retiredValues
     }]);
 }
 
 function make(readModelName, topicName, allQueryDbs, eventsApi, opts) {
   let streamResource = Util_DynamoDbStream$ReventlessAws.findResource(Util_ReadModel$ReventlessCore.queryDbStorageResources(allQueryDbs, readModelName));
-  makeForTable(streamResource.name, Util_DynamoDbStream$ReventlessAws.streamArnFromDynamoDbTableResource(streamResource), Pulumi.output(StateTopic_AppSync_Helpers$ReventlessAws.entityKeyPartitionAttribute), topicName, eventsApi, opts);
+  makeForTable(streamResource.name, Util_DynamoDbStream$ReventlessAws.streamArnFromDynamoDbTableResource(streamResource), Pulumi.output(StateTopic_AppSync_Helpers$ReventlessAws.entityKeyPartitionAttribute), topicName, Stdlib_Option.map(Stdlib_Option.flatMap(Stdlib_Option.flatMap(Plugin_Helpers$ReventlessCore.stateSchemaRegistry[readModelName], StateAnnotations$Reventless.getSpec), spec => spec.retired), r => r.field), Stdlib_Option.flatMap(Stdlib_Option.flatMap(Stdlib_Option.flatMap(Plugin_Helpers$ReventlessCore.stateSchemaRegistry[readModelName], StateAnnotations$Reventless.getSpec), spec => spec.retired), r => r.values), eventsApi, opts);
 }
 
 function finish(eventsApi, opts) {
@@ -94,6 +98,23 @@ function finish(eventsApi, opts) {
     });
     return JSON.stringify(dict);
   });
+  let retiredMapJson = Pulumi.all(entries.map(e => e.tableName)).apply(tableNames => {
+    let dict = {};
+    tableNames.forEach((tableName, i) => {
+      let entry = entries[i];
+      Stdlib_Option.forEach(entry.retiredField, f => {
+        let obj = Object.fromEntries([[
+            "field",
+            f
+          ]]);
+        Stdlib_Option.forEach(entry.retiredValues, vs => {
+          obj["values"] = vs.map(prim => prim);
+        });
+        dict[tableName] = obj;
+      });
+    });
+    return JSON.stringify(dict);
+  });
   let packageDirs = Object.fromEntries([[
       "@reventlessdev/reventless-aws",
       Util_Bundle$ReventlessAws.resolvePackageRoot(undefined, "@reventlessdev/reventless-aws")
@@ -125,6 +146,10 @@ function finish(eventsApi, opts) {
           "STATE_TOPIC_MAP",
           topicMapJson
         ],
+        [
+          "STATE_RETIRED_MAP",
+          retiredMapJson
+        ],
         [
           "NODE_OPTIONS",
           Util_Bundle$ReventlessAws.esmLoaderNodeOptions

package/src/adapter/StateTopic/StateTopic_AppSync_Ops.res

@@ -53,6 +53,55 @@ type event = {@as("Records") records: array<record>}
 
 // ── Per-record derivations (ports of the former inline JS helpers) ───────────
 
+// STATE_RETIRED_MAP: `{ <tableName>: {field, values?} }`, injected at deploy time
+// beside STATE_TOPIC_MAP. This handler runs with no plugin registry in process —
+// there is nothing here that could read a state schema — so the whole predicate
+// has to arrive the same way the topic routing does. A table absent from the map
+// declares no retirement, which is every table until one does.
+//
+// `values` absent is the boolean form. Carried as an object rather than as an
+// encoded string because a `field=Value` convention is a parser this side and a
+// writer the other, and the two drift the first time a state name contains the
+// separator — an argument that only gets stronger now that a lifecycle can name
+// several states.
+let retiredMap: dict<Reventless.OwnerScope.retiredScope> =
+  switch NodeProcess.env
+  ->Dict.get("STATE_RETIRED_MAP")
+  ->Option.getOr("{}")
+  ->JSON.parseOrThrow
+  ->JSON.Decode.object {
+  | Some(d) =>
+    let out = Dict.make()
+    d->Dict.forEachWithKey((v, k) =>
+      v
+      ->JSON.Decode.object
+      ->Option.flatMap(o =>
+        o
+        ->Dict.get("field")
+        ->Option.flatMap(JSON.Decode.string)
+        ->Option.map(field => {
+          Reventless.OwnerScope.field,
+          values: o
+          ->Dict.get("values")
+          ->Option.flatMap(JSON.Decode.array)
+          ->Option.map(vs => vs->Array.filterMap(JSON.Decode.string)),
+        })
+      )
+      ->Option.forEach(scope => out->Dict.set(k, scope))
+    )
+    out
+  | None => Dict.make()
+  }
+
+let tableNameFromEventSourceArn = (arn: string): option<string> => {
+  let parts = arn->String.split("/")
+  switch (parts->Array.get(0), parts->Array.get(1), parts->Array.get(2)) {
+  | (Some(prefix), Some(tableName), Some("stream")) if prefix->String.endsWith(":table") =>
+    Some(tableName)
+  | _ => None
+  }
+}
+
 // Map record.eventSourceARN → topicRoot via STATE_TOPIC_MAP. Stream ARNs look
 // like arn:aws:dynamodb:<region>:<acct>:table/<TableName>/stream/<ts>; split on
 // "/" gives [ "...:table", "<TableName>", "stream", "<ts>" ].
@@ -131,18 +180,34 @@ let makeDescriptor = (
   ~entityKey: string,
   ~image: dict<JSON.t>,
   ~seq: option<string>,
+  ~retiredField: option<string>=?,
+  ~retiredValues: option<array<string>>=?,
 ): JSON.t => {
   let removed = changeKind == "Removed"
+  // A retired row publishes as metadata only, for the reason the other two
+  // implementations do it: this channel reaches every subscriber of the view,
+  // and a payload would deliver the row to the callers the resolvers refuse it
+  // to. `Updated` with no state is the shape an oversized row already takes.
+  // Both forms are the one question `isRetiredValue` answers, so nothing here
+  // branches on which the view declared.
+  let retired = switch retiredField {
+  | Some(field) =>
+    !removed &&
+    {Reventless.OwnerScope.field, values: retiredValues}->Reventless.OwnerScope.isRetiredValue(
+      image->Dict.get(field),
+    )
+  | None => false
+  }
   let descriptor = Dict.make()
   descriptor->Dict.set("changeKind", JSON.Encode.string(changeKind))
   descriptor->Dict.set("id", JSON.Encode.string(entityKey))
-  if !removed {
+  if !removed && !retired {
     pickSortKeyValue(image)->Option.forEach(v =>
       descriptor->Dict.set("sortKeyValue", JSON.Encode.string(v))
     )
   }
   seq->Option.forEach(s => descriptor->Dict.set("seq", JSON.Encode.string(s)))
-  if !removed {
+  if !removed && !retired {
     let state = image->JSON.Encode.object
     let encoded = state->JSON.stringify
     if encoded->String.length <= maxStateChars {
@@ -191,6 +256,12 @@ let processRecord = async (
           ~entityKey,
           ~image=unmarshalled,
           ~seq=dynamodb.sequenceNumber,
+          ~retiredField=?tableNameFromEventSourceArn(record.eventSourceARN)
+          ->Option.flatMap(t => retiredMap->Dict.get(t))
+          ->Option.map(scope => scope.Reventless.OwnerScope.field),
+          ~retiredValues=?tableNameFromEventSourceArn(record.eventSourceARN)
+          ->Option.flatMap(t => retiredMap->Dict.get(t))
+          ->Option.flatMap(scope => scope.Reventless.OwnerScope.values),
         )
         let body =
           Dict.fromArray([