@metaobjectsdev/cli 1.0.2 → 1.0.4-rc.1

package/src/lib/library-prefix-advisory.ts

@@ -0,0 +1,78 @@
+// FR-043 §3.5 — `metaobjects::` in an adopter's own metadata, with no ejection provenance.
+//
+// The loader already REFUSES a node in a library's package while that library is opted
+// in (ERR_LIBRARY_PACKAGE_COLLISION / ERR_LIBRARY_PACKAGE_NOT_OWNED). This is the other
+// half, and it is advisory on purpose: with the library NOT opted in there is nothing
+// broken to refuse — the nodes are simply the adopter's, sitting under a prefix this
+// project ships libraries into.
+//
+// Two ways to arrive there, and the advice is the same for both:
+//
+//   a hand-copy, rather than `meta eject <library>` — no provenance header, so nothing
+//     can tell later where it came from or how far it has drifted;
+//   a package名 chosen freely that happens to start `metaobjects::` — which will
+//     collide the day a library ships into it.
+//
+// A file carrying the eject marker is exempt: that IS the provenance, and `meta eject
+// --list` reports its staleness.
+import { readFile } from "node:fs/promises";
+import { EJECT_MARKER } from "./library-eject.js";
+import type { MetaData } from "@metaobjectsdev/metadata";
+
+/** The prefix every shipped library declares into. */
+export const LIBRARY_PACKAGE_PREFIX = "metaobjects::";
+
+export interface LibraryPrefixFinding {
+  file: string;
+  fqn: string;
+  message: string;
+}
+
+/**
+ * Root nodes under `metaobjects::` whose file carries no ejection provenance.
+ *
+ * Reads the loaded tree for the nodes and the FILES only for the marker — the marker is
+ * `meta eject`'s own bookkeeping, not metadata, so there is nothing in the model to read
+ * it from.
+ */
+export async function scanForUnprovenancedLibraryPrefix(
+  root: MetaData,
+  ownFiles: readonly string[],
+  projectRoot: string,
+): Promise<LibraryPrefixFinding[]> {
+  const suspect = root
+    .children()
+    .filter((n) => n.resolutionKey().startsWith(LIBRARY_PACKAGE_PREFIX));
+  if (suspect.length === 0) return [];
+
+  // Which of this project's own files carry the marker — read once, not per node.
+  const provenanced = new Set<string>();
+  for (const file of ownFiles) {
+    try {
+      if ((await readFile(file, "utf8")).slice(0, 400).includes(EJECT_MARKER)) {
+        provenanced.add(file.slice(projectRoot.length + 1));
+      }
+    } catch {
+      // unreadable — it contributes no exemption, which is the safe direction
+    }
+  }
+
+  const out: LibraryPrefixFinding[] = [];
+  for (const node of suspect) {
+    const files = "files" in node.source ? node.source.files : [];
+    // A node the SHIPPED library contributed is not the adopter's — `library:` ids say so.
+    if (files.some((f) => f.startsWith("library:"))) continue;
+    if (files.some((f) => provenanced.has(f) || [...provenanced].some((p) => p.endsWith(f)))) continue;
+    out.push({
+      file: files[0] ?? "(unknown)",
+      fqn: node.resolutionKey(),
+      message:
+        `${node.resolutionKey()} is declared under "${LIBRARY_PACKAGE_PREFIX}", which is where ` +
+        `MetaObjects ships its libraries, and no file declaring it carries an ejection header. ` +
+        `If it was copied from a library, re-copy it with 'meta eject <library>' so its origin ` +
+        `and its drift stay legible; if it is your own, move it to a package you own — a later ` +
+        `release shipping a node of that name would merge into yours.`,
+    });
+  }
+  return out;
+}

package/src/lib/load-metaobjects-config.ts

@@ -249,11 +249,10 @@ function rewriteImportSpecifiers(source: string, aliasMap: Record<string, string
  * than set to `undefined`, which is what lets `loadMemory` apply its own defaults.
  */
 export function loadMemoryOptionsFrom(
-  cfg: Pick<MetaobjectsGenConfig, "providers" | "libraries"> | undefined,
-): { providers?: readonly MetaDataTypeProvider[]; libraries?: readonly string[] } {
+  cfg: Pick<MetaobjectsGenConfig, "providers"> | undefined,
+): { providers?: readonly MetaDataTypeProvider[] } {
   return {
     ...(cfg?.providers !== undefined ? { providers: cfg.providers } : {}),
-    ...(cfg?.libraries !== undefined ? { libraries: cfg.libraries } : {}),
   };
 }
 
@@ -518,24 +517,19 @@ export async function loadMetaobjectsConfig(projectRoot: string): Promise<Metaob
     if (!cfg || typeof cfg !== "object" || !Array.isArray(cfg.generators)) {
       throw new Error(`metaobjects.config.ts at ${fullPath} did not export a valid MetaobjectsGenConfig (missing 'generators' array).`);
     }
-    // An unknown `libraries` name is a hard config error naming the valid ones, while
-    // `librarySources` keeps skipping one silently for a programmatic caller. The two
-    // are deliberately different: an API caller asking for a package this version does
-    // not ship should still be able to load its own metadata, but a name a human typed
-    // into a config file is a mistake worth failing on — skipped, it resurfaces later as
-    // ERR_UNRESOLVED_SUPER pointing at the adopter's own metadata, which is the wrong
-    // place to send someone looking. Python's `project_config` draws the same line in
-    // the same place, and the two ports agreeing here is the point.
-    if (cfg.libraries !== undefined && cfg.libraries.length > 0) {
-      const { knownLibraryPackages } = await import("@metaobjectsdev/metadata/library");
-      const available = knownLibraryPackages();
-      const unknown = cfg.libraries.filter((n) => !available.includes(n));
-      if (unknown.length > 0) {
-        throw new Error(
-          `metaobjects.config.ts at ${fullPath}: 'libraries' names unknown package(s) ` +
-            `${JSON.stringify(unknown)}; available: ${JSON.stringify(available)}.`,
-        );
-      }
+    // `libraries` used to be validated here. It moved to `.metaobjects/config.json`
+    // (FR-043 Amendment 1), and so did its validation — see `assertKnownLibraries`,
+    // called from `resolveCollection`'s readers. A config still carrying the old key
+    // gets a pointed error rather than silence, because silence is what turns a moved
+    // key into "my library stopped loading and nothing said why".
+    if ("libraries" in (cfg as unknown as Record<string, unknown>)) {
+      throw new Error(
+        `metaobjects.config.ts at ${fullPath}: 'libraries' moved to ` +
+          `.metaobjects/config.json (FR-043). Which designs a project adopts is a fact ` +
+          `about the PROJECT, not about how one port generates code from it, and that ` +
+          `file is the port-neutral one every port already reads. Move the array across ` +
+          `verbatim — the tokens are unchanged.`,
+      );
     }
     return cfg;
   } finally {

package/src/lib/migrate-scope.ts

@@ -10,7 +10,7 @@
 // or a refusal that drifted between them would be drift the user reads.
 
 import type { Collection } from "@metaobjectsdev/sdk";
-import type { SchemaProvenance } from "@metaobjectsdev/migrate-ts";
+import type { ObjectScopePredicate, SchemaProvenance } from "@metaobjectsdev/migrate-ts";
 
 /**
  * Say what a declared `migrate.scope` left out, for `migrate` and `verify --db`
@@ -32,6 +32,56 @@ export function outOfScopeNote(command: string, names: readonly string[]): strin
   );
 }
 
+/**
+ * Say what a DEPENDENCY owns, for `migrate` and `verify --db` alike (FR-023).
+ *
+ * A dependency's nodes are loaded so this project's own model can resolve against
+ * them, and are governed by nobody here. That is not the same sentence as
+ * `outOfScopeNote`'s: an excluded import is usually not the result of anything the
+ * author wrote — a project with no `migrate.scope` at all still excludes its imports —
+ * so reporting it as "outside migrate.scope" would name a key that does not exist.
+ * It also carries the opt-in, which is the whole remedy: name the package.
+ */
+export function dependencyNote(command: string, names: readonly string[]): string {
+  return (
+    `meta ${command} — ${names.length} object(s) from dependencies not governed here ` +
+    `(name the package in migrate.scope to own them): ${names.join(", ")}`
+  );
+}
+
+/**
+ * Every exclusion a run owes the reader, each object named exactly ONCE.
+ *
+ * `outOfScope` is the full suppression set and `fromDependencies` a subset of it, so
+ * reporting both as-is would print an imported table twice under two different
+ * explanations. The partition happens here, once, rather than in each command.
+ */
+export function exclusionNotes(
+  command: string,
+  outOfScope: readonly string[],
+  fromDependencies: readonly string[],
+): string[] {
+  const notes: string[] = [];
+  const imported = new Set(fromDependencies);
+  const declared = outOfScope.filter((name) => !imported.has(name));
+  if (declared.length > 0) notes.push(outOfScopeNote(command, declared));
+  if (fromDependencies.length > 0) notes.push(dependencyNote(command, fromDependencies));
+  return notes;
+}
+
+/**
+ * The import predicate a schema run threads into migrate-ts, or NOTHING.
+ *
+ * Nothing is the load-bearing half. A project with no dependencies must reach
+ * `scopeExpectedSchema` exactly as it always did — passing a predicate that happens to
+ * answer `false` for everything is not the same thing, because supplying one at all
+ * leaves the untouched same-object path and changes `declaredSchemas` from absent to
+ * derived. One helper so all five call sites make that decision identically.
+ */
+export function importedOption(collection: Collection): { imported?: ObjectScopePredicate } {
+  return collection.dependencies.length > 0 ? { imported: collection.imported } : {};
+}
+
 /** How many loaded FQNs to name in the refusal below — enough to show the shape
  *  an author's patterns have to match, short enough to stay readable. */
 const EXAMPLE_FQN_CAP = 3;
@@ -70,8 +120,13 @@ export function migrateScopeMismatch(
    */
   provenance: () => SchemaProvenance,
 ): string | undefined {
-  const { inMigrateScope, migrateScopePatterns } = collection;
-  if (inMigrateScope === undefined) return undefined;
+  // The DECLARED `migrate.scope` alone, never the composed `inMigrateScope` (FR-023).
+  // The composed predicate also excludes imports, so a consumer whose only
+  // table-declaring objects come from a dependency — and who declared no scope at all
+  // — would be refused here, citing patterns that do not exist. There is nothing wrong
+  // with that project: its imports are excluded by design and it governs no tables yet.
+  const { declaredMigrateScope, migrateScopePatterns } = collection;
+  if (declaredMigrateScope === undefined) return undefined;
 
   // The declaring FQNs of every table and view the UNSCOPED model contributes —
   // the same provenance `scopeExpectedSchema` decides scope on, so the refusal
@@ -87,7 +142,7 @@ export function migrateScopeMismatch(
   // nothing for a pattern to govern, scoped or not, and an empty schema has its
   // own (much louder) failure modes downstream.
   if (fqns.length === 0) return undefined;
-  if (fqns.some(inMigrateScope)) return undefined;
+  if (fqns.some(declaredMigrateScope)) return undefined;
 
   const patterns = JSON.stringify(migrateScopePatterns ?? []);
   const examples = fqns.slice(0, EXAMPLE_FQN_CAP).join(", ");

package/src/lib/overlay-lint.ts

@@ -0,0 +1,129 @@
+// server/typescript/packages/cli/src/lib/overlay-lint.ts
+//
+// `meta verify` — the overlay AUTHORING lint (FR-023 §11.1 item 4).
+//
+// The parser's own merge rule (parser-core.ts, "Default: no operator →
+// silently reuse existing or create new") means a top-level redeclaration of
+// an existing node works TODAY whether or not it carries `overlay: true` —
+// as long as the target still exists under the same (type, resolutionKey).
+// That is exactly the trap: a consumer who redeclares an imported node
+// without the flag gets today's silent merge for free, and gets a silent NEW
+// OBJECT the day the upstream node is renamed or removed — no error, just a
+// second, disconnected node under the same name. `overlay: true` turns that
+// into a loud `ERR_OVERLAY_NO_TARGET` instead.
+//
+// This lint does not change that parser behavior (nor could it — it reads
+// raw file content, never the parser's merge decisions). It tells the AUTHOR:
+// every top-level (type, resolutionKey) declared in two or more of the
+// collection's files where more than one declaration lacks the flag. Exactly
+// one unflagged declaration is the base and is fine; every additional
+// unflagged one is a finding.
+//
+// Advisory only, like its sibling in requirement-lint.ts: never fails
+// `meta verify`, never changes load behavior. Deliberately NO severity
+// constant to flip — see requirement-lint.ts's header for why that promise
+// would be false here too.
+
+import { declaredTopLevelKeys, type DeclaredTopLevelKey, type MetaDataSource } from "@metaobjectsdev/metadata";
+import type { Collection } from "@metaobjectsdev/sdk";
+import { relPosix } from "./rel-posix.js";
+import type { Diagnostic } from "./requirement-check.js";
+
+export const WARN_OVERLAY_IMPLICIT = "WARN_OVERLAY_IMPLICIT";
+
+/**
+ * Resolve one collection file path to the `MetaDataSource` `lintOverlays`
+ * reads it through. Injected so the lint never touches the filesystem
+ * directly: the production wiring in `verify.ts` backs this with
+ * `FileSource` (from `@metaobjectsdev/metadata/core`); a test can supply an
+ * in-memory source instead.
+ */
+export type ReadSource = (path: string) => MetaDataSource;
+
+function warn(code: string, message: string): Diagnostic {
+  return { severity: "warn", code, message };
+}
+
+/** One file's declaration of a given (type, resolutionKey). */
+interface Declaration {
+  readonly file: string;
+  readonly overlay: boolean;
+}
+
+/**
+ * Lint the collection's files for unflagged cross-file redeclarations.
+ *
+ * Reads every file in `collection.files` — dependency artifacts first, since
+ * `Collection.files` already orders them that way and they are the BASES a
+ * consumer's own declarations amend — and structurally scans each with
+ * {@link declaredTopLevelKeys} (never the loaded/merged model: the merged
+ * tree has already lost which FILE contributed which declaration).
+ *
+ * Groups by (type, resolutionKey) — mirroring the parser's own merge lookup,
+ * which matches on type AND resolutionKey (parser-core.ts) — and reports
+ * every unflagged declaration after the first one for a key with 2+
+ * declarations. The first unflagged declaration is the base.
+ *
+ * `file` in each finding's message is the collection-relative path
+ * (`relPosix`), or the dependency's `dep:<name>/<artifact>` id when the
+ * declaration came from an imported artifact.
+ *
+ * Unreadable or unparsable files are skipped — the loader itself reports
+ * those (as a load error / `meta verify`'s own failure path); duplicating
+ * that diagnosis here would just be a second, worse-informed version of the
+ * same message.
+ */
+export async function lintOverlays(
+  collection: Collection,
+  readSource: ReadSource,
+): Promise<Diagnostic[]> {
+  // type -> resolutionKey -> every declaration seen for it, in file order.
+  const byType = new Map<string, Map<string, Declaration[]>>();
+
+  for (const path of collection.files) {
+    let declared: ReadonlyArray<DeclaredTopLevelKey>;
+    try {
+      const source = readSource(path);
+      const content = await source.read();
+      declared = await declaredTopLevelKeys(content, source.format);
+    } catch {
+      continue;
+    }
+    const file = collection.fileIds.get(path) ?? relPosix(collection.configDir, path);
+    for (const decl of declared) {
+      let byKey = byType.get(decl.type);
+      if (byKey === undefined) {
+        byKey = new Map<string, Declaration[]>();
+        byType.set(decl.type, byKey);
+      }
+      const list = byKey.get(decl.key) ?? [];
+      list.push({ file, overlay: decl.overlay });
+      byKey.set(decl.key, list);
+    }
+  }
+
+  const diags: Diagnostic[] = [];
+  for (const byKey of byType.values()) {
+    for (const [fqn, declarations] of byKey) {
+      if (declarations.length < 2) continue;
+      let baseSeen = false;
+      for (const decl of declarations) {
+        if (decl.overlay) continue;
+        if (!baseSeen) {
+          // The first unflagged declaration is the base — nothing to report.
+          baseSeen = true;
+          continue;
+        }
+        diags.push(
+          warn(
+            WARN_OVERLAY_IMPLICIT,
+            `${fqn} is redeclared in ${decl.file} without overlay: true — add the flag ` +
+              `so a removed or renamed target fails loudly (ERR_OVERLAY_NO_TARGET) instead ` +
+              `of silently becoming a new object`,
+          ),
+        );
+      }
+    }
+  }
+  return diags;
+}

package/src/lib/requirement-check.ts

@@ -42,6 +42,10 @@ import {
   type MetaRequirement,
   type RequirementStatus,
 } from "@metaobjectsdev/metadata";
+// FR-043 §5.4 — the provenance key for coverage activation. A node-only subpath, which
+// is why it is a second import rather than a name on the barrel above: the library
+// module reaches the filesystem and the root barrel stays browser-safe.
+import { libraryPackages } from "@metaobjectsdev/metadata/library";
 
 export type Severity = "error" | "warn";
 
@@ -82,8 +86,11 @@ export interface RequirementSummary {
   undecided: number;
   /** deferred entries naming no ticket, so nobody will be reminded. */
   deferredUntracked: number;
-  entitiesTotal: number;
-  entitiesClaimed: number;
+  /** ABSENT when coverage was not measured — FR-043 §5.4. A number here is a
+   *  ratio the project is held to; absence is the honest reading of "this project
+   *  has authored no requirement of its own, so it asked to be held to none". */
+  entitiesTotal?: number;
+  entitiesClaimed?: number;
 }
 
 /** Severity of the object-coverage gate. Promotion to `"error"` is a one-line
@@ -249,11 +256,70 @@ export function collectRequirements(root: MetaData): MetaRequirement[] {
 export interface RequirementScan {
   readonly addressed: readonly AddressedRequirement[];
   readonly claimedObjects: ReadonlySet<string>;
+  /** FR-023 — narrows which entities `coverableEntities` counts. Undefined
+   *  means "every non-abstract entity is coverable", exactly as before this
+   *  option existed: a project with no dependencies gets no change at all.
+   *  Threaded through so BOTH `coverableEntities` call sites (the gate and the
+   *  summary) inherit the same narrowing — see `coverableEntities`. */
+  readonly coverable?: (fqn: string) => boolean;
+  /** FR-043 §5.4 — whether object coverage applies at all on this run. See
+   *  {@link projectAuthoredRequirements}. Read by BOTH the gate and the summary from
+   *  this one scan, for the same reason `claimedObjects` is shared: a summary that
+   *  printed a ratio the gate had not enforced would be a measurement nobody could
+   *  reconcile with the diagnostics beneath it. */
+  readonly measureCoverage: boolean;
 }
 
-export function scanRequirements(root: MetaData): RequirementScan {
+/**
+ * Did the ADOPTER author any of these requirements?
+ *
+ * FR-043 §5.4, and the rule exists because `checkRequirements` activates object
+ * coverage on the presence of any requirement at all. A library ships its own ledger
+ * — `iam` ships eleven entries — so without this, opting into a library would switch
+ * the unclaimed-entity gate on across a project that has never written a requirement,
+ * and report every entity in it. The gate would then be measuring the LIBRARY's
+ * decision to ship a ledger rather than anything the adopter did.
+ *
+ * Provenance is the library's declared PACKAGE. That is a manifest fact the standalone
+ * library gate resolves against the library loaded alone, whereas a node's source id
+ * differs between the on-disk dev layout (an absolute path) and the embedded one
+ * (`library:<ref>.yaml`) — a rule keyed on source would hold in this repo and stop
+ * holding in an installed build.
+ *
+ * An adopter OVERLAYING a library requirement (§5.5) is deliberately not authoring one:
+ * the overlay merges into the library's node, in the library's package, and disagreeing
+ * with a shipped verdict is a statement about the library's design rather than about
+ * what the adopter's own model is for. Treating it as activation would mean correcting
+ * one library entry silently acquired a coverage gate over the whole estate.
+ */
+function projectAuthoredRequirements(addressed: readonly AddressedRequirement[]): boolean {
+  const libPkgs = libraryPackages();
+  return addressed.some((r) => {
+    const pkg = r.node.package ?? r.node.fileDefaultPackage ?? "";
+    return !libPkgs.has(pkg);
+  });
+}
+
+export function scanRequirements(
+  root: MetaData,
+  opts?: {
+    coverable?: (fqn: string) => boolean;
+    /** Force coverage on or off instead of deriving it. The one caller that legitimately
+     *  knows better is the gate over a SHIPPED library loaded standalone: there the
+     *  library IS the project under test, and "every entity this library ships is claimed
+     *  by its own ledger" is exactly what is being asserted — so the derivation would
+     *  switch the check off precisely where it is the point. */
+    measureCoverage?: boolean;
+  },
+): RequirementScan {
   const addressed = collectAddressedRequirements(root);
-  return { addressed, claimedObjects: claimedObjectKeys(root, addressed.map((r) => r.node)) };
+  return {
+    addressed,
+    claimedObjects: claimedObjectKeys(root, addressed.map((r) => r.node)),
+    measureCoverage: opts?.measureCoverage ?? projectAuthoredRequirements(addressed),
+    // `exactOptionalPropertyTypes` — an omitted key, never an explicit `undefined`.
+    ...(opts?.coverable !== undefined ? { coverable: opts.coverable } : {}),
+  };
 }
 
 /**
@@ -307,10 +373,22 @@ function claimedObjectKeys(root: MetaData, reqs: MetaRequirement[]): Set<string>
  * An ABSTRACT entity is shape, not data: there is no table and no rows, so
  * demanding a capability claim for it is the same category error as demanding
  * one for an object.value. It is exempt for the same reason.
+ *
+ * FR-023: an entity loaded from a dependency's synced snapshot is load-only —
+ * the publisher owns it, and this project never declared it — unless the
+ * project's own `scope.include` names the dependency's package literally
+ * (`Collection.inScope`, threaded in as `coverable`). Demanding a capability
+ * claim for an import nobody here opted into owning would report a project as
+ * failing to claim entities it does not own. `coverable` is applied INSIDE
+ * this function, once, so every call site inherits it — the alternative
+ * (filtering at a call site) is exactly the shape of bug this task exists to
+ * avoid: the other call site would keep counting imports.
  */
-function coverableEntities(root: MetaData): MetaData[] {
+function coverableEntities(root: MetaData, coverable?: (fqn: string) => boolean): MetaData[] {
   return root.children().filter(
-    (n) => n.type === TYPE_OBJECT && n.subType === OBJECT_SUBTYPE_ENTITY && !n.isAbstract,
+    (n) =>
+      n.type === TYPE_OBJECT && n.subType === OBJECT_SUBTYPE_ENTITY && !n.isAbstract &&
+      (coverable === undefined || coverable(n.resolutionKey())),
   );
 }
 
@@ -324,7 +402,7 @@ function coverableEntities(root: MetaData): MetaData[] {
  */
 export function checkRequirements(root: MetaData, scan: RequirementScan = scanRequirements(root)): Diagnostic[] {
   const out: Diagnostic[] = [];
-  const { addressed, claimedObjects } = scan;
+  const { addressed, claimedObjects, coverable, measureCoverage } = scan;
   if (addressed.length === 0) return out; // opt-in by declaration — no requirements, nothing to say
 
   for (const { node: req, path: reqPath } of addressed) {
@@ -538,7 +616,9 @@ export function checkRequirements(root: MetaData, scan: RequirementScan = scanRe
   //
   // So a green run means "every entity is claimed by something", not "every node is
   // described". The stronger reading would be false.
-  for (const ent of coverableEntities(root)) {
+  //   ADOPTER-AUTHORED ONLY. FR-043 §5.4 — see `projectAuthoredRequirements`. A library's
+  //   ledger is counted and checked, but it cannot volunteer you for coverage.
+  for (const ent of measureCoverage ? coverableEntities(root, coverable) : []) {
     const key = ent.resolutionKey();
     if (!claimedObjects.has(key)) {
       out.push({
@@ -575,8 +655,8 @@ export function summariseRequirements(
     byStatus: {},
     undecided: 0,
     deferredUntracked: 0,
-    entitiesTotal: 0,
-    entitiesClaimed: 0,
+    // The coverage pair is filled in below only when the run measures coverage —
+    // `exactOptionalPropertyTypes`, so the keys are absent rather than undefined.
   };
 
   for (const req of reqs) {
@@ -595,10 +675,16 @@ export function summariseRequirements(
   // Both sides of the ratio come from the SAME scan the gate read, so the printed
   // summary cannot disagree with the diagnostics printed beneath it — previously
   // the same helper, now literally the same result.
-  const claimed = scan.claimedObjects;
-  for (const ent of coverableEntities(root)) {
-    summary.entitiesTotal++;
-    if (claimed.has(ent.resolutionKey())) summary.entitiesClaimed++;
+  if (scan.measureCoverage) {
+    const claimed = scan.claimedObjects;
+    let total = 0;
+    let claimedCount = 0;
+    for (const ent of coverableEntities(root, scan.coverable)) {
+      total++;
+      if (claimed.has(ent.resolutionKey())) claimedCount++;
+    }
+    summary.entitiesTotal = total;
+    summary.entitiesClaimed = claimedCount;
   }
 
   return summary;