@reventlessdev/reventless-spec 3.0.0-alpha.134 → 3.0.0-alpha.136

package/src/lifecycle/CheckLifecycleModel.res

@@ -550,6 +550,18 @@ type derivedCommand = {
       accepted and silent. Kept separately because it is what turns a declared
       state the corpus disagrees with into a contradiction rather than a gap. */
   inertStates: array<string>,
+  /** The strict subset of [inertStates] where the command was *refused* — an
+      error, not an accepted no-op.
+
+      Separate because the two refute different claims. A named from-set says the
+      command **takes effect** from those states, so anything inert there
+      contradicts it. `Unrestricted` says only that the command is **never
+      refused**, which an accepted `Ok([])` agrees with rather than contradicts —
+      returning no events for a command that would change nothing is this
+      codebase's idempotency convention, not evidence the state was illegal.
+      Reading one field for both questions made every idempotent
+      legal-in-every-state command look like a contradiction. */
+  refusedStates: array<string>,
   /** Where the edges land. A relation, not a single value: a command observed
       landing in two states is the signal that the published `targetState` cannot
       carry the model, and that is worth seeing before spending the change. */
@@ -651,6 +663,9 @@ let deriveCommands = (
       inertStates: sortedUnique(
         mine->Array.filterMap(o => o.outcome == Emitted || o.from == noRow ? None : Some(o.from)),
       ),
+      refusedStates: sortedUnique(
+        mine->Array.filterMap(o => o.outcome == Refused && o.from != noRow ? Some(o.from) : None),
+      ),
       targets: sortedUnique(
         effective->Array.filterMap(o => o.to == o.from || o.to == noRow ? None : Some(o.to)),
       ),
@@ -666,6 +681,90 @@ let deriveCommands = (
   })
 }
 
+// ── What each command yields ────────────────────────────────────────────────
+
+/** Which command yields which event or error, as its scenarios show it — what a
+    consumer draws a command's outcome arrows from, read off the corpus rather
+    than guessed from names. It needs no lifecycle labelling, so every corpus a
+    plugin has is read, though only its command scenarios count.
+
+    An empty `then` is skipped rather than read as "accepted, nothing happened".
+    The PPX currently writes `then: []` for `thenNoEvent`, so an empty `then` is
+    indistinguishable from one the sidecar could not read, and an outcome shown
+    here has to be one a scenario actually states. */
+type shownOutcome = {
+  kind: string, // "event" | "error" | "noEvent"
+  /** The whole `then`, in order: `thenEvents([A, B])` is one outcome of two
+      events — both, not either. Empty for `noEvent`. */
+  names: array<string>,
+  /** The title of every scenario showing this outcome, in corpus order. */
+  scenarios: array<string>,
+}
+
+type commandOutcomes = {
+  plugin: string,
+  component: string,
+  command: string,
+  /** One per distinct outcome, in order of first appearance. */
+  outcomes: array<shownOutcome>,
+}
+
+let shownOutcomeOf = (s: scenario): option<(string, array<string>)> =>
+  switch s.thenKind {
+  | "event" | "error" => Some((s.thenKind, s.thenElements->Array.map(e => e.name)))
+  | "noEvent" => Some(("noEvent", []))
+  // The empty `then` above, and a `then` that is not about this command's
+  // result — a side effect, a published command.
+  | _ => None
+  }
+
+let byPluginComponentCommand = (xs: array<commandOutcomes>): array<commandOutcomes> =>
+  xs->Array.toSorted((a, b) =>
+    switch String.compare(a.plugin, b.plugin) {
+    | 0. =>
+      switch String.compare(a.component, b.component) {
+      | 0. => String.compare(a.command, b.command)
+      | c => c
+      }
+    | c => c
+    }
+  )
+
+/** A command with no readable outcome is left out: an entry must say something. */
+let commandOutcomes = (~plugin: string, ~corpora: array<corpus>): array<commandOutcomes> => {
+  let entries: array<commandOutcomes> = []
+  corpora->Array.forEach(c =>
+    c.scenarios->Array.forEach(s =>
+      switch (s.whenKind, s.whenElements->Array.get(0), shownOutcomeOf(s)) {
+      | ("command", Some(command), Some((kind, names))) =>
+        let entry = switch entries->Array.find(
+          e => e.component == c.component && e.command == command.name,
+        ) {
+        | Some(e) => e
+        | None =>
+          let e: commandOutcomes = {
+            plugin,
+            component: c.component,
+            command: command.name,
+            outcomes: [],
+          }
+          entries->Array.push(e)
+          e
+        }
+        switch entry.outcomes->Array.find(o => o.kind == kind && o.names == names) {
+        | Some(o) =>
+          if !(o.scenarios->Array.includes(s.title)) {
+            o.scenarios->Array.push(s.title)
+          }
+        | None => entry.outcomes->Array.push({kind, names, scenarios: [s.title]})
+        }
+      | _ => ()
+      }
+    )
+  )
+  entries->byPluginComponentCommand
+}
+
 // ── The three verdicts ──────────────────────────────────────────────────────
 
 type finding = {
@@ -757,14 +856,24 @@ let compare = (
     // effect somewhere agrees with that rather than narrowing it — the corpus
     // covers the states somebody wrote a scenario for, and silence about the
     // rest is not refusal. What DOES refute the claim is a state the command was
-    // exercised in and did nothing: that is the switch and the behaviour
+    // exercised in and **refused**: that is the switch and the behaviour
     // disagreeing about the same row.
+    //
+    // 🚨 **Refused, not merely inert.** `Unrestricted` claims the command is
+    // never refused — it does not claim the command always emits. A state where a
+    // scenario shows it accepted and silent AGREES with that: returning `Ok([])`
+    // for a command that would change nothing is this codebase's idempotency
+    // convention, required because commands arrive at least once. Reading
+    // `inertStates` here marked every such command contradicted, which is the
+    // opposite of what the corpus showed — a verdict redelivered, or landing
+    // after deactivation, is precisely the case the switch declared legal so that
+    // the reporting slice would not retry forever.
     | None if cmd.allowedStatesSource == Some("unrestricted") =>
-      derived.inertStates->Array.forEach(state =>
+      derived.refusedStates->Array.forEach(state =>
         add(
           "contradicted",
           [state],
-          `the switch declares it legal in every state, and a scenario from "${state}" ` ++ `shows it refused or producing nothing`,
+          `the switch declares it legal in every state, and a scenario from "${state}" ` ++ `shows it refused`,
         )
       )
     | None =>
@@ -928,6 +1037,7 @@ let runPlugin = async (
   ~pluginDir: string,
   ~findings: array<finding>,
   ~opaque: array<opaque>,
+  ~outcomes: array<commandOutcomes>,
 ): result<array<derivedCommand>, string> =>
   switch await readDeclared(~pluginDir) {
   | Error(msg) => Error(msg)
@@ -937,6 +1047,8 @@ let runPlugin = async (
         readCorpus,
       )
 
+    outcomes->Array.pushMany(commandOutcomes(~plugin, ~corpora))
+
     // Every corpus, not only the ones the walk goes on to use: the kinds that
     // are unreadable in full — extension points, automation and translation
     // slices — are exactly the ones that sit outside the view/writable folders
@@ -1106,13 +1218,16 @@ let goldenPath = (~root: appRoot) => NodePath.join([root.dir, "schema", "lifecyc
       ever exercised, which is a sharper "missing scenario" than a verdict.
     - `opaque` — the corpora the walk cannot read, so a consumer can say "not
       analysed" where it would otherwise say "not covered".
+    - `outcomes` — which command yields which event or error, and the scenarios
+      that show it, sorted by plugin, component and command.
 
-    `str` is the schema's own version, bumped when a consumer would have to
-    change. */
+    `version` is the schema's own version, bumped when a consumer would have to
+    change. An added section is not such a change. */
 let reportJson = (
   ~findings: array<finding>,
   ~opaque: array<opaque>,
   ~derived: array<(string, derivedCommand)>,
+  ~outcomes: array<commandOutcomes>,
   ~failures: array<string>,
 ): string => {
   let strs = xs => JSON.Encode.array(xs->Array.map(JSON.Encode.string))
@@ -1149,11 +1264,30 @@ let reportJson = (
       ("unreadable", JSON.Encode.int(o.unreadable)),
     ])
 
+  let shownOutcomeJson = (o: shownOutcome) =>
+    obj([
+      ("kind", JSON.Encode.string(o.kind)),
+      ("names", strs(o.names)),
+      ("scenarios", strs(o.scenarios)),
+    ])
+
+  let commandOutcomesJson = (e: commandOutcomes) =>
+    obj([
+      ("plugin", JSON.Encode.string(e.plugin)),
+      ("component", JSON.Encode.string(e.component)),
+      ("command", JSON.Encode.string(e.command)),
+      ("outcomes", JSON.Encode.array(e.outcomes->Array.map(shownOutcomeJson))),
+    ])
+
   JSON.stringify(
     obj([
       ("version", JSON.Encode.int(1)),
       ("findings", JSON.Encode.array(findings->Array.map(findingJson))),
       ("commands", JSON.Encode.array(derived->Array.map(commandJson))),
+      (
+        "outcomes",
+        JSON.Encode.array(outcomes->byPluginComponentCommand->Array.map(commandOutcomesJson)),
+      ),
       ("opaque", JSON.Encode.array(opaque->Array.map(opaqueJson))),
       ("unreadable", strs(failures)),
     ]),
@@ -1245,6 +1379,7 @@ let writeOrCompare = (~path: string, ~actual: string, ~label: string, ~drifted:
 let main = async () => {
   let findings = []
   let opaque = []
+  let outcomes = []
   let failures = []
   let drifted = []
   let allDerived = []
@@ -1302,7 +1437,7 @@ let main = async () => {
         | Some(pluginDir) =>
           let plugin = NodePath.basename(pluginDir)
           let qualified = `${example}/${plugin}`
-          switch await runPlugin(~plugin=qualified, ~pluginDir, ~findings, ~opaque) {
+          switch await runPlugin(~plugin=qualified, ~pluginDir, ~findings, ~opaque, ~outcomes) {
           | Ok(commands) =>
             commands->Array.forEach(c => {
               derived->Array.push(c)
@@ -1345,7 +1480,7 @@ let main = async () => {
   let contradicted = of_("contradicted")
 
   if json {
-    Console.log(reportJson(~findings, ~opaque, ~derived=allDerived, ~failures))
+    Console.log(reportJson(~findings, ~opaque, ~derived=allDerived, ~outcomes, ~failures))
   } else {
     ["contradicted", "unverified", "undeclared", "level", "ambiguous"]->Array.forEach(severity => {
       let group = of_(severity)
@@ -1378,4 +1513,9 @@ let main = async () => {
   }
 }
 
-let _ = main()
+// 🚨 **No top-level call.** `../../run-check-lifecycle.mjs` invokes [main]; this
+// module only defines it. While the call was here, importing the module *ran the
+// whole check* and then called `NodeProcess.exit`, so nothing in this file could
+// be reached from a test — including [deriveCommands] and [compare], which are
+// pure and are where every verdict is actually decided. That is the same trap
+// `ProvisionIdentity` records having shipped a never-matching guard through.

package/src/lifecycle/CheckLifecycleModel.res.mjs

@@ -469,6 +469,11 @@ function deriveCommands(component, observations, labelled) {
           return o.from;
         }
       })),
+      refusedStates: sortedUnique(Stdlib_Array.filterMap(mine, o => {
+        if (o.outcome === "Refused" && o.from !== noRow) {
+          return o.from;
+        }
+      })),
       targets: sortedUnique(Stdlib_Array.filterMap(effective, o => {
         if (o.to === o.from || o.to === noRow) {
           return;
@@ -484,6 +489,109 @@ function deriveCommands(component, observations, labelled) {
   });
 }
 
+function shownOutcomeOf(s) {
+  let match = s.thenKind;
+  switch (match) {
+    case "error" :
+    case "event" :
+      break;
+    case "noEvent" :
+      return [
+        "noEvent",
+        []
+      ];
+    default:
+      return;
+  }
+  return [
+    s.thenKind,
+    s.thenElements.map(e => e.name)
+  ];
+}
+
+function byPluginComponentCommand(xs) {
+  return xs.toSorted((a, b) => {
+    let c = Primitive_string.compare(a.plugin, b.plugin);
+    if (c !== 0) {
+      return c;
+    }
+    let c$1 = Primitive_string.compare(a.component, b.component);
+    if (c$1 !== 0) {
+      return c$1;
+    } else {
+      return Primitive_string.compare(a.command, b.command);
+    }
+  });
+}
+
+function commandOutcomes(plugin, corpora) {
+  let entries = [];
+  corpora.forEach(c => {
+    c.scenarios.forEach(s => {
+      let match = s.whenKind;
+      let match$1 = s.whenElements[0];
+      let match$2 = shownOutcomeOf(s);
+      if (match !== "command") {
+        return;
+      }
+      if (match$1 === undefined) {
+        return;
+      }
+      if (match$2 === undefined) {
+        return;
+      }
+      let names = match$2[1];
+      let kind = match$2[0];
+      let e = entries.find(e => {
+        if (e.component === c.component) {
+          return e.command === match$1.name;
+        } else {
+          return false;
+        }
+      });
+      let entry;
+      if (e !== undefined) {
+        entry = e;
+      } else {
+        let e_component = c.component;
+        let e_command = match$1.name;
+        let e_outcomes = [];
+        let e$1 = {
+          plugin: plugin,
+          component: e_component,
+          command: e_command,
+          outcomes: e_outcomes
+        };
+        entries.push(e$1);
+        entry = e$1;
+      }
+      let o = entry.outcomes.find(o => {
+        if (o.kind === kind) {
+          return Primitive_object.equal(o.names, names);
+        } else {
+          return false;
+        }
+      });
+      if (o !== undefined) {
+        if (!o.scenarios.includes(s.title)) {
+          o.scenarios.push(s.title);
+          return;
+        } else {
+          return;
+        }
+      } else {
+        entry.outcomes.push({
+          kind: kind,
+          names: names,
+          scenarios: [s.title]
+        });
+        return;
+      }
+    });
+  });
+  return byPluginComponentCommand(entries);
+}
+
 function allUnverified(cmd, add, why) {
   let states = cmd.allowedStates;
   if (states !== undefined && states.length !== 0) {
@@ -531,7 +639,7 @@ function compare(plugin, writable, derived, findings) {
       add("unverified", states, `the switch declares ` + states.length.toString() + ` state(s) and no scenario shows the command taking effect anywhere`);
     }
   } else if (Primitive_object.equal(declared.allowedStatesSource, "unrestricted")) {
-    derived.inertStates.forEach(state => add("contradicted", [state], `the switch declares it legal in every state, and a scenario from "` + state + `" shows it refused or producing nothing`));
+    derived.refusedStates.forEach(state => add("contradicted", [state], `the switch declares it legal in every state, and a scenario from "` + state + `" shows it refused`));
   } else if (derived.allowedStates.length !== 0) {
     add("undeclared", derived.allowedStates, `scenarios show it taking effect from ` + derived.allowedStates.join(", ") + `, and it declares no edge`);
   }
@@ -654,7 +762,7 @@ function isWritablePath(path) {
   }
 }
 
-async function runPlugin(plugin, pluginDir, findings, opaque) {
+async function runPlugin(plugin, pluginDir, findings, opaque, outcomes) {
   let msg = await readDeclared(pluginDir);
   if (msg.TAG !== "Ok") {
     return {
@@ -664,6 +772,7 @@ async function runPlugin(plugin, pluginDir, findings, opaque) {
   }
   let declared = msg._0;
   let corpora = Stdlib_Array.filterMap(filesUnder(Nodepath.join(pluginDir, "tests"), ".gwt.json"), readCorpus);
+  outcomes.push(...commandOutcomes(plugin, corpora));
   corpora.forEach(c => {
     let unreadable = c.scenarios.filter(s => s.whenElements.length === 0);
     if (unreadable.length !== 0) {
@@ -800,7 +909,7 @@ function goldenPath(root) {
   return Nodepath.join(root.dir, "schema", "lifecycle-model.json");
 }
 
-function reportJson(findings, opaque, derived, failures) {
+function reportJson(findings, opaque, derived, outcomes, failures) {
   let findingJson = f => Object.fromEntries([
     [
       "verdict",
@@ -886,6 +995,38 @@ function reportJson(findings, opaque, derived, failures) {
       o.unreadable
     ]
   ]);
+  let shownOutcomeJson = o => Object.fromEntries([
+    [
+      "kind",
+      o.kind
+    ],
+    [
+      "names",
+      o.names.map(prim => prim)
+    ],
+    [
+      "scenarios",
+      o.scenarios.map(prim => prim)
+    ]
+  ]);
+  let commandOutcomesJson = e => Object.fromEntries([
+    [
+      "plugin",
+      e.plugin
+    ],
+    [
+      "component",
+      e.component
+    ],
+    [
+      "command",
+      e.command
+    ],
+    [
+      "outcomes",
+      e.outcomes.map(shownOutcomeJson)
+    ]
+  ]);
   return JSON.stringify(Object.fromEntries([
     [
       "version",
@@ -899,6 +1040,10 @@ function reportJson(findings, opaque, derived, failures) {
       "commands",
       derived.map(commandJson)
     ],
+    [
+      "outcomes",
+      byPluginComponentCommand(outcomes).map(commandOutcomesJson)
+    ],
     [
       "opaque",
       opaque.map(opaqueJson)
@@ -990,6 +1135,7 @@ function writeOrCompare(path, actual, label, drifted) {
 async function main() {
   let findings = [];
   let opaque = [];
+  let outcomes = [];
   let failures = [];
   let drifted = [];
   let allDerived = [];
@@ -1019,7 +1165,7 @@ async function main() {
         if (pluginDir !== undefined) {
           let plugin = Nodepath.basename(pluginDir);
           let qualified = example + `/` + plugin;
-          let commands = await runPlugin(qualified, pluginDir, findings, opaque);
+          let commands = await runPlugin(qualified, pluginDir, findings, opaque, outcomes);
           if (commands.TAG === "Ok") {
             let commands$1 = commands._0;
             commands$1.forEach(c => {
@@ -1052,7 +1198,7 @@ async function main() {
   let of_ = severity => findings.filter(f => f.severity === severity);
   let contradicted = of_("contradicted");
   if (json) {
-    console.log(reportJson(findings, opaque, allDerived, failures));
+    console.log(reportJson(findings, opaque, allDerived, outcomes, failures));
   } else {
     [
       "contradicted",
@@ -1086,8 +1232,6 @@ async function main() {
   }
 }
 
-main();
-
 export {
   repoRoot,
   examplesDir,
@@ -1128,6 +1272,9 @@ export {
   sameRow,
   observe,
   deriveCommands,
+  shownOutcomeOf,
+  byPluginComponentCommand,
+  commandOutcomes,
   allUnverified,
   compare,
   pluginDirsIn,

package/src/semantic/Capabilities.res

@@ -27,6 +27,15 @@ type t = {
   /** Send a message to a person, and say which channels this deployment can
       attempt at all. See `Messaging.provider`. */
   messaging: Messaging.provider,
+  /** Make, group and unmake principals, and say which of those this
+      deployment's provider can do at all. Administrative only — authenticating
+      one is `Auth_Adapter.Provider`'s. See `IdentityProvider.t`. */
+  identityProvider: IdentityProvider.t,
+  /** Unguessable material and a one-way function over it. Injected rather than
+      imported so a test can pin the secret a flow is about to use — a suite
+      cannot assert what a flow does with a value it cannot predict. See
+      `Secrets.t`. */
+  secrets: Secrets.t,
 }
 
 /**
@@ -54,4 +63,12 @@ let none: t = {
     ~recipient as _,
     ~message as _,
   ) => Error(Unavailable("no messaging provider is configured for this platform"))),
+  identityProvider: IdentityProvider.unavailable(
+    ~reason="no identity provider is configured for this platform",
+  ),
+  // Refusing rather than falling back to a weak source. Every runtime has a
+  // cryptographic one, so a platform reaching this arm has skipped wiring rather
+  // than declined to provision — and a guessable token would be accepted
+  // everywhere while looking exactly like a real one.
+  secrets: Secrets.unavailable(~reason="no secret source is configured for this platform"),
 }

package/src/semantic/Capabilities.res.mjs

@@ -1,6 +1,8 @@
 // Generated by ReScript, PLEASE EDIT WITH CARE
 
+import * as Secrets$Reventless from "./Secrets.res.mjs";
 import * as Messaging$Reventless from "./Messaging.res.mjs";
+import * as IdentityProvider$Reventless from "./IdentityProvider.res.mjs";
 
 async function none_geocode(param) {
   return {
@@ -20,9 +22,15 @@ let none_messaging = Messaging$Reventless.makeProvider([], [], async (param, par
   }
 }));
 
+let none_identityProvider = IdentityProvider$Reventless.unavailable("no identity provider is configured for this platform");
+
+let none_secrets = Secrets$Reventless.unavailable("no secret source is configured for this platform");
+
 let none = {
   geocode: none_geocode,
-  messaging: none_messaging
+  messaging: none_messaging,
+  identityProvider: none_identityProvider,
+  secrets: none_secrets
 };
 
 export {

package/src/semantic/CapabilityNeed.res

@@ -24,6 +24,16 @@ type t =
         declaration, because a plugin that named `Sms` would fail a deploy it
         could have run on email. */
   | Messaging
+  /** Making, grouping and unmaking principals, reached through
+        `Capabilities.identityProvider`. No payload, for the reason `Geocoding`
+        has none: one identity provider per deployment is a real answer, and a
+        deployment wanting a second pool is the `{alternatives, min}` question
+        `Messaging` already answers by publishing what it provisioned.
+
+        Not authentication. Token issuance and session handling are
+        `Auth_Adapter.Provider`'s, read at a different time — two seams over one
+        provider, the way this type and `Capabilities.t` are already two. */
+  | IdentityProvider
 
 /** The spelling carried in `pluginStructure` and in `capabilities.json`.
     Persisted structures hold strings, not enum members, so a plugin built
@@ -32,6 +42,7 @@ let toString = (need: t): string =>
   switch need {
   | Geocoding => "Geocoding"
   | Messaging => "Messaging"
+  | IdentityProvider => "IdentityProvider"
   }
 
 /** The inverse, for readers of a persisted structure or a committed manifest.
@@ -41,6 +52,7 @@ let fromString = (name: string): option<t> =>
   switch name {
   | "Geocoding" => Some(Geocoding)
   | "Messaging" => Some(Messaging)
+  | "IdentityProvider" => Some(IdentityProvider)
   | _ => None
   }
 

package/src/semantic/CapabilityNeed.res.mjs

@@ -3,10 +3,13 @@
 import * as Stdlib_Array from "@rescript/runtime/lib/es6/Stdlib_Array.js";
 
 function toString(need) {
-  if (need === "Geocoding") {
-    return "Geocoding";
-  } else {
-    return "Messaging";
+  switch (need) {
+    case "Geocoding" :
+      return "Geocoding";
+    case "Messaging" :
+      return "Messaging";
+    case "IdentityProvider" :
+      return "IdentityProvider";
   }
 }
 
@@ -14,6 +17,8 @@ function fromString(name) {
   switch (name) {
     case "Geocoding" :
       return "Geocoding";
+    case "IdentityProvider" :
+      return "IdentityProvider";
     case "Messaging" :
       return "Messaging";
     default: