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

package/CHANGELOG.md

@@ -3,6 +3,25 @@
 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.227 (2026-08-18)
+
+### Bug Fixes
+
+* **api:** declare the reference door in the SDL every backend is built from ([5c1857e](https://github.com/ReventlessDev/reventless-core/commit/5c1857ea90ff40305a1c44a9e57043528e6a93aa))
+* **api:** make the by-index door answer, and let an elevated caller widen it ([0fe0c6f](https://github.com/ReventlessDev/reventless-core/commit/0fe0c6f8dec6228ecaba39577e28d780b4f79c83))
+### Features
+
+* **core:** let a reference name a retired row, and let an elevated caller open one ([9e2623a](https://github.com/ReventlessDev/reventless-core/commit/9e2623a4b22487561607fcc0ca19d51726069ee4))
+
+
+# 3.0.0-alpha.226 (2026-08-16)
+
+**Note:** Version bump only for package @reventlessdev/reventless-local
+
+
+
+
+
 # 3.0.0-alpha.225 (2026-08-16)
 
 ### Bug Fixes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reventlessdev/reventless-local",
-  "version": "3.0.0-alpha.225",
+  "version": "3.0.0-alpha.227",
   "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-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-mcp-sdk": "1.0.0-alpha.21",
+    "@reventlessdev/rescript-node": "2.0.0-alpha.8",
+    "@reventlessdev/reventless-core": "3.0.0-alpha.239",
     "@reventlessdev/rescript-pulumi-pulumi": "2.3.0-alpha.19",
-    "@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"
+    "@reventlessdev/reventless-gwt": "1.0.0-alpha.186",
+    "@reventlessdev/reventless-graphql-server": "1.0.0-alpha.87",
+    "@reventlessdev/reventless-infra": "3.0.0-alpha.145",
+    "@reventlessdev/reventless-postgres": "3.0.0-alpha.103",
+    "@reventlessdev/reventless-seed": "1.0.0-alpha.16",
+    "@reventlessdev/reventless-spec": "3.0.0-alpha.117"
   },
   "devDependencies": {
     "rescript": "12.3.0",
     "sury-ppx": "11.0.0-alpha.2",
-    "@reventlessdev/reventless-ppx": "1.0.0-alpha.67"
+    "@reventlessdev/reventless-ppx": "1.0.0-alpha.69"
   },
   "peerDependencies": {
     "rescript": "12.3.0"

package/src/Platform.res

@@ -700,7 +700,7 @@ module MakeWithConfig = (
       StateViewSliceMaker.Make(Spec, Projection)
   }
 
-  // Admin UI-fragment registry (docs/plans/event-sourced-fragment-registries.md): the
+  // Admin UI-fragment registry (docs/plans/done/event-sourced-fragment-registries.md): the
   // platform UI-fragment registry hosted as an admin DCB slice on the admin DcbEventLog.
   // Built once and passed into Admin.construct below.
   module UiFragmentRegistrySlice = StateChangeSlice.Make(
@@ -1428,11 +1428,10 @@ module MakeWithConfig = (
       switch entry.indexQueries {
       | Some(indexes) =>
         indexes->Array.forEach((ic: Reventless.ReadModel.indexConfig) => {
-          let stripped =
-            ic.index->String.startsWith("by") && ic.index->String.length > 2
-              ? ic.index->String.slice(~start=2, ~end=ic.index->String.length)
-              : ic.index
-          let fieldName = entry.singleFieldName ++ "By" ++ stripped->String.capitalize
+          let fieldName = ReventlessCore.GraphQL_FragmentGenerator.indexQueryFieldName(
+            ~singleFieldName=entry.singleFieldName,
+            ~index=ic.index,
+          )
           queryResolvers->Dict.set(fieldName, async (_root, _args, _ctx): JSON.t =>
             connectionResponse([])
           )

package/src/Platform.res.mjs

@@ -9,7 +9,6 @@ import * as Stdlib_JSON from "@rescript/runtime/lib/es6/Stdlib_JSON.js";
 import * as Stdlib_Array from "@rescript/runtime/lib/es6/Stdlib_Array.js";
 import * as Id$Reventless from "@reventlessdev/reventless-spec/src/types/Id.res.mjs";
 import * as Stdlib_Option from "@rescript/runtime/lib/es6/Stdlib_Option.js";
-import * as Stdlib_String from "@rescript/runtime/lib/es6/Stdlib_String.js";
 import * as Effect from "effect/Effect";
 import * as Pulumi from "@pulumi/pulumi";
 import * as Stdlib_Promise from "@rescript/runtime/lib/es6/Stdlib_Promise.js";
@@ -81,6 +80,7 @@ import * as LocalDcbEventLogStorage$ReventlessLocal from "./adapter/DcbEventLog/
 import * as LocalRuntimeEnvironment$ReventlessLocal from "./adapter/Runtime/LocalRuntimeEnvironment.res.mjs";
 import * as LocalScheduledPublisher$ReventlessLocal from "./adapter/Scheduler/LocalScheduledPublisher.res.mjs";
 import * as Platform_Admin_Structure$ReventlessCore from "@reventlessdev/reventless-core/src/admin/Platform_Admin_Structure.res.mjs";
+import * as GraphQL_FragmentGenerator$ReventlessCore from "@reventlessdev/reventless-core/src/components/Api/GraphQL_FragmentGenerator.res.mjs";
 import * as LocalCommandTopicChannel$ReventlessLocal from "./adapter/CommandTopic/LocalCommandTopicChannel.res.mjs";
 import * as LocalEventTopicPublisher$ReventlessLocal from "./adapter/EventTopic/LocalEventTopicPublisher.res.mjs";
 import * as StateChangeSlice_Builder$ReventlessLocal from "./components/StateChangeSlice_Builder.res.mjs";
@@ -1206,8 +1206,7 @@ function MakeWithConfig(Config) {
       let indexes = entry.indexQueries;
       if (indexes !== undefined) {
         indexes.forEach(ic => {
-          let stripped = ic.index.startsWith("by") && ic.index.length > 2 ? ic.index.slice(2, ic.index.length) : ic.index;
-          let fieldName = entry.singleFieldName + "By" + Stdlib_String.capitalize(stripped);
+          let fieldName = GraphQL_FragmentGenerator$ReventlessCore.indexQueryFieldName(entry.singleFieldName, ic.index);
           queryResolvers[fieldName] = async (_root, _args, _ctx) => connectionResponse([]);
         });
         return;
@@ -2933,8 +2932,7 @@ function Make($star) {
       let indexes = entry.indexQueries;
       if (indexes !== undefined) {
         indexes.forEach(ic => {
-          let stripped = ic.index.startsWith("by") && ic.index.length > 2 ? ic.index.slice(2, ic.index.length) : ic.index;
-          let fieldName = entry.singleFieldName + "By" + Stdlib_String.capitalize(stripped);
+          let fieldName = GraphQL_FragmentGenerator$ReventlessCore.indexQueryFieldName(entry.singleFieldName, ic.index);
           queryResolvers[fieldName] = async (_root, _args, _ctx) => connectionResponse([]);
         });
         return;

package/src/adapter/EventLog/EventLogStorage_Sqlite.res

@@ -20,7 +20,7 @@ let ensureSchema = (db: SqliteDriver.t) => {
   db->SqliteDriver.exec(
     "CREATE TABLE IF NOT EXISTS event_log (log_name TEXT NOT NULL, aggregate_id TEXT NOT NULL, seq_nr INTEGER NOT NULL, payload TEXT NOT NULL, PRIMARY KEY (log_name, aggregate_id, seq_nr))",
   )
-  // Keep-one aggregate-state snapshots (docs/plans/aggregate-snapshotting.md):
+  // Keep-one aggregate-state snapshots (docs/plans/done/aggregate-snapshotting.md):
   // one row per (log, aggregate), overwritten on every snapshot write. `state`
   // is the JSON-encoded fold of events seq 0..seq_nr-1; `schema_hash` lets the
   // consumer detect a state-schema drift and fall back to full replay.

package/src/adapter/QueryDb/LocalQueryDbStorage.res

@@ -9,7 +9,7 @@
 // refactor. So under Backend.Postgres the read-model live-query path uses the
 // in-memory arm (getDb() is None for Postgres → Memory), rebuilt by replay from
 // the durable pg event log; the deploy-usable ReventlessPostgres.QueryDbStorage_Postgres
-// serves non-local compute layers. See docs/plans/postgres-storage-adapter.md §E.
+// serves non-local compute layers. See docs/plans/done/postgres-storage-adapter.md §E.
 
 module Make = (Bus: LocalBus.T) => {
   module Mem = QueryDbStorage_InMemory.Make(Bus)

package/src/adapter/QueryDb/QueryDbResolvers_GraphQL.res

@@ -228,8 +228,6 @@ module Make = (Bus: LocalBus.T) => {
         )
       }
 
-    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.
     // Fallbacks use simple GraphQL built-in types to avoid referencing non-existent custom types.
     let registryEntry = Plugin_Helpers.queryFieldNamesRegistry->Dict.get(name)
@@ -271,10 +269,16 @@ module Make = (Bus: LocalBus.T) => {
     }
 
     // -- Main query: getById ---------------------------------------------------
+    // `includeRetired` here matches the connection field and the AppSync SDL the
+    // FragmentGenerator emits. The resolver below already reads it — `retiredAllows`
+    // consults `askedForRetired(~args)` on every door — so this argument was the
+    // only missing half, and without it an elevated caller could see an archived
+    // row in a list and not open it.
     let byIdSdl = if includeIdParam {
       switch subIdField {
-      | Some(sf) => `  ${singleQueryName}(id: ID!, ${sf}: String): ${returnTypeName}`
-      | None => `  ${singleQueryName}(id: ID!): ${returnTypeName}`
+      | Some(sf) =>
+        `  ${singleQueryName}(id: ID!, ${sf}: String, includeRetired: Boolean): ${returnTypeName}`
+      | None => `  ${singleQueryName}(id: ID!, includeRetired: Boolean): ${returnTypeName}`
       }
     } else {
       `  ${singleQueryName}: ${returnTypeName}`
@@ -402,6 +406,124 @@ module Make = (Bus: LocalBus.T) => {
     | None => "id"
     }
 
+    // -- Reference door: {listFieldName}Refs -----------------------------------
+    // Names the rows a caller already holds pointers to, and nothing more. Three
+    // fields, fixed by the type, so this cannot be widened by what a caller
+    // selects.
+    //
+    // Retirement is lifted here only where the view declared `@namedWhenRetired`.
+    // Ownership is not lifted at all, and the asymmetry is the point: an archived
+    // product is a thing the shop sold and every order naming one may say what it
+    // was, while a deactivated customer is somebody's row before it is anything
+    // else. One predicate answers "is this row still on offer", the other "is this
+    // row yours", and only the first is what an archive withdraws.
+    let refsSdl = if includeIdParam && subIdField === None {
+      [GraphQL_FragmentGenerator.deriveRefsQueryField(~listFieldName=listQueryName, ~returnTypeName)]
+    } else {
+      []
+    }
+    let refsResolverEntry: option<(string, ReventlessGraphqlServer.GraphQL_ServerInstance.resolverFn)> =
+      if includeIdParam && subIdField === None {
+        server.registerTypes(~sdlTypes=[GraphQL_FragmentGenerator.deriveRefTypeSdl(~returnTypeName)])
+        let resolver: ReventlessGraphqlServer.GraphQL_ServerInstance.resolverFn = async (
+          _root,
+          args,
+          ctx,
+        ) => {
+          switch await runInterceptor(~ctx, ~args) {
+          | Deny(_) => []->JSON.Encode.array
+          | Allow =>
+            let ids =
+              args
+              ->JSON.Decode.object
+              ->Option.flatMap(d => d->Dict.get("ids"))
+              ->Option.flatMap(JSON.Decode.array)
+              ->Option.getOr([])
+              ->Array.filterMap(JSON.Decode.string)
+            let spec = retiredSpecOf()
+            let namesRetired = spec->Option.mapOr(false, r => r.namedWhenRetired)
+            // The row's own retirement, read with the same `isRetiredValue` every
+            // other door narrows by — so "retired" here and "withheld" there are
+            // one answer, not two that drift.
+            let retirementOf = (item: JSON.t) =>
+              switch spec {
+              | None => (false, None)
+              | Some(r) =>
+                let cell = item->JSON.Decode.object->Option.flatMap(d => d->Dict.get(r.field))
+                let scope: Reventless.OwnerScope.retiredScope = {field: r.field, values: r.values}
+                let retired = scope->Reventless.OwnerScope.isRetiredValue(cell)
+                (
+                  retired,
+                  // The state that retired it, and only that. A live row reports
+                  // none — this door names rows, it does not publish a lifecycle
+                  // column to callers the list withholds. Nor does the boolean
+                  // form, where the field is the state and `retired` said it.
+                  retired && r.values->Option.isSome
+                    ? cell->Option.flatMap(JSON.Decode.string)
+                    : None,
+                )
+              }
+            switch Bus.getQueryDb(name) {
+            | Some(ops) =>
+              let load = key =>
+                ops.loadStream(key)
+                ->Stream.runCollect
+                ->Effect.catchAll(_ => Effect.succeed([]))
+                ->Effect.runPromise
+              let loaded = await ids->Array.map(async id =>
+                switch (await load(id))->Array.get(0) {
+                | Some(item) => (id, Some(item))
+                | None =>
+                  switch Api_Ids.alternateKey(id) {
+                  | Some(localId) => (localId, (await load(localId))->Array.get(0))
+                  | None => (id, None)
+                  }
+                }
+              )->Promise.all
+              loaded
+              ->Array.filterMap(((id, opt)) =>
+                opt
+                ->Option.filter(item => ownerAllows(~ctx, item))
+                ->Option.flatMap(item => {
+                  let (retired, state) = retirementOf(item)
+                  // A retired row leaves through this door only where the view
+                  // said it may. Where it did not, the door answers exactly as
+                  // every other one does — with nothing.
+                  if retired && !namesRetired {
+                    None
+                  } else {
+                    let label =
+                      item
+                      ->JSON.Decode.object
+                      ->Option.flatMap(d => d->Dict.get(labelField))
+                      ->Option.flatMap(JSON.Decode.string)
+                      // A view with no label field resolves to its id, which is
+                      // what `labelField`'s own fallback already decided.
+                      ->Option.getOr(id)
+                    Some(
+                      Dict.fromArray([
+                        ("id", JSON.Encode.string(id)),
+                        ("label", JSON.Encode.string(label)),
+                        ("retired", JSON.Encode.bool(retired)),
+                        (
+                          "retiredState",
+                          state->Option.mapOr(JSON.Encode.null, JSON.Encode.string),
+                        ),
+                      ])->JSON.Encode.object,
+                    )
+                  }
+                })
+              )
+              ->JSON.Encode.array
+            | None => []->JSON.Encode.array
+            }
+          }
+        }
+        Some((listQueryName ++ "Refs", resolver))
+      } else {
+        None
+      }
+
     // -- List query -------------------------------------------------------------
     // Look up the registered state schema (populated alongside queryFieldNamesRegistry)
     // so the resolver derives the same serverCapability the FragmentGenerator emitted.
@@ -666,20 +788,95 @@ module Make = (Bus: LocalBus.T) => {
     }
 
     // -- Index queries: {name}By{Index} ---------------------------------------
+    // Name, argument and return type all come from `GraphQL_FragmentGenerator`,
+    // which is also where the AppSync SDL gets them. They used to be spelled out
+    // here independently and disagreed with that emitter on all three, so the
+    // same door had a different signature per backend and worked on neither.
     let indexSdlFields = indexes->Array.map((ic: Reventless.ReadModel.indexConfig) =>
-      `  ${singleQueryName}By${cap(ic.index)}(${ic.index}: String!): [String]`
+      GraphQL_FragmentGenerator.deriveIndexQueryField(
+        ~singleFieldName=singleQueryName,
+        ~indexConfig=ic,
+        ~connectionTypeName=returnTypeName ++ "Connection",
+      )
     )
+    // Backward paging is refused rather than ignored, and refused on both
+    // backends rather than on the one that cannot do it. `listAllItemsConnection`
+    // already sets the rule for a door whose read cannot walk backwards — "fail
+    // loud rather than silently returning the forward page" — and its reasoning
+    // is about the answer, not about DynamoDB: `last: 2` handed the first two
+    // rows is a different question answered without saying so.
+    //
+    // The arguments stay in the SDL. One that appeared and disappeared with the
+    // backend would make adding a sort key a breaking schema change and force
+    // every client to feature-detect, which is the same argument `includeRetired`
+    // and the reference door are emitted unconditionally for.
+    let rejectBackwardPaging = (~args) => {
+      let given = key =>
+        switch args->JSON.Decode.object->Option.flatMap(d => d->Dict.get(key)) {
+        | None | Some(JSON.Null) => false
+        | Some(_) => true
+        }
+      if given("last") || given("before") {
+        throw(
+          GraphQL_CallerError.badUserInput(
+            "Backward pagination (last/before) is not supported on by-index connections; use first/after.",
+          ),
+        )
+      }
+    }
+    // A positional connection. This door answers an equality lookup on one index
+    // value and has no ordering key to cut a cursor from — the list door borrows
+    // its sort key because it orders by one. An offset is stable for as long as
+    // a page-forward takes, which is what the field advertises and no more.
+    let indexConnection = (~args, items: array<JSON.t>) => {
+      let arg = key => args->JSON.Decode.object->Option.flatMap(d => d->Dict.get(key))
+      let after =
+        arg("after")->Option.flatMap(JSON.Decode.string)->Option.flatMap(s => Int.fromString(s))->Option.getOr(-1)
+      let first =
+        arg("first")->Option.flatMap(JSON.Decode.float)->Option.map(Float.toInt)->Option.getOr(50)
+      let start = after + 1
+      let page = items->Array.slice(~start, ~end=start + first)
+      let taken = page->Array.length
+      let edges =
+        page->Array.mapWithIndex((item, i) =>
+          Dict.fromArray([
+            ("node", item),
+            ("cursor", (start + i)->Int.toString->JSON.Encode.string),
+          ])->JSON.Encode.object
+        )
+      let cursorAt = i => i->Int.toString->JSON.Encode.string
+      Dict.fromArray([
+        ("edges", edges->JSON.Encode.array),
+        (
+          "pageInfo",
+          Dict.fromArray([
+            ("hasNextPage", JSON.Encode.bool(start + taken < items->Array.length)),
+            ("hasPreviousPage", JSON.Encode.bool(start > 0)),
+            ("startCursor", taken > 0 ? cursorAt(start) : JSON.Encode.null),
+            ("endCursor", taken > 0 ? cursorAt(start + taken - 1) : JSON.Encode.null),
+          ])->JSON.Encode.object,
+        ),
+      ])->JSON.Encode.object
+    }
     let indexResolvers: array<(string, ReventlessGraphqlServer.GraphQL_ServerInstance.resolverFn)> = indexes->Array.map(
       (ic: Reventless.ReadModel.indexConfig) => {
-        let index = ic.index
-        let resolverName = singleQueryName ++ "By" ++ cap(index)
-        let filterField = ic.idField->Option.getOr(index)
+        let resolverName = GraphQL_FragmentGenerator.indexQueryFieldName(
+          ~singleFieldName=singleQueryName,
+          ~index=ic.index,
+        )
+        // The argument the caller passes and the row field this filters on are
+        // one and the same — the door reads the index's key, not its name.
+        let filterField = GraphQL_FragmentGenerator.indexKeyField(ic)
         let resolver: ReventlessGraphqlServer.GraphQL_ServerInstance.resolverFn = async (_root, args, ctx) => {
           switch await runInterceptor(~ctx, ~args) {
-          | Deny(_) => []->JSON.Encode.array
+          | Deny(_) => indexConnection(~args, [])
           | Allow =>
+            // After the interceptor, matching the AppSync pipeline, where the
+            // interceptor leads the chain and the query function's `request`
+            // raises this second.
+            rejectBackwardPaging(~args)
             let value =
-              args->JSON.Decode.object->Option.flatMap(d => d->Dict.get(index))->Option.flatMap(JSON.Decode.string)->Option.getOr("")
+              args->JSON.Decode.object->Option.flatMap(d => d->Dict.get(filterField))->Option.flatMap(JSON.Decode.string)->Option.getOr("")
             // Applied to whichever arm answers, rather than inside one of them: the
             // 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
@@ -690,22 +887,24 @@ module Make = (Bus: LocalBus.T) => {
             // in-memory reuses its lazy snapshot). Fall back to scan+filter only
             // if no lookup is registered for this QueryDb.
             switch Bus.getQueryDbIndexLookup(name) {
-            | Some(lookup) => lookup(filterField, value)->scoped->JSON.Encode.array
+            | Some(lookup) => indexConnection(~args, lookup(filterField, value)->scoped)
             | None =>
               switch Bus.getQueryDbScan(name) {
               | Some(scanAll) =>
-                scanAll()
-                ->Array.filter(item =>
-                  item
-                  ->JSON.Decode.object
-                  ->Option.flatMap(d => d->Dict.get(filterField))
-                  ->Option.flatMap(JSON.Decode.string)
-                  ->Option.map(v => v == value)
-                  ->Option.getOr(false)
+                indexConnection(
+                  ~args,
+                  scanAll()
+                  ->Array.filter(item =>
+                    item
+                    ->JSON.Decode.object
+                    ->Option.flatMap(d => d->Dict.get(filterField))
+                    ->Option.flatMap(JSON.Decode.string)
+                    ->Option.map(v => v == value)
+                    ->Option.getOr(false)
+                  )
+                  ->scoped,
                 )
-                ->scoped
-                ->JSON.Encode.array
-              | None => []->JSON.Encode.array
+              | None => indexConnection(~args, [])
               }
             }
           }
@@ -718,6 +917,7 @@ module Make = (Bus: LocalBus.T) => {
     let allSdl =
       [byIdSdl]
       ->Array.concat(byIdsSdl)
+      ->Array.concat(refsSdl)
       ->Array.concat(listSdl)
       ->Array.concat(itemsSdl)
       ->Array.concat(indexSdlFields)
@@ -725,6 +925,7 @@ module Make = (Bus: LocalBus.T) => {
     let resolvers = Dict.make()
     resolvers->Dict.set(singleQueryName, byIdResolver)
     byIdsResolverEntry->Option.forEach(((k, v)) => resolvers->Dict.set(k, v))
+    refsResolverEntry->Option.forEach(((k, v)) => resolvers->Dict.set(k, v))
     listResolvers->Array.forEach(((k, v)) => resolvers->Dict.set(k, v))
     itemsResolvers->Array.forEach(((k, v)) => resolvers->Dict.set(k, v))
     indexResolvers->Array.forEach(((k, v)) => resolvers->Dict.set(k, v))