@reventlessdev/reventless-core 3.0.0-alpha.239 → 3.0.0-alpha.241

package/src/util/Interstack.res

@@ -21,7 +21,7 @@ module DefaultTaskQuery = ReventlessInterop.Query.Task.Make({
   let requiredFields = ["name"]
   let optionalFields = ["bucketNames", "sideEffectSources"]
   let fromJson = (json: JSON.t) =>
-    try Ok(json->S.parseOrThrow(ReventlessInterop.Task.resolvedOutputsSchema))
+    try Ok(json->S.parseOrThrow(~to=ReventlessInterop.Task.resolvedOutputsSchema))
     catch {
     | exn =>
       let msg =
@@ -35,7 +35,7 @@ module DefaultEventMapperQuery = ReventlessInterop.Query.EventMapper.Make({
   let requiredFields = ["name", "eventCollector"]
   let optionalFields = ["counter"]
   let fromJson = (json: JSON.t) =>
-    try Ok(json->S.parseOrThrow(ReventlessInterop.EventMapper.resolvedOutputsSchema))
+    try Ok(json->S.parseOrThrow(~to=ReventlessInterop.EventMapper.resolvedOutputsSchema))
     catch {
     | exn =>
       let msg =
@@ -54,7 +54,7 @@ module DefaultExtensionPointQuery = ReventlessInterop.Query.ExtensionPoint.Make(
   let requiredFields = ["name", "commandTopic", "eventTopic"]
   let optionalFields = []
   let fromJson = (json: JSON.t) =>
-    try Ok(json->S.parseOrThrow(ReventlessInterop.ExtensionPoint.resolvedOutputsSchema))
+    try Ok(json->S.parseOrThrow(~to=ReventlessInterop.ExtensionPoint.resolvedOutputsSchema))
     catch {
     | exn =>
       let msg =

package/src/util/LogFormat.res

@@ -248,8 +248,7 @@ let fmtState = (~name: string, ~id: string, ~seq: int): string =>
   `state=${name}(${id}) seq=${seq->Int.toString}`
 
 // "err=<message>"
-let fmtExn = (e: exn): string =>
-  `err=${e->JsExn.fromException->Option.flatMap(JsExn.message)->Option.getOr("unknown")}`
+let fmtExn = (e: exn): string => `err=${e->Reventless.Util_Sury.exnMessage}`
 
 // ─── Legacy aliases (kept for existing callers) ──────────────────────────────
 

package/src/util/LogFormat.res.mjs

@@ -3,10 +3,10 @@
 import * as Stdlib_Int from "@rescript/runtime/lib/es6/Stdlib_Int.js";
 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 Stdlib_JsExn from "@rescript/runtime/lib/es6/Stdlib_JsExn.js";
 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 AnsiStyle$Reventless from "@reventlessdev/reventless-spec/src/AnsiStyle.res.mjs";
+import * as Util_Sury$Reventless from "@reventlessdev/reventless-spec/src/util/Util_Sury.res.mjs";
 import * as Message$ReventlessCore from "../Message.res.mjs";
 
 let maxValueChars = Stdlib_Option.getOr(Stdlib_Option.flatMap(process.env["REVENTLESS_LOG_MAX_VALUE"], v => Stdlib_Int.fromString(v, undefined)), 512);
@@ -204,7 +204,7 @@ function fmtState(name, id, seq) {
 }
 
 function fmtExn(e) {
-  return `err=` + Stdlib_Option.getOr(Stdlib_Option.flatMap(Stdlib_JsExn.fromException(e), Stdlib_JsExn.message), "unknown");
+  return `err=` + Util_Sury$Reventless.exnMessage(e, undefined);
 }
 
 function commandJsonsToLogMessages(cmdJsons) {

package/tests/IdentityTest.res

@@ -1,6 +1,5 @@
 open JestGlobals
 
-S.enableJson()
 
 describe("Identity", () => {
   describe("anonymous", () => {
@@ -71,8 +70,8 @@ describe("Identity", () => {
         claims: Dict.fromArray([("tenant", "acme")]),
         provider: Cognito,
       }
-      let json = identity->S.reverseConvertToJsonOrThrow(Reventless.Identity.schema)
-      let decoded = json->S.parseJsonOrThrow(Reventless.Identity.schema)
+      let json = identity->Reventless.Util_Sury.toJson(Reventless.Identity.schema)
+      let decoded = json->Reventless.Util_Sury.fromJson(Reventless.Identity.schema)
       expect(decoded)->toEqual(identity)
     })
 
@@ -83,8 +82,8 @@ describe("Identity", () => {
         groups: [],
         provider: Custom("oauth2"),
       }
-      let json = identity->S.reverseConvertToJsonOrThrow(Reventless.Identity.schema)
-      let decoded = json->S.parseJsonOrThrow(Reventless.Identity.schema)
+      let json = identity->Reventless.Util_Sury.toJson(Reventless.Identity.schema)
+      let decoded = json->Reventless.Util_Sury.fromJson(Reventless.Identity.schema)
       expect(decoded)->toEqual(identity)
     })
 
@@ -95,8 +94,8 @@ describe("Identity", () => {
         groups: [],
         provider: InMemory,
       }
-      let json = identity->S.reverseConvertToJsonOrThrow(Reventless.Identity.schema)
-      let decoded = json->S.parseJsonOrThrow(Reventless.Identity.schema)
+      let json = identity->Reventless.Util_Sury.toJson(Reventless.Identity.schema)
+      let decoded = json->Reventless.Util_Sury.fromJson(Reventless.Identity.schema)
       expect(decoded.userId)->toBe("user-3")->ignore
       expect(decoded.provider)->toEqual(Reventless.Identity.InMemory)
     })

package/tests/IdentityTest.res.mjs

@@ -1,11 +1,9 @@
 // Generated by ReScript, PLEASE EDIT WITH CARE
 
-import * as S from "sury/src/S.res.mjs";
 import * as Identity$Reventless from "@reventlessdev/reventless-spec/src/types/Identity.res.mjs";
+import * as Util_Sury$Reventless from "@reventlessdev/reventless-spec/src/util/Util_Sury.res.mjs";
 import * as RequestContext$ReventlessCore from "../src/RequestContext.res.mjs";
 
-S.enableJson();
-
 globalThis.describe("Identity", () => {
   globalThis.describe("anonymous", () => {
     globalThis.test("has userId 'anonymous'", () => {
@@ -86,8 +84,8 @@ globalThis.describe("Identity", () => {
         claims: identity_claims,
         provider: "Cognito"
       };
-      let json = S.reverseConvertToJsonOrThrow(identity, Identity$Reventless.schema);
-      let decoded = S.parseJsonOrThrow(json, Identity$Reventless.schema);
+      let json = Util_Sury$Reventless.toJson(identity, Identity$Reventless.schema);
+      let decoded = Util_Sury$Reventless.fromJson(json, Identity$Reventless.schema);
       globalThis.expect(decoded).toEqual(identity);
     });
     globalThis.test("roundtrip with Custom provider", () => {
@@ -102,8 +100,8 @@ globalThis.describe("Identity", () => {
         groups: identity_groups,
         provider: identity_provider
       };
-      let json = S.reverseConvertToJsonOrThrow(identity, Identity$Reventless.schema);
-      let decoded = S.parseJsonOrThrow(json, Identity$Reventless.schema);
+      let json = Util_Sury$Reventless.toJson(identity, Identity$Reventless.schema);
+      let decoded = Util_Sury$Reventless.fromJson(json, Identity$Reventless.schema);
       globalThis.expect(decoded).toEqual(identity);
     });
     globalThis.test("roundtrip without optional claims", () => {
@@ -114,8 +112,8 @@ globalThis.describe("Identity", () => {
         groups: identity_groups,
         provider: "InMemory"
       };
-      let json = S.reverseConvertToJsonOrThrow(identity, Identity$Reventless.schema);
-      let decoded = S.parseJsonOrThrow(json, Identity$Reventless.schema);
+      let json = Util_Sury$Reventless.toJson(identity, Identity$Reventless.schema);
+      let decoded = Util_Sury$Reventless.fromJson(json, Identity$Reventless.schema);
       globalThis.expect(decoded.userId).toBe("user-3");
       globalThis.expect(decoded.provider).toEqual("InMemory");
     });

package/tests/adapter/MonitoringTest.res

@@ -15,7 +15,7 @@ describe("Monitoring", () => {
   testSync("use registers a backend that receives every notify, role and name", () => {
     let recorded: array<(Monitoring.unitKind, string)> = []
     module Recorder: Monitoring.Backend = {
-      let onProvisioned = (~kind, ~name, ~component as _, ~plugin as _, ~platform as _) =>
+      let onProvisioned = (~kind, ~name, ~component as _, ~plugin as _, ~platform as _, ~logLocator as _) =>
         recorded->Array.push((kind, name))
     }
     Monitoring.use(module(Recorder: Monitoring.Backend))
@@ -39,7 +39,7 @@ describe("Monitoring", () => {
   testSync("notify forwards the static name and component resource to the backend", () => {
     let seen: ref<option<(string, ReventlessInfra.Adapter.resource)>> = ref(None)
     module Capture: Monitoring.Backend = {
-      let onProvisioned = (~kind as _, ~name, ~component, ~plugin as _, ~platform as _) =>
+      let onProvisioned = (~kind as _, ~name, ~component, ~plugin as _, ~platform as _, ~logLocator as _) =>
         seen := Some((name, component))
     }
     Monitoring.use(module(Capture: Monitoring.Backend))
@@ -56,7 +56,7 @@ describe("Monitoring", () => {
   testSync("notify delivers the ambient plugin/platform inside a construct scope, None outside", () => {
     let seen: array<(option<string>, option<string>)> = []
     module OwnerCapture: Monitoring.Backend = {
-      let onProvisioned = (~kind as _, ~name as _, ~component as _, ~plugin, ~platform) =>
+      let onProvisioned = (~kind as _, ~name as _, ~component as _, ~plugin, ~platform, ~logLocator as _) =>
         seen->Array.push((plugin, platform))
     }
     Monitoring.use(module(OwnerCapture: Monitoring.Backend))
@@ -80,4 +80,31 @@ describe("Monitoring", () => {
 
     Monitoring.use(module(Monitoring.Noop))
   })
+
+  // Unlike the owner, the locator is not ambient — the seam only forwards what the provisioning
+  // site passed. A site with nothing to say omits it, and the backend must see that as "this unit
+  // has no logs of its own" rather than receiving a fabricated address.
+  testSync("notify forwards the log locator when given one, None when omitted", () => {
+    // The registry only forwards the locator; it never resolves it. A structural stand-in keeps
+    // @pulumi/pulumi out of the Jest run, exactly as `stubResource` does.
+    let stubLocator: Pulumi.Output.t<string> = %raw(`{}`)
+    let seen: array<bool> = []
+    module LocatorCapture: Monitoring.Backend = {
+      let onProvisioned = (~kind as _, ~name as _, ~component as _, ~plugin as _, ~platform as _, ~logLocator) =>
+        seen->Array.push(logLocator->Option.isSome)
+    }
+    Monitoring.use(module(LocatorCapture: Monitoring.Backend))
+
+    Monitoring.notify(
+      ~kind=CommandHandler,
+      ~name="AllAggregatesCmdHandler",
+      ~component=stubResource,
+      ~logLocator=stubLocator,
+    )
+    Monitoring.notify(~kind=DeadLetterSink, ~name="DeadLetterQueue", ~component=stubResource)
+
+    expect(seen)->toEqual([true, false])
+
+    Monitoring.use(module(Monitoring.Noop))
+  })
 })

package/tests/adapter/MonitoringTest.res.mjs

@@ -1,5 +1,6 @@
 // Generated by ReScript, PLEASE EDIT WITH CARE
 
+import * as Stdlib_Option from "@rescript/runtime/lib/es6/Stdlib_Option.js";
 import * as Monitoring$ReventlessCore from "../../src/adapter/Monitoring/Monitoring.res.mjs";
 import * as ResourceAttribution$ReventlessCore from "../../src/ResourceAttribution.res.mjs";
 
@@ -7,12 +8,12 @@ let stubResource = {};
 
 globalThis.describe("Monitoring", () => {
   globalThis.test("Noop default: notify is silent and does not throw", () => {
-    Monitoring$ReventlessCore.notify("CommandHandler", "before", stubResource);
+    Monitoring$ReventlessCore.notify("CommandHandler", "before", stubResource, undefined);
     globalThis.expect(true).toBe(true);
   });
   globalThis.test("use registers a backend that receives every notify, role and name", () => {
     let recorded = [];
-    let onProvisioned = (kind, name, param, param$1, param$2) => {
+    let onProvisioned = (kind, name, param, param$1, param$2, param$3) => {
       recorded.push([
         kind,
         name
@@ -22,13 +23,13 @@ globalThis.describe("Monitoring", () => {
       onProvisioned: onProvisioned
     };
     Monitoring$ReventlessCore.use(Recorder);
-    Monitoring$ReventlessCore.notify("CommandHandler", "AllAggregatesCmdHandler", stubResource);
-    Monitoring$ReventlessCore.notify("Projection", "AllStateViewSlices", stubResource);
-    Monitoring$ReventlessCore.notify("DeadLetterSink", "DeadLetterQueue", stubResource);
+    Monitoring$ReventlessCore.notify("CommandHandler", "AllAggregatesCmdHandler", stubResource, undefined);
+    Monitoring$ReventlessCore.notify("Projection", "AllStateViewSlices", stubResource, undefined);
+    Monitoring$ReventlessCore.notify("DeadLetterSink", "DeadLetterQueue", stubResource, undefined);
     Monitoring$ReventlessCore.notify({
       TAG: "Other",
       _0: "Counter"
-    }, "ProductCounter", stubResource);
+    }, "ProductCounter", stubResource, undefined);
     globalThis.expect(recorded).toEqual([
       [
         "CommandHandler",
@@ -56,7 +57,7 @@ globalThis.describe("Monitoring", () => {
     let seen = {
       contents: undefined
     };
-    let onProvisioned = (param, name, component, param$1, param$2) => {
+    let onProvisioned = (param, name, component, param$1, param$2, param$3) => {
       seen.contents = [
         name,
         component
@@ -66,7 +67,7 @@ globalThis.describe("Monitoring", () => {
       onProvisioned: onProvisioned
     };
     Monitoring$ReventlessCore.use(Capture);
-    Monitoring$ReventlessCore.notify("Scheduler", "HeartbeatUnit", stubResource);
+    Monitoring$ReventlessCore.notify("Scheduler", "HeartbeatUnit", stubResource, undefined);
     let match = seen.contents;
     if (match !== undefined) {
       globalThis.expect(match[0]).toBe("HeartbeatUnit");
@@ -77,7 +78,7 @@ globalThis.describe("Monitoring", () => {
   });
   globalThis.test("notify delivers the ambient plugin/platform inside a construct scope, None outside", () => {
     let seen = [];
-    let onProvisioned = (param, param$1, param$2, plugin, platform) => {
+    let onProvisioned = (param, param$1, param$2, plugin, platform, param$3) => {
       seen.push([
         plugin,
         platform
@@ -87,11 +88,11 @@ globalThis.describe("Monitoring", () => {
       onProvisioned: onProvisioned
     };
     Monitoring$ReventlessCore.use(OwnerCapture);
-    Monitoring$ReventlessCore.notify("CommandHandler", "ApiRouter", stubResource);
+    Monitoring$ReventlessCore.notify("CommandHandler", "ApiRouter", stubResource, undefined);
     let prev = ResourceAttribution$ReventlessCore.enter("online-shop", "Ordering");
-    Monitoring$ReventlessCore.notify("CommandHandler", "AllAggregatesCmdHandler", stubResource);
+    Monitoring$ReventlessCore.notify("CommandHandler", "AllAggregatesCmdHandler", stubResource, undefined);
     ResourceAttribution$ReventlessCore.restore(prev);
-    Monitoring$ReventlessCore.notify("Projection", "AllStateViewSlices", stubResource);
+    Monitoring$ReventlessCore.notify("Projection", "AllStateViewSlices", stubResource, undefined);
     globalThis.expect(seen).toEqual([
       [
         undefined,
@@ -108,6 +109,24 @@ globalThis.describe("Monitoring", () => {
     ]);
     Monitoring$ReventlessCore.use(Monitoring$ReventlessCore.Noop);
   });
+  globalThis.test("notify forwards the log locator when given one, None when omitted", () => {
+    let stubLocator = {};
+    let seen = [];
+    let onProvisioned = (param, param$1, param$2, param$3, param$4, logLocator) => {
+      seen.push(Stdlib_Option.isSome(logLocator));
+    };
+    let LocatorCapture = {
+      onProvisioned: onProvisioned
+    };
+    Monitoring$ReventlessCore.use(LocatorCapture);
+    Monitoring$ReventlessCore.notify("CommandHandler", "AllAggregatesCmdHandler", stubResource, stubLocator);
+    Monitoring$ReventlessCore.notify("DeadLetterSink", "DeadLetterQueue", stubResource, undefined);
+    globalThis.expect(seen).toEqual([
+      true,
+      false
+    ]);
+    Monitoring$ReventlessCore.use(Monitoring$ReventlessCore.Noop);
+  });
 });
 
 export {

package/tests/adapter/RuntimeExtensionHookReachTest.res

@@ -1,6 +1,5 @@
 open JestGlobals
 
-S.enableJson()
 
 // The point of the seam, end to end at the hook level: an extension that only
 // ever gets `onColdStart` can reach the framework's runtime callback hooks from

package/tests/adapter/RuntimeExtensionHookReachTest.res.mjs

@@ -1,6 +1,6 @@
 // Generated by ReScript, PLEASE EDIT WITH CARE
 
-import * as S from "sury/src/S.res.mjs";
+import * as Sury from "sury";
 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 Effect from "effect/Effect";
@@ -8,12 +8,10 @@ import * as Primitive_exceptions from "@rescript/runtime/lib/es6/Primitive_excep
 import * as RuntimeExtension$ReventlessCore from "../../src/adapter/RuntimeExtension/RuntimeExtension.res.mjs";
 import * as CommandGenerator_Callback$ReventlessCore from "../../src/components/CommandGenerator/CommandGenerator_Callback.res.mjs";
 
-S.enableJson();
-
-let commandSchema = S.schema(s => ({
+let commandSchema = Sury.$schema(s => ({
   TAG: "Add",
-  productId: s.m(S.string),
-  name: s.m(S.string)
+  productId: s.m(Sury.string),
+  name: s.m(Sury.string)
 }));
 
 let published = {
@@ -94,4 +92,4 @@ export {
   addChair,
   runAdd,
 }
-/*  Not a pure module */
+/* commandSchema Not a pure module */

package/tests/admin/Platform_Admin_StructureTest.res

@@ -15,6 +15,17 @@
 open JestGlobals
 open Reventless.Plugin
 
+// The commands are derived from `PluginSpec.command` rather than hand-written, so
+// a test names one by looking it up. Raises rather than defaulting: a missing
+// variant is the failure these tests exist to catch, and a placeholder would let
+// the assertions below pass against nothing.
+let commandNamed = (name: string): commandDef =>
+  Platform_Admin_Structure.pluginCommands
+  ->Array.find(c => c.name == name)
+  ->Option.getOrThrow(~message=`Platform_Admin_Structure publishes no "${name}" command`)
+
+let activate = () => commandNamed("Activate")
+
 describe("the Plugins read model declares its lifecycle", () => {
   let rm: queryableDef = Platform_Admin_Structure.pluginReadModel
 
@@ -47,3 +58,246 @@ describe("the Plugins read model declares its lifecycle", () => {
     )->toEqual(false)
   )
 })
+
+// `Plugin_Structure.make` never sees the platform's own components, so the checks it
+// runs over every ordinary plugin do not run here. A test rather than a startup call:
+// both sides are compile-time constants in this package, so nothing varies at runtime.
+describe("the admin structure's declared transitions are checked", () => {
+  let states = Plugin_Structure.lifecycleStatesFromStateSchema(
+    ~entityName=PluginsReadModelSpec.name,
+    PluginsReadModelSpec.stateSchema->S.castToUnknown,
+  )
+
+  let statesByView = () => {
+    let d = Dict.make()
+    states->Option.forEach(s => d->Dict.set(PluginsReadModelSpec.name, s))
+    d
+  }
+
+  let raises = writables =>
+    switch Plugin_Structure.checkDeclaredTransitions(
+      ~pluginName="Platform",
+      ~writables,
+      ~lifecycleStatesByView=statesByView(),
+    ) {
+    | () => false
+    | exception _ => true
+    }
+
+  // The precondition the rest of the block is worthless without: with no states the
+  // check counts the commands as unvalidated and passes.
+  testSync("the linked view yields its lifecycle states", () =>
+    expect(states)->toEqual(Some(["Connected", "Disconnected", "Inactive", "Retired"]))
+  )
+
+  testSync("every state the Plugin commands name is one the view declares", () =>
+    expect(raises([Platform_Admin_Structure.pluginAggregate]))->toEqual(false)
+  )
+
+  // A check that cannot fail is indistinguishable from one that is not running.
+  testSync("and a state the view does not declare is caught", () => {
+    let bogus: Reventless.Plugin.writableDef = {
+      ...Platform_Admin_Structure.pluginAggregate,
+      commands: [
+        {
+          ...activate(),
+          targetState: Some("Conected"),
+        },
+      ],
+    }
+    expect(raises([bogus]))->toEqual(true)
+  })
+})
+
+// The drift that made deriving these defs worth doing rather than tidy. The
+// hand-written arg schema described only `id`, while the SDL generated off the
+// same `commandSchema` declares `Platform_Plugin_Activate(_0: String!, id: ID!)`.
+// AutoUI builds its mutation document from the published schema, so it sent a
+// document missing a required argument and every admin row action was rejected at
+// GraphQL validation, before the aggregate saw it.
+describe("the Plugin command defs carry every argument the SDL requires", () => {
+  testSync("the version argument is published", () =>
+    expect(activate().schema->String.includes(`"_0"`))->toEqual(true)
+  )
+
+  testSync("and so is the aggregate id", () => {
+    // `id` is not in the command schema — it is the aggregate instance, injected
+    // by the auto-resolver flow. What the def has to get right is naming it, so
+    // the consumer declares the variable rather than guessing.
+    expect(activate().aggregateIdField)->toEqual(None)
+  })
+
+  testSync("the exposed commands name the field PluginBaseFragment generates", () =>
+    expect(
+      Platform_Admin_Structure.pluginCommands
+      ->Array.filter(c => c.apiExposed != Some(false))
+      ->Array.map(c => c.mutationField),
+    )->toEqual([
+      "Platform_Plugin_Activate",
+      "Platform_Plugin_Deactivate",
+      "Platform_Plugin_Retire",
+    ])
+  )
+
+  // The `@noApi` protocol variants come back from the same walk. They belong on
+  // the event graph — `Disconnect` is the only edge into `Disconnected` — but
+  // `Connect` carries a whole plugin definition, so publishing metadata about
+  // them must not publish a way to call them.
+  testSync("the internal commands are published as uncallable", () => {
+    let internal =
+      Platform_Admin_Structure.pluginCommands->Array.filter(c => c.apiExposed == Some(false))
+    expect(internal->Array.map(c => c.name))->toEqual([
+      "Connect",
+      "ReportIncompatibility",
+      "Heartbeat",
+      "Redetect",
+      "Disconnect",
+    ])
+    expect(internal->Array.every(c => c.mutationField == ""))->toEqual(true)
+  })
+})
+
+// A heartbeat timing out is the only way a row reaches `Disconnected`, and the
+// command that does it carries `@noApi`. Until it declared its edge the topology
+// check reported the state unreachable and was right to: nothing in the
+// declarations said how a row got there.
+describe("the internal commands declare the edges they move rows along", () => {
+  let states = Plugin_Structure.lifecycleStatesFromStateSchema(
+    ~entityName=PluginsReadModelSpec.name,
+    PluginsReadModelSpec.stateSchema->S.castToUnknown,
+  )
+
+  let statesByView = () => {
+    let d = Dict.make()
+    states->Option.forEach(s => d->Dict.set(PluginsReadModelSpec.name, s))
+    d
+  }
+
+  testSync("the only edge into Disconnected is declared", () =>
+    expect((commandNamed("Disconnect").allowedStates, commandNamed("Disconnect").targetState))
+    ->toEqual((Some(["Connected"]), Some("Disconnected")))
+  )
+
+  // The creating form's claim: a target and no from-set. `Connect` brings the
+  // version's row into being, so there is no state it runs from — and an empty
+  // `allowedStates` would say the opposite, that it is legal in none.
+  testSync("the handshake declares a target and no from-set", () =>
+    expect((commandNamed("Connect").allowedStates, commandNamed("Connect").targetState))
+    ->toEqual((None, Some("Connected")))
+  )
+
+  testSync("and no state is left unreachable", () =>
+    expect(
+      Plugin_Structure.lifecycleTopologyFindings(
+        ~writables=[Platform_Admin_Structure.pluginAggregate],
+        ~lifecycleStatesByView=statesByView(),
+      ),
+    )->toEqual([])
+  )
+})
+
+// One rule, read on both sides of the wire. `PluginBaseFragment` hand-wrote an
+// `Admin` Cognito gate while the spec defaulted to `AllowAuthenticated`, and the
+// published `requiredAccess` said `None` — so a shell was told the Plugins view
+// was open to everyone and the server refused anyone outside `Admin`. The
+// mismatch is invisible until a non-admin clicks the page.
+describe("the Plugins view publishes the rule the server enforces", () => {
+  testSync("the spec declares the group", () =>
+    expect(PluginsReadModelSpec.authorization)->toEqual(
+      Reventless.Authorization.AllowGroups(["Admin"]),
+    )
+  )
+
+  testSync("and the published access keys are derived from it", () =>
+    expect(Platform_Admin_Structure.pluginReadModel.requiredAccess)->toEqual(Some(["Admin"]))
+  )
+
+  // The API entry reads the same binding rather than restating it, so the two
+  // cannot be edited apart.
+  testSync("the query entry carries the spec's rule and no hand-written pair", () => {
+    let entry = PluginBaseFragment.queryEntries->Array.getUnsafe(0)
+    expect((entry.permission, entry.authorization))->toEqual((
+      Some(PluginsReadModelSpec.authorization),
+      None,
+    ))
+  })
+})
+
+// The `queryableDef` is derived from the spec, not hand-written. The analysis
+// that preceded this expected the admin's naming to be bespoke and it is not:
+// `Api_Naming.queryFieldNamesForReadModel` returns byte-identical names, because
+// `singularize` already handles the plural-spec-name / singular-type shape that
+// looked special. Asserted rather than assumed — the whole case for deriving
+// rests on the generic helpers reaching the same answers.
+describe("the Plugins queryableDef is what the generic helpers produce", () => {
+  let rm: queryableDef = Platform_Admin_Structure.pluginReadModel
+
+  testSync("the field names are the generic ones", () =>
+    expect((rm.queryField, rm.singleQueryField))->toEqual((
+      "Platform_Plugins",
+      Some("Platform_Plugin"),
+    ))
+  )
+
+  testSync("the label ladder reaches the same field, by convention", () =>
+    expect((rm.labelField, rm.labelFieldSource, rm.searchableFields))->toEqual((
+      "name",
+      Some("convention"),
+      ["name"],
+    ))
+  )
+
+  // The row id is `name@version` and the state carries the two halves
+  // separately, never the composed key — so `None` is the honest answer, and it
+  // is the one the resolver ladder reaches on its own.
+  testSync("the key ladder finds no id field, as the hand-written def claimed", () =>
+    expect((rm.idField, rm.idFieldSource))->toEqual((None, None))
+  )
+
+  // `apiSchemaFragment` and `structure` are on the API — the shell fetches them
+  // through dedicated resolver paths — but each is a multi-kilobyte JSON blob
+  // that a generated list view must not name. They used to be cut out of the
+  // published schema by a hand-written list; they now carry `@hidden`, so they
+  // are described and the consumer decides.
+  //
+  // This is the difference between the two markers, asserted side by side: a
+  // `@hidden` field is present and flagged, an `@internal` one is not there at
+  // all. Cutting a hidden field out here would leave a consumer unable to tell
+  // "not for you" from "does not exist".
+  testSync("the blob fields are published, and marked hidden", () => {
+    // Read as property NAMES, not as substrings of the JSON: the schema carries
+    // nested object types whose own fields would match a naive `includes`.
+    let props =
+      rm.schema
+      ->JSON.parseExn
+      ->JSON.Decode.object
+      ->Option.flatMap(o => o->Dict.get("properties"))
+      ->Option.flatMap(JSON.Decode.object)
+      ->Option.getOr(Dict.make())
+    let isHidden = key =>
+      props
+      ->Dict.get(key)
+      ->Option.flatMap(JSON.Decode.object)
+      ->Option.flatMap(o => o->Dict.get("x-reventless-hidden"))
+      ->Option.flatMap(JSON.Decode.bool)
+    expect((isHidden("apiSchemaFragment"), isHidden("structure")))->toEqual((
+      Some(true),
+      Some(true),
+    ))
+  })
+
+  testSync("while the internal fields are not published at all", () => {
+    let props =
+      rm.schema
+      ->JSON.parseExn
+      ->JSON.Decode.object
+      ->Option.flatMap(o => o->Dict.get("properties"))
+      ->Option.flatMap(JSON.Decode.object)
+      ->Option.mapOr([], Dict.keysToArray)
+    expect((
+      props->Array.includes("eventCollector"),
+      props->Array.includes("extensionNames"),
+      props->Array.includes("statusChange"),
+    ))->toEqual((false, false, true))
+  })
+})