@reventlessdev/reventless-spec 3.0.0-alpha.154 → 3.0.0-alpha.155

package/CHANGELOG.md

@@ -3,6 +3,14 @@
 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.155 (2026-10-01)
+
+### Features
+
+* **spec, aws, core, local:** an app declares its environments, and every deployment records its commit ([c7cc925](https://github.com/ReventlessDev/reventless-core/commit/c7cc92573e97742b681a9000cea0bdfd6e9a33fc))
+* **spec, core, gwt, ppx:** a command acts only on what its caller owns ([2636f0e](https://github.com/ReventlessDev/reventless-core/commit/2636f0ee44797ee2c0b0c40a7107cf306113173f))
+
+
 # 3.0.0-alpha.154 (2026-09-29)
 
 **Note:** Version bump only for package @reventlessdev/reventless-spec

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reventlessdev/reventless-spec",
-  "version": "3.0.0-alpha.154",
+  "version": "3.0.0-alpha.155",
   "description": "Specifications for Reventless",
   "license": "Apache-2.0",
   "bin": {

package/src/components/Owner.res

@@ -138,3 +138,33 @@ let variantFieldNames = (schema: S.t<unknown>, ~variant: string): array<string>
   | _ => []
   }
 }
+
+/**
+The owner fields of every constructor that declares one, keyed by its tag.
+
+Read off a slice's consumed events, this says which recorded facts name the
+owner of the partition a command acts on. An empty dict means the union records
+no owner, and the handler then has nothing to enforce — so, as with every reader
+here, it must be handed the real schema: a permissive stand-in answers empty.
+*/
+let fieldNamesByVariant = (schema: S.t<unknown>): dict<array<string>> => {
+  let byVariant = Dict.make()
+  let visit = (properties: dict<S.t<unknown>>) =>
+    switch (properties->Dict.get("TAG"), fieldNamesOfProperties(properties)) {
+    | (_, []) => ()
+    | (Some(String({const: ?Some(name)})), fields) => byVariant->Dict.set(name, fields)
+    | _ => ()
+    }
+  switch schema {
+  | AnyOf({anyOf}) =>
+    anyOf->Array.forEach(v =>
+      switch v {
+      | Object({properties}) => visit(properties)
+      | _ => ()
+      }
+    )
+  | Object({properties}) => visit(properties)
+  | _ => ()
+  }
+  byVariant
+}

package/src/components/Owner.res.mjs

@@ -90,6 +90,41 @@ function variantFieldNames(schema, variant) {
   }
 }
 
+function fieldNamesByVariant(schema) {
+  let byVariant = {};
+  let visit = properties => {
+    let match = properties["TAG"];
+    let match$1 = fieldNamesOfProperties(properties);
+    if (match$1.length === 0) {
+      return;
+    }
+    if (match === undefined) {
+      return;
+    }
+    if (match.type !== "string") {
+      return;
+    }
+    let name = match.const;
+    if (name !== undefined) {
+      byVariant[name] = match$1;
+      return;
+    }
+  };
+  switch (schema.type) {
+    case "object" :
+      visit(schema.properties);
+      break;
+    case "anyOf" :
+      schema.anyOf.forEach(v => {
+        if (v.type === "object") {
+          return visit(v.properties);
+        }
+      });
+      break;
+  }
+  return byVariant;
+}
+
 export {
   ownerId,
   mark,
@@ -100,5 +135,6 @@ export {
   fieldNamesOfProperties,
   fieldNames,
   variantFieldNames,
+  fieldNamesByVariant,
 }
 /* ownerId Not a pure module */

package/src/lifecycle/CheckLifecycleModel.res

@@ -687,6 +687,9 @@ let observe = (
 
   scenarios->Array.filterMap(s =>
     switch s.whenElements->Array.get(0) {
+    // `thenRefused`: the caller did not own the row, which says nothing about
+    // the states the command is legal in.
+    | Some(_) if s.thenKind == "forbidden" => None
     | Some(command) if s.whenKind == "command" =>
       let idField = idFieldFor(command.name)
       let idValue = idField->Option.flatMap(field => command.values->valueOf(~field))

package/src/lifecycle/CheckLifecycleModel.res.mjs

@@ -503,6 +503,9 @@ function observe(scenarios, map, idFieldFor) {
     if (command === undefined) {
       return;
     }
+    if (s.thenKind === "forbidden") {
+      return;
+    }
     if (s.whenKind !== "command") {
       return;
     }

package/src/types/DeploymentProvenance.res

@@ -0,0 +1,84 @@
+/***
+Where a deployment came from: the commit it was built from, whether the tree had
+uncommitted changes, and the environment it was made for.
+
+Read by the deploy while it runs, and recorded with the deployment, so a reader
+can say which commit runs in which environment without asking whoever deployed.
+A deployment from CI knows its commit from the CI's variables; one from a laptop
+asks git. Neither gives up a timestamp in place of a commit: a timestamp is not
+an answer to *which commit*, and a reader cannot tell it from one.
+*/
+
+type t = {
+  commit: option<string>,
+  /** True only when the commit came from git and the working tree had changes:
+    what was deployed is not what the commit says. */
+  dirty: bool,
+  environment: option<string>,
+  purpose: option<string>,
+  tag: option<string>,
+  pullRequest: option<int>,
+}
+
+/** What git can say about the checkout the deploy runs in. */
+type git = {
+  head: unit => option<string>,
+  dirty: unit => bool,
+}
+
+let nonEmpty = (value: option<string>): option<string> =>
+  value->Option.flatMap(v => v->String.trim == "" ? None : Some(v->String.trim))
+
+/**
+The provenance of a deployment from the process's variables, asking git only when
+no CI variable names the commit.
+
+`REVENTLESS_COMMIT` comes first because on a pull request `GITHUB_SHA` is the merge
+commit GitHub made, not the head the review environment runs.
+*/
+let fromEnv = (env: dict<string>, ~git: git): t => {
+  let get = name => env->Dict.get(name)->nonEmpty
+  let fromCi =
+    get("REVENTLESS_COMMIT")
+    ->Option.orElse(get("GITHUB_SHA"))
+    ->Option.orElse(get("CI_COMMIT_SHA"))
+  let (commit, dirty) = switch fromCi {
+  | Some(_) => (fromCi, false)
+  | None =>
+    switch git.head() {
+    | Some(_) as head => (head, git.dirty())
+    | None => (None, false)
+    }
+  }
+  {
+    commit,
+    dirty,
+    environment: get("REVENTLESS_ENVIRONMENT"),
+    purpose: get("REVENTLESS_ENVIRONMENT_PURPOSE"),
+    tag: get("GITHUB_REF_TYPE") == Some("tag") ? get("GITHUB_REF_NAME") : None,
+    pullRequest: get("REVENTLESS_PULL_REQUEST")->Option.flatMap(n => Int.fromString(n)),
+  }
+}
+
+let run = (~cwd: string, args: array<string>): option<string> =>
+  try {
+    Some(
+      NodeChildProcess.execFileSync(
+        "git",
+        args,
+        {cwd, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"]},
+      )->String.trim,
+    )
+  } catch {
+  | _ => None
+  }
+
+/** Git in `cwd`. A directory that is not a checkout, or a machine with no git,
+  answers *no commit* and *not dirty*. */
+let gitAt = (~cwd: string): git => {
+  head: () => run(~cwd, ["rev-parse", "HEAD"])->nonEmpty,
+  dirty: () => run(~cwd, ["status", "--porcelain"])->nonEmpty->Option.isSome,
+}
+
+/** The provenance of the deployment this process is making, in its working directory. */
+let current = (): t => fromEnv(NodeProcess.env, ~git=gitAt(~cwd=NodeProcess.cwd()))

package/src/types/DeploymentProvenance.res.mjs

@@ -0,0 +1,86 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+
+import * as Stdlib_Int from "@rescript/runtime/lib/es6/Stdlib_Int.js";
+import * as Stdlib_Option from "@rescript/runtime/lib/es6/Stdlib_Option.js";
+import * as Primitive_object from "@rescript/runtime/lib/es6/Primitive_object.js";
+import * as Nodechild_process from "node:child_process";
+
+function nonEmpty(value) {
+  return Stdlib_Option.flatMap(value, v => {
+    if (v.trim() === "") {
+      return;
+    } else {
+      return v.trim();
+    }
+  });
+}
+
+function fromEnv(env, git) {
+  let fromCi = Stdlib_Option.orElse(Stdlib_Option.orElse(nonEmpty(env["REVENTLESS_COMMIT"]), nonEmpty(env["GITHUB_SHA"])), nonEmpty(env["CI_COMMIT_SHA"]));
+  let match;
+  if (fromCi !== undefined) {
+    match = [
+      fromCi,
+      false
+    ];
+  } else {
+    let head = git.head();
+    match = head !== undefined ? [
+        head,
+        git.dirty()
+      ] : [
+        undefined,
+        false
+      ];
+  }
+  return {
+    commit: match[0],
+    dirty: match[1],
+    environment: nonEmpty(env["REVENTLESS_ENVIRONMENT"]),
+    purpose: nonEmpty(env["REVENTLESS_ENVIRONMENT_PURPOSE"]),
+    tag: Primitive_object.equal(nonEmpty(env["GITHUB_REF_TYPE"]), "tag") ? nonEmpty(env["GITHUB_REF_NAME"]) : undefined,
+    pullRequest: Stdlib_Option.flatMap(nonEmpty(env["REVENTLESS_PULL_REQUEST"]), n => Stdlib_Int.fromString(n, undefined))
+  };
+}
+
+function run(cwd, args) {
+  try {
+    return Nodechild_process.execFileSync("git", args, {
+      cwd: cwd,
+      encoding: "utf8",
+      stdio: [
+        "ignore",
+        "pipe",
+        "ignore"
+      ]
+    }).trim();
+  } catch (exn) {
+    return;
+  }
+}
+
+function gitAt(cwd) {
+  return {
+    head: () => nonEmpty(run(cwd, [
+      "rev-parse",
+      "HEAD"
+    ])),
+    dirty: () => Stdlib_Option.isSome(nonEmpty(run(cwd, [
+      "status",
+      "--porcelain"
+    ])))
+  };
+}
+
+function current() {
+  return fromEnv(process.env, gitAt(process.cwd()));
+}
+
+export {
+  nonEmpty,
+  fromEnv,
+  run,
+  gitAt,
+  current,
+}
+/* node:child_process Not a pure module */

package/src/types/Environments.res

@@ -0,0 +1,230 @@
+/***
+The environments an app deploys to, as a file: `environments.yaml`, beside its
+`deploy-manifest.yaml`.
+
+```yaml
+environments:
+  - { name: review,     purpose: review,     pullRequestsInto: dev }
+  - { name: dev,        purpose: dev,        branch: dev }
+  - { name: test,       purpose: test,       branch: test }
+  - { name: production, purpose: production, branch: main, tags: "v*", stack: prod }
+  - { name: demo,       purpose: demo,       tags: "v*" }
+```
+
+A *shared* environment has one stack and is fed by a branch, by tags, or by both.
+A *review* environment is fed by the pull requests into one branch and has one
+stack per open pull request, named `<name>-pr-<number>`.
+
+Here rather than in the AWS package because more than the deploy reads it: a
+tool that shows which commit runs where needs the same answer to *which branch
+feeds which environment* as the workflow that deploys, and a second reading of
+the file is how the two would come to disagree.
+
+The file is optional. Without it a deploy uses the branch name as the stack, as
+it always has; nothing here is consulted.
+*/
+
+/**
+What an environment is for. `Other` keeps a team's own word rather than refusing
+the file, because a purpose nothing here branches on costs nothing to carry.
+*/
+type purpose =
+  | Dev
+  | Test
+  | Production
+  | Demo
+  | Review
+  | Other(string)
+
+let purposeSchema: S.t<purpose> = S.union([
+  S.literal("dev")->S.shape(_ => Dev),
+  S.literal("test")->S.shape(_ => Test),
+  S.literal("production")->S.shape(_ => Production),
+  S.literal("demo")->S.shape(_ => Demo),
+  S.literal("review")->S.shape(_ => Review),
+  S.string->S.shape(other => Other(other)),
+])
+
+let purposeName = (purpose: purpose): string =>
+  switch purpose {
+  | Dev => "dev"
+  | Test => "test"
+  | Production => "production"
+  | Demo => "demo"
+  | Review => "review"
+  | Other(name) => name
+  }
+
+/** One entry as the file spells it. [parseString] turns it into an [environment]. */
+@schema
+type entry = {
+  name: string,
+  purpose: @s.matches(purposeSchema) purpose,
+  branch?: string,
+  tags?: string,
+  stack?: string,
+  pullRequestsInto?: string,
+  drafts?: bool,
+}
+
+@schema
+type file = {environments: array<entry>}
+
+/** What feeds an environment, and so how many stacks it has. */
+type feed =
+  | Shared({branch: option<string>, tags: option<string>, stack: string})
+  | ReviewOf({into: string, drafts: bool})
+
+type environment = {name: string, purpose: purpose, feed: feed}
+
+type t = array<environment>
+
+// ── Reading ──────────────────────────────────────────────────────────────────
+
+@module("yaml") external parseYaml: string => JSON.t = "parse"
+@module("yaml") external stringifyYaml: JSON.t => string = "stringify"
+
+let environmentOf = (entry: entry): result<environment, string> =>
+  switch (entry.pullRequestsInto, entry.branch, entry.tags) {
+  | (Some(_), Some(_), _) | (Some(_), _, Some(_)) =>
+    Error(`${entry.name}: pullRequestsInto cannot be combined with branch or tags`)
+  | (Some(_), None, None) if entry.stack->Option.isSome =>
+    Error(`${entry.name}: a review environment names its stacks itself; remove stack`)
+  | (Some(into), None, None) =>
+    Ok({
+      name: entry.name,
+      purpose: entry.purpose,
+      feed: ReviewOf({into, drafts: entry.drafts->Option.getOr(false)}),
+    })
+  | (None, None, None) =>
+    Error(`${entry.name}: says neither branch, tags nor pullRequestsInto, so nothing feeds it`)
+  | (None, _, _) if entry.drafts->Option.isSome =>
+    Error(`${entry.name}: drafts is only meaningful with pullRequestsInto`)
+  | (None, branch, tags) =>
+    Ok({
+      name: entry.name,
+      purpose: entry.purpose,
+      feed: Shared({branch, tags, stack: entry.stack->Option.getOr(entry.name)}),
+    })
+  }
+
+/** Parses an environments document. Strict, like the accounts manifest: a
+  malformed entry refuses the whole file, because a skipped environment is a
+  branch that silently stops deploying. */
+let parseString = (yamlText: string): result<t, string> =>
+  switch try Ok(S.parseOrThrow(parseYaml(yamlText), ~to=fileSchema)) catch {
+  | JsExn(err) => Error(JsExn.message(err)->Option.getOr("YAML parse error"))
+  | _ => Error("YAML parse error")
+  } {
+  | Error(_) as e => e
+  | Ok({environments}) =>
+    let names = environments->Array.map(e => e.name)
+    switch names->Array.find(n => names->Array.filter(m => m == n)->Array.length > 1) {
+    | Some(duplicate) => Error(`${duplicate}: named twice`)
+    | None =>
+      environments->Array.reduce(Ok([]), (acc, entry) =>
+        switch (acc, environmentOf(entry)) {
+        | (Error(_) as e, _) => e
+        | (Ok(_), Error(message)) => Error(message)
+        | (Ok(done), Ok(environment)) => Ok(done->Array.concat([environment]))
+        }
+      )
+    }
+  }
+
+let parseFile = (path: string): result<t, string> =>
+  try {
+    parseString(NodeFs.readFileSync(path))
+  } catch {
+  | JsExn(err) => Error(JsExn.message(err)->Option.getOr(`Cannot read ${path}`))
+  | _ => Error(`Cannot read ${path}`)
+  }
+
+let entryOf = (environment: environment): entry =>
+  switch environment.feed {
+  | Shared({branch, tags, stack}) => {
+      name: environment.name,
+      purpose: environment.purpose,
+      ?branch,
+      ?tags,
+      stack: ?(stack == environment.name ? None : Some(stack)),
+    }
+  | ReviewOf({into, drafts}) => {
+      name: environment.name,
+      purpose: environment.purpose,
+      pullRequestsInto: into,
+      drafts: ?(drafts ? Some(true) : None),
+    }
+  }
+
+/** The document for a set of environments. Comments are not kept: this writes a
+  new file, it does not edit one. */
+let print = (environments: t): string =>
+  {environments: environments->Array.map(entryOf)}->Util_Sury.toJson(fileSchema)->stringifyYaml
+
+/** Where a deploy looks for it: beside the deploy manifest. */
+let fileName = "environments.yaml"
+
+let pathBeside = (~manifest: string): string =>
+  NodePath.join([NodePath.dirname(manifest), fileName])
+
+// ── Resolving ────────────────────────────────────────────────────────────────
+
+/**
+A branch or tag pattern as GitHub's workflow filters spell them: `*` matches
+within one path segment, `**` across segments. Nothing else is special.
+*/
+let matches = (~pattern: string, name: string): bool => {
+  let escaped =
+    pattern
+    ->String.split("**")
+    ->Array.map(part =>
+      part
+      ->String.replaceRegExp(/[.+?^${}()|[\]\\]/g, "\\$&")
+      ->String.replaceAll("*", "[^/]*")
+    )
+    ->Array.join(".*")
+  RegExp.fromString(`^${escaped}$`)->RegExp.test(name)
+}
+
+/** What a push or a tag deploys to. */
+type ref_ =
+  | Branch(string)
+  | Tag(string)
+
+/** `refs/heads/test` and `refs/tags/v1`; anything else is not deployable. */
+let refOf = (ref: string): option<ref_> =>
+  if ref->String.startsWith("refs/heads/") {
+    Some(Branch(ref->String.slice(~start=11)))
+  } else if ref->String.startsWith("refs/tags/") {
+    Some(Tag(ref->String.slice(~start=10)))
+  } else {
+    None
+  }
+
+type resolved = {name: string, stack: string, purpose: purpose}
+
+/** The first shared environment, in file order, that the branch or tag feeds. */
+let resolve = (environments: t, ref: ref_): option<resolved> =>
+  environments->Array.findMap(({name, purpose, feed}) =>
+    switch (feed, ref) {
+    | (Shared({branch: Some(pattern), stack}), Branch(branch)) if matches(~pattern, branch) =>
+      Some({name, stack, purpose})
+    | (Shared({tags: Some(pattern), stack}), Tag(tag)) if matches(~pattern, tag) =>
+      Some({name, stack, purpose})
+    | (Shared(_), _) | (ReviewOf(_), _) => None
+    }
+  )
+
+/** The review stack of one pull request, if the branch it targets has a review
+  environment. `draft` pull requests get one only where the environment asks. */
+let resolvePullRequest = (environments: t, ~base: string, ~number: int, ~draft: bool): option<
+  resolved,
+> =>
+  environments->Array.findMap(({name, purpose, feed}) =>
+    switch feed {
+    | ReviewOf({into, drafts}) if matches(~pattern=into, base) && (drafts || !draft) =>
+      Some({name, stack: `${name}-pr-${number->Int.toString}`, purpose})
+    | ReviewOf(_) | Shared(_) => None
+    }
+  )

package/src/types/Environments.res.mjs

@@ -0,0 +1,314 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+
+import * as Sury from "sury";
+import * as Yaml from "yaml";
+import * as Nodefs from "node:fs";
+import * as Nodepath from "node:path";
+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_exceptions from "@rescript/runtime/lib/es6/Primitive_exceptions.js";
+import * as Util_Sury$Reventless from "../util/Util_Sury.res.mjs";
+
+let purposeSchema = Sury.union([
+  Sury.shape(Sury.literal("dev"), param => "Dev"),
+  Sury.shape(Sury.literal("test"), param => "Test"),
+  Sury.shape(Sury.literal("production"), param => "Production"),
+  Sury.shape(Sury.literal("demo"), param => "Demo"),
+  Sury.shape(Sury.literal("review"), param => "Review"),
+  Sury.shape(Sury.string, other => ({
+    TAG: "Other",
+    _0: other
+  }))
+]);
+
+function purposeName(purpose) {
+  if (typeof purpose === "object") {
+    return purpose._0;
+  }
+  switch (purpose) {
+    case "Dev" :
+      return "dev";
+    case "Test" :
+      return "test";
+    case "Production" :
+      return "production";
+    case "Demo" :
+      return "demo";
+    case "Review" :
+      return "review";
+  }
+}
+
+let entrySchema = Sury.$schema(s => ({
+  name: s.m(Sury.string),
+  purpose: s.m(purposeSchema),
+  branch: s.m(Sury.$option(Sury.string)),
+  tags: s.m(Sury.$option(Sury.string)),
+  stack: s.m(Sury.$option(Sury.string)),
+  pullRequestsInto: s.m(Sury.$option(Sury.string)),
+  drafts: s.m(Sury.$option(Sury.boolean))
+}));
+
+let fileSchema = Sury.$schema(s => ({
+  environments: s.m(Sury.array(entrySchema))
+}));
+
+function environmentOf(entry) {
+  let match = entry.pullRequestsInto;
+  let match$1 = entry.branch;
+  let match$2 = entry.tags;
+  if (match !== undefined) {
+    if (match$1 === undefined && match$2 === undefined) {
+      if (Stdlib_Option.isSome(entry.stack)) {
+        return {
+          TAG: "Error",
+          _0: entry.name + `: a review environment names its stacks itself; remove stack`
+        };
+      } else {
+        return {
+          TAG: "Ok",
+          _0: {
+            name: entry.name,
+            purpose: entry.purpose,
+            feed: {
+              TAG: "ReviewOf",
+              into: match,
+              drafts: Stdlib_Option.getOr(entry.drafts, false)
+            }
+          }
+        };
+      }
+    }
+  } else {
+    let exit = 0;
+    if (match$1 !== undefined) {
+      exit = 2;
+    } else {
+      if (match$2 === undefined) {
+        return {
+          TAG: "Error",
+          _0: entry.name + `: says neither branch, tags nor pullRequestsInto, so nothing feeds it`
+        };
+      }
+      exit = 2;
+    }
+    if (exit === 2) {
+      if (Stdlib_Option.isSome(entry.drafts)) {
+        return {
+          TAG: "Error",
+          _0: entry.name + `: drafts is only meaningful with pullRequestsInto`
+        };
+      } else {
+        return {
+          TAG: "Ok",
+          _0: {
+            name: entry.name,
+            purpose: entry.purpose,
+            feed: {
+              TAG: "Shared",
+              branch: match$1,
+              tags: match$2,
+              stack: Stdlib_Option.getOr(entry.stack, entry.name)
+            }
+          }
+        };
+      }
+    }
+  }
+  return {
+    TAG: "Error",
+    _0: entry.name + `: pullRequestsInto cannot be combined with branch or tags`
+  };
+}
+
+function parseString(yamlText) {
+  let e;
+  try {
+    e = {
+      TAG: "Ok",
+      _0: Sury.parseOrThrow(Yaml.parse(yamlText), fileSchema)
+    };
+  } catch (raw_err) {
+    let err = Primitive_exceptions.internalToException(raw_err);
+    e = err.RE_EXN_ID === "JsExn" ? ({
+        TAG: "Error",
+        _0: Stdlib_Option.getOr(Stdlib_JsExn.message(err._1), "YAML parse error")
+      }) : ({
+        TAG: "Error",
+        _0: "YAML parse error"
+      });
+  }
+  if (e.TAG !== "Ok") {
+    return e;
+  }
+  let environments = e._0.environments;
+  let names = environments.map(e => e.name);
+  let duplicate = names.find(n => names.filter(m => m === n).length > 1);
+  if (duplicate !== undefined) {
+    return {
+      TAG: "Error",
+      _0: duplicate + `: named twice`
+    };
+  } else {
+    return Stdlib_Array.reduce(environments, {
+      TAG: "Ok",
+      _0: []
+    }, (acc, entry) => {
+      let match = environmentOf(entry);
+      if (acc.TAG === "Ok") {
+        if (match.TAG === "Ok") {
+          return {
+            TAG: "Ok",
+            _0: acc._0.concat([match._0])
+          };
+        } else {
+          return {
+            TAG: "Error",
+            _0: match._0
+          };
+        }
+      } else {
+        return acc;
+      }
+    });
+  }
+}
+
+function parseFile(path) {
+  try {
+    return parseString(Nodefs.readFileSync(path, "utf8"));
+  } catch (raw_err) {
+    let err = Primitive_exceptions.internalToException(raw_err);
+    if (err.RE_EXN_ID === "JsExn") {
+      return {
+        TAG: "Error",
+        _0: Stdlib_Option.getOr(Stdlib_JsExn.message(err._1), `Cannot read ` + path)
+      };
+    } else {
+      return {
+        TAG: "Error",
+        _0: `Cannot read ` + path
+      };
+    }
+  }
+}
+
+function entryOf(environment) {
+  let match = environment.feed;
+  if (match.TAG !== "Shared") {
+    return {
+      name: environment.name,
+      purpose: environment.purpose,
+      pullRequestsInto: match.into,
+      drafts: match.drafts ? true : undefined
+    };
+  }
+  let stack = match.stack;
+  return {
+    name: environment.name,
+    purpose: environment.purpose,
+    branch: match.branch,
+    tags: match.tags,
+    stack: stack === environment.name ? undefined : stack
+  };
+}
+
+function print(environments) {
+  return Yaml.stringify(Util_Sury$Reventless.toJson({
+    environments: environments.map(entryOf)
+  }, fileSchema));
+}
+
+let fileName = "environments.yaml";
+
+function pathBeside(manifest) {
+  return Nodepath.join(Nodepath.dirname(manifest), fileName);
+}
+
+function matches(pattern, name) {
+  let escaped = pattern.split("**").map(part => part.replace(/[.+?^${}()|[\]\\]/g, "\\$&").replaceAll("*", "[^/]*")).join(".*");
+  return new RegExp(`^` + escaped + `$`).test(name);
+}
+
+function refOf(ref) {
+  if (ref.startsWith("refs/heads/")) {
+    return {
+      TAG: "Branch",
+      _0: ref.slice(11)
+    };
+  } else if (ref.startsWith("refs/tags/")) {
+    return {
+      TAG: "Tag",
+      _0: ref.slice(10)
+    };
+  } else {
+    return;
+  }
+}
+
+function resolve(environments, ref) {
+  return Stdlib_Array.findMap(environments, param => {
+    let feed = param.feed;
+    let purpose = param.purpose;
+    let name = param.name;
+    if (feed.TAG !== "Shared") {
+      return;
+    }
+    let pattern = feed.branch;
+    if (pattern !== undefined && ref.TAG === "Branch") {
+      if (matches(pattern, ref._0)) {
+        return {
+          name: name,
+          stack: feed.stack,
+          purpose: purpose
+        };
+      } else {
+        return;
+      }
+    }
+    let pattern$1 = feed.tags;
+    if (pattern$1 !== undefined && ref.TAG !== "Branch" && matches(pattern$1, ref._0)) {
+      return {
+        name: name,
+        stack: feed.stack,
+        purpose: purpose
+      };
+    }
+  });
+}
+
+function resolvePullRequest(environments, base, number, draft) {
+  return Stdlib_Array.findMap(environments, param => {
+    let feed = param.feed;
+    let name = param.name;
+    if (feed.TAG === "Shared" || !(matches(feed.into, base) && (feed.drafts || !draft))) {
+      return;
+    } else {
+      return {
+        name: name,
+        stack: name + `-pr-` + number.toString(),
+        purpose: param.purpose
+      };
+    }
+  });
+}
+
+export {
+  purposeSchema,
+  purposeName,
+  entrySchema,
+  fileSchema,
+  environmentOf,
+  parseString,
+  parseFile,
+  entryOf,
+  print,
+  fileName,
+  pathBeside,
+  matches,
+  refOf,
+  resolve,
+  resolvePullRequest,
+}
+/* purposeSchema Not a pure module */

package/src/types/Message.res

@@ -2,6 +2,23 @@
 @schema
 type service = string
 
+/**
+The issuing caller, classified for `@owner` enforcement (`OwnerScope.toClaim`).
+
+Written only by the command generator, from the authenticated identity, so a
+handler can tell an owner from an operator without seeing the caller's groups.
+Absent on every command that did not come through the generator — an
+automation's follow-up, an internal dispatch — which a handler reads as the
+platform acting for itself.
+*/
+module CallerClaim = {
+  @schema
+  type t =
+    | Owned({userId: string})
+    | Exempt
+    | Unidentified
+}
+
 /**
 Envelope metadata attached to every event and command.
 
@@ -50,6 +67,10 @@ type meta = {
   /** Extensible header bag for cross-cutting context (tenantId, feature flags, etc.).
       Absent when empty — consumers normalise with `->Option.getOr(Dict.make())`. */
   headers?: dict<string>,
+  /** Commands only: the caller as the generator classified it. Deliberately not
+      inherited by `deriveMeta`, so an event or a follow-up command never carries
+      the claim of the command that caused it. */
+  callerClaim?: CallerClaim.t,
 }
 
 /**

package/src/types/Message.res.mjs

@@ -6,6 +6,19 @@ import * as Util_Sury$Reventless from "../util/Util_Sury.res.mjs";
 
 let serviceSchema = Sury.string;
 
+let schema = Sury.union([
+  Sury.$schema(s => ({
+    TAG: "Owned",
+    userId: s.m(Sury.string)
+  })),
+  Sury.literal("Exempt"),
+  Sury.literal("Unidentified")
+]);
+
+let CallerClaim = {
+  schema: schema
+};
+
 let metaSchema = Sury.$schema(s => ({
   service: s.m(serviceSchema),
   time: s.m(Sury.string),
@@ -16,7 +29,8 @@ let metaSchema = Sury.$schema(s => ({
   causationId: s.m(Sury.$option(Sury.string)),
   traceparent: s.m(Sury.$option(Sury.string)),
   schemaVersion: s.m(Sury.$option(Sury.string)),
-  headers: s.m(Sury.$option(Sury.record(Sury.string)))
+  headers: s.m(Sury.$option(Sury.record(Sury.string))),
+  callerClaim: s.m(Sury.$option(schema))
 }));
 
 let contextSchema = Sury.$schema(s => ({
@@ -189,6 +203,7 @@ function composeEventJson$p(id, meta, eventJson) {
 
 export {
   serviceSchema,
+  CallerClaim,
   metaSchema,
   contextSchema,
   statusChangeSchema,

package/src/types/OwnerScope.res

@@ -207,6 +207,78 @@ let isExempt = (scope: t): bool =>
   | Owned(_) | Unidentified(_) => false
   }
 
+/**
+The classification as it travels on a command's envelope.
+
+`System` and `Elevated` collapse into `Exempt` here, unlike in `t`: the handler
+that reads the claim only asks whether the caller may act for anyone, and the
+audit distinction is already on the envelope as `meta.user`.
+*/
+let toClaim = (scope: t): Message.CallerClaim.t =>
+  switch scope {
+  | Owned({userId}) => Owned({userId: userId})
+  | System | Elevated(_) => Exempt
+  | Unidentified(_) => Unidentified
+  }
+
+/**
+Whether a command may act on a partition whose history records an owner.
+
+`ConflictingOwners` comes first and holds for every caller: two owners in one
+partition is a data defect, and picking either would be guessing whose thing it
+is. `CallerUnidentified` holds even on an empty history — a creating command
+from nobody has no owner to stamp.
+*/
+type acting =
+  | MayAct
+  | NotTheOwner({owner: string})
+  | CallerUnidentified
+  | ConflictingOwners(array<string>)
+  | OwnerUnreadable
+
+/**
+Apply the rule to a command's claim and the distinct owners its partition records.
+
+`recordedOwners: None` says the handler could not name the partition the command
+acts on, so it could not read who owns it. That refuses an owned caller rather
+than reading as "no owner yet", which would let anyone act.
+
+A missing claim is the platform acting for itself: the generator writes one on
+every command it issues, so a command without one reached the handler by an
+internal route — the same routes `@authorize` already trusts.
+*/
+let decideActing = (
+  ~claim: option<Message.CallerClaim.t>,
+  ~recordedOwners: option<array<string>>,
+): acting =>
+  switch (recordedOwners, claim) {
+  | (Some(owners), _) if owners->Array.length > 1 => ConflictingOwners(owners)
+  | (_, None | Some(Exempt)) => MayAct
+  | (_, Some(Unidentified)) => CallerUnidentified
+  | (None, Some(Owned(_))) => OwnerUnreadable
+  | (Some(owners), Some(Owned({userId}))) =>
+    switch owners[0] {
+    | Some(owner) if owner != userId => NotTheOwner({owner: owner})
+    | Some(_) | None => MayAct
+    }
+  }
+
+/**
+Add the owners one recorded event names to the ones already folded.
+
+`fields` are that event type's `@owner` fields (`Owner.fieldNamesByVariant`).
+Distinct, so a partition whose every event repeats the same owner folds to one.
+*/
+let recordOwners = (owners: array<string>, ~fields: array<string>, data: dict<JSON.t>): array<
+  string,
+> =>
+  fields->Array.reduce(owners, (acc, field) =>
+    switch data->Dict.get(field)->Option.flatMap(JSON.Decode.string) {
+    | Some(owner) if !(acc->Array.includes(owner)) => acc->Array.concat([owner])
+    | _ => acc
+    }
+  )
+
 /**
 What owner scoping does to one read of one view.
 

package/src/types/OwnerScope.res.mjs

@@ -1,6 +1,7 @@
 // Generated by ReScript, PLEASE EDIT WITH CARE
 
 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_Option from "@rescript/runtime/lib/es6/Stdlib_Option.js";
 import * as Primitive_option from "@rescript/runtime/lib/es6/Primitive_option.js";
 import * as Identity$Reventless from "./Identity.res.mjs";
@@ -133,6 +134,75 @@ function isExempt(scope) {
   }
 }
 
+function toClaim(scope) {
+  if (typeof scope !== "object") {
+    return "Exempt";
+  }
+  switch (scope.TAG) {
+    case "Elevated" :
+      return "Exempt";
+    case "Owned" :
+      return {
+        TAG: "Owned",
+        userId: scope.userId
+      };
+    case "Unidentified" :
+      return "Unidentified";
+  }
+}
+
+function decideActing(claim, recordedOwners) {
+  if (recordedOwners !== undefined) {
+    if (recordedOwners.length > 1) {
+      return {
+        TAG: "ConflictingOwners",
+        _0: recordedOwners
+      };
+    }
+    if (claim !== undefined) {
+      if (typeof claim !== "object") {
+        claim === "Exempt";
+      } else {
+        let owner = recordedOwners[0];
+        if (owner !== undefined && owner !== claim.userId) {
+          return {
+            TAG: "NotTheOwner",
+            owner: owner
+          };
+        } else {
+          return "MayAct";
+        }
+      }
+    }
+  } else if (claim !== undefined) {
+    if (typeof claim === "object") {
+      return "OwnerUnreadable";
+    }
+    claim === "Exempt";
+  }
+  if (claim === undefined) {
+    return "MayAct";
+  }
+  if (typeof claim !== "object") {
+    if (claim === "Exempt") {
+      return "MayAct";
+    } else {
+      return "CallerUnidentified";
+    }
+  }
+}
+
+function recordOwners(owners, fields, data) {
+  return Stdlib_Array.reduce(fields, owners, (acc, field) => {
+    let owner = Stdlib_Option.flatMap(data[field], Stdlib_JSON.Decode.string);
+    if (owner !== undefined && !acc.includes(owner)) {
+      return acc.concat([owner]);
+    } else {
+      return acc;
+    }
+  });
+}
+
 function decide(identity, ownerField, elevatedOpt) {
   let elevated = elevatedOpt !== undefined ? elevatedOpt : elevatedGroups();
   if (ownerField === undefined) {
@@ -244,6 +314,9 @@ export {
   resolve,
   ownerId,
   isExempt,
+  toClaim,
+  decideActing,
+  recordOwners,
   decide,
   scopeOf,
   decideRetired,