@reventlessdev/reventless-spec 3.0.0-alpha.85 → 3.0.0-alpha.87

package/CHANGELOG.md

@@ -3,6 +3,22 @@
 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.87 (2026-07-30)
+
+### Bug Fixes
+
+* **spec,core:** record the storageRef annotation instead of inferring it ([06fb5d6](https://github.com/ReventlessDev/reventless-core/commit/06fb5d671db91fb536acefd0c2db69d98671da39))
+* **spec:** read a semantic marker through an optional field's wrapper ([abebaa9](https://github.com/ReventlessDev/reventless-core/commit/abebaa9e6c73986765bb3de589ba0414eb0d85da))
+
+
+# 3.0.0-alpha.86 (2026-07-30)
+
+### Features
+
+* **spec,local:** resolve capability manifests beyond the example topology ([8bfadd5](https://github.com/ReventlessDev/reventless-core/commit/8bfadd5beef90c0c9f6f6f3fbb753c8b789469ed))
+* **spec:** semantic branded scalars — Email, Url, Phone, Percent, Color, Bytes, Duration ([2e64ff9](https://github.com/ReventlessDev/reventless-core/commit/2e64ff992e913c038a71659c731c25a104e3c5a9))
+
+
 # 3.0.0-alpha.85 (2026-07-30)
 
 ### Features

package/package.json

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

package/src/components/CapabilityManifest.res

@@ -17,9 +17,14 @@ emits the platform's capability list from them.
 type kind = ObjectStore
 
 /** The declaration site: the component's spec name and the field carrying the
-    `@storageRef` annotation. */
+    `@storageRef` annotation, plus the store exactly as that field spells it.
+
+    `annotation` is optional only to keep reading a manifest emitted before it
+    existed: a plugin built earlier still parses, and a reader that cannot say
+    what the source says omits the claim rather than inventing one. Every
+    manifest emitted now carries it. */
 @schema
-type provenance = {component: string, field: string}
+type provenance = {component: string, field: string, annotation?: string}
 
 @schema
 type entry = {
@@ -50,7 +55,9 @@ let fromStructure = (structure: Plugin.pluginStructure): t => {
       kind: ObjectStore,
       key,
       declaredBy: declarations->Array.filterMap(d =>
-        d.store == key ? Some({component: d.component, field: d.field}) : None
+        d.store == key
+          ? Some({component: d.component, field: d.field, annotation: d.annotation})
+          : None
       ),
     }),
   }

package/src/components/CapabilityManifest.res.mjs

@@ -8,7 +8,8 @@ let kindSchema = S.literal("ObjectStore");
 
 let provenanceSchema = S.schema(s => ({
   component: s.m(S.string),
-  field: s.m(S.string)
+  field: s.m(S.string),
+  annotation: s.m(S.option(S.string))
 }));
 
 let entrySchema = S.schema(s => ({
@@ -31,7 +32,8 @@ function fromStructure(structure) {
         if (d.store === key) {
           return {
             component: d.component,
-            field: d.field
+            field: d.field,
+            annotation: d.annotation
           };
         }
       })

package/src/components/Plugin.res

@@ -386,12 +386,20 @@ One field's store requirement, with its provenance.
 carries; `component` and `field` name the declaration site. The site matters
 because a requirement only ever changes by editing a field — when a rename
 removes a store from the manifest, the diff has to say which field caused it.
+
+`annotation` is the store exactly as the field spells it — bare for a store
+the declaring plugin owns, qualified for a foreign one. It is recorded rather
+than reconstructed: only here is the owning plugin unambiguous, so anything
+downstream would have to infer it by comparing a registered plugin name with
+whatever name a deploy manifest happened to use, and those were never required
+to match.
 */
 @schema
 type requiredStoreDeclaration = {
   store: string,
   component: string,
   field: string,
+  annotation: string,
 }
 
 let requiredStoreDeclarationArrayOptionSchema = _jsNullable(

package/src/components/Plugin.res.mjs

@@ -181,7 +181,8 @@ let extensionPointDefArrayOptionSchema = SuryResMjs.js_nullable(S.array(extensio
 let requiredStoreDeclarationSchema = S.schema(s => ({
   store: s.m(S.string),
   component: s.m(S.string),
-  field: s.m(S.string)
+  field: s.m(S.string),
+  annotation: s.m(S.string)
 }));
 
 let requiredStoreDeclarationArrayOptionSchema = SuryResMjs.js_nullable(S.array(requiredStoreDeclarationSchema));

package/src/generator/PlatformCodegen.res

@@ -22,6 +22,7 @@ type provenance = {
   pluginName: string,
   component: string,
   field: string,
+  annotation: option<string>,
 }
 
 /** One capability the platform must provision: the qualified `{plugin}.{store}`
@@ -45,6 +46,7 @@ let union = (manifests: array<pluginManifest>): array<unionEntry> => {
           pluginName,
           component: site.component,
           field: site.field,
+          annotation: site.annotation,
         })
       switch byKey->Dict.get(entry.key) {
       | Some(existing) =>
@@ -71,17 +73,17 @@ let splitKey = (key: string): option<(string, string)> =>
     key->String.slice(~start=i + 1),
   ))
 
-// The provenance comment quotes the annotation as its author wrote it: a store
-// declared by its own plugin is unqualified, a foreign store keeps the
-// qualified form. The manifest carries only the deploy-manifest plugin name
-// (lowercase by convention) while the key carries the registered name, so the
-// comparison is case-insensitive — and it only shapes a comment.
-let annotationStore = (~pluginName, ~key): string =>
-  switch splitKey(key) {
-  | Some((keyPlugin, store)) if keyPlugin->String.toLowerCase == pluginName->String.toLowerCase => store
-  | _ => key
-  }
-
+// The provenance comment quotes the annotation as its author wrote it — taken
+// from the manifest, which recorded it at the one place the owning plugin was
+// unambiguous. Inferring it here is what this replaced: the manifest carries a
+// deploy-manifest entry name and the key carries the registered name, and no
+// rule relates the two (`platform-inspector` against `PlatformInspector` is an
+// ordinary pairing), so any comparison here eventually quotes a string that is
+// in no source file.
+//
+// A site with no recorded annotation predates the recording. It still names the
+// field, which is the comment's job; it just makes no claim about the source
+// text it cannot see.
 let renderEntry = (entry: unionEntry): result<array<string>, string> =>
   switch splitKey(entry.key) {
   | None =>
@@ -90,11 +92,13 @@ let renderEntry = (entry: unionEntry): result<array<string>, string> =>
     )
   | Some((plugin, store)) => {
       let comments =
-        entry.declaredBy->Array.map(site =>
-          `  // ${site.pluginName}: ${site.component}.${site.field} @storageRef(${quote(
-              annotationStore(~pluginName=site.pluginName, ~key=entry.key),
-            )})`
-        )
+        entry.declaredBy->Array.map(site => {
+          let site_ = `  // ${site.pluginName}: ${site.component}.${site.field}`
+          switch site.annotation {
+          | Some(annotation) => `${site_} @storageRef(${quote(annotation)})`
+          | None => site_
+          }
+        })
       let line = switch entry.kind {
       | ObjectStore => `  ObjectStore({plugin: ${quote(plugin)}, store: ${quote(store)}}),`
       }

package/src/generator/PlatformCodegen.res.mjs

@@ -14,7 +14,8 @@ function union(manifests) {
       let sites = entry.declaredBy.map(site => ({
         pluginName: pluginName,
         component: site.component,
-        field: site.field
+        field: site.field,
+        annotation: site.annotation
       }));
       let existing = byKey[entry.key];
       if (existing !== undefined) {
@@ -46,15 +47,6 @@ function splitKey(key) {
   ]);
 }
 
-function annotationStore(pluginName, key) {
-  let match = splitKey(key);
-  if (match !== undefined && match[0].toLowerCase() === pluginName.toLowerCase()) {
-    return match[1];
-  } else {
-    return key;
-  }
-}
-
 function renderEntry(entry) {
   let match = splitKey(entry.key);
   if (match === undefined) {
@@ -63,7 +55,15 @@ function renderEntry(entry) {
       _0: `malformed capability key ` + JSON.stringify(entry.key) + ` — expected "{plugin}.{store}" (is the plugin's capabilities.json hand-edited?)`
     };
   }
-  let comments = entry.declaredBy.map(site => `  // ` + site.pluginName + `: ` + site.component + `.` + site.field + ` @storageRef(` + JSON.stringify(annotationStore(site.pluginName, entry.key)) + `)`);
+  let comments = entry.declaredBy.map(site => {
+    let site_ = `  // ` + site.pluginName + `: ` + site.component + `.` + site.field;
+    let annotation = site.annotation;
+    if (annotation !== undefined) {
+      return site_ + ` @storageRef(` + JSON.stringify(annotation) + `)`;
+    } else {
+      return site_;
+    }
+  });
   let line = `  ObjectStore({plugin: ` + JSON.stringify(match[0]) + `, store: ` + JSON.stringify(match[1]) + `}),`;
   return {
     TAG: "Ok",
@@ -108,7 +108,6 @@ export {
   union,
   quote,
   splitKey,
-  annotationStore,
   renderEntry,
   header,
   render,

package/src/generator/PlatformGenerator.res

@@ -6,11 +6,10 @@
 // `PlatformCapabilities.res` (see PlatformCodegen). The platform root stays
 // hand-written and reads `PlatformCapabilities.capabilities`.
 //
-// A plugin path may be the composition package itself (its `src/` carries the
-// manifest) or an `-aws` deploy root that delegates to one. The delegation's
-// single existing record is the root's own `generate` script —
-// `generate-plugin --aws <Namespace> <srcDir>` — so the composition `src/` is
-// read from there rather than from a second, hand-typed spelling of the path.
+// A deploy manifest enumerates *deployables*, not plugins, and a plugin's
+// manifest can sit in any of three places. `PlatformManifests` owns both facts —
+// its head comment states the resolution order and why each arm exists; add a
+// fourth arm there, not here.
 
 @val external processExit: int => unit = "process.exit"
 @module("yaml") external parseYaml: string => JSON.t = "parse"
@@ -24,42 +23,6 @@ let asObject = (json: JSON.t): option<dict<JSON.t>> => json->JSON.Decode.object
 let stringAt = (obj: dict<JSON.t>, field: string): option<string> =>
   obj->Dict.get(field)->Option.flatMap(JSON.Decode.string)
 
-// Where a plugin keeps its capability manifest. The direct arm covers a plugin
-// path that is itself a composition package; the delegated arm follows the
-// `-aws` root's `generate-plugin --aws <Namespace> <srcDir>` script to the
-// composition `src/` it is generated from.
-let manifestPathFor = (~pluginDir: string): option<string> => {
-  let direct = Generator_Node.join([pluginDir, "src", "capabilities.json"])
-  if Generator_Node.existsSync(direct) {
-    Some(direct)
-  } else {
-    let packageJsonPath = Generator_Node.join([pluginDir, "package.json"])
-    if !Generator_Node.existsSync(packageJsonPath) {
-      None
-    } else {
-      let generateScript =
-        try Generator_Node.readFileSync(packageJsonPath)
-        ->JSON.parseOrThrow
-        ->asObject
-        ->Option.flatMap(pkg => pkg->Dict.get("scripts"))
-        ->Option.flatMap(asObject)
-        ->Option.flatMap(scripts => scripts->stringAt("generate")) catch {
-        | _ => None
-        }
-      generateScript
-      ->Option.flatMap(script => {
-        let tokens = script->String.split(" ")->Array.filter(t => t != "")
-        switch tokens {
-        | ["generate-plugin", "--aws", _namespace, srcDir] =>
-          Some(Generator_Node.resolve([pluginDir, srcDir, "capabilities.json"]))
-        | _ => None
-        }
-      })
-      ->Option.filter(Generator_Node.existsSync)
-    }
-  }
-}
-
 let () = {
   let manifestArg = Generator_Node.argv->Array.get(2)->Option.getOr("")
   if manifestArg == "" {
@@ -104,27 +67,43 @@ let () = {
 
     switch (platformPath, plugins) {
     | (Some(platformPath), Some(plugins)) => {
-        let pluginManifests = plugins->Array.map(((pluginName, pluginPath)) => {
+        let pluginManifests = plugins->Array.flatMap(((pluginName, pluginPath)) => {
           let pluginDir = Generator_Node.resolve([manifestDir, pluginPath])
-          switch manifestPathFor(~pluginDir) {
-          | None => {
+          if !Generator_Node.existsSync(pluginDir) {
+            fail(`plugin "${pluginName}" points at ${pluginDir}, which does not exist`)
+          }
+          switch PlatformManifests.resolve(~pluginDir) {
+          // A stack whose package graph holds no plugin composition — an
+          // SdkService, an SPA, a standalone Lambda — has no capabilities to
+          // contribute, which is not an error. Said out loud so a plugin
+          // skipped by mistake is visible in the generator's output.
+          | NotAPlugin => {
+              Console.log(`Skipped: ${pluginName} (${pluginDir}) — no plugin composition`)
+              []
+            }
+          | Unbuilt({evidence, expected}) => {
               fail(
                 `no capabilities.json found for plugin "${pluginName}" (${pluginDir}) — ` ++
-                `build the plugin first; its build emits src/capabilities.json beside Plugin.res`,
+                `build the plugin first; its build emits src/capabilities.json beside Plugin.res ` ++
+                `(${evidence}; expected ${expected})`,
               )
-              ({pluginName, manifest: {capabilities: []}}: PlatformCodegen.pluginManifest)
+              []
             }
-          | Some(capabilitiesPath) => {
-              let manifest = try Generator_Node.readFileSync(capabilitiesPath)
+          | Manifests(manifests) =>
+            manifests->Array.map(({path, via}) => {
+              Console.log(
+                `Read: ${pluginName} — ${path} (via ${PlatformManifests.describeVia(via)})`,
+              )
+              let manifest = try Generator_Node.readFileSync(path)
               ->JSON.parseOrThrow
               ->S.parseOrThrow(CapabilityManifest.schema) catch {
               | _ => {
-                  fail(`could not parse ${capabilitiesPath} as a capability manifest`)
+                  fail(`could not parse ${path} as a capability manifest`)
                   ({capabilities: []}: CapabilityManifest.t)
                 }
               }
               ({pluginName, manifest}: PlatformCodegen.pluginManifest)
-            }
+            })
           }
         })
 

package/src/generator/PlatformGenerator.res.mjs

@@ -8,6 +8,7 @@ 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 PlatformCodegen$Reventless from "./PlatformCodegen.res.mjs";
+import * as PlatformManifests$Reventless from "./PlatformManifests.res.mjs";
 import * as CapabilityManifest$Reventless from "../components/CapabilityManifest.res.mjs";
 
 function fail(message) {
@@ -23,39 +24,6 @@ function stringAt(obj, field) {
   return Stdlib_Option.flatMap(obj[field], Stdlib_JSON.Decode.string);
 }
 
-function manifestPathFor(pluginDir) {
-  let direct = Nodepath.join(pluginDir, "src", "capabilities.json");
-  if (Nodefs.existsSync(direct)) {
-    return direct;
-  }
-  let packageJsonPath = Nodepath.join(pluginDir, "package.json");
-  if (!Nodefs.existsSync(packageJsonPath)) {
-    return;
-  }
-  let generateScript;
-  try {
-    generateScript = Stdlib_Option.flatMap(Stdlib_Option.flatMap(Stdlib_Option.flatMap(Stdlib_JSON.Decode.object(JSON.parse(Nodefs.readFileSync(packageJsonPath, "utf8"))), pkg => pkg["scripts"]), asObject), scripts => stringAt(scripts, "generate"));
-  } catch (exn) {
-    generateScript = undefined;
-  }
-  return Stdlib_Option.filter(Stdlib_Option.flatMap(generateScript, script => {
-    let tokens = script.split(" ").filter(t => t !== "");
-    if (tokens.length !== 4) {
-      return;
-    }
-    let match = tokens[0];
-    if (match !== "generate-plugin") {
-      return;
-    }
-    let match$1 = tokens[1];
-    if (match$1 !== "--aws") {
-      return;
-    }
-    let srcDir = tokens[3];
-    return Nodepath.resolve(pluginDir, srcDir, "capabilities.json");
-  }), prim => Nodefs.existsSync(prim));
-}
-
 let manifestArg = Stdlib_Option.getOr(process.argv[2], "");
 
 if (manifestArg === "") {
@@ -88,32 +56,39 @@ if (manifestArg === "") {
   }));
   if (platformPath !== undefined) {
     if (plugins !== undefined) {
-      let pluginManifests = plugins.map(param => {
+      let pluginManifests = plugins.flatMap(param => {
         let pluginName = param[0];
         let pluginDir = Nodepath.resolve(manifestDir, param[1]);
-        let capabilitiesPath = manifestPathFor(pluginDir);
-        if (capabilitiesPath !== undefined) {
-          let manifest;
-          try {
-            manifest = S.parseOrThrow(JSON.parse(Nodefs.readFileSync(capabilitiesPath, "utf8")), CapabilityManifest$Reventless.schema);
-          } catch (exn) {
-            fail(`could not parse ` + capabilitiesPath + ` as a capability manifest`);
-            manifest = {
-              capabilities: []
+        if (!Nodefs.existsSync(pluginDir)) {
+          fail(`plugin "` + pluginName + `" points at ` + pluginDir + `, which does not exist`);
+        }
+        let manifests = PlatformManifests$Reventless.resolve(undefined, pluginDir);
+        if (typeof manifests !== "object") {
+          console.log(`Skipped: ` + pluginName + ` (` + pluginDir + `) — no plugin composition`);
+          return [];
+        }
+        if (manifests.TAG === "Manifests") {
+          return manifests._0.map(param => {
+            let path = param.path;
+            console.log(`Read: ` + pluginName + ` — ` + path + ` (via ` + PlatformManifests$Reventless.describeVia(param.via) + `)`);
+            let manifest;
+            try {
+              manifest = S.parseOrThrow(JSON.parse(Nodefs.readFileSync(path, "utf8")), CapabilityManifest$Reventless.schema);
+            } catch (exn) {
+              fail(`could not parse ` + path + ` as a capability manifest`);
+              manifest = {
+                capabilities: []
+              };
+            }
+            return {
+              pluginName: pluginName,
+              manifest: manifest
             };
-          }
-          return {
-            pluginName: pluginName,
-            manifest: manifest
-          };
+          });
         }
-        fail(`no capabilities.json found for plugin "` + pluginName + `" (` + pluginDir + `) — build the plugin first; its build emits src/capabilities.json beside Plugin.res`);
-        return {
-          pluginName: pluginName,
-          manifest: {
-            capabilities: []
-          }
-        };
+        let match = manifests._0;
+        fail(`no capabilities.json found for plugin "` + pluginName + `" (` + pluginDir + `) — build the plugin first; its build emits src/capabilities.json beside Plugin.res ` + (`(` + match.evidence + `; expected ` + match.expected + `)`));
+        return [];
       });
       let message = PlatformCodegen$Reventless.render(pluginManifests);
       if (message.TAG === "Ok") {
@@ -135,6 +110,5 @@ export {
   fail,
   asObject,
   stringAt,
-  manifestPathFor,
 }
 /* manifestArg Not a pure module */

package/src/generator/PlatformManifests.res

@@ -0,0 +1,203 @@
+// Where a deploy-manifest entry's capability manifests live — and, when it
+// contributes none, whether that is because the entry is not a plugin at all.
+//
+// A deploy manifest enumerates *deployables*, not plugins. An SdkService stack,
+// a static SPA, a standalone ingester Lambda are all legitimate entries with no
+// `pluginStructure` to derive capabilities from; contributing nothing is the
+// right answer for those. A plugin whose manifest is merely unbuilt is the
+// opposite case, and silently skipping it would deprovision the stores it
+// declared. The two are told apart by evidence — something in the package graph
+// that emits a capability manifest — never by falling through the arms below.
+//
+// Resolution order, first arm that yields manifests wins:
+//
+//   1. `<dir>/src/capabilities.json` — the entry is itself a composition
+//      package, so its manifest sits beside its composition root.
+//   2. `<dir>`'s own `generate: generate-plugin --aws <Namespace> <srcDir>`
+//      script — an `-aws` root generated from a composition `src/` elsewhere in
+//      the same repo. The script is the single existing record of that
+//      delegation, so no second hand-typed spelling of the path is introduced.
+//   3. `<dir>`'s dependencies — an `-aws` root that *installs* a published
+//      composition package, which is the shape the framework recommends and the
+//      one arms 1 and 2 both miss. Every plugin dependency contributes: a root
+//      deploying two plugins legitimately needs both manifests.
+//   4. Nothing in the package graph emits a manifest — not a plugin stack.
+//
+// I/O goes through `fileSystem` so the arms are testable without a fixture
+// tree; `nodeFileSystem` is what the generator passes.
+
+/** How a manifest was found — reported so the resolving arm never has to be
+    reconstructed from the output. */
+type via =
+  | Composition
+  | Generated(string)
+  | Dependency(string)
+
+type manifest = {path: string, via: via}
+
+/** Why the entry counted as a plugin, and where its manifest was looked for. */
+type unbuilt = {evidence: string, expected: string}
+
+type t =
+  | Manifests(array<manifest>)
+  /** Something here emits a capability manifest, but the manifest is not on
+      disk: a plugin that has not been built. */
+  | Unbuilt(unbuilt)
+  /** No plugin composition anywhere in the entry's package graph. */
+  | NotAPlugin
+
+type fileSystem = {
+  exists: string => bool,
+  readJson: string => option<JSON.t>,
+}
+
+let nodeFileSystem: fileSystem = {
+  exists: Generator_Node.existsSync,
+  readJson: path =>
+    try Some(Generator_Node.readFileSync(path)->JSON.parseOrThrow) catch {
+    | _ => None
+    },
+}
+
+let describeVia = (via: via): string =>
+  switch via {
+  | Composition => "its own src/"
+  | Generated(srcDir) => `its \`generate\` script's ${srcDir}`
+  | Dependency(name) => `dependency ${name}`
+  }
+
+let asObject = (json: JSON.t): option<dict<JSON.t>> => json->JSON.Decode.object
+
+let packageJsonAt = (~fs: fileSystem, ~dir: string): option<dict<JSON.t>> =>
+  fs.readJson(Generator_Node.join([dir, "package.json"]))->Option.flatMap(asObject)
+
+let scriptsOf = (pkg: dict<JSON.t>): array<string> =>
+  pkg
+  ->Dict.get("scripts")
+  ->Option.flatMap(asObject)
+  ->Option.mapOr([], scripts =>
+    scripts->Dict.valuesToArray->Array.filterMap(JSON.Decode.string)
+  )
+
+// The composition `src/` an `-aws` root is generated from, read off the script
+// that performs the generation.
+let generatedSrcDir = (pkg: dict<JSON.t>): option<string> =>
+  pkg
+  ->Dict.get("scripts")
+  ->Option.flatMap(asObject)
+  ->Option.flatMap(scripts => scripts->Dict.get("generate"))
+  ->Option.flatMap(JSON.Decode.string)
+  ->Option.flatMap(script => {
+    let tokens = script->String.split(" ")->Array.filter(t => t != "")
+    switch tokens {
+    | ["generate-plugin", "--aws", _namespace, srcDir] => Some(srcDir)
+    | _ => None
+    }
+  })
+
+// A package that runs `emit-capabilities` as part of its build is a plugin
+// composition package, whether or not it has been built yet. That is the whole
+// signal G1 needs: it is stated once, by the package that owns the fact, and it
+// is already there in every plugin package — unlike a `kind:` on the deploy
+// manifest, which would restate it a second time.
+//
+// `reventless-local` *provides* the bin under `bin`, and so is correctly not
+// matched here.
+let emitsCapabilities = (pkg: dict<JSON.t>): bool =>
+  pkg->scriptsOf->Array.some(script => script->String.includes("emit-capabilities"))
+
+let dependencyNames = (pkg: dict<JSON.t>): array<string> => {
+  let seen = Dict.make()
+  ["dependencies", "devDependencies"]
+  ->Array.flatMap(field =>
+    pkg->Dict.get(field)->Option.flatMap(asObject)->Option.mapOr([], Dict.keysToArray)
+  )
+  ->Array.filter(name =>
+    switch seen->Dict.get(name) {
+    | Some(_) => false
+    | None => {
+        seen->Dict.set(name, true)
+        true
+      }
+    }
+  )
+}
+
+/** Node's directory resolution: `<dir>/node_modules/<name>`, then each parent's,
+    up to the filesystem root. Walking it rather than binding `require.resolve`
+    keeps the lookup on the package directory itself — a package's entry point
+    may be anywhere, and it is `src/capabilities.json` that is wanted. */
+let resolvePackageDir = (~fs: fileSystem, ~fromDir: string, ~name: string): option<string> => {
+  let rec search = dir => {
+    let candidate = Generator_Node.join([dir, "node_modules", name])
+    if fs.exists(Generator_Node.join([candidate, "package.json"])) {
+      Some(candidate)
+    } else {
+      let parent = Generator_Node.dirname(dir)
+      parent == dir ? None : search(parent)
+    }
+  }
+  search(fromDir)
+}
+
+// Arm 3. Unbuilt wins over what was found: a root deploying two plugins needs
+// both manifests, so one of them missing is a failure even though the other
+// resolved.
+let fromDependencies = (~fs: fileSystem, ~pluginDir: string, ~pkg: dict<JSON.t>): t => {
+  let found = []
+  let unbuilt = ref(None)
+  pkg
+  ->dependencyNames
+  ->Array.forEach(name =>
+    switch resolvePackageDir(~fs, ~fromDir=pluginDir, ~name) {
+    | None => ()
+    | Some(packageDir) => {
+        let candidate = Generator_Node.join([packageDir, "src", "capabilities.json"])
+        if fs.exists(candidate) {
+          found->Array.push({path: candidate, via: Dependency(name)})
+        } else if packageJsonAt(~fs, ~dir=packageDir)->Option.mapOr(false, emitsCapabilities) {
+          switch unbuilt.contents {
+          | Some(_) => ()
+          | None =>
+            unbuilt :=
+              Some({
+                evidence: `dependency ${name} emits a capability manifest`,
+                expected: candidate,
+              })
+          }
+        }
+      }
+    }
+  )
+  switch (unbuilt.contents, found) {
+  | (Some({evidence, expected}), _) => Unbuilt({evidence, expected})
+  | (None, []) => NotAPlugin
+  | (None, manifests) => Manifests(manifests)
+  }
+}
+
+let resolve = (~fs: fileSystem=nodeFileSystem, ~pluginDir: string): t => {
+  let direct = Generator_Node.join([pluginDir, "src", "capabilities.json"])
+  if fs.exists(direct) {
+    Manifests([{path: direct, via: Composition}])
+  } else {
+    switch packageJsonAt(~fs, ~dir=pluginDir) {
+    | None => NotAPlugin
+    | Some(pkg) =>
+      switch generatedSrcDir(pkg) {
+      | Some(srcDir) => {
+          let expected = Generator_Node.resolve([pluginDir, srcDir, "capabilities.json"])
+          if fs.exists(expected) {
+            Manifests([{path: expected, via: Generated(srcDir)}])
+          } else {
+            Unbuilt({
+              evidence: `its \`generate\` script composes ${srcDir}`,
+              expected,
+            })
+          }
+        }
+      | None => fromDependencies(~fs, ~pluginDir, ~pkg)
+      }
+    }
+  }
+}