@reventlessdev/reventless-spec 3.0.0-alpha.107 → 3.0.0-alpha.109

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.109 (2026-08-12)
+
+### Features
+
+* **plugin:** publish the access a component's authorization rule implies ([e0d0f09](https://github.com/ReventlessDev/reventless-core/commit/e0d0f096b72fe44b185ed28dc1c133364fa841b8))
+* **plugin:** publish which field ties a component to its owner ([ca71289](https://github.com/ReventlessDev/reventless-core/commit/ca7128931ce525af0d7d3a4487b2b5c54b19bec0))
+* **spec:** let a record name the field that identifies its owner ([b69ee91](https://github.com/ReventlessDev/reventless-core/commit/b69ee9123e6beb38fcdd716519103ab9328213c6))
+* **spec:** let the environment name the groups exempt from owner scoping ([2de5c51](https://github.com/ReventlessDev/reventless-core/commit/2de5c5118347a46998f9ab603308fca09addf00b))
+
+
+# 3.0.0-alpha.108 (2026-08-11)
+
+### Features
+
+* **api:** infer a queryable's key field and publish its provenance ([c835a42](https://github.com/ReventlessDev/reventless-core/commit/c835a42a0da07cdc4a3f010212e1f340a4a0ca27))
+* **plugin:** publish singleQueryField on queryableDef ([a724ab5](https://github.com/ReventlessDev/reventless-core/commit/a724ab573614792c0615d68b6486b94da14f9f82))
+
+
 # 3.0.0-alpha.107 (2026-08-10)
 
 ### Bug Fixes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reventlessdev/reventless-spec",
-  "version": "3.0.0-alpha.107",
+  "version": "3.0.0-alpha.109",
   "description": "Specifications for Reventless",
   "license": "Apache-2.0",
   "bin": {
@@ -21,7 +21,7 @@
     "sury": "11.0.0-alpha.4",
     "sury-ppx": "11.0.0-alpha.2",
     "yaml": "^2.8.3",
-    "@reventlessdev/rescript-node": "2.0.0-alpha.3"
+    "@reventlessdev/rescript-node": "2.0.0-alpha.4"
   },
   "devDependencies": {
     "rescript": "12.3.0",

package/src/components/Owner.res

@@ -0,0 +1,118 @@
+/**
+Marks the field that ties a row — or a command — to the caller who owns it.
+
+`@owner` is a *position*, not a type: it says "this field holds the id of the
+principal this record belongs to". The field's nature (an entity id, a
+reference) is declared separately and independently, exactly as a DCB tag and a
+reference are two independent facts about one field.
+
+Two things follow from the marker, both server-side and neither optional:
+
+- the write path **overwrites** the field with the authenticated caller's id
+  before the command is published, so an absent field and a forged field produce
+  the same row; and
+- reads of a view whose state carries the marker are narrowed to the caller's
+  own rows, unless the caller is elevated.
+
+Because it drives enforcement, a reader that misses the marker fails *open* —
+the field goes unstamped and the view goes unscoped, silently. That is why
+`fieldNames` follows the same wrappers `Reference.getFieldTarget` follows, and
+why it exists at all rather than leaving each consumer to look the marker up
+itself.
+
+There is no `@owner` ppx shorthand yet — `@s.matches(Owner.string)` is the
+authoring form, not a workaround for one. The shorthand is sugar over exactly
+this, the way `@ref` is sugar over `Reference.to_`, so it can be added without
+changing what any reader here does; until it exists, prefer the explicit form
+over inventing an attribute the ppx will reject.
+
+@example
+```rescript
+@schema type command =
+  PlaceOrder({
+    @partitionTag orderId: string,
+    customerId: @s.matches(Owner.string) string,
+  })
+```
+*/
+let ownerId: S.Metadata.Id.t<bool> = S.Metadata.Id.make(~namespace="reventless", ~name="owner")
+
+/** A string field declared as the record's owner. */
+let string: S.t<string> = S.string->S.Metadata.set(~id=ownerId, true)
+
+/** Whether this exact schema carries the marker. Does not look through wrappers. */
+let isOwner = (schema: S.t<unknown>): bool =>
+  S.Metadata.get(schema, ~id=ownerId)->Option.getOr(false)
+
+/**
+Whether a *field* is the owner, wherever inside the field's type the marker sits.
+
+An optional field keeps its marker inside the union wrapper, so a walk reading
+only the outer schema answers `false` for `customerId?: string` — which for an
+access-control predicate means an unscoped view rather than a reported mistake.
+Object properties are deliberately not followed: a marker on a nested record's
+field belongs to that field, and attributing it to the enclosing one would scope
+the view on the wrong value.
+*/
+let isFieldOwner = (schema: S.t<unknown>): bool =>
+  isOwner(schema) ||
+    switch schema->Semantic.unwrapOptional {
+    | Some(inner) => isOwner(inner)
+    | None => false
+    }
+
+/**
+The owner fields declared on an object schema, in declaration order.
+
+Returns an array rather than an `option<string>` so the *caller* decides what a
+second owner means. The structure walk rejects it; a plain reader emitting a
+wire marker has no reason to.
+*/
+let fieldNamesOfProperties = (properties: dict<S.t<unknown>>): array<string> =>
+  properties
+  ->Dict.toArray
+  ->Array.filterMap(((propName, propSchema)) => isFieldOwner(propSchema) ? Some(propName) : None)
+
+let fieldNames = (schema: S.t<unknown>): array<string> =>
+  switch schema {
+  | Object({properties}) => fieldNamesOfProperties(properties)
+  | _ => []
+  }
+
+/**
+The owner fields of one constructor of a command or event union.
+
+A command schema is a union of variants, and only the variant actually being
+issued may be stamped — `PlaceOrder` and `ImportProducts` live in the same union
+and have nothing to say about each other's fields. Resolving by TAG here, rather
+than at the call site, is what stops a caller from stamping across variants.
+
+Answers `[]` for an unknown tag and for a payload-less variant, both of which
+mean the same thing to every caller: this command carries no owner.
+*/
+let variantFieldNames = (schema: S.t<unknown>, ~variant: string): array<string> => {
+  let isVariant = (properties: dict<S.t<unknown>>) =>
+    switch properties->Dict.get("TAG") {
+    | Some(String({const: ?Some(name)})) => name == variant
+    | _ => false
+    }
+  switch schema {
+  | Union({anyOf}) =>
+    anyOf
+    ->Array.find(v =>
+      switch v {
+      | Object({properties}) => isVariant(properties)
+      | _ => false
+      }
+    )
+    ->Option.mapOr([], v =>
+      switch v {
+      | Object({properties}) => fieldNamesOfProperties(properties)
+      | _ => []
+      }
+    )
+  // A single-constructor command compiles to a bare object rather than a union.
+  | Object({properties}) => isVariant(properties) ? fieldNamesOfProperties(properties) : []
+  | _ => []
+  }
+}

package/src/components/Owner.res.mjs

@@ -0,0 +1,96 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+
+import * as S from "sury/src/S.res.mjs";
+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 Semantic$Reventless from "../semantic/Semantic.res.mjs";
+
+let ownerId = S.Metadata.Id.make("reventless", "owner");
+
+let string = S.Metadata.set(S.string, ownerId, true);
+
+function isOwner(schema) {
+  return Stdlib_Option.getOr(S.Metadata.get(schema, ownerId), false);
+}
+
+function isFieldOwner(schema) {
+  if (isOwner(schema)) {
+    return true;
+  }
+  let inner = Semantic$Reventless.unwrapOptional(schema);
+  if (inner !== undefined) {
+    return isOwner(inner);
+  } else {
+    return false;
+  }
+}
+
+function fieldNamesOfProperties(properties) {
+  return Stdlib_Array.filterMap(Object.entries(properties), param => {
+    if (isFieldOwner(param[1])) {
+      return param[0];
+    }
+  });
+}
+
+function fieldNames(schema) {
+  if (schema.type === "object") {
+    return fieldNamesOfProperties(schema.properties);
+  } else {
+    return [];
+  }
+}
+
+function variantFieldNames(schema, variant) {
+  let isVariant = properties => {
+    let match = properties["TAG"];
+    if (match === undefined) {
+      return false;
+    }
+    if (match.type !== "string") {
+      return false;
+    }
+    let name = match.const;
+    if (name !== undefined) {
+      return name === variant;
+    } else {
+      return false;
+    }
+  };
+  switch (schema.type) {
+    case "object" :
+      let properties = schema.properties;
+      if (isVariant(properties)) {
+        return fieldNamesOfProperties(properties);
+      } else {
+        return [];
+      }
+    case "union" :
+      return Stdlib_Option.mapOr(schema.anyOf.find(v => {
+        if (v.type === "object") {
+          return isVariant(v.properties);
+        } else {
+          return false;
+        }
+      }), [], v => {
+        if (v.type === "object") {
+          return fieldNamesOfProperties(v.properties);
+        } else {
+          return [];
+        }
+      });
+    default:
+      return [];
+  }
+}
+
+export {
+  ownerId,
+  string,
+  isOwner,
+  isFieldOwner,
+  fieldNamesOfProperties,
+  fieldNames,
+  variantFieldNames,
+}
+/* ownerId Not a pure module */

package/src/components/Plugin.res

@@ -194,6 +194,34 @@ type commandDef = {
   (read as None) — those stores must be reset. See [[sury-optional-field-absent-vs-null]].
   */
   apiExposed: @s.matches(boolOptionSchema) option<bool>,
+  /**
+  Access keys a caller must hold — any one of them — to be *offered* this command,
+  derived from the authorization rule the server already enforces. `None` (or `[]`)
+  means the rule asks for nothing a client can check.
+
+  A hint, never a boundary: the rule in the resolver is what refuses a call, and a
+  caller who edits this list gains nothing. It exists so a client stops advertising
+  what the server would refuse — an offered command that always fails is a worse
+  answer than no command at all. Derived rather than authored, so it cannot drift
+  from the rule it describes. js_nullable, so defs written before this field
+  existed decode as None.
+  */
+  requiredAccess: @s.matches(stringArrayOptionSchema) option<array<string>>,
+  /**
+  Name of the command field the server stamps with the caller's own identity, when
+  the command declares one (`@owner`). A client should omit it from a generated
+  form for a caller who is not elevated: whatever it collects there is discarded
+  and replaced, so offering the field asks a question whose answer is ignored.
+
+  Derived from the annotation, never authored, so it cannot disagree with what the
+  write path actually does. js_nullable for the same JSON-safety reason as
+  `requiredAccess`.
+
+  ⚠️ A client cannot decide the *elevated* half from this alone — the manifest
+  states which field carries the owner, and the caller's own identity says whether
+  they are exempt. Both are needed, and neither is derivable from the other.
+  */
+  ownerField: @s.matches(stringOptionSchema) option<string>,
 }
 
 @schema
@@ -246,6 +274,17 @@ type queryableDef = {
   */
   statusField: @s.matches(stringOptionSchema) option<string>,
   /**
+  Name of the state field that ties a row to the principal owning it (`@owner`),
+  when the view declares one. Two consequences for a client: reads of this view
+  are narrowed server-side to a non-elevated caller's own rows, and the column is
+  constant for such a caller and so carries no information in a list.
+
+  Derived from the annotation. As on `commandDef.ownerField`, this states which
+  field carries the owner and not whether the current caller is exempt — that is
+  the caller's own identity to answer.
+  */
+  ownerField: @s.matches(stringOptionSchema) option<string>,
+  /**
   Component visibility hint (`@@reventless.visibility`). `Some("Internal")` marks a
   ReadModel / StateViewSlice that the deployed AutoUI hides from its menu, drill-down
   pages, web event graph and cross-plugin edges. `None` (absent) means Public. Internal
@@ -269,6 +308,62 @@ type queryableDef = {
   before this field existed must be reset/re-emitted. See [[deployed-chapter-grouping]].
   */
   chapter: @s.matches(stringOptionSchema) option<string>,
+  /**
+  The singular counterpart of `queryField`: the generated single-entity query
+  (`Plugin_Order(id: ID!)` beside the list field `Plugin_Orders`), and — because
+  `Api_Naming` returns the same string for both — the prefix of the queryable's
+  generated input types (`Plugin_OrderFilter`, `Plugin_OrderOrderBy`). One field
+  rather than two, so the two uses cannot drift apart.
+
+  Published because it is not derivable from `queryField` without re-implementing
+  `Api_Naming.singularize`: a consumer that strips a trailing `s` turns
+  `Plugin_Categories` into `Plugin_Categorie`, a name the schema does not serve,
+  and fails at query time against that one view. Sourced from the naming module
+  itself, never re-derived.
+
+  `None` means not stated — defs persisted before this field existed, and
+  hand-rolled defs that decline to say; a consumer falls back to its own
+  derivation there. js_nullable for the same JSON-safety reason as `statusField`.
+  */
+  singleQueryField: @s.matches(stringOptionSchema) option<string>,
+  /**
+  The state field that identifies a row — the queryable's own key, as opposed to
+  a reference to some other entity. `Products` carries `productId` and
+  `categoryId`; this says which of the two the row is about.
+
+  `None` means unresolved: a state with several `*Id` fields and no name match,
+  or with none at all. Such a component gets no key-derived filter or sort until
+  its spec declares `@id`. Also `None` on defs persisted before this field
+  existed. js_nullable for the same JSON-safety reason as `statusField`.
+  */
+  idField: @s.matches(stringOptionSchema) option<string>,
+  /**
+  Which rung produced `idField`, so a consumer can tell a declaration from a
+  guess — the same reason `labelFieldSource` exists:
+
+  - `"annotation"` — the state declares `@id`. The author said which field keys
+    the row; nothing inferred outranks it.
+  - `"convention"` — a field named `<singular component name>Id` exists
+    (`Products` → `productId`). A guess, and the one guess a client can make for
+    itself.
+  - `"sole"` — the state has exactly one `*Id` field, so there is nothing else
+    the key could be (`AvailableProducts` → `productId`). A guess, and one that
+    needs the state's full field list to make.
+
+  `None` whenever `idField` is `None`, and on defs that predate the field.
+  */
+  idFieldSource: @s.matches(stringOptionSchema) option<string>,
+  /**
+  Access keys a caller must hold — any one of them — to be *offered* this view,
+  derived from the component's module-level authorization rule. Same terms as
+  `commandDef.requiredAccess`: a hint that keeps a client from advertising a
+  surface the server would refuse, never the refusal itself.
+
+  Worth stating for reads in particular: a denied query does not error, it comes
+  back empty, so a client that offers a view it may not read renders a confident
+  blank table rather than a visible failure.
+  */
+  requiredAccess: @s.matches(stringArrayOptionSchema) option<array<string>>,
 }
 
 /**

package/src/components/Plugin.res.mjs

@@ -104,7 +104,9 @@ let commandDefSchema = S.schema(s => ({
   references: s.m(S.array(fieldReferenceSchema)),
   allowedStates: s.m(stringArrayOptionSchema),
   targetState: s.m(stringOptionSchema),
-  apiExposed: s.m(boolOptionSchema)
+  apiExposed: s.m(boolOptionSchema),
+  requiredAccess: s.m(stringArrayOptionSchema),
+  ownerField: s.m(stringOptionSchema)
 }));
 
 let queryableDefSchema = S.schema(s => ({
@@ -117,8 +119,13 @@ let queryableDefSchema = S.schema(s => ({
   searchableFields: s.m(S.array(S.string)),
   labelFieldSource: s.m(stringOptionSchema),
   statusField: s.m(stringOptionSchema),
+  ownerField: s.m(stringOptionSchema),
   visibility: s.m(stringOptionSchema),
-  chapter: s.m(stringOptionSchema)
+  chapter: s.m(stringOptionSchema),
+  singleQueryField: s.m(stringOptionSchema),
+  idField: s.m(stringOptionSchema),
+  idFieldSource: s.m(stringOptionSchema),
+  requiredAccess: s.m(stringArrayOptionSchema)
 }));
 
 let eventDefSchema = S.schema(s => ({

package/src/types/OwnerScope.res

@@ -0,0 +1,227 @@
+/**
+Classifies the caller behind a request for the purposes of `@owner` enforcement:
+whose id gets stamped into an owner-marked command field, and whose rows an
+owner-scoped read is narrowed to.
+
+This is deliberately one function rather than a check written twice. The write
+path and the read path must agree about who is exempt — an implementation that
+scopes reads but not writes labels rows correctly and shows them to everyone,
+and one that scopes writes but not reads does the reverse. Both call `resolve`.
+
+⚠️ **`Identity.t` is not trustworthy at this boundary, and this module is where
+that stops mattering.** The AppSync resolver templates build the identity object
+in generated JavaScript and hand it to a handler that types it as `Identity.t`
+without decoding it. For a Cognito caller the shape matches. For an IAM-signed
+caller — every AppSync API in a deployed estate carries `AWS_IAM` as an
+additional provider for service-to-service traffic — the template emits
+`{userArn, accountId, username, provider: 'IAM'}`: no `userId`, no `groups`, and
+a `provider` string that is not one of the three the variant models. So the
+fields this module reads are typed non-optional and are, at runtime, sometimes
+absent. Every read here goes through a nullable cast for that reason; deleting
+one restores a silent failure rather than a type error.
+*/
+
+/** Whether a JS value is a primitive string — `Cognito` and `InMemory` compile to
+    bare strings while `Custom(_)` compiles to an object, so this is how a modelled
+    provider is told from an unmodelled one that arrived as raw JSON. */
+let isJsString: 'a => bool = %raw(`v => typeof v === "string"`)
+
+external asNullableString: string => Nullable.t<string> = "%identity"
+external asNullableArray: array<string> => Nullable.t<array<string>> = "%identity"
+external asString: Identity.provider => string = "%identity"
+external asNullableIdentity: Identity.t => Nullable.t<Identity.t> = "%identity"
+
+/**
+The caller, classified.
+
+`System` and `Elevated` behave identically today — neither is stamped, neither is
+scoped — and are still separate cases because they are different claims. `System`
+says the platform is calling itself; `Elevated` says a named human holds an
+operator group. Collapsing them would make an audit unable to tell a service
+write from an administrator's.
+
+`Unidentified` carries a short reason because it is the fail-closed branch, and
+the fail-closed branch is the one someone will be debugging.
+*/
+type t =
+  | System
+  | Elevated({userId: string})
+  | Owned({userId: string})
+  | Unidentified(string)
+
+/**
+Providers that identify a *machine*, not a person. Members are exempt from
+stamping and scoping.
+
+An allowlist rather than "anything not modelled", because the fallback direction
+is the whole safety property here: a provider nobody has classified must land in
+`Unidentified` and be refused, not in `System` and be handed unscoped reads. Add
+to this list deliberately.
+*/
+let systemProviders = ["IAM"]
+
+/**
+Groups whose members read across every owner.
+
+A single deployment-wide list, not a parameter of the annotation. Per-annotation
+elevation would let two views disagree about who an operator is, so a caller
+scoped on one view would be unscoped on the next — and the gap would appear one
+view at a time, as views were added.
+
+Resolved as: an explicit `setElevatedGroups` wins, else the environment, else
+empty. The env fallback exists because a deployment is **two kinds of process**,
+not one. On a cloud provider the read predicate for a table-backed view is baked
+into resolver source by the deploy program, while stamping and the SQL-backed
+reads run later inside separate function runtimes the deploy never enters. A
+value set in the deploy program alone reaches the first and not the second — and
+the failure that produces is a *wrong write*, not a narrow read: an operator
+acting on someone's behalf gets the row stamped with their own id, because the
+runtime believes nobody is elevated. An environment variable is the only carrier
+both kinds of process share, which is the same reason the logger's level is one.
+
+Empty remains the default in both directions: a deployment that configures
+nothing shows operators too little rather than showing customers each other.
+*/
+@val
+external _elevatedGroupsEnv: option<string> = "process.env.REVENTLESS_ELEVATED_GROUPS"
+
+let explicitElevatedGroups: ref<option<array<string>>> = ref(None)
+
+/** Set the list for this process. Wins over the environment — a platform root
+    that states its operator groups in code means it, and should not be silently
+    overridden by a stray variable. */
+let setElevatedGroups = (groups: array<string>) => explicitElevatedGroups := Some(groups)
+
+/** Forget an explicit setting and fall back to the environment again. */
+let clearElevatedGroups = () => explicitElevatedGroups := None
+
+let parseElevatedGroups = (raw: string): array<string> =>
+  raw
+  ->String.split(",")
+  ->Array.map(String.trim)
+  ->Array.filter(part => part->String.length > 0)
+
+/**
+The groups exempt from owner scoping, right now.
+
+A function rather than a `ref` anyone can read: the answer depends on the
+environment as well as on what was set, and it is re-read per call so a value
+appearing later in a process still takes effect. Reading a raw ref would have
+frozen whichever half happened to be consulted first.
+*/
+let elevatedGroups = (): array<string> =>
+  switch explicitElevatedGroups.contents {
+  | Some(groups) => groups
+  | None =>
+    switch _elevatedGroupsEnv {
+    | Some(raw) => parseElevatedGroups(raw)
+    | None => []
+    }
+  }
+
+// Order matters: the provider is examined before `userId`, because the IAM
+// caller fails the `userId` test for a reason that has nothing to do with being
+// anonymous and must not be refused as though it did.
+let classify = (identity: Identity.t, ~elevated: array<string>): t => {
+  let provider = identity.provider
+  let providerName = isJsString(provider) ? Some(provider->asString) : None
+
+  switch providerName {
+  | Some(name) if systemProviders->Array.includes(name) => System
+  // A modelled string provider, or `Custom(_)` (an object, so `providerName` is
+  // None) — either way a caller claiming to be a person. Unmodelled strings fall
+  // through to the refusal below.
+  | Some("Cognito") | Some("InMemory") | None =>
+    switch identity.userId->asNullableString->Nullable.toOption {
+    | None => Unidentified("identity carries no userId")
+    | Some("") => Unidentified("identity carries an empty userId")
+    | Some(userId) if userId == Identity.anonymous.userId =>
+      Unidentified("caller is anonymous")
+    | Some(userId) =>
+      let groups = identity.groups->asNullableArray->Nullable.toOption->Option.getOr([])
+      groups->Array.some(g => elevated->Array.includes(g))
+        ? Elevated({userId: userId})
+        : Owned({userId: userId})
+    }
+  | Some(name) => Unidentified(`unrecognised identity provider "${name}"`)
+  }
+}
+
+/**
+Classify a caller. `~elevated` defaults to the configured list so call sites do
+not each have to remember to read it.
+*/
+let resolve = (identity: Identity.t, ~elevated: array<string>=elevatedGroups()): t =>
+  // The whole identity, not just its fields, can be missing: an internal caller
+  // that builds a payload without one reaches here with `undefined`. Reading
+  // through it would raise a TypeError, which surfaces as a crash rather than as
+  // the refusal this case actually is.
+  switch identity->asNullableIdentity->Nullable.toOption {
+  | None => Unidentified("request carries no identity")
+  | Some(identity) => classify(identity, ~elevated)
+  }
+
+/**
+The id an owner-marked field takes, and the value an owner-scoped read matches.
+
+`None` for `System` and `Elevated` means "do not stamp, do not scope" — and it
+means the same for `Unidentified`, which is why no caller may treat this as the
+whole answer. A write must refuse an `Unidentified` caller outright rather than
+publish an unstamped command; use `resolve` directly there.
+*/
+let ownerId = (scope: t): option<string> =>
+  switch scope {
+  | Owned({userId}) => Some(userId)
+  | System | Elevated(_) | Unidentified(_) => None
+  }
+
+/** Whether the caller reads and writes across every owner. */
+let isExempt = (scope: t): bool =>
+  switch scope {
+  | System | Elevated(_) => true
+  | Owned(_) | Unidentified(_) => false
+  }
+
+/**
+What owner scoping does to one read of one view.
+
+`RefuseOwned` is kept apart from "scope to a value nobody holds" because the two
+produce the same empty page for different reasons, and only one of them is a
+refusal — a door that wants to say so needs to be able to tell.
+*/
+type decision =
+  | Unscoped
+  | ScopeTo(string, string)
+  | RefuseOwned
+
+/**
+Combine a view's declared owner field with the caller behind the request.
+
+Lives here rather than at each read path because there are four of them —
+the shared list spec, two SQL push-downs and the generated AppSync resolver —
+and they must answer identically. Four copies of this `switch` would be four
+chances to decide that an unidentified caller "just sees nothing".
+*/
+let decide = (
+  identity: Identity.t,
+  ~ownerField: option<string>,
+  ~elevated: array<string>=elevatedGroups(),
+): decision =>
+  switch ownerField {
+  | None => Unscoped
+  | Some(field) =>
+    switch resolve(identity, ~elevated) {
+    | System | Elevated(_) => Unscoped
+    | Owned({userId}) => ScopeTo(field, userId)
+    // The view records an owner and the caller has none. Scoping to a value
+    // nobody holds would be indistinguishable from an empty view.
+    | Unidentified(_) => RefuseOwned
+    }
+  }
+
+/** The `(field, value)` pair a list query narrows on, or `None` when it does not. */
+let scopeOf = (decision: decision): option<(string, string)> =>
+  switch decision {
+  | ScopeTo(field, required) => Some((field, required))
+  | Unscoped | RefuseOwned => None
+  }

package/src/types/OwnerScope.res.mjs

@@ -0,0 +1,173 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+
+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";
+
+let isJsString = (v => typeof v === "string");
+
+let systemProviders = ["IAM"];
+
+let explicitElevatedGroups = {
+  contents: undefined
+};
+
+function setElevatedGroups(groups) {
+  explicitElevatedGroups.contents = groups;
+}
+
+function clearElevatedGroups() {
+  explicitElevatedGroups.contents = undefined;
+}
+
+function parseElevatedGroups(raw) {
+  return raw.split(",").map(prim => prim.trim()).filter(part => part.length > 0);
+}
+
+function elevatedGroups() {
+  let groups = explicitElevatedGroups.contents;
+  if (groups !== undefined) {
+    return groups;
+  }
+  let raw = process.env.REVENTLESS_ELEVATED_GROUPS;
+  if (raw !== undefined) {
+    return parseElevatedGroups(raw);
+  } else {
+    return [];
+  }
+}
+
+function classify(identity, elevated) {
+  let provider = identity.provider;
+  let providerName = isJsString(provider) ? provider : undefined;
+  if (providerName !== undefined) {
+    if (systemProviders.includes(providerName)) {
+      return "System";
+    }
+    switch (providerName) {
+      case "Cognito" :
+      case "InMemory" :
+        break;
+      default:
+        return {
+          TAG: "Unidentified",
+          _0: `unrecognised identity provider "` + providerName + `"`
+        };
+    }
+  }
+  let userId = identity.userId;
+  if (userId == null) {
+    return {
+      TAG: "Unidentified",
+      _0: "identity carries no userId"
+    };
+  }
+  if (userId === "") {
+    return {
+      TAG: "Unidentified",
+      _0: "identity carries an empty userId"
+    };
+  }
+  if (userId === Identity$Reventless.anonymous.userId) {
+    return {
+      TAG: "Unidentified",
+      _0: "caller is anonymous"
+    };
+  }
+  let groups = Stdlib_Option.getOr(Primitive_option.fromNullable(identity.groups), []);
+  if (groups.some(g => elevated.includes(g))) {
+    return {
+      TAG: "Elevated",
+      userId: userId
+    };
+  } else {
+    return {
+      TAG: "Owned",
+      userId: userId
+    };
+  }
+}
+
+function resolve(identity, elevatedOpt) {
+  let elevated = elevatedOpt !== undefined ? elevatedOpt : elevatedGroups();
+  if (identity == null) {
+    return {
+      TAG: "Unidentified",
+      _0: "request carries no identity"
+    };
+  } else {
+    return classify(identity, elevated);
+  }
+}
+
+function ownerId(scope) {
+  if (typeof scope !== "object" || scope.TAG !== "Owned") {
+    return;
+  } else {
+    return scope.userId;
+  }
+}
+
+function isExempt(scope) {
+  if (typeof scope !== "object") {
+    return true;
+  }
+  switch (scope.TAG) {
+    case "Elevated" :
+      return true;
+    case "Owned" :
+    case "Unidentified" :
+      return false;
+  }
+}
+
+function decide(identity, ownerField, elevatedOpt) {
+  let elevated = elevatedOpt !== undefined ? elevatedOpt : elevatedGroups();
+  if (ownerField === undefined) {
+    return "Unscoped";
+  }
+  let match = resolve(identity, elevated);
+  if (typeof match !== "object") {
+    return "Unscoped";
+  }
+  switch (match.TAG) {
+    case "Elevated" :
+      return "Unscoped";
+    case "Owned" :
+      return {
+        TAG: "ScopeTo",
+        _0: ownerField,
+        _1: match.userId
+      };
+    case "Unidentified" :
+      return "RefuseOwned";
+  }
+}
+
+function scopeOf(decision) {
+  if (typeof decision !== "object") {
+    return;
+  } else {
+    return [
+      decision._0,
+      decision._1
+    ];
+  }
+}
+
+export {
+  isJsString,
+  systemProviders,
+  explicitElevatedGroups,
+  setElevatedGroups,
+  clearElevatedGroups,
+  parseElevatedGroups,
+  elevatedGroups,
+  classify,
+  resolve,
+  ownerId,
+  isExempt,
+  decide,
+  scopeOf,
+}
+/* Identity-Reventless Not a pure module */