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

package/CHANGELOG.md

@@ -3,6 +3,50 @@
 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.136 (2026-09-16)
+
+### Bug Fixes
+
+* **aws:** make the demo accounts work on a pool that signs in by email ([97b036f](https://github.com/ReventlessDev/reventless-core/commit/97b036f86979ba55dbbf93d460fe8076c35abf1a))
+* feat(spec)!: infer the DCB partition key per slice, and drop @partitionTag where inference agrees ([6c10161](https://github.com/ReventlessDev/reventless-core/commit/6c101611d438beea4bc9175ae8ea0ea1f6f7493b))
+### Features
+
+* **spec:** let a slice's chapter break a partition-key tie ([2b9ae77](https://github.com/ReventlessDev/reventless-core/commit/2b9ae77e98eb42177d2bdd4977bc62bb7c7911aa))
+* **spec:** report which command yields which event or error ([ac0bdc2](https://github.com/ReventlessDev/reventless-core/commit/ac0bdc23f76a5b71b5bf5c99415ff0937690a279))
+
+### BREAKING CHANGES
+
+* DcbTag.derivePartitionTag is removed; a boundary whose
+partition cannot be inferred no longer deploys.
+
+
+
+# 3.0.0-alpha.135 (2026-09-11)
+
+### Bug Fixes
+
+* **spec:** a command that declines to act is not a command that was refused ([0b3d8a4](https://github.com/ReventlessDev/reventless-core/commit/0b3d8a40092ce7ed7801a2aae5d4d7bbed03c179))
+* feat(spec)!: a secret is a capability, so a test can know it in advance ([71507c6](https://github.com/ReventlessDev/reventless-core/commit/71507c6459b49178746f00c5040cb479d7fdade8))
+* feat(spec)!: making a principal is a capability, so the provider is replaceable ([3e59b9b](https://github.com/ReventlessDev/reventless-core/commit/3e59b9b665cc7e4b6b6f156b63b1b6bd0c6181ca))
+### Features
+
+* **aws:** the first administrator is one command, not the console ([5f1a846](https://github.com/ReventlessDev/reventless-core/commit/5f1a84603b21a9feb691a08a148751c6c6e8eca8))
+* **aws:** the rest of the cast is a file, not a comment ([aa23581](https://github.com/ReventlessDev/reventless-core/commit/aa23581f09948a47fb451ec2ecf2fc2bdd8e6ee6))
+* **spec:** preparing a manifest is not an AWS errand ([bd7f8e2](https://github.com/ReventlessDev/reventless-core/commit/bd7f8e2f6132c0cacac2ab839165f21fe91eaf6c))
+
+### BREAKING CHANGES
+
+* Capabilities.t gains a secrets member. A platform that builds
+the record literally no longer compiles until it supplies one;
+Capabilities.none.secrets is the refusing value. Code that spreads
+Capabilities.none is unaffected.
+* Capabilities.t gains an identityProvider member. A platform
+that builds the record literally no longer compiles until it supplies one;
+Capabilities.none.identityProvider is the refusing value to pass while no
+backend exists. Code that spreads Capabilities.none is unaffected.
+
+
+
 # 3.0.0-alpha.134 (2026-09-09)
 
 ### Bug Fixes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reventlessdev/reventless-spec",
-  "version": "3.0.0-alpha.134",
+  "version": "3.0.0-alpha.136",
   "description": "Specifications for Reventless",
   "license": "Apache-2.0",
   "bin": {
@@ -9,7 +9,8 @@
     "graft-trait": "./run-graft-trait.mjs",
     "certify-trait": "./run-certify-trait.mjs",
     "trait-manifest": "./run-trait-manifest.mjs",
-    "check-lifecycle": "./run-check-lifecycle.mjs"
+    "check-lifecycle": "./run-check-lifecycle.mjs",
+    "prepare-accounts": "./run-prepare-accounts.mjs"
   },
   "jest": {
     "testMatch": [
@@ -25,7 +26,7 @@
     "sury": "11.0.0-rc.2",
     "sury-ppx": "11.0.0-rc.2",
     "yaml": "^2.8.3",
-    "@reventlessdev/rescript-node": "2.0.0-alpha.11"
+    "@reventlessdev/rescript-node": "2.0.0-alpha.12"
   },
   "devDependencies": {
     "rescript": "12.3.0",

package/run-check-lifecycle.mjs

@@ -1,2 +1,3 @@
 #!/usr/bin/env node
-import "./src/lifecycle/CheckLifecycleModel.res.mjs"
+import { main } from "./src/lifecycle/CheckLifecycleModel.res.mjs"
+await main()

package/run-prepare-accounts.mjs

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { main } from "./src/types/PrepareAccounts.res.mjs"
+await main()

package/src/components/CapabilityManifest.res

@@ -21,6 +21,9 @@ type kind =
   /** Sending a message, reached through `Capabilities.messaging`. Slice-declared
       like `Geocoding`, and for the same reason carries no `field`. */
   | Messaging
+  /** Making, grouping and unmaking principals, reached through
+      `Capabilities.identityProvider`. Slice-declared, so no `field`. */
+  | IdentityProvider
 
 /** The declaration site: the component's spec name, and — for a store — the field
     carrying the `@storageRef` annotation plus the store exactly as that field
@@ -80,6 +83,7 @@ let fromStructure = (structure: Plugin.pluginStructure): t => {
       kind: switch need {
       | Geocoding => Geocoding
       | Messaging => Messaging
+      | IdentityProvider => IdentityProvider
       },
       key,
       declaredBy: needs->Array.filterMap(

package/src/components/CapabilityManifest.res.mjs

@@ -10,7 +10,8 @@ import * as CapabilityNeed$Reventless from "../semantic/CapabilityNeed.res.mjs";
 let kindSchema = Sury.union([
   Sury.literal("ObjectStore"),
   Sury.literal("Geocoding"),
-  Sury.literal("Messaging")
+  Sury.literal("Messaging"),
+  Sury.literal("IdentityProvider")
 ]);
 
 let provenanceSchema = Sury.$schema(s => ({
@@ -48,7 +49,17 @@ function fromStructure(structure) {
   let capabilityKeys = Belt_SetString.toArray(Belt_SetString.fromArray(needs.map(d => d.capability)));
   let capabilities = Stdlib_Array.filterMap(capabilityKeys, key => Stdlib_Option.map(CapabilityNeed$Reventless.fromString(key), need => {
     let tmp;
-    tmp = need === "Geocoding" ? "Geocoding" : "Messaging";
+    switch (need) {
+      case "Geocoding" :
+        tmp = "Geocoding";
+        break;
+      case "Messaging" :
+        tmp = "Messaging";
+        break;
+      case "IdentityProvider" :
+        tmp = "IdentityProvider";
+        break;
+    }
     return {
       kind: tmp,
       key: key,

package/src/components/DcbScopeInference.res

@@ -17,7 +17,12 @@ The three rules (over the representation):
    reads from a *foreign* producer (a consumed arm whose event type is produced by
    a different slice). For `AddProduct` (`ProductAdded({productId, categoryId})`,
    consuming `CategoryAdded({categoryId})`) the foreign-read `categoryId` is
-   removed, leaving `productId`. No fixpoint needed.
+   removed, leaving `productId`. Only when that leaves nothing is a key given
+   back: one whose every foreign arm comes from a slice partitioned by that same
+   key, since reading your own entity's events is identity, not a reference.
+   That step depends on other slices' partitions, so it runs to a fixpoint.
+   When several keys are left, the slice's chapter breaks the tie if exactly one
+   of them is carried by every event its chapter writes.
 
 2. **Cross-partition.** A key is cross-partition iff some slice reads it on a
    *foreign* consumed event while partitioned by something else *and* the key is
@@ -50,6 +55,8 @@ type sliceShape = {
   consumed: array<eventShape>,
   produced: array<eventShape>,
   partitionHint: option<string>,
+  /** The chapter the slice sits in (`src/<Chapter>/<Kind>/…`), when it has one. */
+  chapter?: string,
 }
 
 /** Derived scope for one tag key. */
@@ -129,39 +136,227 @@ let foreignConsumedKeys = (s: sliceShape): array<string> => {
   )
 }
 
+/** Rule 1's outcome for a boundary, before the scope rules build on it. */
+type partitionResolution = {
+  /** sliceName -> its partition key (absent when unresolved). */
+  partitionBySlice: dict<string>,
+  /** sliceName -> the keys rule 1 left standing; one entry means resolved. */
+  candidatesBySlice: dict<array<string>>,
+  /** sliceName -> (produced key, the foreign arms that kept it from the slice). */
+  blockersBySlice: dict<array<(string, array<string>)>>,
+  /** (sliceName, reason) for slices whose partition couldn't be inferred. */
+  ambiguities: array<(string, string)>,
+}
+
+let sameAssignment = (a: dict<string>, b: dict<string>): bool => {
+  let entries = d => d->Dict.toArray->Array.toSorted(((x, _), (y, _)) => String.compare(x, y))
+  entries(a) == entries(b)
+}
+
+/**
+Rule 1 over a whole boundary.
+
+1. **Seeds.** A slice whose events carry a single key is partitioned by it, whatever
+   it reads; an explicit `@partitionTag` naming a produced key is a seed too.
+2. **Subtraction.** Otherwise, `producedKeys − foreignConsumedKeys`. One key left
+   is the partition; several go to the chapter (4), then to `@partitionTag`.
+3. **Give-back.** Only when the subtraction leaves nothing: a key comes back when
+   every foreign arm carrying it is produced by a slice partitioned by that key.
+   An unseen producer makes the arm a reference. An unresolved producer counts as
+   possibly partitioned by any key it writes, which breaks cycles such as two
+   slices each reading the other's event; the answer counts only once a further
+   pass changes nothing, so that optimism never decides it alone.
+4. **Chapter.** When several keys are left, keep the ones every id-carrying event
+   written in the slice's chapter carries. `PlaceOrder` is left with `orderId` and
+   `customerId`, whose reads never show the customer to be a reference; every
+   event under `Order/` carries `orderId`, and only some carry `customerId`. Only a
+   single survivor decides — a join such as `RecordProductDemand`, whose chapter's
+   events all carry both ids, stays ambiguous. It is a tie-breaker, not a rule:
+   it never overrides a seed, the subtraction or the give-back, and moving a slice
+   to another chapter can change only a partition this step decided.
+
+Applying the give-back everywhere would be wrong: `AddProduct` reads
+`CategoryAdded({categoryId})` from a slice partitioned by `categoryId`, which
+would hand `categoryId` back and leave it two candidates.
+*/
+let resolvePartitions = (slices: array<sliceShape>): partitionResolution => {
+  let producersByEventType: dict<array<sliceShape>> = Dict.make()
+  slices->Array.forEach(s =>
+    s.produced->Array.forEach(e => {
+      let prev = producersByEventType->Dict.get(e.eventType)->Option.getOr([])
+      if !(prev->Array.some(p => p.sliceName == s.sliceName)) {
+        producersByEventType->Dict.set(e.eventType, prev->Array.concat([s]))
+      }
+    })
+  )
+  // chapter -> the keys every id-carrying event written in that chapter carries.
+  let chapterKeys = Dict.make()
+  slices->Array.forEach(s =>
+    s.chapter->Option.forEach(chapter => {
+      let events = s.produced->Array.filter(e => e.idFields->Array.length > 0)
+      events->Array.forEach(
+        e => {
+          let keys = e->keysOfEvent
+          let shared = switch chapterKeys->Dict.get(chapter) {
+          | Some(prev) => prev->Array.filter(k => keys->Array.includes(k))
+          | None => dedupSorted(keys)
+          }
+          chapterKeys->Dict.set(chapter, shared)
+        },
+      )
+    })
+  )
+  let chapterKeysOf = (s: sliceShape) => s.chapter->Option.flatMap(c => chapterKeys->Dict.get(c))
+  let byChapter = (s: sliceShape, candidates) =>
+    switch s->chapterKeysOf {
+    | Some(keys) =>
+      switch candidates->Array.filter(k => keys->Array.includes(k)) {
+      | [k] => [k]
+      | _ => candidates
+      }
+    | None => candidates
+    }
+  let foreignArms = (s: sliceShape) => {
+    let own = Set.make()
+    s.produced->Array.forEach(e => own->Set.add(e.eventType))
+    s.consumed->Array.filter(e => !(own->Set.has(e.eventType)))
+  }
+  // An arm is identity evidence for `k` iff every producer of its event type is
+  // (or, while unresolved, could be) partitioned by `k`.
+  let armIsIdentity = (e: eventShape, k, known: dict<string>) =>
+    switch producersByEventType->Dict.get(e.eventType) {
+    | None | Some([]) => false
+    | Some(producers) =>
+      producers->Array.every(p =>
+        switch known->Dict.get(p.sliceName) {
+        | Some(pk) => pk == k
+        | None => producedKeys(p)->Array.includes(k)
+        }
+      )
+    }
+  let blockersOf = (s: sliceShape, known) =>
+    producedKeys(s)->Array.filterMap(k => {
+      let arms =
+        s
+        ->foreignArms
+        ->Array.filter(e => e->keysOfEvent->Array.includes(k) && !armIsIdentity(e, k, known))
+        ->Array.map(e => e.eventType)
+      arms->Array.length > 0 ? Some((k, arms)) : None
+    })
+  let seedOf = (s: sliceShape) => {
+    let produced = producedKeys(s)
+    switch (s.partitionHint, produced) {
+    | (Some(h), _) if produced->Array.includes(h) => Some(h)
+    | (_, [single]) => Some(single)
+    | _ => None
+    }
+  }
+  let subtracted = (s: sliceShape) => {
+    let foreign = foreignConsumedKeys(s)
+    producedKeys(s)->Array.filter(k => !(foreign->Array.includes(k)))
+  }
+  let candidatesOf = (s: sliceShape, known) =>
+    switch seedOf(s) {
+    | Some(k) => [k]
+    | None =>
+      switch subtracted(s) {
+      | [] =>
+        let blocked = s->blockersOf(known)->Array.map(((k, _)) => k)
+        s->byChapter(producedKeys(s)->Array.filter(k => !(blocked->Array.includes(k))))
+      | remaining => s->byChapter(remaining)
+      }
+    }
+
+  let pass = known => {
+    let next = Dict.make()
+    slices->Array.forEach(s =>
+      switch candidatesOf(s, known) {
+      | [k] => next->Dict.set(s.sliceName, k)
+      | _ => ()
+      }
+    )
+    next
+  }
+  // Each pass can resolve at most one more link of a chain, so a boundary that
+  // settles does so within one pass per slice; the extra pass confirms it.
+  let rec settle = (known, remaining) => {
+    let next = pass(known)
+    if sameAssignment(next, known) {
+      (next, true)
+    } else if remaining == 0 {
+      (next, false)
+    } else {
+      settle(next, remaining - 1)
+    }
+  }
+  let (settled, converged) = settle(Dict.make(), slices->Array.length + 1)
+  let previous = pass(settled)
+
+  let partitionBySlice = Dict.make()
+  let candidatesBySlice = Dict.make()
+  let blockersBySlice = Dict.make()
+  let ambiguities = []
+  slices->Array.forEach(s => {
+    let candidates = candidatesOf(s, settled)
+    candidatesBySlice->Dict.set(s.sliceName, candidates)
+    switch candidates {
+    | _ if !converged && settled->Dict.get(s.sliceName) != previous->Dict.get(s.sliceName) =>
+      ambiguities->Array.push((
+        s.sliceName,
+        `partition inference did not settle — the slices it reads from keep changing each other's partition. Add an explicit @partitionTag`,
+      ))
+    | [k] => partitionBySlice->Dict.set(s.sliceName, k)
+    | [] =>
+      // Name the arms that took the key. Almost always a lifecycle arm
+      // declaring the id the slice is already partitioned by, where the fix is
+      // to drop the field rather than to annotate around it.
+      let blockers = s->blockersOf(settled)
+      blockersBySlice->Dict.set(s.sliceName, blockers)
+      let blame =
+        blockers
+        ->Array.map(((key, arms)) => `${arms->Array.join("/")} declares ${key}`)
+        ->Array.join("; ")
+      ambiguities->Array.push((
+        s.sliceName,
+        `no own partition key — every produced *Id is read from a foreign producer (${blame}). If that field is this slice's own partition, remove it from the consumed arm; if the slice really is a pure join, add an explicit @partitionTag`,
+      ))
+    | many =>
+      let chapterNote = switch (s.chapter, s->chapterKeysOf) {
+      | (Some(chapter), Some(keys)) =>
+        ` The ${chapter} chapter does not decide: the ids every event in it carries are [${keys->Array.join(
+            ", ",
+          )}].`
+      | _ => ""
+      }
+      ambiguities->Array.push((
+        s.sliceName,
+        `multiple candidate partition keys (${many->Array.join(
+            ", ",
+          )}) — add an explicit @partitionTag.${chapterNote}`,
+      ))
+    }
+  })
+  {partitionBySlice, candidatesBySlice, blockersBySlice, ambiguities}
+}
+
 /**
 Which consumed arms cost a slice its partition — the actionable half of the
-"no own partition key" ambiguity.
+"no own partition key" ambiguity, seen from this slice alone.
 
-Rule 1 subtracts `foreignConsumedKeys` from `producedKeys`, so a slice whose only
-produced key is also declared on a consumed arm it does not itself produce is left
-with nothing. In practice that is almost always one mistake: a *lifecycle* arm
-naming the id it is already partitioned by (`ProductAdded({productId})` on a slice
-whose every event carries `productId`), which reads as "this id comes from a
-foreign producer" when it is in fact this slice's own partition.
+A slice whose produced keys all ride consumed arms from other producers, and
+whose arms cannot be given back, is left with nothing. In practice that is almost
+always one mistake: a *lifecycle* arm naming the id the slice is already
+partitioned by, which reads as "this id comes from a foreign producer".
 
 The ambiguity message can only say a partition was not found. This says which arm
-to delete, which is the whole difference between a diagnostic and a puzzle — so it
-is here, beside the rule that produces the ambiguity, rather than duplicated by
-each surface that reports one.
+to delete, which is the whole difference between a diagnostic and a puzzle.
 
-Returns one entry per produced key that a foreign arm claims, naming those arms.
-Empty when the slice has a partition (nothing to explain) or when the produced
-keys are simply too many (a different ambiguity, answered by `@partitionTag`).
+Alone, no producer is in sight, so every foreign arm is a reference. Returns one
+entry per produced key a foreign arm claims, naming those arms. Empty when the
+slice has a partition or when too many keys are left (answered by `@partitionTag`).
 */
-let partitionBlockers = (s: sliceShape): array<(string, array<string>)> => {
-  let foreign = foreignConsumedKeys(s)
-  let ownProduced = Set.make()
-  s.produced->Array.forEach(e => ownProduced->Set.add(e.eventType))
-  producedKeys(s)
-  ->Array.filter(k => foreign->Array.includes(k))
-  ->Array.map(k => (
-    k,
-    s.consumed
-    ->Array.filter(e => !(ownProduced->Set.has(e.eventType)) && e->keysOfEvent->Array.includes(k))
-    ->Array.map(e => e.eventType),
-  ))
-}
+let partitionBlockers = (s: sliceShape): array<(string, array<string>)> =>
+  resolvePartitions([s]).blockersBySlice->Dict.get(s.sliceName)->Option.getOr([])
 
 /**
 Per-slice cross-partition keys for the test harness, which has no global owner
@@ -173,58 +368,14 @@ annotation so capacity/escape-hatch reads remain covered.
 let crossPartitionForSlice = (s: sliceShape): array<string> => {
   let foreign = foreignConsumedKeys(s)
   let scalar = commandScalarKeys(s)
-  let partition = switch s.partitionHint {
-  | Some(h) if producedKeys(s)->Array.includes(h) => Some(h)
-  | _ =>
-    switch producedKeys(s)->Array.filter(k => !(foreign->Array.includes(k))) {
-    | [single] => Some(single)
-    | _ => None
-    }
-  }
+  let partition = resolvePartitions([s]).partitionBySlice->Dict.get(s.sliceName)
   // A foreign read is cross-partition only when the command carries the key as a
   // scalar (must be fanned); an array-only foreign key auto-fans partition-scoped.
   foreign->Array.filter(k => Some(k) != partition && scalar->Array.includes(k))
 }
 
 let infer = (slices: array<sliceShape>): derived => {
-  // Rule 1 — partition(S) = producedKeys(S) \ foreignConsumedKeys(S), where a
-  // foreign-consumed key rides a consumed arm the slice does not itself produce.
-  // An explicit @partitionTag hint overrides the derivation (escape hatch for
-  // slices whose own events legitimately carry two owned keys).
-  let partitionBySlice = Dict.make()
-  let ambiguities = []
-  slices->Array.forEach(s => {
-    let produced = producedKeys(s)
-    switch s.partitionHint {
-    | Some(h) if produced->Array.includes(h) => partitionBySlice->Dict.set(s.sliceName, h)
-    | _ =>
-      let foreign = foreignConsumedKeys(s)
-      switch produced->Array.filter(k => !(foreign->Array.includes(k))) {
-      | [single] => partitionBySlice->Dict.set(s.sliceName, single)
-      | [] =>
-        // Name the arms that took the key. Almost always a lifecycle arm
-        // declaring the id the slice is already partitioned by, where the fix is
-        // to drop the field rather than to annotate around it.
-        let blame =
-          partitionBlockers(s)
-          ->Array.map(((key, arms)) => `${arms->Array.join("/")} declares ${key}`)
-          ->Array.join("; ")
-        let _ =
-          ambiguities->Array.push((
-            s.sliceName,
-            `no own partition key — every produced *Id is read from a foreign producer (${blame}). If that field is this slice's own partition, remove it from the consumed arm; if the slice really is a pure join, add an explicit @partitionTag`,
-          ))
-      | many =>
-        let _ =
-          ambiguities->Array.push((
-            s.sliceName,
-            `multiple candidate partition keys (${many->Array.join(
-                ", ",
-              )}) — add an explicit @partitionTag`,
-          ))
-      }
-    }
-  })
+  let {partitionBySlice, ambiguities} = resolvePartitions(slices)
 
   // owner map + the set of keys that are *some* entity's partition.
   let ownerByKey = Dict.make()