@reventlessdev/reventless-local 3.0.0-alpha.221 → 3.0.0-alpha.223

package/CHANGELOG.md

@@ -3,6 +3,24 @@
 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.223 (2026-08-15)
+
+### Bug Fixes
+
+* **local:** keep a dev session alive across a platform restart ([9f08206](https://github.com/ReventlessDev/reventless-core/commit/9f082060d73664720c77bb323a112a494bb68507))
+### Features
+
+* **core:** curate the pages a shell builds across a plugin's views ([589835a](https://github.com/ReventlessDev/reventless-core/commit/589835a1ad428c5e2dea8bf6e4c64e49d2f67e0d))
+* **local:** serve ui-hints.json edits without restarting the platform ([b29b104](https://github.com/ReventlessDev/reventless-core/commit/b29b1044f31f620071423c618486daef9692c614))
+
+
+# 3.0.0-alpha.222 (2026-08-14)
+
+### Features
+
+* **core:** one contract for which refusal a platform gave ([7705c13](https://github.com/ReventlessDev/reventless-core/commit/7705c13ec63f41a3a659bc98cfb45b880fd5b222))
+
+
 # 3.0.0-alpha.221 (2026-08-14)
 
 ### Features

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reventlessdev/reventless-local",
-  "version": "3.0.0-alpha.221",
+  "version": "3.0.0-alpha.223",
   "description": "Local platform for Reventless (in-memory or SQLite backend, for development and testing without AWS)",
   "license": "Apache-2.0",
   "bin": {
@@ -35,18 +35,18 @@
     "sury": "11.0.0-alpha.4",
     "ws": "^8.18.0",
     "@reventlessdev/rescript-effect": "0.1.0-alpha.32",
+    "@reventlessdev/rescript-jest": "1.0.0-alpha.10",
     "@reventlessdev/rescript-mcp-sdk": "1.0.0-alpha.21",
     "@reventlessdev/rescript-graphql-yoga": "1.0.0-alpha.27",
-    "@reventlessdev/rescript-jest": "1.0.0-alpha.10",
-    "@reventlessdev/rescript-node": "2.0.0-alpha.6",
     "@reventlessdev/rescript-pulumi-pulumi": "2.3.0-alpha.19",
-    "@reventlessdev/reventless-core": "3.0.0-alpha.233",
-    "@reventlessdev/reventless-graphql-server": "1.0.0-alpha.81",
-    "@reventlessdev/reventless-gwt": "1.0.0-alpha.180",
-    "@reventlessdev/reventless-postgres": "3.0.0-alpha.97",
-    "@reventlessdev/reventless-seed": "1.0.0-alpha.13",
-    "@reventlessdev/reventless-infra": "3.0.0-alpha.140",
-    "@reventlessdev/reventless-spec": "3.0.0-alpha.113"
+    "@reventlessdev/rescript-node": "2.0.0-alpha.7",
+    "@reventlessdev/reventless-graphql-server": "1.0.0-alpha.83",
+    "@reventlessdev/reventless-gwt": "1.0.0-alpha.182",
+    "@reventlessdev/reventless-infra": "3.0.0-alpha.142",
+    "@reventlessdev/reventless-postgres": "3.0.0-alpha.99",
+    "@reventlessdev/reventless-core": "3.0.0-alpha.235",
+    "@reventlessdev/reventless-seed": "1.0.0-alpha.14",
+    "@reventlessdev/reventless-spec": "3.0.0-alpha.114"
   },
   "devDependencies": {
     "rescript": "12.3.0",

package/src/BakedManifest.res

@@ -22,6 +22,7 @@ let toSelections = (
     plugin: s.plugin,
     views: s.views,
     commands: s.commands,
+    derived: s.derived,
   })
 
 /**

package/src/BakedManifest.res.mjs

@@ -14,7 +14,8 @@ function toSelections(components) {
   return components.map(s => ({
     plugin: s.plugin,
     views: s.views,
-    commands: s.commands
+    commands: s.commands,
+    derived: s.derived
   }));
 }
 

package/src/Platform.res

@@ -1642,6 +1642,19 @@ module MakeWithConfig = (
     // restores the shell package's own hints for a platform that has stopped
     // declaring its own.
     UiHints.emit(~uiHintsFile=hostUiBundle->Option.flatMap(cfg => cfg.uiHintsFile))
+    // The dev loop for the file just written. Editing hints is presentation
+    // work — you change a label, you want to see the label — and routing that
+    // through a platform restart puts fifteen seconds between the two. The
+    // watcher re-serves the file and says so on the events channel every shell
+    // already holds, so the menu restacks where it stands.
+    //
+    // Returned watcher deliberately dropped: it is unref'd and lives exactly as
+    // long as the process, like the servers above it, and holding it to close
+    // would imply a shutdown path this platform does not have.
+    let _ = UiHints.watch(
+      ~uiHintsFile=hostUiBundle->Option.flatMap(cfg => cfg.uiHintsFile),
+      ~onReload=LocalEvents_Server.broadcastUiHintsChanged,
+    )
     switch hostUiBundle->Option.flatMap(cfg => cfg.bakedManifest) {
     | None => ()
     | Some(cfg) => bakeManifest(~pluginComponents=plugins, ~config=cfg)
@@ -2251,7 +2264,7 @@ module MakeWithConfig = (
     // extracts identity from the bearer token, same as the Domain server.
     // Without this, Platform_* queries / mutations run as `anonymous` and
     // skip the group authorization that AppSync would enforce via
-    // `@aws_auth(cognito_groups: ["Admin"])` in production. The Domain
+    // `@aws_cognito_user_pools(cognito_groups: ["Admin"])` in production. The Domain
     // server's `asInterface.start` accepts but ignores `~contextFactory`
     // because it always wires its own internal auth context.
     adminGraphQL.start(

package/src/Platform.res.mjs

@@ -1295,6 +1295,7 @@ function MakeWithConfig(Config) {
     subscribeToPluginEvents();
     ShellConfig$ReventlessLocal.emit(Stdlib_Option.flatMap(hostUiBundle, cfg => cfg.bakedManifest), Stdlib_Option.flatMap(hostUiBundle, cfg => cfg.shellConfig), undefined);
     UiHints$ReventlessLocal.emit(Stdlib_Option.flatMap(hostUiBundle, cfg => cfg.uiHintsFile), undefined);
+    UiHints$ReventlessLocal.watch(Stdlib_Option.flatMap(hostUiBundle, cfg => cfg.uiHintsFile), undefined, LocalEvents_Server$ReventlessLocal.broadcastUiHintsChanged);
     let cfg = Stdlib_Option.flatMap(hostUiBundle, cfg => cfg.bakedManifest);
     if (cfg !== undefined) {
       bakeManifest(plugins$1, cfg);
@@ -1437,7 +1438,7 @@ function MakeWithConfig(Config) {
       });
       return Object.values(latestByName).map(param => param[1]);
     };
-    queryResolvers["Platform_ComponentDefinitions"] = async (_root, _args, _ctx) => connectedLatestStructures().map(param => Platform_ComponentDefinitionsApi$ReventlessCore.encodePluginStructureEntry(param[0], param[1]));
+    queryResolvers["Platform_ComponentDefinitions"] = async (_root, _args, _ctx) => connectedLatestStructures().map(param => Platform_ComponentDefinitionsApi$ReventlessCore.encodePluginStructureEntry(param[0], undefined, param[1]));
     queryResolvers["Platform_PluginStructures"] = async (_root, _args, _ctx) => connectedLatestStructures().map(param => Platform_PluginStructuresApi$ReventlessCore.encodePluginStructureEntry(param[0], param[1]));
     queryResolvers["Platform_UIFragments"] = async (_root, _args, _ctx) => {
       let scanAll = Bus.getQueryDbScan(UiFragments$ReventlessCore.name);
@@ -1772,7 +1773,7 @@ function MakeWithConfig(Config) {
           return Platform_UIFragmentsApi$ReventlessCore.encodeUIFragmentEntry(state);
         });
       };
-      queryResolvers["Platform_ComponentDefinitions"] = async (_root, _args, _ctx) => Object.entries(pluginStructuresStore.contents).map(param => Platform_ComponentDefinitionsApi$ReventlessCore.encodePluginStructureEntry(param[0], param[1]));
+      queryResolvers["Platform_ComponentDefinitions"] = async (_root, _args, _ctx) => Object.entries(pluginStructuresStore.contents).map(param => Platform_ComponentDefinitionsApi$ReventlessCore.encodePluginStructureEntry(param[0], undefined, param[1]));
       registerAdminItemsAndIndexResolvers(queryResolvers, true);
       adminGraphQL.registerQueries(baseParts.queries, queryResolvers);
       let mutationResolvers = {};
@@ -3020,6 +3021,7 @@ function Make($star) {
     subscribeToPluginEvents();
     ShellConfig$ReventlessLocal.emit(Stdlib_Option.flatMap(hostUiBundle, cfg => cfg.bakedManifest), Stdlib_Option.flatMap(hostUiBundle, cfg => cfg.shellConfig), undefined);
     UiHints$ReventlessLocal.emit(Stdlib_Option.flatMap(hostUiBundle, cfg => cfg.uiHintsFile), undefined);
+    UiHints$ReventlessLocal.watch(Stdlib_Option.flatMap(hostUiBundle, cfg => cfg.uiHintsFile), undefined, LocalEvents_Server$ReventlessLocal.broadcastUiHintsChanged);
     let cfg = Stdlib_Option.flatMap(hostUiBundle, cfg => cfg.bakedManifest);
     if (cfg !== undefined) {
       bakeManifest(plugins$1, cfg);
@@ -3162,7 +3164,7 @@ function Make($star) {
       });
       return Object.values(latestByName).map(param => param[1]);
     };
-    queryResolvers["Platform_ComponentDefinitions"] = async (_root, _args, _ctx) => connectedLatestStructures().map(param => Platform_ComponentDefinitionsApi$ReventlessCore.encodePluginStructureEntry(param[0], param[1]));
+    queryResolvers["Platform_ComponentDefinitions"] = async (_root, _args, _ctx) => connectedLatestStructures().map(param => Platform_ComponentDefinitionsApi$ReventlessCore.encodePluginStructureEntry(param[0], undefined, param[1]));
     queryResolvers["Platform_PluginStructures"] = async (_root, _args, _ctx) => connectedLatestStructures().map(param => Platform_PluginStructuresApi$ReventlessCore.encodePluginStructureEntry(param[0], param[1]));
     queryResolvers["Platform_UIFragments"] = async (_root, _args, _ctx) => {
       let scanAll = Bus.getQueryDbScan(UiFragments$ReventlessCore.name);
@@ -3488,7 +3490,7 @@ function Make($star) {
           return Platform_UIFragmentsApi$ReventlessCore.encodeUIFragmentEntry(state);
         });
       };
-      queryResolvers["Platform_ComponentDefinitions"] = async (_root, _args, _ctx) => Object.entries(pluginStructuresStore.contents).map(param => Platform_ComponentDefinitionsApi$ReventlessCore.encodePluginStructureEntry(param[0], param[1]));
+      queryResolvers["Platform_ComponentDefinitions"] = async (_root, _args, _ctx) => Object.entries(pluginStructuresStore.contents).map(param => Platform_ComponentDefinitionsApi$ReventlessCore.encodePluginStructureEntry(param[0], undefined, param[1]));
       registerAdminItemsAndIndexResolvers(queryResolvers, true);
       adminGraphQL.registerQueries(baseParts.queries, queryResolvers);
       let mutationResolvers = {};

package/src/UiHints.res

@@ -105,3 +105,85 @@ let emit = (
     }
   }
 }
+
+/**
+ Re-copy the declared hints into the served `dist/` whenever the file changes,
+ so editing it is a browser refresh rather than a platform restart.
+
+ Local only, and deliberately so: on AWS the file is an object written once by a
+ deploy, and "the running deployment follows my working copy" is not a thing a
+ deployment should be able to do. This is the dev loop, in the package that is
+ the dev loop.
+
+ **Failures here are logged, not thrown**, which is the one place this parts
+ company with `emit`. At boot a declaration that does not resolve or does not
+ parse is the deployment's mistake and taking the process down is the whole
+ point. Mid-session it is almost always an editor: a save that writes in two
+ steps is briefly a truncated file, and reading it at that instant is normal
+ rather than wrong. Killing a running dev server over a keystroke would make the
+ feature worse than the restart it replaces — so a bad read is reported and the
+ previously served copy stands until the next event, which the save itself
+ produces.
+
+ `onReload` runs only after a re-copy actually succeeded, so a subscriber cannot
+ be told to re-fetch a file that did not change.
+ */
+let watch = (
+  ~uiHintsFile: option<string>,
+  // The same seam `emit` takes, and threaded to it: a test has to be able to
+  // watch a file it wrote into a temp dir without a host-shell package on disk.
+  ~dir: option<string>=?,
+  ~onReload: unit => unit,
+): option<NodeFs.watcher> =>
+  uiHintsFile->Option.flatMap(path => {
+    // Named apart from the `~dir` above, which is where the file is SERVED. This
+    // is where it is AUTHORED, and the two are never the same place — letting
+    // one shadow the other would re-serve the hints into the source tree beside
+    // the file just edited.
+    let sourceDir = NodePath.dirname(path)
+    let base = NodePath.basename(path)
+    if !NodeFs.existsSync(sourceDir) {
+      // `emit` has already thrown on an unreadable declaration by the time this
+      // is reached, so this is the narrow case of a path whose directory went
+      // away between the two — worth a line, not worth a throw.
+      log.warn(
+        ~comp="UiHints",
+        `not watching ${base}: ${sourceDir} does not exist, so changes to the declared ` ++
+        `uiHintsFile will need a restart`,
+      )
+      None
+    } else {
+      // Editors coalesce badly: one save can raise `rename` and `change` within
+      // a millisecond of each other, and re-copying twice would publish twice
+      // and restack the menu twice. The trailing timer collapses a burst into
+      // the single reload the developer actually made.
+      let pending = ref(None)
+      let reload = () => {
+        pending := None
+        switch emit(~uiHintsFile, ~dir?) {
+        | () =>
+          log.info(~comp="UiHints", `${base} changed — re-served`)
+          onReload()
+        | exception JsExn(e) =>
+          log.warn(
+            ~comp="UiHints",
+            `${base} changed but could not be re-served: ` ++
+            e->JsExn.message->Option.getOr("unknown error"),
+          )
+        }
+      }
+      let watcher = NodeFs.watch(sourceDir, (_event, filename) =>
+        switch filename->Nullable.toOption {
+        | Some(name) if name == base =>
+          pending.contents->Option.forEach(clearTimeout)
+          pending := Some(setTimeout(reload, 50))
+        | _ => ()
+        }
+      )
+      log.info(~comp="UiHints", `watching ${path} — edits are served without a restart`)
+      // Never the reason a process stays alive. A platform booted by a test
+      // that happens to declare hints would otherwise hold the event loop open
+      // and hang the run.
+      Some(watcher->NodeFs.watcherUnref)
+    }
+  })

package/src/UiHints.res.mjs

@@ -2,8 +2,11 @@
 
 import * as Nodefs from "node:fs";
 import * as Nodepath from "node:path";
+import * as Stdlib_JsExn from "@rescript/runtime/lib/es6/Stdlib_JsExn.js";
 import * as Stdlib_Option from "@rescript/runtime/lib/es6/Stdlib_Option.js";
 import * as Stdlib_JsError from "@rescript/runtime/lib/es6/Stdlib_JsError.js";
+import * as Primitive_option from "@rescript/runtime/lib/es6/Primitive_option.js";
+import * as Primitive_exceptions from "@rescript/runtime/lib/es6/Primitive_exceptions.js";
 import * as Logger$ReventlessCore from "@reventlessdev/reventless-core/src/util/Logger.res.mjs";
 import * as HostShellDist$ReventlessLocal from "./HostShellDist.res.mjs";
 
@@ -52,10 +55,50 @@ function emit(uiHintsFile, dir) {
   }
 }
 
+function watch(uiHintsFile, dir, onReload) {
+  return Stdlib_Option.flatMap(uiHintsFile, path => {
+    let sourceDir = Nodepath.dirname(path);
+    let base = Nodepath.basename(path);
+    if (Nodefs.existsSync(sourceDir)) {
+      let pending = {
+        contents: undefined
+      };
+      let reload = () => {
+        pending.contents = undefined;
+        let val;
+        try {
+          val = emit(uiHintsFile, dir);
+        } catch (raw_e) {
+          let e = Primitive_exceptions.internalToException(raw_e);
+          if (e.RE_EXN_ID === "JsExn") {
+            return log.warn("UiHints", undefined, base + ` changed but could not be re-served: ` + Stdlib_Option.getOr(Stdlib_JsExn.message(e._1), "unknown error"));
+          }
+          throw e;
+        }
+        log.info("UiHints", undefined, base + ` changed — re-served`);
+        onReload();
+      };
+      let watcher = Nodefs.watch(sourceDir, (_event, filename) => {
+        if (!(filename == null) && filename === base) {
+          Stdlib_Option.forEach(pending.contents, prim => {
+            clearTimeout(prim);
+          });
+          pending.contents = Primitive_option.some(setTimeout(reload, 50));
+          return;
+        }
+      });
+      log.info("UiHints", undefined, `watching ` + path + ` — edits are served without a restart`);
+      return Primitive_option.some(watcher.unref());
+    }
+    log.warn("UiHints", undefined, `not watching ` + base + `: ` + sourceDir + ` does not exist, so changes to the declared uiHintsFile will need a restart`);
+  });
+}
+
 export {
   log,
   fileName,
   baselineFileName,
   emit,
+  watch,
 }
 /* log Not a pure module */

package/src/adapter/Api/LocalEvents_Server.res

@@ -100,6 +100,30 @@ let broadcast = (~channel: string, ~event: string): unit =>
     )
   )
 
+/** The channel a shell listens on to learn that this platform re-served its
+    hints file.
+
+    A fixed path rather than a derived one because it names no entity: there is
+    one hints file per deployment and one thing to say about it. Under `/dev/`
+    so it reads as what it is — a local development signal with no counterpart
+    on AWS, where the file is an object a deploy writes once.
+
+    Kept here, beside the broadcaster, because the string has to be identical on
+    both sides of a socket and a channel nothing listens to fails silently: the
+    connection stays open and the message simply lands nowhere. */
+let devUiHintsChannel = "/default/dev/uiHints"
+
+/** Tell every connected shell that `ui-hints.json` has been re-served.
+
+    The payload carries no hints. The shell re-fetches the file it already knows
+    how to fetch, which keeps this a cache-invalidation signal rather than a
+    second delivery path that could disagree with the first. */
+let broadcastUiHintsChanged = (): unit =>
+  broadcast(
+    ~channel=devUiHintsChannel,
+    ~event=frame([("kind", JSON.Encode.string("uiHintsChanged"))]),
+  )
+
 /** LocalBus bridge: a Source B change descriptor becomes a publish on the
     same channel the AWS StateTopic Lambda would use. No-op without matching
     subscribers, so wiring order against server start doesn't matter. */

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

@@ -95,6 +95,15 @@ function broadcast(channel, event) {
   });
 }
 
+let devUiHintsChannel = "/default/dev/uiHints";
+
+function broadcastUiHintsChanged() {
+  broadcast(devUiHintsChannel, frame([[
+      "kind",
+      "uiHintsChanged"
+    ]]));
+}
+
 function broadcastStateChange(name, descriptor) {
   let entityKey = Stdlib_Option.getOr(Stdlib_Option.flatMap(Stdlib_Option.flatMap(Stdlib_JSON.Decode.object(descriptor), o => o["id"]), Stdlib_JSON.Decode.string), "");
   if (entityKey === "") {
@@ -328,6 +337,8 @@ export {
   connectionAckFrame,
   dataFrame,
   broadcast,
+  devUiHintsChannel,
+  broadcastUiHintsChanged,
   broadcastStateChange,
   decodeStringField,
   handleFrame,

package/src/adapter/Auth/Auth_GraphqlContext.res

@@ -7,8 +7,8 @@
 //   - Invalid bearer is rejected at HTTP level before this runs (see
 //     `DomainGraphQL_Server._dispatch`); on the admin server there is no
 //     dispatch layer, so an invalid bearer reaches this as an `AuthError`.
-//     AppSync enforces the same `@aws_auth(cognito_groups: ["Admin"])`
-//     directive at the schema layer in production.
+//     AppSync enforces the same `@aws_cognito_user_pools(cognito_groups:
+//     ["Admin"])` directive at the schema layer in production.
 //
 // The outcome is carried onto the context beside the identity, not folded into
 // it. Whether credentials verified and whether the verified caller holds a group
@@ -97,8 +97,9 @@ let extractAuthenticated = (ctx: JSON.t): bool =>
   }
 
 // An unauthorized caller reads the reason: `GraphQL_CallerError` explains why a
-// resolver has to construct the error rather than throw a bare one. Mirrors the
-// directive-level `@aws_auth` rejection that AppSync surfaces in production.
+// resolver has to construct the error rather than throw a bare one. The AWS
+// counterpart is the field-level refusal AppSync returns for a caller who fails
+// an `@aws_cognito_user_pools(cognito_groups: [...])` gate.
 let makeGraphqlError = GraphQL_CallerError.make
 
 /**
@@ -112,7 +113,7 @@ let makeGraphqlError = GraphQL_CallerError.make
 let unauthorizedError = (~group: string): exn =>
   makeGraphqlError(
     `Unauthorized: requires group "${group}"`,
-    {"extensions": {"code": "UNAUTHORIZED"}},
+    {"extensions": {"code": ReventlessCore.Auth_RefusalVocabulary.localIdentityCode}},
   )
 
 /**
@@ -128,13 +129,15 @@ let unauthorizedError = (~group: string): exn =>
 let forbiddenError = (~group: string): exn =>
   makeGraphqlError(
     `Forbidden: requires group "${group}"`,
-    {"extensions": {"code": "FORBIDDEN"}},
+    {"extensions": {"code": ReventlessCore.Auth_RefusalVocabulary.localEntitlementCode}},
   )
 
 // Wrap a resolver so it refuses a caller whose identity lacks the required
-// group. Mirrors AppSync's `@aws_auth(cognito_groups: [...])` semantics for
-// admin fields on the in-memory adapter, save that AppSync has one rejection to
-// give and this has two. Use for fields whose corresponding read-model entry
+// group. Mirrors AppSync's `@aws_cognito_user_pools(cognito_groups: [...])`
+// semantics for admin fields on the in-memory adapter. Both paths draw the same
+// two-way distinction — AppSync as HTTP 401 versus a field error, this as two
+// `extensions.code` values — and `ReventlessCore.Auth_RefusalVocabulary` is the
+// mapping between them. Use for fields whose corresponding read-model entry
 // carries `authorization: Some({group, ...})` — pass the group string here.
 let requireGroup = (~group: string, resolver: YG.resolverFn): YG.resolverFn =>
   async (root, args, ctx) => {

package/src/adapter/Auth/Auth_GraphqlContext.res.mjs

@@ -3,6 +3,7 @@
 import * as Graphql from "graphql";
 import * as Identity$Reventless from "@reventlessdev/reventless-spec/src/types/Identity.res.mjs";
 import * as LocalAuth$ReventlessLocal from "./LocalAuth.res.mjs";
+import * as Auth_RefusalVocabulary$ReventlessCore from "@reventlessdev/reventless-core/src/adapter/Auth/Auth_RefusalVocabulary.res.mjs";
 
 function extractHeaders(headers) {
   let acc = {};
@@ -74,7 +75,7 @@ function makeGraphqlError(prim0, prim1) {
 function unauthorizedError(group) {
   return new Graphql.GraphQLError(`Unauthorized: requires group "` + group + `"`, {
     extensions: {
-      code: "UNAUTHORIZED"
+      code: Auth_RefusalVocabulary$ReventlessCore.localIdentityCode
     }
   });
 }
@@ -82,7 +83,7 @@ function unauthorizedError(group) {
 function forbiddenError(group) {
   return new Graphql.GraphQLError(`Forbidden: requires group "` + group + `"`, {
     extensions: {
-      code: "FORBIDDEN"
+      code: Auth_RefusalVocabulary$ReventlessCore.localEntitlementCode
     }
   });
 }

package/src/adapter/Auth/LocalAuth.res

@@ -89,22 +89,81 @@ module Login = {
 
   // ── HMAC secret (lazy) ──
   //
-  // Reads `REVENTLESS_INMEMORY_TOKEN_SECRET` once on first use. When the env
-  // var is set (≥16 chars) the issued tokens survive process restarts, which
-  // matches the dev loop's expectation that a logged-in tab keeps working
-  // after a backend reload. When unset, falls back to a random per-process
-  // secret — secure for ephemeral test runs but invalidates every previously
-  // issued token on every restart.
+  // Resolved once on first use, from three sources in order:
+  //
+  //   1. `REVENTLESS_INMEMORY_TOKEN_SECRET` (≥16 chars) — an explicit pin, for
+  //      a deployment or a test that wants to state the secret itself.
+  //   2. `.reventless/token-secret` beside the platform's other local state,
+  //      minted on the first boot that finds the directory and reused by every
+  //      boot after. This is what keeps a logged-in tab working across a
+  //      restart, which is not a nicety: `tsx watch` re-execs the process on
+  //      every ReScript rebuild, so a per-process secret logs the developer out
+  //      several times an hour, mid-task, with a "reconnecting" spinner as the
+  //      only explanation.
+  //   3. A random 32 bytes, per process — today's behaviour, kept for the run
+  //      that has no `.reventless/` to write to.
+  //
+  // The directory is used but never created. Its presence is what distinguishes
+  // a platform someone develops against — `pnpm run setup` puts `users.yaml`
+  // there, so anything with logins to preserve has one — from a unit test, and
+  // an auth module that made directories would leave one in every test's cwd.
+  //
+  // Local dev only, as the whole module is: these tokens are not security-grade
+  // and AWS never sees them. The file sits in a gitignored directory beside
+  // `users.yaml`, which already holds plaintext dev passwords.
+
+  let _secretFileName = "token-secret"
+  let _secretDir = (): string => NodePath.join([NodeProcess.cwd(), ".reventless"])
+
+  let _mint = (): string => NodeCrypto.randomBytes(32)->NodeCrypto.bufferToString("hex")
+
+  // A short or empty file is treated as absent rather than as an error: it is
+  // either a half-written mint or somebody's experiment, and either way the
+  // recovery — mint a new one over it — is the same and costs one login.
+  let _readPersistedAt = (path: string): option<string> =>
+    switch NodeFs.readFileSync(path) {
+    | contents if String.length(String.trim(contents)) >= 16 => Some(String.trim(contents))
+    | _ => None
+    | exception _ => None
+    }
+
+  // Failure to write is not failure to boot. A read-only checkout still gets a
+  // working platform; what it loses is the session surviving the next restart,
+  // which is exactly what it had before this existed.
+  let _persistAt = (path: string, secret: string): unit =>
+    switch NodeFs.writeFileSync(path, secret) {
+    | () => ()
+    | exception _ => ()
+    }
+
+  /** The ladder, against a stated directory. Separate from `_getSecret` so a
+      test can exercise every rung without a `.reventless/` in its own working
+      directory — which it must not have, since the rule below is precisely that
+      the directory's presence decides whether anything is written at all. */
+  let _resolveIn = (~dir: string): string =>
+    switch NodeProcess.env->Dict.get("REVENTLESS_INMEMORY_TOKEN_SECRET") {
+    | Some(envSecret) if String.length(envSecret) >= 16 => envSecret
+    | _ =>
+      if NodeFs.existsSync(dir) {
+        let path = NodePath.join([dir, _secretFileName])
+        switch _readPersistedAt(path) {
+        | Some(persisted) => persisted
+        | None =>
+          let minted = _mint()
+          _persistAt(path, minted)
+          minted
+        }
+      } else {
+        _mint()
+      }
+    }
 
   let _secret: ref<option<string>> = ref(None)
   let _getSecret = (): string =>
     switch _secret.contents {
     | Some(s) => s
     | None =>
-      let s = switch NodeProcess.env->Dict.get("REVENTLESS_INMEMORY_TOKEN_SECRET") {
-      | Some(envSecret) if String.length(envSecret) >= 16 => envSecret
-      | _ => NodeCrypto.randomBytes(32)->NodeCrypto.bufferToString("hex")
-      }
+      let s = _resolveIn(~dir=_secretDir())
       _secret := Some(s)
       s
     }

package/src/adapter/Auth/LocalAuth.res.mjs

@@ -1,6 +1,8 @@
 // Generated by ReScript, PLEASE EDIT WITH CARE
 
 import * as S from "sury/src/S.res.mjs";
+import * as Nodefs from "node:fs";
+import * as Nodepath from "node:path";
 import * as Nodecrypto from "node:crypto";
 import * as Stdlib_Option from "@rescript/runtime/lib/es6/Stdlib_Option.js";
 import * as Pulumi from "@pulumi/pulumi";
@@ -81,6 +83,55 @@ function resetStore() {
   store.contents = {};
 }
 
+let _secretFileName = "token-secret";
+
+function _secretDir() {
+  return Nodepath.join(process.cwd(), ".reventless");
+}
+
+function _mint() {
+  return Nodecrypto.randomBytes(32).toString("hex");
+}
+
+function _readPersistedAt(path) {
+  let contents;
+  try {
+    contents = Nodefs.readFileSync(path, "utf8");
+  } catch (exn) {
+    return;
+  }
+  if (contents.trim().length >= 16) {
+    return contents.trim();
+  }
+}
+
+function _persistAt(path, secret) {
+  try {
+    Nodefs.writeFileSync(path, secret, "utf8");
+    return;
+  } catch (exn) {
+    return;
+  }
+}
+
+function _resolveIn(dir) {
+  let envSecret = process.env["REVENTLESS_INMEMORY_TOKEN_SECRET"];
+  if (envSecret !== undefined && envSecret.length >= 16) {
+    return envSecret;
+  }
+  if (!Nodefs.existsSync(dir)) {
+    return Nodecrypto.randomBytes(32).toString("hex");
+  }
+  let path = Nodepath.join(dir, _secretFileName);
+  let persisted = _readPersistedAt(path);
+  if (persisted !== undefined) {
+    return persisted;
+  }
+  let minted = Nodecrypto.randomBytes(32).toString("hex");
+  _persistAt(path, minted);
+  return minted;
+}
+
 let _secret = {
   contents: undefined
 };
@@ -90,8 +141,7 @@ function _getSecret() {
   if (s !== undefined) {
     return s;
   }
-  let envSecret = process.env["REVENTLESS_INMEMORY_TOKEN_SECRET"];
-  let s$1 = envSecret !== undefined && envSecret.length >= 16 ? envSecret : Nodecrypto.randomBytes(32).toString("hex");
+  let s$1 = _resolveIn(_secretDir());
   _secret.contents = s$1;
   return s$1;
 }
@@ -231,6 +281,12 @@ let Login = {
   store: store,
   setCredentials: setCredentials,
   resetStore: resetStore,
+  _secretFileName: _secretFileName,
+  _secretDir: _secretDir,
+  _mint: _mint,
+  _readPersistedAt: _readPersistedAt,
+  _persistAt: _persistAt,
+  _resolveIn: _resolveIn,
   _secret: _secret,
   _getSecret: _getSecret,
   setTokenSecret: setTokenSecret,

package/src/adapter/PlatformGraphQL_Server.res

@@ -11,8 +11,8 @@
 // Authorization: every query AND mutation resolver registered here is
 // wrapped with `Auth_GraphqlContext.requireGroup(~group="Admin")` so
 // non-Admin identities are refused before the underlying resolver runs.
-// Mirrors AppSync's `@aws_auth(cognito_groups: ["Admin"])` directive that
-// gates Platform_* fields in the AWS adapter.
+// Mirrors AppSync's `@aws_cognito_user_pools(cognito_groups: ["Admin"])`
+// directive that gates Platform_* fields in the AWS adapter.
 //
 // The refusal names which kind it is: `FORBIDDEN` for a caller the server
 // identified who does not hold the group, `UNAUTHORIZED` for one it could not

package/tests/UiHintsTest.res

@@ -92,3 +92,97 @@ describe("UiHints.emit", () => {
     expect(NodeFs.existsSync(baselinePath(dir)))->toBe(false)
   })
 })
+
+// The dev loop: the platform follows the declared file so editing hints is a
+// browser refresh rather than a restart. Real `fs.watch` events rather than a
+// stubbed clock, because what is being tested IS the plumbing — a debounce over
+// a fake timer would pass with the watcher wired to nothing.
+//
+// The rule these turn on is the one place `watch` parts company with `emit`: at
+// boot a bad file is the deployment's mistake and taking the process down is the
+// point, while mid-session it is almost always an editor mid-save, and killing a
+// running dev server over a keystroke is worse than the restart this replaces.
+
+// Both exits close the watcher AND clear the deadline. A watcher is `unref`ed
+// and would not hold the run open on its own, but a live 4-second timer would —
+// and "Jest did not exit" on a suite that passed is exactly the noise that
+// teaches a reader to ignore it.
+let waitForReload = (~timeoutMs: int=4000, ~afterWatching: unit => unit, ~uiHintsFile, ~dir) =>
+  Promise.make((resolve, _) => {
+    let fired = ref(0)
+    let watcher = ref(None)
+    let deadline = ref(None)
+    // Resolves with a count rather than rejecting on the deadline: "nothing was
+    // re-served" is the expected answer in half these cases, and a rejection
+    // would make the assertion read as an infrastructure failure.
+    let finish = () => {
+      watcher.contents->Option.forEach(NodeFs.watcherClose)
+      deadline.contents->Option.forEach(clearTimeout)
+      resolve(fired.contents)
+    }
+    watcher :=
+      UiHints.watch(~uiHintsFile, ~dir, ~onReload=() => {
+        fired := fired.contents + 1
+        finish()
+      })
+    deadline := Some(setTimeout(finish, timeoutMs))
+    afterWatching()
+  })
+
+describe("UiHints.watch", () => {
+  testSync("watches nothing when the platform declares no hints file", () =>
+    expect(UiHints.watch(~uiHintsFile=None, ~onReload=() => ()))->toEqual(None)
+  )
+
+  testSync("declines to watch a path whose directory is gone, without throwing", () => {
+    let missing = NodePath.join([tmpdir("reventless-uihints-gone-"), "nowhere", "ui-hints.json"])
+    expect(UiHints.watch(~uiHintsFile=Some(missing), ~onReload=() => ()))->toEqual(None)
+  })
+
+  test("re-serves the file when it changes, and says so", async () => {
+    let dir = distWithHints()
+    let path = declaredFile(declared)
+    UiHints.emit(~uiHintsFile=Some(path), ~dir)
+    let edited = `{"Catalog": {"views": {"Products": {"nav": {"label": "Edited"}}}}}`
+    let fired = await waitForReload(
+      ~uiHintsFile=Some(path),
+      ~dir,
+      ~afterWatching=() => NodeFs.writeFileSync(path, edited),
+    )
+    expect((fired > 0, served(dir)))->toEqual((true, edited))
+  })
+
+  // The save that arrives in two writes. Serving the truncated middle would put
+  // a file the shell cannot parse in front of every caller; throwing would end
+  // the session over a keystroke. Neither: the previous copy stands.
+  test("keeps serving the last good copy when the file is momentarily not JSON", async () => {
+    let dir = distWithHints()
+    let path = declaredFile(declared)
+    UiHints.emit(~uiHintsFile=Some(path), ~dir)
+    let fired = await waitForReload(
+      ~timeoutMs=1500,
+      ~uiHintsFile=Some(path),
+      ~dir,
+      ~afterWatching=() => NodeFs.writeFileSync(path, `{"Catalog": {"views":`),
+    )
+    expect((fired, served(dir)))->toEqual((0, declared))
+  })
+
+  // …and the save completing is itself the next event, so recovery needs no
+  // second trigger. This is why a failed reload can be silent about retrying.
+  test("recovers on the write that finishes the save", async () => {
+    let dir = distWithHints()
+    let path = declaredFile(declared)
+    UiHints.emit(~uiHintsFile=Some(path), ~dir)
+    let whole = `{"Catalog": {"views": {"Products": {"nav": {"label": "Whole"}}}}}`
+    let fired = await waitForReload(
+      ~uiHintsFile=Some(path),
+      ~dir,
+      ~afterWatching=() => {
+        NodeFs.writeFileSync(path, `{"Catalog": {"views":`)
+        let _ = setTimeout(() => NodeFs.writeFileSync(path, whole), 200)
+      },
+    )
+    expect((fired > 0, served(dir)))->toEqual((true, whole))
+  })
+})

package/tests/UiHintsTest.res.mjs

@@ -3,6 +3,8 @@
 import * as Nodefs from "node:fs";
 import * as Nodeos from "node:os";
 import * as Nodepath from "node:path";
+import * as Stdlib_Option from "@rescript/runtime/lib/es6/Stdlib_Option.js";
+import * as Primitive_option from "@rescript/runtime/lib/es6/Primitive_option.js";
 import * as UiHints$ReventlessLocal from "../src/UiHints.res.mjs";
 import * as TestRunner$ReventlessLocal from "../src/test/TestRunner.res.mjs";
 
@@ -86,6 +88,96 @@ globalThis.describe("UiHints.emit", () => {
   });
 });
 
+function waitForReload(timeoutMsOpt, afterWatching, uiHintsFile, dir) {
+  let timeoutMs = timeoutMsOpt !== undefined ? timeoutMsOpt : 4000;
+  return new Promise((resolve, param) => {
+    let fired = {
+      contents: 0
+    };
+    let watcher = {
+      contents: undefined
+    };
+    let deadline = {
+      contents: undefined
+    };
+    let finish = () => {
+      Stdlib_Option.forEach(watcher.contents, prim => {
+        prim.close();
+      });
+      Stdlib_Option.forEach(deadline.contents, prim => {
+        clearTimeout(prim);
+      });
+      resolve(fired.contents);
+    };
+    watcher.contents = UiHints$ReventlessLocal.watch(uiHintsFile, dir, () => {
+      fired.contents = fired.contents + 1 | 0;
+      finish();
+    });
+    deadline.contents = Primitive_option.some(setTimeout(finish, timeoutMs));
+    afterWatching();
+  });
+}
+
+globalThis.describe("UiHints.watch", () => {
+  globalThis.test("watches nothing when the platform declares no hints file", () => {
+    globalThis.expect(UiHints$ReventlessLocal.watch(undefined, undefined, () => {})).toEqual(undefined);
+  });
+  globalThis.test("declines to watch a path whose directory is gone, without throwing", () => {
+    let missing = Nodepath.join(tmpdir("reventless-uihints-gone-"), "nowhere", "ui-hints.json");
+    globalThis.expect(UiHints$ReventlessLocal.watch(missing, undefined, () => {})).toEqual(undefined);
+  });
+  globalThis.test("re-serves the file when it changes, and says so", async () => {
+    let dir = distWithHints();
+    let path = declaredFile(declared);
+    UiHints$ReventlessLocal.emit(path, dir);
+    let edited = `{"Catalog": {"views": {"Products": {"nav": {"label": "Edited"}}}}}`;
+    let fired = await waitForReload(undefined, () => {
+      Nodefs.writeFileSync(path, edited, "utf8");
+    }, path, dir);
+    globalThis.expect([
+      fired > 0,
+      served(dir)
+    ]).toEqual([
+      true,
+      edited
+    ]);
+  });
+  globalThis.test("keeps serving the last good copy when the file is momentarily not JSON", async () => {
+    let dir = distWithHints();
+    let path = declaredFile(declared);
+    UiHints$ReventlessLocal.emit(path, dir);
+    let fired = await waitForReload(1500, () => {
+      Nodefs.writeFileSync(path, `{"Catalog": {"views":`, "utf8");
+    }, path, dir);
+    globalThis.expect([
+      fired,
+      served(dir)
+    ]).toEqual([
+      0,
+      declared
+    ]);
+  });
+  globalThis.test("recovers on the write that finishes the save", async () => {
+    let dir = distWithHints();
+    let path = declaredFile(declared);
+    UiHints$ReventlessLocal.emit(path, dir);
+    let whole = `{"Catalog": {"views": {"Products": {"nav": {"label": "Whole"}}}}}`;
+    let fired = await waitForReload(undefined, () => {
+      Nodefs.writeFileSync(path, `{"Catalog": {"views":`, "utf8");
+      setTimeout(() => {
+        Nodefs.writeFileSync(path, whole, "utf8");
+      }, 200);
+    }, path, dir);
+    globalThis.expect([
+      fired > 0,
+      served(dir)
+    ]).toEqual([
+      true,
+      whole
+    ]);
+  });
+});
+
 export {
   shipped,
   declared,
@@ -95,5 +187,6 @@ export {
   served,
   baselinePath,
   threw,
+  waitForReload,
 }
 /*  Not a pure module */

package/tests/adapter/LocalAuthLoginTest.res

@@ -436,3 +436,57 @@ describe("the conformance table, minted locally", () => {
     })
   )
 })
+
+// The secret the tokens are signed with, and the one thing that decides whether
+// a logged-in tab survives a backend restart.
+//
+// It is not the manual restart that makes this matter. `tsx watch` re-execs the
+// process on every ReScript rebuild, so a per-process secret signs the developer
+// out several times an hour, mid-task — and the symptom is a socket that will
+// not reconnect rather than anything that says "log in again".
+describe("Login token secret", () => {
+  let tmpdir = prefix => NodeFs.mkdtempSync(NodePath.join([NodeOs.tmpdir(), prefix]))
+  let secretPath = dir => NodePath.join([dir, "token-secret"])
+
+  testSync("mints one into a directory that exists, and reuses it next boot", () => {
+    let dir = tmpdir("reventless-secret-")
+    let first = LocalAuth.Login._resolveIn(~dir)
+    // A second call with no memoised value is what the next process does.
+    let second = LocalAuth.Login._resolveIn(~dir)
+    expect((first == second, NodeFs.existsSync(secretPath(dir)), String.length(first) >= 16))->toEqual((
+      true,
+      true,
+      true,
+    ))
+  })
+
+  testSync("reads a secret a previous boot left behind", () => {
+    let dir = tmpdir("reventless-secret-")
+    NodeFs.writeFileSync(secretPath(dir), "a-previous-boots-secret-value")
+    expect(LocalAuth.Login._resolveIn(~dir))->toEqual("a-previous-boots-secret-value")
+  })
+
+  // The directory is used, never created — its absence is what tells a unit test
+  // apart from a platform someone develops against, and an auth module that made
+  // directories would leave one in every test's working directory.
+  testSync("writes nothing when there is no .reventless directory", () => {
+    let dir = NodePath.join([tmpdir("reventless-secret-"), "absent"])
+    let secret = LocalAuth.Login._resolveIn(~dir)
+    expect((NodeFs.existsSync(dir), String.length(secret) >= 16))->toEqual((false, true))
+  })
+
+  testSync("gives a different secret per run when nothing is persisted", () => {
+    let dir = NodePath.join([tmpdir("reventless-secret-"), "absent"])
+    expect(LocalAuth.Login._resolveIn(~dir) == LocalAuth.Login._resolveIn(~dir))->toEqual(false)
+  })
+
+  // Ignoring a half-written file costs one login; treating it as the secret
+  // would sign tokens nothing can verify, which costs the same login and a
+  // debugging session.
+  testSync("mints over a file too short to be a secret", () => {
+    let dir = tmpdir("reventless-secret-")
+    NodeFs.writeFileSync(secretPath(dir), "short")
+    let resolved = LocalAuth.Login._resolveIn(~dir)
+    expect((resolved == "short", String.length(resolved) >= 16))->toEqual((false, true))
+  })
+})

package/tests/adapter/LocalAuthLoginTest.res.mjs

@@ -1,5 +1,8 @@
 // Generated by ReScript, PLEASE EDIT WITH CARE
 
+import * as Nodefs from "node:fs";
+import * as Nodeos from "node:os";
+import * as Nodepath from "node:path";
 import * as Stdlib_Option from "@rescript/runtime/lib/es6/Stdlib_Option.js";
 import * as Stdlib_JsError from "@rescript/runtime/lib/es6/Stdlib_JsError.js";
 import * as Identity$Reventless from "@reventlessdev/reventless-spec/src/types/Identity.res.mjs";
@@ -410,6 +413,56 @@ globalThis.describe("the conformance table, minted locally", () => {
   });
 });
 
+globalThis.describe("Login token secret", () => {
+  let tmpdir = prefix => Nodefs.mkdtempSync(Nodepath.join(Nodeos.tmpdir(), prefix));
+  globalThis.test("mints one into a directory that exists, and reuses it next boot", () => {
+    let dir = tmpdir("reventless-secret-");
+    let first = LocalAuth$ReventlessLocal.Login._resolveIn(dir);
+    let second = LocalAuth$ReventlessLocal.Login._resolveIn(dir);
+    globalThis.expect([
+      first === second,
+      Nodefs.existsSync(Nodepath.join(dir, "token-secret")),
+      first.length >= 16
+    ]).toEqual([
+      true,
+      true,
+      true
+    ]);
+  });
+  globalThis.test("reads a secret a previous boot left behind", () => {
+    let dir = tmpdir("reventless-secret-");
+    Nodefs.writeFileSync(Nodepath.join(dir, "token-secret"), "a-previous-boots-secret-value", "utf8");
+    globalThis.expect(LocalAuth$ReventlessLocal.Login._resolveIn(dir)).toEqual("a-previous-boots-secret-value");
+  });
+  globalThis.test("writes nothing when there is no .reventless directory", () => {
+    let dir = Nodepath.join(tmpdir("reventless-secret-"), "absent");
+    let secret = LocalAuth$ReventlessLocal.Login._resolveIn(dir);
+    globalThis.expect([
+      Nodefs.existsSync(dir),
+      secret.length >= 16
+    ]).toEqual([
+      false,
+      true
+    ]);
+  });
+  globalThis.test("gives a different secret per run when nothing is persisted", () => {
+    let dir = Nodepath.join(tmpdir("reventless-secret-"), "absent");
+    globalThis.expect(LocalAuth$ReventlessLocal.Login._resolveIn(dir) === LocalAuth$ReventlessLocal.Login._resolveIn(dir)).toEqual(false);
+  });
+  globalThis.test("mints over a file too short to be a secret", () => {
+    let dir = tmpdir("reventless-secret-");
+    Nodefs.writeFileSync(Nodepath.join(dir, "token-secret"), "short", "utf8");
+    let resolved = LocalAuth$ReventlessLocal.Login._resolveIn(dir);
+    globalThis.expect([
+      resolved === "short",
+      resolved.length >= 16
+    ]).toEqual([
+      false,
+      true
+    ]);
+  });
+});
+
 export {
   alice,
   bob,