@reventlessdev/reventless-core 3.0.0-alpha.198 → 3.0.0-alpha.200

package/CHANGELOG.md

@@ -3,6 +3,41 @@
 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.200 (2026-08-01)
+
+* feat(aws,core,spec)!: qualify store prefixes by plugin and refuse name collisions ([da39405](https://github.com/ReventlessDev/reventless-core/commit/da394059d9f8f981bf7adc79e2c1ce2b429e0267))
+* feat(core,aws)!: name task buckets for their plugin and task ([05203cb](https://github.com/ReventlessDev/reventless-core/commit/05203cb3b0b019401a6f32cf78109f397b6799d5))
+### Features
+
+* **spec:** a coordinate is one declared point, not two fields and a name guess ([bfe2f90](https://github.com/ReventlessDev/reventless-core/commit/bfe2f90241492422d6c242e3f50e31b81ed2a010))
+
+### BREAKING CHANGES
+
+* objects minted under the old bare prefix are orphaned and their
+refs unresolvable. The migration is `seed:reset` for the owning plugin, then
+re-seed. Legacy-prefix grandfathering was considered and deliberately dropped —
+it would have added a permanent prefix SET across the deploy argument, both store
+configs, the presign IAM fan-out, the release scope check and the stack output,
+to spare a disposable stack one wipe.
+* a bucket name change is a replace. TaskBucket_S3 now sets
+forceDestroy on disposable stacks (Util_StoreLayout.protectionFor), so pr-*
+stacks recreate cleanly; protected stacks must have the task bucket drained by
+hand before the first deploy after this, or the replace fails BucketNotEmpty.
+
+
+
+# 3.0.0-alpha.199 (2026-08-01)
+
+### Bug Fixes
+
+* **core:** don't flag js_nullable scalars in the required-scalar guard ([fb394a3](https://github.com/ReventlessDev/reventless-core/commit/fb394a3f556ffa6a95b1cf746cfd55ded8a5021a))
+* **spec,core:** heal a missing scalar on read ([de9a98e](https://github.com/ReventlessDev/reventless-core/commit/de9a98ec5fe11ec19bef80626e99244d9c30a6b1))
+* **spec,core:** make the storageRef annotation optional, as its readers already are ([c8477c5](https://github.com/ReventlessDev/reventless-core/commit/c8477c5c34384b864c06716dc5896310629dc349))
+### Features
+
+* **upload:** add the release half of the upload contract via the domain API ([448f887](https://github.com/ReventlessDev/reventless-core/commit/448f88714a5875be420f794a08d482fcf4ba8404))
+
+
 # 3.0.0-alpha.198 (2026-08-01)
 
 ### Bug Fixes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reventlessdev/reventless-core",
-  "version": "3.0.0-alpha.198",
+  "version": "3.0.0-alpha.200",
   "description": "Core package for Reventless framework",
   "license": "Apache-2.0",
   "jest": {
@@ -30,15 +30,15 @@
     "uuid": "^13.0.0",
     "@reventlessdev/rescript-effect": "0.1.0-alpha.32",
     "@reventlessdev/rescript-hash-object": "1.2.0-alpha.14",
-    "@reventlessdev/rescript-fast-csv": "2.0.0-alpha.0",
     "@reventlessdev/rescript-jest": "1.0.0-alpha.10",
-    "@reventlessdev/rescript-node": "2.0.0-alpha.0",
     "@reventlessdev/rescript-pulumi-pulumi": "2.3.0-alpha.18",
+    "@reventlessdev/rescript-node": "2.0.0-alpha.0",
+    "@reventlessdev/rescript-fast-csv": "2.0.0-alpha.0",
     "@reventlessdev/rescript-ssh2": "2.0.0-alpha.0",
+    "@reventlessdev/reventless-infra": "3.0.0-alpha.117",
     "@reventlessdev/rescript-uuid": "2.0.0-alpha.0",
-    "@reventlessdev/reventless-interop": "3.0.0-alpha.30",
-    "@reventlessdev/reventless-infra": "3.0.0-alpha.115",
-    "@reventlessdev/reventless-spec": "3.0.0-alpha.90"
+    "@reventlessdev/reventless-spec": "3.0.0-alpha.92",
+    "@reventlessdev/reventless-interop": "3.0.0-alpha.30"
   },
   "devDependencies": {
     "rescript": "12.3.0",

package/src/admin/Platform_AdminApi.res

@@ -77,6 +77,29 @@ let pluginStatusSubscriptionSource: GraphQL_Stitcher.subscriptionSource = {
   mutations: ["Platform_PluginStatusChanged"],
 }
 
+// Upload service (route B): mint and release object-store uploads through the GraphQL
+// API instead of an anonymous Function URL, so AppSync's Cognito authorizer
+// authenticates the caller and the verified identity reaches the resolver. `store` is
+// the qualified `{plugin}.{store}` the caller declares; the resolver Lambda maps it to
+// a bucket/prefix. No subscription source — these are request/response operations, not
+// Source-C event fan-ins.
+//
+// These constants live here (next to the other cross-provider platform SDL constants)
+// but are deliberately NOT part of `baseFragment`: the admin base is Admin-group gated
+// (`injectAwsAuthAll(~group="Admin")`), and uploads are a regular authenticated-user
+// operation. They are added instead to the **domain** API's platform-owned base
+// (`domainBaseFragment` in the AWS/local Platform), which takes the default
+// `AllowAuthenticated` auth. See [docs/plans/upload-release-path.md] § "Which API".
+let uploadTypes = [
+  `type Upload_Ticket {\n  uploadUrl: String!\n  storageRef: String!\n}`,
+  `type Upload_ReleaseResult {\n  released: Boolean!\n  reason: String\n}`,
+]
+
+let uploadMutationFields = [
+  `  Upload_Presign(store: ID!, fileName: String!, contentType: String): Upload_Ticket`,
+  `  Upload_Release(store: ID!, storageRef: String!): Upload_ReleaseResult`,
+]
+
 let baseFragment = (~cloner: bool) => {
   let base = GraphQL_FragmentGenerator.generate(
     ~mutationEntries=mutationEntries(~cloner),

package/src/admin/Platform_AdminApi.res.mjs

@@ -71,6 +71,16 @@ let pluginStatusSubscriptionSource = {
   mutations: pluginStatusSubscriptionSource_mutations
 };
 
+let uploadTypes = [
+  `type Upload_Ticket {\n  uploadUrl: String!\n  storageRef: String!\n}`,
+  `type Upload_ReleaseResult {\n  released: Boolean!\n  reason: String\n}`
+];
+
+let uploadMutationFields = [
+  `  Upload_Presign(store: ID!, fileName: String!, contentType: String): Upload_Ticket`,
+  `  Upload_Release(store: ID!, storageRef: String!): Upload_ReleaseResult`
+];
+
 function baseFragment(cloner) {
   let base = GraphQL_FragmentGenerator$ReventlessCore.generate(mutationEntries(cloner), PluginBaseFragment$ReventlessCore.queryEntries);
   let parts = GraphQL_Stitcher$ReventlessCore.decode(base);
@@ -108,6 +118,8 @@ export {
   pluginStatusMutationFields,
   pluginStatusSubscriptionField,
   pluginStatusSubscriptionSource,
+  uploadTypes,
+  uploadMutationFields,
   baseFragment,
 }
 /* cloneArgsSchema Not a pure module */

package/src/components/Task/Task_Builder.res

@@ -14,6 +14,71 @@ let pascalCase = s =>
   )
   ->Array.join("")
 
+// Split words out of a PascalCase/camelCase run so kebab-casing keeps the word
+// boundaries. Two passes: `aB` splits an ordinary hump, `ABc` splits the tail of
+// an acronym off the word that follows it ("HTTPServer" -> "HTTP-Server").
+let humpBoundary = %re("/([a-z0-9])([A-Z])/g")
+let acronymBoundary = %re("/([A-Z]+)([A-Z][a-z])/g")
+
+// Kebab-case an identifier for use in an S3 bucket name: "ImportProducts" and
+// "product-imports" both reduce to "import-products".
+//
+// S3 lowercases bucket names, so a PascalCase segment collapses into an
+// unreadable run-on ("importproductsproductimportsbucket"). Kebab survives the
+// lowercasing with its word boundaries intact, which is why the framework's
+// declared-store buckets (`Util_StoreLayout.bucketNameFor`) already use it.
+let kebabCase = s =>
+  s
+  ->String.replaceRegExp(acronymBoundary, "$1-$2")
+  ->String.replaceRegExp(humpBoundary, "$1-$2")
+  ->String.split("-")
+  ->Array.flatMap(p => p->String.split("_"))
+  ->Array.filter(p => p->String.length > 0)
+  ->Array.map(String.toLowerCase)
+  ->Array.join("-")
+
+// S3 caps a bucket name at 63 characters and Pulumi appends `-` plus a 7-char
+// uniqueness suffix, so the composed name has 55 to work with.
+let maxBucketNameLength = 55
+
+/**
+The Pulumi resource name for a task's bucket: `{plugin}-{task}` for a task's
+default bucket, `{plugin}-{task}-{bucketId}` when the declaration names one.
+
+`plugin` is the ambient plugin under construction, absent for a task built
+outside any plugin. No `Bucket` suffix — `aws:s3/bucket` and the
+`reventless:role=Bucket` tag both already say what it is.
+
+Composed rather than sanitised, so a name too long for S3 is the caller's to fix:
+truncating here would silently manufacture a collision between two long names
+that share a prefix.
+*/
+let bucketResourceName = (
+  ~plugin: option<string>,
+  ~task: string,
+  ~bucketId: option<string>,
+): string => {
+  let name =
+    [plugin, Some(task), bucketId]
+    ->Array.filterMap(segment => segment)
+    ->Array.map(kebabCase)
+    ->Array.filter(segment => segment != "")
+    ->Array.join("-")
+  if name->String.length > maxBucketNameLength {
+    JsError.throwWithMessage(
+      `Task bucket name "${name}" is ${name
+        ->String.length
+        ->Int.toString} characters; S3 allows ${maxBucketNameLength->Int.toString} once Pulumi's ` ++
+      `uniqueness suffix is added. Shorten the task name` ++
+      switch bucketId {
+      | Some(id) => ` or the bucket id "${id}".`
+      | None => "."
+      },
+    )
+  }
+  name
+}
+
 module Make = (
   Spec: Task.Spec,
   RuntimeEnvironment: Runtime.Environment,
@@ -169,11 +234,17 @@ module Make = (
       buckets
       ->Array.map(bucketSpec => {
         let bucketName = bucketSpec.bucketName->Option.getOr("Bucket")
-        // `bucketStem` is the PascalCase resource-name segment (empty for the
-        // default unnamed bucket so the name stays `<Task>Bucket`, not
-        // `<Task>BucketBucket`). `bucketName` above remains the runtime key.
+        // `bucketStem` is the PascalCase segment naming this bucket's Lambda
+        // (empty for the default unnamed bucket). `bucketName` above remains the
+        // runtime key into `Task.bucketNames`; `name` is the bucket's own
+        // resource name, kebab-cased and plugin-qualified because S3 lowercases
+        // it — see `bucketResourceName`.
         let bucketStem = bucketSpec.bucketName->Option.mapOr("", pascalCase)
-        let name = taskName ++ bucketStem ++ "Bucket"
+        let name = bucketResourceName(
+          ~plugin=ResourceAttribution.current.contents.plugin,
+          ~task=taskName,
+          ~bucketId=bucketSpec.bucketName,
+        )
         let bucket = TaskBucket.make(~name, ~opts)
         let opts = {Pulumi.ComponentResource.parent: bucket.parts->Pulumi.Resource.makeFromJs}
 

package/src/components/Task/Task_Builder.res.mjs

@@ -1,9 +1,11 @@
 // Generated by ReScript, PLEASE EDIT WITH CARE
 
 import * as Stdlib_Dict from "@rescript/runtime/lib/es6/Stdlib_Dict.js";
+import * as Stdlib_Array from "@rescript/runtime/lib/es6/Stdlib_Array.js";
 import * as Output$Pulumi from "@reventlessdev/rescript-pulumi-pulumi/src/Output.res.mjs";
 import * as Stdlib_Option from "@rescript/runtime/lib/es6/Stdlib_Option.js";
 import * as Pulumi from "@pulumi/pulumi";
+import * as Stdlib_JsError from "@rescript/runtime/lib/es6/Stdlib_JsError.js";
 import * as Primitive_option from "@rescript/runtime/lib/es6/Primitive_option.js";
 import * as Task$ReventlessCore from "./Task.res.mjs";
 import * as Logger$ReventlessCore from "../../util/Logger.res.mjs";
@@ -13,6 +15,7 @@ import * as Util_Promise$ReventlessCore from "../../util/Util_Promise.res.mjs";
 import * as ComponentType$ReventlessCore from "../../ComponentType.res.mjs";
 import * as RuntimeHints$ReventlessInfra from "@reventlessdev/reventless-infra/src/types/RuntimeHints.res.mjs";
 import * as Builder_Helpers$ReventlessCore from "../Builder_Helpers.res.mjs";
+import * as ResourceAttribution$ReventlessCore from "../../ResourceAttribution.res.mjs";
 
 let log = Logger$ReventlessCore.fromEnv();
 
@@ -20,6 +23,28 @@ function pascalCase(s) {
   return s.split("-").flatMap(p => p.split("_")).filter(p => p.length > 0).map(p => p.slice(0, 1).toUpperCase() + p.slice(1, p.length)).join("");
 }
 
+let humpBoundary = /([a-z0-9])([A-Z])/g;
+
+let acronymBoundary = /([A-Z]+)([A-Z][a-z])/g;
+
+function kebabCase(s) {
+  return s.replace(acronymBoundary, "$1-$2").replace(humpBoundary, "$1-$2").split("-").flatMap(p => p.split("_")).filter(p => p.length > 0).map(prim => prim.toLowerCase()).join("-");
+}
+
+function bucketResourceName(plugin, task, bucketId) {
+  let name = Stdlib_Array.filterMap([
+    plugin,
+    task,
+    bucketId
+  ], segment => segment).map(kebabCase).filter(segment => segment !== "").join("-");
+  if (name.length > 55) {
+    Stdlib_JsError.throwWithMessage(`Task bucket name "` + name + `" is ` + name.length.toString() + ` characters; S3 allows ` + (55).toString() + ` once Pulumi's uniqueness suffix is added. Shorten the task name` + (
+      bucketId !== undefined ? ` or the bucket id "` + bucketId + `".` : "."
+    ));
+  }
+  return name;
+}
+
 function Make(Spec) {
   return RuntimeEnvironment => (EventCollectorChannel => (EventCollectorRuntimeBuilder => (TaskRuntimeBuilder => (TaskBucket => (SpecificSideEffectHandler => (Defaults => {
     let make = (queryBucketName, scheduler, schedulerRoleUrn, publishToAggregates, queryEngine, resourceNaming, allAggregates, runtime, opts) => Component$ReventlessCore.make(ComponentType$ReventlessCore.toString(Task$ReventlessCore.componentType), Spec.name, (extra, extra$1) => {
@@ -85,7 +110,7 @@ function Make(Spec) {
       let bucketNames = Stdlib_Option.map(config.buckets, buckets => Object.fromEntries(buckets.map(bucketSpec => {
         let bucketName = Stdlib_Option.getOr(bucketSpec.bucketName, "Bucket");
         let bucketStem = Stdlib_Option.mapOr(bucketSpec.bucketName, "", pascalCase);
-        let name = extra$1 + bucketStem + "Bucket";
+        let name = bucketResourceName(ResourceAttribution$ReventlessCore.current.contents.plugin, extra$1, bucketSpec.bucketName);
         let bucket = TaskBucket.make(name, opts);
         let opts_parent = bucket.parts;
         let opts$1 = {
@@ -112,9 +137,16 @@ function Make(Spec) {
   }))))));
 }
 
+let maxBucketNameLength = 55;
+
 export {
   log,
   pascalCase,
+  humpBoundary,
+  acronymBoundary,
+  kebabCase,
+  maxBucketNameLength,
+  bucketResourceName,
   Make,
 }
 /* log Not a pure module */

package/src/plugin/component/Plugin_Structure.res

@@ -510,11 +510,14 @@ let make = (
         // The annotation as its author wrote it. `target.plugin` is `None`
         // exactly when the field left the store unqualified, so this is the
         // source text rather than a guess at it — and this is the only place
-        // that distinction survives.
-        annotation: switch target.plugin {
-        | None => target.store
-        | Some(plugin) => plugin ++ "." ++ target.store
-        },
+        // that distinction survives. Always `Some` here: the field is optional
+        // on the type only so definitions stored before it existed still decode.
+        annotation: Some(
+          switch target.plugin {
+          | None => target.store
+          | Some(plugin) => plugin ++ "." ++ target.store
+          },
+        ),
       })
     )
 

package/src/util/StorePrefixCollision.res

@@ -0,0 +1,96 @@
+// Two declared object stores a platform cannot keep apart.
+//
+// Lives in core, not in an adapter: the rule is about a namespace, not about a
+// cloud. The deployed platform enforces it as a gate before it provisions
+// anything, and the local platform reports it at composition — one predicate, so
+// the two cannot drift into disagreeing about what a collision is.
+
+/** One declared store as the collision check sees it: its qualified key and the
+    prefix its objects are rooted at.
+
+    `site` is the `{component}.{field}` that declared it, when the caller has it.
+    The deploy-time capability list does not — `Platform.capability` carries only
+    `{plugin, store}`, and the generator renders provenance as comments in the
+    platform's generated capability file — so the deploy message points a reader
+    there instead of inventing a site it cannot know. */
+type declaredStore = {
+  qualified: string,
+  prefix: string,
+  site?: string,
+}
+
+/**
+Two stores a platform cannot keep apart.
+
+The prefix is a **platform-global** namespace, not a per-bucket one: exactly one
+distribution fronts every store bucket, and it takes one cache behavior per
+served prefix. So two stores on one prefix are unroutable in either layout — a
+shared bucket lists the prefix twice, a per-store layout lists it once per
+bucket, and CloudFront accepts neither. Left to the deploy, that surfaces as an
+AWS error naming a path pattern rather than the two plugins that caused it,
+minutes in, after the silent damage below has already been provisioned:
+intermixed objects, and a presign grant scoped by prefix that reaches into both
+stores at once.
+
+Compares **prefixes, not store names**, and on **containment, not equality**:
+`a` collides with `a/b`, because a store rooted at `a` encloses one rooted at
+`a/b` for serving, for IAM and for wiping alike. Both choices are what let a
+qualified prefix scheme relax this check without rewriting it — a qualified
+prefix simply stops colliding.
+*/
+type collision = {
+  first: declaredStore,
+  second: declaredStore,
+  /** True when the first prefix encloses the second rather than equalling it. */
+  nested: bool,
+}
+
+let collisionsFor = (~stores: array<declaredStore>): array<collision> =>
+  stores->Array.reduceWithIndex([], (found, a, i) =>
+    stores->Array.reduceWithIndex(found, (found, b, j) =>
+      if j <= i || a.qualified == b.qualified {
+        found
+      } else if a.prefix == b.prefix {
+        Array.concat(found, [{first: a, second: b, nested: false}])
+      } else if b.prefix->String.startsWith(a.prefix ++ "/") {
+        Array.concat(found, [{first: a, second: b, nested: true}])
+      } else if a.prefix->String.startsWith(b.prefix ++ "/") {
+        Array.concat(found, [{first: b, second: a, nested: true}])
+      } else {
+        found
+      }
+    )
+  )
+
+/** The refusal text. Names both declaration sites, because "two stores collide"
+    without them sends a reader hunting through every schema in the platform —
+    and states both remedies, because a cross-plugin store is legitimate when the
+    `@storageRef` annotation qualifies it, and only accidental when it does not. */
+let collisionMessage = (c: collision): string => {
+  let site = (s: declaredStore) =>
+    switch s.site {
+    | Some(site) => `  ${s.qualified} — declared at ${site}\n`
+    | None => ""
+    }
+  let sites = site(c.first) ++ site(c.second)
+  let where = sites == ""
+    ? `  Both keys appear in the platform's generated capability file, which records each ` ++
+      `declaring component and field as a comment.\n`
+    : sites
+  if c.nested {
+    `Object store "${c.first.qualified}" is rooted at "${c.first.prefix}/", which encloses ` ++
+    `"${c.second.qualified}" at "${c.second.prefix}/".\n` ++
+    where ++
+    `  One store's objects would sit inside the other's — for serving, for upload grants and ` ++
+    `for a store wipe alike. Rename one of them.`
+  } else {
+    `Object stores "${c.first.qualified}" and "${c.second.qualified}" both root their objects ` ++
+    `at "${c.first.prefix}/".\n` ++
+    where ++
+    `  A platform serves one cache behavior per prefix and scopes upload grants by prefix, so ` ++
+    `two stores cannot share one.\n` ++
+    `  Rename one store, or — if they were meant to be one shared store — qualify the ` ++
+    `\`@storageRef\` annotation with the owning plugin.`
+  }
+}
+

package/src/util/StorePrefixCollision.res.mjs

@@ -0,0 +1,55 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+
+import * as Stdlib_Array from "@rescript/runtime/lib/es6/Stdlib_Array.js";
+
+function collisionsFor(stores) {
+  return Stdlib_Array.reduceWithIndex(stores, [], (found, a, i) => Stdlib_Array.reduceWithIndex(stores, found, (found, b, j) => {
+    if (j <= i || a.qualified === b.qualified) {
+      return found;
+    } else if (a.prefix === b.prefix) {
+      return found.concat([{
+          first: a,
+          second: b,
+          nested: false
+        }]);
+    } else if (b.prefix.startsWith(a.prefix + "/")) {
+      return found.concat([{
+          first: a,
+          second: b,
+          nested: true
+        }]);
+    } else if (a.prefix.startsWith(b.prefix + "/")) {
+      return found.concat([{
+          first: b,
+          second: a,
+          nested: true
+        }]);
+    } else {
+      return found;
+    }
+  }));
+}
+
+function collisionMessage(c) {
+  let site = s => {
+    let site$1 = s.site;
+    if (site$1 !== undefined) {
+      return `  ` + s.qualified + ` — declared at ` + site$1 + `\n`;
+    } else {
+      return "";
+    }
+  };
+  let sites = site(c.first) + site(c.second);
+  let where = sites === "" ? `  Both keys appear in the platform's generated capability file, which records each declaring component and field as a comment.\n` : sites;
+  if (c.nested) {
+    return `Object store "` + c.first.qualified + `" is rooted at "` + c.first.prefix + `/", which encloses ` + (`"` + c.second.qualified + `" at "` + c.second.prefix + `/".\n`) + where + `  One store's objects would sit inside the other's — for serving, for upload grants and for a store wipe alike. Rename one of them.`;
+  } else {
+    return `Object stores "` + c.first.qualified + `" and "` + c.second.qualified + `" both root their objects ` + (`at "` + c.first.prefix + `/".\n`) + where + `  A platform serves one cache behavior per prefix and scopes upload grants by prefix, so two stores cannot share one.\n  Rename one store, or — if they were meant to be one shared store — qualify the \`@storageRef\` annotation with the owning plugin.`;
+  }
+}
+
+export {
+  collisionsFor,
+  collisionMessage,
+}
+/* No side effect */

package/tests/StorePrefixCollisionTest.res

@@ -0,0 +1,160 @@
+open JestGlobals
+
+// The rule these guard is that a store's key prefix is a PLATFORM-global
+// namespace: one distribution fronts every store bucket and takes one cache
+// behavior per prefix, so two stores on one prefix are unroutable whatever the
+// bucket layout. Left to the deploy that surfaces as a CloudFront error about a
+// path pattern, minutes in and naming neither plugin.
+
+module Collision = StorePrefixCollision
+
+let store = (~qualified, ~prefix, ~site=?): Collision.declaredStore => {
+  qualified,
+  prefix,
+  ?site,
+}
+
+describe("collisionsFor", () => {
+  testSync("distinct prefixes do not collide", () =>
+    expect(
+      Collision.collisionsFor(
+        ~stores=[
+          store(~qualified="Catalog.productImages", ~prefix="productImages"),
+          store(~qualified="Ordering.labels", ~prefix="labels"),
+        ],
+      )->Array.length,
+    )->toBe(0)
+  )
+
+  testSync("two plugins declaring one store name collide", () =>
+    switch Collision.collisionsFor(
+      ~stores=[
+        store(~qualified="Catalog.productImages", ~prefix="productImages"),
+        store(~qualified="Ordering.productImages", ~prefix="productImages"),
+      ],
+    ) {
+    | [c] => expect((c.first.qualified, c.second.qualified, c.nested))->toEqual((
+        "Catalog.productImages",
+        "Ordering.productImages",
+        false,
+      ))
+    | other => fail(`expected exactly one collision, got ${other->Array.length->Int.toString}`)
+    }
+  )
+
+  // Deliberate cross-plugin sharing resolves to ONE qualified key upstream, so
+  // it never reaches this predicate as two stores. Sharing is legitimate; only
+  // two independent claims on one prefix are not.
+  testSync("one store referenced by several plugins is a single entry, not a collision", () =>
+    expect(
+      Collision.collisionsFor(
+        ~stores=[store(~qualified="Catalog.productImages", ~prefix="productImages")],
+      )->Array.length,
+    )->toBe(0)
+  )
+
+  // Containment, not equality: a store rooted at `a` encloses one at `a/b` for
+  // serving, for upload grants and for a store wipe alike.
+  testSync("an enclosing prefix collides with what it encloses", () =>
+    switch Collision.collisionsFor(
+      ~stores=[
+        store(~qualified="Catalog.productImages", ~prefix="Catalog/productImages"),
+        store(~qualified="Legacy.catalog", ~prefix="Catalog"),
+      ],
+    ) {
+    | [c] =>
+      // The enclosing store is reported first whichever order they arrive in.
+      expect((c.first.qualified, c.nested))->toEqual(("Legacy.catalog", true))
+    | other => fail(`expected exactly one collision, got ${other->Array.length->Int.toString}`)
+    }
+  )
+
+  // A shared character run is not nesting — the delete/serve boundary is a path
+  // segment, so `images` does not reach `images-archive`.
+  testSync("a sibling prefix sharing a character run does not collide", () =>
+    expect(
+      Collision.collisionsFor(
+        ~stores=[
+          store(~qualified="Catalog.images", ~prefix="images"),
+          store(~qualified="Catalog.imagesArchive", ~prefix="images-archive"),
+        ],
+      )->Array.length,
+    )->toBe(0)
+  )
+
+  // This is the property that lets a plugin-qualified prefix scheme relax the
+  // rule without the predicate changing: qualified prefixes simply stop
+  // colliding, so "unique per platform" narrows to "unique per plugin".
+  testSync("qualifying the prefix with the plugin removes the collision", () =>
+    expect(
+      Collision.collisionsFor(
+        ~stores=[
+          store(~qualified="Catalog.productImages", ~prefix="Catalog/productImages"),
+          store(~qualified="Ordering.productImages", ~prefix="Ordering/productImages"),
+        ],
+      )->Array.length,
+    )->toBe(0)
+  )
+
+  testSync("each colliding pair is reported once, not twice", () =>
+    expect(
+      Collision.collisionsFor(
+        ~stores=[
+          store(~qualified="A.images", ~prefix="images"),
+          store(~qualified="B.images", ~prefix="images"),
+          store(~qualified="C.images", ~prefix="images"),
+        ],
+      )->Array.length,
+    )->toBe(3)
+  )
+})
+
+describe("collisionMessage", () => {
+  testSync("names both stores and both remedies", () => {
+    let message =
+      Collision.collisionsFor(
+        ~stores=[
+          store(~qualified="Catalog.productImages", ~prefix="productImages"),
+          store(~qualified="Ordering.productImages", ~prefix="productImages"),
+        ],
+      )
+      ->Array.get(0)
+      ->Option.mapOr("", Collision.collisionMessage)
+    expect(
+      message->String.includes("Catalog.productImages") &&
+      message->String.includes("Ordering.productImages") &&
+      message->String.includes("Rename one store") &&
+      message->String.includes("@storageRef"),
+    )->toBe(true)
+  })
+
+  // Without provenance the message must not invent a declaration site; it points
+  // at the file that does record one.
+  testSync("points at the capability file when it has no declaration site", () => {
+    let message =
+      Collision.collisionsFor(
+        ~stores=[
+          store(~qualified="A.images", ~prefix="images"),
+          store(~qualified="B.images", ~prefix="images"),
+        ],
+      )
+      ->Array.get(0)
+      ->Option.mapOr("", Collision.collisionMessage)
+    expect(message->String.includes("capability file"))->toBe(true)
+  })
+
+  testSync("uses the declaration site when the caller has one", () => {
+    let message =
+      Collision.collisionsFor(
+        ~stores=[
+          store(~qualified="A.images", ~prefix="images", ~site="Product.imageUrl"),
+          store(~qualified="B.images", ~prefix="images", ~site="Shipment.imageUrl"),
+        ],
+      )
+      ->Array.get(0)
+      ->Option.mapOr("", Collision.collisionMessage)
+    expect(
+      message->String.includes("Product.imageUrl") && message->String.includes("Shipment.imageUrl"),
+    )->toBe(true)
+  })
+})