@reventlessdev/reventless-core 3.0.0-alpha.191 → 3.0.0-alpha.193

package/src/plugin/component/Plugin_Structure.res

@@ -481,23 +481,34 @@ let make = (
   // An unqualified store belongs to the declaring plugin, so every collected
   // entry is qualified to `{plugin}.{store}` — one shape, and the string is
   // directly the store's identity. Many fields legitimately name one store, so
-  // the result is deduplicated.
-
-  let storesFromProperties = (properties: dict<S.t<unknown>>): array<string> =>
+  // the key set is deduplicated.
+  //
+  // Each collected entry keeps its declaration site `(component, field)` as
+  // provenance, and `requiredStores` is derived from the collected entries —
+  // one walk, so the capability manifest's provenance and the deploy's key set
+  // cannot come from different readings of the schemas.
+
+  let storesFromProperties = (~component, properties: dict<S.t<unknown>>): array<
+    Reventless.Plugin.requiredStoreDeclaration,
+  > =>
     properties
     ->Dict.toArray
-    ->Array.filterMap(((_, fieldSchema)) =>
-      Reventless.StorageRef.getStore(fieldSchema)->Option.map(target =>
-        target.plugin->Option.getOr(name) ++ "." ++ target.store
-      )
+    ->Array.filterMap(((field, fieldSchema)) =>
+      Reventless.StorageRef.getStore(fieldSchema)->Option.map(target => {
+        Reventless.Plugin.store: target.plugin->Option.getOr(name) ++ "." ++ target.store,
+        component,
+        field,
+      })
     )
 
   // Commands and events are unions of per-variant objects; state is a single
   // object. Both reduce to "the properties of every object in this schema".
-  let storesFromSchema = (schema: S.t<unknown>): array<string> => {
+  let storesFromSchema = (~component, schema: S.t<unknown>): array<
+    Reventless.Plugin.requiredStoreDeclaration,
+  > => {
     let fromVariant = v =>
       switch v {
-      | S.Object({properties}) => storesFromProperties(properties)
+      | S.Object({properties}) => storesFromProperties(~component, properties)
       | _ => []
       }
     switch schema {
@@ -506,37 +517,82 @@ let make = (
     }
   }
 
-  let requiredStores =
+  let compareDeclarations = (
+    a: Reventless.Plugin.requiredStoreDeclaration,
+    b: Reventless.Plugin.requiredStoreDeclaration,
+  ) => {
+    let byStore = String.compare(a.store, b.store)
+    if byStore != Ordering.equal {
+      byStore
+    } else {
+      let byComponent = String.compare(a.component, b.component)
+      if byComponent != Ordering.equal {
+        byComponent
+      } else {
+        String.compare(a.field, b.field)
+      }
+    }
+  }
+
+  // The (component, schema) sites the store walk reads. One list feeds both the
+  // declared-store collection and the heuristic lint below, so a field is read
+  // exactly once: either its declaration is collected, or its name is eligible
+  // to warn — never a third reading that could disagree with both.
+  let storeDeclarationSites: array<(string, S.t<unknown>)> =
     [
-      aggregates->Array.flatMap((module(A: ReventlessInfra.Aggregate.T with type api = api)) =>
-        Array.concat(
-          storesFromSchema(A.Spec.commandSchema->S.castToUnknown),
-          storesFromSchema(A.Spec.eventSchema->S.castToUnknown),
-        )
-      ),
-      stateChangeSlices->Array.flatMap((module(SCS: ReventlessInfra.StateChangeSlice.T)) =>
-        Array.concat(
-          storesFromSchema(SCS.Spec.commandSchema->S.castToUnknown),
-          storesFromSchema(SCS.Spec.eventSchema->S.castToUnknown),
-        )
-      ),
-      stateViewSlices->Array.flatMap((module(SVS: ReventlessInfra.StateViewSlice.T)) =>
-        storesFromSchema(SVS.Spec.stateSchema->S.castToUnknown)
-      ),
-      readModels->Array.flatMap((
+      aggregates->Array.flatMap((module(A: ReventlessInfra.Aggregate.T with type api = api)) => [
+        (A.Spec.name, A.Spec.commandSchema->S.castToUnknown),
+        (A.Spec.name, A.Spec.eventSchema->S.castToUnknown),
+      ]),
+      stateChangeSlices->Array.flatMap((module(SCS: ReventlessInfra.StateChangeSlice.T)) => [
+        (SCS.Spec.name, SCS.Spec.commandSchema->S.castToUnknown),
+        (SCS.Spec.name, SCS.Spec.eventSchema->S.castToUnknown),
+      ]),
+      stateViewSlices->Array.map((module(SVS: ReventlessInfra.StateViewSlice.T)) => (
+        SVS.Spec.name,
+        SVS.Spec.stateSchema->S.castToUnknown,
+      )),
+      readModels->Array.map((
         module(R: ReventlessInfra.ReadModel.T with type api = api and type role = role),
-      ) => storesFromSchema(R.Spec.stateSchema->S.castToUnknown)),
-      automationSlices->Array.flatMap((module(AS: ReventlessInfra.AutomationSlice.T)) =>
-        storesFromSchema(AS.Spec.commandSchema->S.castToUnknown)
-      ),
-      inboundTranslationSlices->Array.flatMap((
+      ) => (R.Spec.name, R.Spec.stateSchema->S.castToUnknown)),
+      automationSlices->Array.map((module(AS: ReventlessInfra.AutomationSlice.T)) => (
+        AS.Spec.name,
+        AS.Spec.commandSchema->S.castToUnknown,
+      )),
+      inboundTranslationSlices->Array.map((
         module(ITS: ReventlessInfra.InboundTranslationSlice.T),
-      ) => storesFromSchema(ITS.Spec.commandSchema->S.castToUnknown)),
-    ]
-    ->Array.flat
+      ) => (ITS.Spec.name, ITS.Spec.commandSchema->S.castToUnknown)),
+    ]->Array.flat
+
+  // Sorted so the emitted manifest is deterministic; identical triples collapse
+  // (one store named by a component's command field and again by its event
+  // field under the same field name is one declaration site).
+  let requiredStoreDeclarations =
+    storeDeclarationSites
+    ->Array.flatMap(((component, schema)) => storesFromSchema(~component, schema))
+    ->Array.toSorted(compareDeclarations)
+    ->Array.reduce([], (acc, d) =>
+      switch acc->Array.last {
+      | Some(prev) if prev == d => acc
+      | _ => acc->Array.concat([d])
+      }
+    )
+
+  let requiredStores =
+    requiredStoreDeclarations
+    ->Array.map(d => d.store)
     ->Belt.Set.String.fromArray
     ->Belt.Set.String.toArray
 
+  // Heuristic-only matches — a field *named* like a stored-object ref with no
+  // `@storageRef` — warn and provision nothing. Declaration outranks inference;
+  // the warning names the annotation that would settle it.
+  storeDeclarationSites->Array.forEach(((component, schema)) =>
+    Capability_Inference.scanSchema(~component, schema)->Array.forEach(w =>
+      log.warn(~comp="Plugin_Structure", Capability_Inference.message(w))
+    )
+  )
+
   // ── Build queryable defs ───────────────────────────────────────────────────
   //
   // Internal ReadModels and StateViewSlices (marked `@@reventless.visibility(Internal)`)
@@ -755,5 +811,6 @@ let make = (
     extensions: extensionDefs,
     extensionPoints: Some(extensionPointDefs),
     requiredStores: Some(requiredStores),
+    requiredStoreDeclarations: Some(requiredStoreDeclarations),
   }
 }

package/src/plugin/component/Plugin_Structure.res.mjs

@@ -5,6 +5,8 @@ import * as Stdlib_Array from "@rescript/runtime/lib/es6/Stdlib_Array.js";
 import * as Primitive_int from "@rescript/runtime/lib/es6/Primitive_int.js";
 import * as Stdlib_Option from "@rescript/runtime/lib/es6/Stdlib_Option.js";
 import * as Belt_SetString from "@rescript/runtime/lib/es6/Belt_SetString.js";
+import * as Primitive_object from "@rescript/runtime/lib/es6/Primitive_object.js";
+import * as Primitive_string from "@rescript/runtime/lib/es6/Primitive_string.js";
 import * as DcbTag$Reventless from "@reventlessdev/reventless-spec/src/components/DcbTag.res.mjs";
 import * as Reference$Reventless from "@reventlessdev/reventless-spec/src/components/Reference.res.mjs";
 import * as Logger$ReventlessCore from "../../util/Logger.res.mjs";
@@ -15,6 +17,7 @@ import * as SchemaType$ReventlessCore from "../../components/Api/SchemaType.res.
 import * as StateAnnotations$Reventless from "@reventlessdev/reventless-spec/src/components/StateAnnotations.res.mjs";
 import * as ApiNoApiHelpers$ReventlessCore from "../../components/Api/ApiNoApiHelpers.res.mjs";
 import * as SuryToJsonSchema$ReventlessCore from "../../components/Api/SuryToJsonSchema.res.mjs";
+import * as Capability_Inference$ReventlessCore from "./Capability_Inference.res.mjs";
 import * as ApiTargetStateHelpers$ReventlessCore from "../../components/Api/ApiTargetStateHelpers.res.mjs";
 import * as ApiAllowedStatesHelpers$ReventlessCore from "../../components/Api/ApiAllowedStatesHelpers.res.mjs";
 
@@ -386,11 +389,70 @@ function make(name, aggregatesOpt, readModelsOpt, stateViewSlicesOpt, stateChang
     let match$3 = scored[0];
     return match$3[0];
   };
-  let storesFromSchema = schema => {
+  let compareDeclarations = (a, b) => {
+    let byStore = Primitive_string.compare(a.store, b.store);
+    if (byStore !== 0) {
+      return byStore;
+    }
+    let byComponent = Primitive_string.compare(a.component, b.component);
+    if (byComponent !== 0) {
+      return byComponent;
+    } else {
+      return Primitive_string.compare(a.field, b.field);
+    }
+  };
+  let storeDeclarationSites = [
+    aggregates.flatMap(A => [
+      [
+        A.Spec.name,
+        A.Spec.commandSchema
+      ],
+      [
+        A.Spec.name,
+        A.Spec.eventSchema
+      ]
+    ]),
+    stateChangeSlices.flatMap(SCS => [
+      [
+        SCS.Spec.name,
+        SCS.Spec.commandSchema
+      ],
+      [
+        SCS.Spec.name,
+        SCS.Spec.eventSchema
+      ]
+    ]),
+    stateViewSlices.map(SVS => [
+      SVS.Spec.name,
+      SVS.Spec.stateSchema
+    ]),
+    readModels.map(R => [
+      R.Spec.name,
+      R.Spec.stateSchema
+    ]),
+    automationSlices.map(AS => [
+      AS.Spec.name,
+      AS.Spec.commandSchema
+    ]),
+    inboundTranslationSlices.map(ITS => [
+      ITS.Spec.name,
+      ITS.Spec.commandSchema
+    ])
+  ].flat();
+  let requiredStoreDeclarations = Stdlib_Array.reduce(storeDeclarationSites.flatMap(param => {
+    let component = param[0];
+    let schema = param[1];
     let fromVariant = v => {
       if (v.type === "object") {
         let properties = v.properties;
-        return Stdlib_Array.filterMap(Object.entries(properties), param => Stdlib_Option.map(StorageRef$Reventless.getStore(param[1]), target => Stdlib_Option.getOr(target.plugin, name) + "." + target.store));
+        return Stdlib_Array.filterMap(Object.entries(properties), param => {
+          let field = param[0];
+          return Stdlib_Option.map(StorageRef$Reventless.getStore(param[1]), target => ({
+            store: Stdlib_Option.getOr(target.plugin, name) + "." + target.store,
+            component: component,
+            field: field
+          }));
+        });
       } else {
         return [];
       }
@@ -400,15 +462,22 @@ function make(name, aggregatesOpt, readModelsOpt, stateViewSlicesOpt, stateChang
     } else {
       return fromVariant(schema);
     }
-  };
-  let requiredStores = Belt_SetString.toArray(Belt_SetString.fromArray([
-    aggregates.flatMap(A => storesFromSchema(A.Spec.commandSchema).concat(storesFromSchema(A.Spec.eventSchema))),
-    stateChangeSlices.flatMap(SCS => storesFromSchema(SCS.Spec.commandSchema).concat(storesFromSchema(SCS.Spec.eventSchema))),
-    stateViewSlices.flatMap(SVS => storesFromSchema(SVS.Spec.stateSchema)),
-    readModels.flatMap(R => storesFromSchema(R.Spec.stateSchema)),
-    automationSlices.flatMap(AS => storesFromSchema(AS.Spec.commandSchema)),
-    inboundTranslationSlices.flatMap(ITS => storesFromSchema(ITS.Spec.commandSchema))
-  ].flat()));
+  }).toSorted(compareDeclarations), [], (acc, d) => {
+    let prev = Stdlib_Array.last(acc);
+    if (prev !== undefined) {
+      if (Primitive_object.equal(prev, d)) {
+        return acc;
+      } else {
+        return acc.concat([d]);
+      }
+    } else {
+      return acc.concat([d]);
+    }
+  });
+  let requiredStores = Belt_SetString.toArray(Belt_SetString.fromArray(requiredStoreDeclarations.map(d => d.store)));
+  storeDeclarationSites.forEach(param => {
+    Capability_Inference$ReventlessCore.scanSchema(param[0], param[1]).forEach(w => log.warn("Plugin_Structure", undefined, Capability_Inference$ReventlessCore.message(w)));
+  });
   let visibilityTag = v => {
     if (v === "Public") {
       return;
@@ -554,7 +623,8 @@ function make(name, aggregatesOpt, readModelsOpt, stateViewSlicesOpt, stateChang
     inboundTranslationSlices: inboundTranslationSliceDefs,
     extensions: extensionDefs,
     extensionPoints: extensionPointDefs,
-    requiredStores: requiredStores
+    requiredStores: requiredStores,
+    requiredStoreDeclarations: requiredStoreDeclarations
   };
 }
 

package/tests/admin/Platform_ComponentDefinitionsApiTest.res

@@ -87,6 +87,7 @@ let structure: pluginStructure = {
   ],
   extensionPoints: None,
   requiredStores: None,
+  requiredStoreDeclarations: None,
 }
 
 let encoded = Platform_ComponentDefinitionsApi.encodePluginStructureEntry(
@@ -300,6 +301,7 @@ describe("allowedStates + statusField populated", () => {
     extensions: [],
     extensionPoints: None,
     requiredStores: None,
+    requiredStoreDeclarations: None,
   }
 
   let json =

package/tests/admin/Platform_ComponentDefinitionsApiTest.res.mjs

@@ -122,7 +122,8 @@ let structure = {
   inboundTranslationSlices: structure_inboundTranslationSlices,
   extensions: structure_extensions,
   extensionPoints: undefined,
-  requiredStores: undefined
+  requiredStores: undefined,
+  requiredStoreDeclarations: undefined
 };
 
 let encoded = Platform_ComponentDefinitionsApi$ReventlessCore.encodePluginStructureEntry("Catalog", structure);
@@ -221,7 +222,8 @@ globalThis.describe("translation-slice externalSystem round-trip", () => {
     inboundTranslationSlices: externalStructure_inboundTranslationSlices,
     extensions: externalStructure_extensions,
     extensionPoints: undefined,
-    requiredStores: undefined
+    requiredStores: undefined,
+    requiredStoreDeclarations: undefined
   };
   let externalJson = JSON.stringify(Platform_ComponentDefinitionsApi$ReventlessCore.encodePluginStructureEntry("Catalog", externalStructure));
   globalThis.test("surfaces Some outbound externalSystem as its inner string", () => {
@@ -272,7 +274,8 @@ globalThis.describe("visibility filtering (deployed AutoUI hides Internal)", ()
     inboundTranslationSlices: mixed_inboundTranslationSlices,
     extensions: mixed_extensions,
     extensionPoints: undefined,
-    requiredStores: undefined
+    requiredStores: undefined,
+    requiredStoreDeclarations: undefined
   };
   let mixedJson = JSON.stringify(Platform_ComponentDefinitionsApi$ReventlessCore.encodePluginStructureEntry("Ordering", mixed));
   globalThis.test("excludes an Internal queryableDef from the encoded read-side", () => {
@@ -351,7 +354,8 @@ globalThis.describe("allowedStates + statusField populated", () => {
     inboundTranslationSlices: structureWithStates_inboundTranslationSlices,
     extensions: structureWithStates_extensions,
     extensionPoints: undefined,
-    requiredStores: undefined
+    requiredStores: undefined,
+    requiredStoreDeclarations: undefined
   };
   let json = JSON.stringify(Platform_ComponentDefinitionsApi$ReventlessCore.encodePluginStructureEntry("Platform", structureWithStates));
   globalThis.test("encodes populated allowedStates as a JSON array", () => {

package/tests/api/SuryToJsonSchemaTest.res

@@ -619,4 +619,46 @@ describe("SuryToJsonSchema:", () => {
       expect(semanticOf(json, "imageUrl"))->toEqual(Some(JSON.Encode.string("storageRef")))
     })
   })
+
+  // The claim the branded scalars rest on: marking a field adds an annotation,
+  // not a shape. A string stays a string and a number stays a number on the
+  // wire, which is what makes them retrofittable onto a log that already has
+  // events in it. One of each is enough — the emission path is the same for all
+  // seven, and it is the *shape* half that is the load-bearing assertion here.
+  describe("branded scalars keep their underlying shape:", () => {
+    let fieldOf = (json, name) => getPropertyOf(json, name)
+    let keyOf = (json, name, key) => fieldOf(json, name)->Option.flatMap(s => getProperty(s, key))
+
+    let json = SuryToJsonSchema.deriveObjectSchema(
+      S.schema(s =>
+        {
+          "contactEmail": s.matches(Reventless.Email.schema),
+          "taxRate": s.matches(Reventless.Percent.schema),
+        }
+      )->S.castToUnknown,
+    )
+
+    testSync("a string scalar stays a string and carries its id", () =>
+      expect((
+        keyOf(json, "contactEmail", "type"),
+        keyOf(json, "contactEmail", "x-reventless-semantic"),
+      ))->toEqual((Some(JSON.Encode.string("string")), Some(JSON.Encode.string("email"))))
+    )
+
+    testSync("a numeric scalar stays a number and carries its id", () =>
+      expect((
+        keyOf(json, "taxRate", "type"),
+        keyOf(json, "taxRate", "x-reventless-semantic"),
+      ))->toEqual((Some(JSON.Encode.string("number")), Some(JSON.Encode.string("percent"))))
+    )
+
+    // The provenance half: a typed field outranks an annotated one, and this is
+    // the key a consumer reads to tell them apart.
+    testSync("both name the type as their source", () =>
+      expect((
+        keyOf(json, "contactEmail", "x-reventless-semantic-source"),
+        keyOf(json, "taxRate", "x-reventless-semantic-source"),
+      ))->toEqual((Some(JSON.Encode.string("type")), Some(JSON.Encode.string("type"))))
+    )
+  })
 })

package/tests/api/SuryToJsonSchemaTest.res.mjs

@@ -4,8 +4,10 @@ import * as S from "sury/src/S.res.mjs";
 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 Email$Reventless from "@reventlessdev/reventless-spec/src/semantic/Email.res.mjs";
 import * as Primitive_string from "@rescript/runtime/lib/es6/Primitive_string.js";
 import * as DcbTag$Reventless from "@reventlessdev/reventless-spec/src/components/DcbTag.res.mjs";
+import * as Percent$Reventless from "@reventlessdev/reventless-spec/src/semantic/Percent.res.mjs";
 import * as DateTime$Reventless from "@reventlessdev/reventless-spec/src/types/DateTime.res.mjs";
 import * as Reference$Reventless from "@reventlessdev/reventless-spec/src/components/Reference.res.mjs";
 import * as StorageRef$Reventless from "@reventlessdev/reventless-spec/src/semantic/StorageRef.res.mjs";
@@ -937,6 +939,40 @@ globalThis.describe("SuryToJsonSchema:", () => {
       globalThis.expect(semanticOf(json, "imageUrl")).toEqual("storageRef");
     });
   });
+  globalThis.describe("branded scalars keep their underlying shape:", () => {
+    let keyOf = (json, name, key) => Stdlib_Option.flatMap(getPropertyOf(json, name), s => getProperty(s, key));
+    let json = SuryToJsonSchema$ReventlessCore.deriveObjectSchema(S.schema(s => ({
+      contactEmail: s.m(Email$Reventless.schema),
+      taxRate: s.m(Percent$Reventless.schema)
+    })));
+    globalThis.test("a string scalar stays a string and carries its id", () => {
+      globalThis.expect([
+        keyOf(json, "contactEmail", "type"),
+        keyOf(json, "contactEmail", "x-reventless-semantic")
+      ]).toEqual([
+        "string",
+        "email"
+      ]);
+    });
+    globalThis.test("a numeric scalar stays a number and carries its id", () => {
+      globalThis.expect([
+        keyOf(json, "taxRate", "type"),
+        keyOf(json, "taxRate", "x-reventless-semantic")
+      ]).toEqual([
+        "number",
+        "percent"
+      ]);
+    });
+    globalThis.test("both name the type as their source", () => {
+      globalThis.expect([
+        keyOf(json, "contactEmail", "x-reventless-semantic-source"),
+        keyOf(json, "taxRate", "x-reventless-semantic-source")
+      ]).toEqual([
+        "type",
+        "type"
+      ]);
+    });
+  });
 });
 
 export {

package/tests/message/MessageTest.res

@@ -131,6 +131,7 @@ describe("Message should", () => {
         extensions: [],
         extensionPoints: None,
         requiredStores: None,
+        requiredStoreDeclarations: None,
       }),
       dcbEventLog: None,
       kind: Domain,

package/tests/message/MessageTest.res.mjs

@@ -118,7 +118,8 @@ globalThis.describe("Message should", () => {
         inboundTranslationSlices: [],
         extensions: [],
         extensionPoints: undefined,
-        requiredStores: undefined
+        requiredStores: undefined,
+        requiredStoreDeclarations: undefined
       },
       dcbEventLog: undefined,
       kind: "Domain"

package/tests/plugin/PluginStructureTest.res

@@ -93,6 +93,20 @@ module PsAttachInvoiceSlice: ReventlessInfra.StateChangeSlice.T = {
   let make = (~dcbEventLog as _, ~publishJsons as _, ~tagKeysByEventType as _=?, ~crossPartitionTagKeys as _=?, ~runtime as _=?, ~opts as _=?): component => Obj.magic(0)
 }
 
+module PsChangePhotoSlice: ReventlessInfra.StateChangeSlice.T = {
+  module Spec = PsChangePhoto
+  module Behavior = {
+    type state = PsChangePhoto.state
+    let initialState = PsChangePhoto.initialState
+    let evolve = PsChangePhoto.evolve
+    let decide = PsChangePhoto.decide
+    let moduleUrl = PsChangePhoto.moduleUrl
+  }
+  let isAsync = false
+  type component = scsComponent
+  let make = (~dcbEventLog as _, ~publishJsons as _, ~tagKeysByEventType as _=?, ~crossPartitionTagKeys as _=?, ~runtime as _=?, ~opts as _=?): component => Obj.magic(0)
+}
+
 let structure = Plugin_Structure.make(
   ~name="TestPlugin",
   ~stateChangeSlices=[module(PsPlaceOrderSlice), module(PsShipOrderSlice)],
@@ -675,5 +689,136 @@ describe("Plugin_Structure.make — Phase 2 graph fields", () => {
     testSync("a plugin declaring no stores collects none — not None", () =>
       expect(structure.requiredStores)->toEqual(Some([]))
     )
+
+    testSync("each requirement keeps its declaring (component, field) sites", () => {
+      // `documents` is declared on a command field AND an event field of the
+      // same component under the same field name — one declaration site, so
+      // the identical triples collapse to one entry.
+      let expected: array<Reventless.Plugin.requiredStoreDeclaration> = [
+        {store: "TestPlugin.documents", component: "AttachInvoice", field: "documentUrl"},
+        {store: "branding.logos", component: "AttachInvoice", field: "logoUrl"},
+      ]
+      expect(withStores.requiredStoreDeclarations)->toEqual(Some(expected))
+    })
+
+    // The manifest is a rendering of the structure. Its key set must be
+    // byte-identical to what the deployed plugin reports as `requiredStores`,
+    // because the deploy-time coverage assertion compares against exactly that
+    // — this equality is the whole contract of `capabilities.json`.
+    describe("capability manifest", () => {
+      let manifest = Reventless.CapabilityManifest.fromStructure(withStores)
+
+      testSync("keys are byte-identical to requiredStores", () =>
+        expect(manifest.capabilities->Array.map(c => c.key))->toEqual(
+          withStores.requiredStores->Option.getOr([]),
+        )
+      )
+
+      testSync("each entry carries its provenance", () => {
+        let entry =
+          manifest.capabilities->Array.find(c => c.key == "TestPlugin.documents")->Option.getOrThrow
+        let expected: array<Reventless.CapabilityManifest.provenance> = [
+          {component: "AttachInvoice", field: "documentUrl"},
+        ]
+        expect(entry.declaredBy)->toEqual(expected)
+      })
+
+      testSync("a structure declaring nothing yields an empty list, not a missing manifest", () =>
+        expect(Reventless.CapabilityManifest.fromStructure(structure).capabilities)->toEqual([])
+      )
+
+      testSync("rendering is deterministic and newline-terminated", () => {
+        let rendered = Reventless.CapabilityManifest.renderForStructure(withStores)
+        expect(rendered)->toBe(
+          `{
+  "capabilities": [
+    {
+      "kind": "ObjectStore",
+      "key": "TestPlugin.documents",
+      "declaredBy": [
+        {
+          "component": "AttachInvoice",
+          "field": "documentUrl"
+        }
+      ]
+    },
+    {
+      "kind": "ObjectStore",
+      "key": "branding.logos",
+      "declaredBy": [
+        {
+          "component": "AttachInvoice",
+          "field": "logoUrl"
+        }
+      ]
+    }
+  ]
+}
+`,
+        )
+      })
+    })
+  })
+
+  // Declarations are authoritative; the name heuristics are a lint. A
+  // heuristic-only match warns and never reaches the manifest, so nothing is
+  // provisioned from a guess — `imageUrl` is genuinely ambiguous between an
+  // uploaded object and an external URL, and only the author can settle it.
+  describe("capability inference", () => {
+    let commandWarnings = Capability_Inference.scanSchema(
+      ~component="ChangePhoto",
+      PsChangePhoto.commandSchema->S.castToUnknown,
+    )
+    let eventWarnings = Capability_Inference.scanSchema(
+      ~component="ChangePhoto",
+      PsChangePhoto.eventSchema->S.castToUnknown,
+    )
+
+    testSync("a heuristic-only match produces a warning", () => {
+      let expected: array<Capability_Inference.warning> = [
+        {component: "ChangePhoto", field: "photoUrl"},
+      ]
+      expect(commandWarnings)->toEqual(expected)
+    })
+
+    testSync("a declared field with a heuristic name does not warn", () => {
+      // The event's `thumbnail` matches the name heuristic but carries
+      // @storageRef — only the undeclared `photoUrl` warns.
+      let expected: array<Capability_Inference.warning> = [
+        {component: "ChangePhoto", field: "photoUrl"},
+      ]
+      expect(eventWarnings)->toEqual(expected)
+    })
+
+    testSync("a heuristic-only match reaches no manifest entry", () => {
+      let withHeuristicField = Plugin_Structure.make(
+        ~name="TestPlugin",
+        ~stateChangeSlices=[module(PsChangePhotoSlice)],
+      )
+      // Only the *declared* `thumbnail` store is collected; `photoUrl` — the
+      // heuristic-only match — provisions nothing.
+      expect(withHeuristicField.requiredStores)->toEqual(Some(["TestPlugin.productPhotos"]))
+      let manifest = Reventless.CapabilityManifest.fromStructure(withHeuristicField)
+      expect(
+        manifest.capabilities->Array.every(entry =>
+          entry.declaredBy->Array.every(site => site.field != "photoUrl")
+        ),
+      )->toBe(true)
+    })
+
+    testSync("the warning names the field and the settling annotation", () => {
+      let text =
+        commandWarnings->Array.getUnsafe(0)->Capability_Inference.message
+      expect(text->String.includes("ChangePhoto.photoUrl"))->toBe(true)
+      expect(text->String.includes("@storageRef"))->toBe(true)
+    })
+
+    testSync("suffix and exact name rules match; ordinary names do not", () => {
+      expect(
+        ["invoiceFileRef", "upload", "thumbnail", "customerName", "documentUrl"]->Array.map(
+          Capability_Inference.nameMatches,
+        ),
+      )->toEqual([true, true, true, false, false])
+    })
   })
 })