graphddb 0.3.1 → 0.4.0

package/README.md

@@ -680,7 +680,7 @@ Relation traversal は、Entity 上に定義されたアクセスパスのみを
 | ドキュメント | 内容 |
 |----------|-------------|
 | [Specification](./docs/spec.md) | コア API: entity、structured keys/GSIs、query/filter、relation、batch/transaction、design rule、runtime の挙動。 |
-| [Design patterns](./docs/design-patterns.md) | DynamoDB の代表的な 10 設計パターン（RFC #118 §1）を graphddb の機能にマッピング: same-partition / embedded snapshot / edge / materialized view / sparse view / aggregate counter / versioned / reverse lookup / external projection。各パターンの用途・宣言方法（`pattern` / `defineView` / `defineVersioned` / `defineProjection` / `@aggregate`）・read & write 維持の挙動・Phase 別の対応状況。 |
+| [Design patterns](./docs/design-patterns.md) | DynamoDB の代表的な 10 設計パターン（RFC #118 §1）を graphddb の機能にマッピング: same-partition / embedded snapshot / edge / materialized view / sparse view / aggregate counter / versioned / reverse lookup / external projection。各パターンの用途・宣言方法（`pattern` / `@model({ kind })` + `@maintainedFrom` / `@hasOne`・`@hasMany` の versioned pattern / `@aggregate`）・read & write 維持の挙動・Phase 別の対応状況。 |
 | [CQRS contract layer](./docs/cqrs-contract.md) | public な Query/Command contract、cardinality matrix、N+1 安全性、contract をまたぐ合成、context 境界。 |
 | [Mutation → command derivation](./docs/mutation-command-derivation.md) | Command IF の背後にある内部的な write-plan 合成 DSL: モデルの write セマンティクス（`entityWrites`）、fragment 合成、atomic な `TransactWriteItems` の導出。 |
 | [Class hydration](./docs/class-hydration.md) | read 結果をホスト言語のオブジェクトにロードする opt-in な `options.hydrate` ファクトリ（Phase 1: `query` トップレベル; Phase 2–3 は今後）。 |

package/dist/{chunk-YIXXTGZ6.js → chunk-72VZYOSG.js}

@@ -167,6 +167,7 @@ var requireLimitRule = {
     const results = [];
     for (const relation of metadata.relations) {
       if (relation.type !== "hasMany") continue;
+      if (relation.options?.versioned) continue;
       const limit = relation.options?.limit;
       if (!limit || limit.default === void 0 || limit.max === void 0) {
         const kb = Object.keys(relation.keyBinding).join(", ");
@@ -3453,11 +3454,14 @@ function makeProjectionTransform(path, op, args) {
     `transform: unknown projection op ${JSON.stringify(op)} (expected \`identity\` or \`preview\`).`
   );
 }
+function pathOf(value) {
+  return typeof value === "string" ? value : value.path;
+}
 function preview(path, n) {
-  return makeProjectionTransform(path, "preview", [n]);
+  return makeProjectionTransform(pathOf(path), "preview", [n]);
 }
 function identity(path) {
-  return makeProjectionTransform(path, "identity", []);
+  return makeProjectionTransform(pathOf(path), "identity", []);
 }
 var LIFECYCLE_CONTRACT_MARKER = /* @__PURE__ */ Symbol(
   "graphddb:lifecycleContract"
@@ -3549,251 +3553,208 @@ function lifecyclePhaseForIntent(intent) {
   return intent;
 }
 
-// src/define/view.ts
-function whenMember(field, op, value) {
-  const path = field.startsWith("$.input.") || field.startsWith("$.entity.") ? field : `$.entity.${field}`;
-  const needsValue = op === "eq" || op === "ne";
-  if (needsValue && value === void 0) {
-    throw new Error(
-      `whenMember('${field}', '${op}', \u2026): the '${op}' op requires a comparand value (e.g. \`whenMember('${field}', '${op}', 'active')\`).`
-    );
-  }
-  return needsValue ? { path, op, value } : { path, op };
+// src/relation/maintenance-view-adapter.ts
+function logicalNameOf(meta) {
+  return meta.prefix.endsWith("#") ? meta.prefix.slice(0, -1) : meta.prefix;
 }
-var VIEW_DEFINITION_MARKER = /* @__PURE__ */ Symbol("graphddb:viewDefinition");
-var ViewRegistry = class {
-  static views = /* @__PURE__ */ new Map();
-  static gen = 0;
-  /** Register (or replace, by view class) a declared view. Bumps the generation. */
-  static register(def) {
-    this.views.set(def.viewClass, def);
-    this.gen += 1;
-  }
-  /** Every registered view, in declaration order. */
-  static getAll() {
-    return [...this.views.values()];
-  }
-  /** The monotonic generation counter (changes whenever the set of views changes). */
-  static get generation() {
-    return this.gen;
-  }
-  /** Forget every registered view (test reset). Bumps the generation. */
-  static clear() {
-    this.views.clear();
-    this.gen += 1;
-  }
-};
-function isViewDefinition(value) {
-  return typeof value === "object" && value !== null && value[VIEW_DEFINITION_MARKER] === true;
+function resolveClass(factory) {
+  return factory();
 }
-function resolveSourceClass(factory) {
-  const resolved = factory();
-  try {
-    return resolveModelClass(resolved);
-  } catch {
-    return resolved;
-  }
+function sourceLogicalName(sourceClass) {
+  const meta = MetadataRegistry.get(sourceClass);
+  return logicalNameOf(meta);
 }
-function isPathRooted(value) {
-  return value.startsWith("$.input.") || value.startsWith("$.entity.");
+function triggersFor(sourceLogical, on) {
+  return on.map((ev) => `${sourceLogical}.${ev}`);
 }
-function buildProjection(viewName, fields) {
-  const entries = fields ? Object.entries(fields) : [];
-  if (entries.length === 0) {
-    throw new Error(
-      `defineView('${viewName}'): a source projects no \`fields\` (and the view declares no default \`fields\`). A materialized view with no captured attributes projects nothing \u2014 declare \`fields\` (e.g. \`{ postId: 'postId', textPreview: preview('$.entity.body', 120) }\`).`
-    );
-  }
-  const out = {};
-  for (const [attr, value] of entries) {
-    if (typeof value === "string") {
-      const path = isPathRooted(value) ? value : `$.entity.${value}`;
-      out[attr] = identity(path);
-    } else {
-      out[attr] = value;
+function assertNoCrossSliceCollision(viewName, decls) {
+  const projectionOwner = /* @__PURE__ */ new Map();
+  const collectionOwner = /* @__PURE__ */ new Map();
+  let keyFieldShape;
+  decls.forEach((d, idx) => {
+    for (const attr of Object.keys(d.project)) {
+      const prev = projectionOwner.get(attr);
+      if (prev !== void 0 && prev !== idx) {
+        throw new Error(
+          `View '${viewName}': projection target '${attr}' is maintained by more than one \`@maintainedFrom\` declaration. A view field must be filled by exactly one source \u2014 the declaration order carries no meaning, so this is ambiguous. Remove '${attr}' from one of the declarations (or split it onto a distinct view field).`
+        );
+      }
+      projectionOwner.set(attr, idx);
     }
-  }
-  return out;
-}
-function validateTrigger(viewName, raw) {
-  if (!isMaintainTrigger(raw)) {
-    throw new Error(
-      `defineView('${viewName}'): maintenance trigger ${JSON.stringify(raw)} is not a well-formed \`Entity.event\` trigger (event must be one of 'created' / 'updated' / 'removed'). Fix the source's \`maintainedOn\`.`
-    );
-  }
-  return raw;
-}
-function defineView(view, input) {
-  const viewClass = resolveSourceClass((() => view));
-  const name = viewClass.name;
-  if (typeof name !== "string" || name.length === 0) {
-    throw new Error("defineView(view, input): the view model must be a named class.");
-  }
-  if (input.pattern !== void 0 && input.pattern !== "materializedView" && input.pattern !== "sparseView") {
-    throw new Error(
-      `defineView('${name}'): \`pattern\` must be 'materializedView' or 'sparseView' (got ${JSON.stringify(input.pattern)}).`
-    );
-  }
-  const pattern = input.pattern ?? "materializedView";
-  const sources = Array.isArray(input.source) ? input.source : [input.source];
-  if (sources.length === 0) {
-    throw new Error(
-      `defineView('${name}'): at least one \`source\` is required (a view with no source is maintained by nothing).`
-    );
-  }
-  const slices = [];
-  for (const src of sources) {
-    const keys = src.keys ?? input.keys;
-    if (keys === void 0 || Object.keys(keys).length === 0) {
-      throw new Error(
-        `defineView('${name}'): a source declares no \`keys\` and the view has no default \`keys\`. The view-row key binding (view-row key field \u2192 \`$.entity.<sourceField>\`) is required to resolve which view row a source event maintains.`
-      );
+    if (d.collectionField !== void 0) {
+      const prev = collectionOwner.get(d.collectionField);
+      if (prev !== void 0 && prev !== idx) {
+        throw new Error(
+          `View '${viewName}': collection field '${d.collectionField}' is maintained by more than one \`@maintainedFrom\` declaration. A maintained collection has exactly one source \u2014 split the second source onto a distinct collection field.`
+        );
+      }
+      collectionOwner.set(d.collectionField, idx);
     }
-    if (!src.maintainedOn || src.maintainedOn.length === 0) {
+    const shape = Object.keys(d.keyBind).slice().sort().join(",");
+    if (keyFieldShape === void 0) {
+      keyFieldShape = shape;
+    } else if (keyFieldShape !== shape) {
       throw new Error(
-        `defineView('${name}'): a source declares no \`maintainedOn\` triggers. Each source must name the lifecycle events that maintain the view (e.g. \`['Post.created', 'Post.removed']\`).`
+        `View '${viewName}': \`@maintainedFrom\` declarations bind different view-key field SETS ([${keyFieldShape}] vs [${shape}]). All sources must resolve the SAME view row identity \u2014 they must bind the same set of view-key fields (the source field a given key reads from may differ per source, but the key SHAPE may not). A divergent key shape would split the row.`
       );
     }
-    const maintainedOn = src.maintainedOn.map((t) => validateTrigger(name, t));
-    const project = buildProjection(name, src.fields ?? input.fields);
-    const collection = src.collection ? {
-      field: src.collection.field,
-      ...src.collection.maxItems !== void 0 ? { maxItems: src.collection.maxItems } : {},
-      ...src.collection.orderBy !== void 0 ? {
-        orderBy: src.collection.orderBy,
-        orderDir: src.collection.order ?? "DESC"
-      } : {}
-    } : void 0;
-    const predicate = src.when;
-    if (predicate && collection) {
+  });
+}
+function viewFromMaintainedFrom(viewClass, meta, kind) {
+  const viewName = viewClass.name ?? logicalNameOf(meta);
+  const decls = meta.maintainedFrom ?? [];
+  const pattern = kind === "sparseView" ? "sparseView" : "materializedView";
+  for (const d of decls) {
+    if (kind === "sparseView" && !d.when) {
       throw new Error(
-        `defineView('${name}'): a source declares both \`when\` (a sparse-view membership predicate) and \`collection\`. They are mutually exclusive \u2014 a membership row appears/disappears as a whole; a collection slice holds a maintained list.`
+        `View '${viewName}': \`kind: 'sparseView'\` requires every \`@maintainedFrom\` to declare a \`when\` membership predicate (e.g. \`whenMember(source.status, 'eq', 'active')\`) \u2014 the predicate decides PUT (holds) vs DELETE (flips false).`
       );
     }
-    if (pattern === "sparseView" && !predicate) {
+    if (kind !== "sparseView" && d.when) {
       throw new Error(
-        `defineView('${name}'): \`pattern: 'sparseView'\` requires every source to declare a \`when\` membership predicate (e.g. \`whenMember('status', 'eq', 'active')\`) \u2014 the predicate is what decides PUT (holds) vs DELETE (flips false) of the view row.`
+        `View '${viewName}': a \`@maintainedFrom\` declares a \`when\` membership predicate but the view \`kind\` is '${kind}'. Declare \`kind: 'sparseView'\` to maintain a predicate-gated put/delete row.`
       );
     }
-    if (predicate && pattern !== "sparseView") {
-      throw new Error(
-        `defineView('${name}'): a source declares a \`when\` membership predicate but the view \`pattern\` is '${pattern}'. Declare \`pattern: 'sparseView'\` to maintain a predicate-gated put/delete row.`
-      );
+  }
+  assertNoCrossSliceCollision(
+    viewName,
+    decls.map((d) => ({
+      keyBind: d.keyBind,
+      project: d.project,
+      collectionField: d.collection?.field
+    }))
+  );
+  let updateMode;
+  let consistency;
+  for (const d of decls) {
+    if (d.updateMode !== void 0) {
+      if (updateMode !== void 0 && updateMode !== d.updateMode) {
+        throw new Error(
+          `View '${viewName}': conflicting \`updateMode\` across \`@maintainedFrom\` declarations ('${updateMode}' vs '${d.updateMode}'). A view row has a single write path \u2014 declare the same \`updateMode\` on every source.`
+        );
+      }
+      updateMode = d.updateMode;
+    }
+    if (d.consistency !== void 0) {
+      if (consistency !== void 0 && consistency !== d.consistency) {
+        throw new Error(
+          `View '${viewName}': conflicting \`consistency\` across \`@maintainedFrom\` declarations ('${consistency}' vs '${d.consistency}').`
+        );
+      }
+      consistency = d.consistency;
     }
-    slices.push({
-      sourceClass: resolveSourceClass(src.entity),
-      maintainedOn,
-      keys,
-      project,
-      ...collection ? { collection } : {},
-      ...predicate ? { predicate } : {}
-    });
   }
-  const def = {
-    [VIEW_DEFINITION_MARKER]: true,
-    name,
+  const slices = decls.map((d) => sliceFromDeclaration(d));
+  return {
+    name: viewName,
     viewClass,
     pattern,
     slices,
-    ...input.write?.updateMode !== void 0 ? { updateMode: input.write.updateMode } : {},
-    ...input.write?.consistency !== void 0 ? { consistency: input.write.consistency } : {}
+    ...updateMode !== void 0 ? { updateMode } : {},
+    ...consistency !== void 0 ? { consistency } : {}
   };
-  ViewRegistry.register(def);
-  return def;
 }
-function defineViews(definitions) {
-  for (const [name, def] of Object.entries(definitions)) {
-    if (!isViewDefinition(def)) {
+function sliceFromDeclaration(d) {
+  const sourceClass = resolveClass(d.sourceFactory);
+  const sourceLogical = sourceLogicalName(sourceClass);
+  const collection = d.collection ? {
+    field: d.collection.field,
+    ...d.collection.maxItems !== void 0 ? { maxItems: d.collection.maxItems } : {},
+    ...d.collection.orderBy !== void 0 ? { orderBy: d.collection.orderBy, orderDir: d.collection.order ?? "DESC" } : {}
+  } : void 0;
+  return {
+    sourceClass,
+    maintainedOn: triggersFor(sourceLogical, d.on),
+    keys: d.keyBind,
+    project: d.project,
+    ...collection ? { collection } : {},
+    ...d.when ? { predicate: d.when } : {}
+  };
+}
+function versionedViews(ownerClass, ownerMeta) {
+  const ownerLogical = logicalNameOf(ownerMeta);
+  const rels = [];
+  for (const rel of ownerMeta.relations) {
+    const v = rel.options?.versioned;
+    if (!v) continue;
+    const targetClass = resolveClass(rel.targetFactory);
+    const targetMeta = MetadataRegistry.get(targetClass);
+    if (!targetMeta.primaryKey) {
       throw new Error(
-        `defineViews: '${name}' is not a view definition. Use defineView(name, { pattern: 'materializedView', source, keys, fields }) to build entries.`
+        `Versioned relation '${rel.propertyName}' on '${ownerLogical}': the target model '${targetClass.name}' has no \`key\` \u2014 a versioned latest/history row needs a key to resolve which row to overwrite / append.`
       );
     }
+    const keyFields = [
+      ...segmentFieldNames(targetMeta.primaryKey.segmented.pkSegments),
+      ...segmentFieldNames(targetMeta.primaryKey.segmented.skSegments)
+    ];
+    rels.push({
+      propertyName: rel.propertyName,
+      mode: v.mode,
+      on: v.on,
+      project: v.project,
+      ...v.updateMode !== void 0 ? { updateMode: v.updateMode } : {},
+      ...v.consistency !== void 0 ? { consistency: v.consistency } : {},
+      targetClass,
+      targetMeta,
+      keyFields
+    });
   }
-  return definitions;
-}
-function defineVersioned(latest, history, input) {
-  if (input.pattern !== void 0 && input.pattern !== "versioned") {
-    throw new Error(
-      `defineVersioned: \`pattern\` must be 'versioned' (got ${JSON.stringify(input.pattern)}).`
-    );
-  }
-  const latestClass = resolveSourceClass((() => latest));
-  const historyClass = resolveSourceClass((() => history));
-  if (latestClass === historyClass) {
-    throw new Error(
-      `defineVersioned: the latest-pointer and history models must be DISTINCT (both are '${latestClass.name}'). The latest row is overwritten per revision and the history row is appended per version, so they live on different rows.`
-    );
-  }
-  const latestKeyFields = new Set(Object.keys(input.latestKeys));
-  const historyKeyFields = Object.keys(input.historyKeys);
-  const discriminators = historyKeyFields.filter((f) => !latestKeyFields.has(f));
-  if (discriminators.length === 0) {
-    throw new Error(
-      `defineVersioned: \`historyKeys\` [${historyKeyFields.map((f) => `'${f}'`).join(", ")}] carries no version discriminator beyond \`latestKeys\` [${[...latestKeyFields].map((f) => `'${f}'`).join(", ")}]. The history row must be keyed by a per-version field (e.g. add \`version: '$.entity.version'\`) so each revision is a NEW row; otherwise every revision overwrites one row (a latest pointer, not an append-only history).`
-    );
+  assertVersionedDiscriminator(ownerLogical, rels);
+  const out = [];
+  for (const rel of rels) {
+    const keys = {};
+    for (const f of rel.keyFields) keys[f] = `$.entity.${f}`;
+    const targetName = rel.targetClass.name ?? logicalNameOf(rel.targetMeta);
+    out.push({
+      name: targetName,
+      viewClass: rel.targetClass,
+      pattern: "materializedView",
+      slices: [
+        {
+          sourceClass: ownerClass,
+          maintainedOn: triggersFor(ownerLogical, rel.on),
+          keys,
+          project: rel.project
+        }
+      ],
+      ...rel.updateMode !== void 0 ? { updateMode: rel.updateMode } : {},
+      ...rel.consistency !== void 0 ? { consistency: rel.consistency } : {}
+    });
   }
-  const latestView = defineView(latest, {
-    pattern: "materializedView",
-    source: { entity: input.source, maintainedOn: input.maintainedOn, keys: input.latestKeys },
-    fields: input.fields,
-    ...input.write ? { write: input.write } : {}
-  });
-  const historyView = defineView(history, {
-    pattern: "materializedView",
-    source: { entity: input.source, maintainedOn: input.maintainedOn, keys: input.historyKeys },
-    fields: input.fields,
-    ...input.write ? { write: input.write } : {}
-  });
-  return { latest: latestView, history: historyView };
-}
-var PROJECTION_DEFINITION_MARKER = /* @__PURE__ */ Symbol(
-  "graphddb:projectionDefinition"
-);
-function isProjectionDefinition(value) {
-  return typeof value === "object" && value !== null && value[PROJECTION_DEFINITION_MARKER] === true;
+  return out;
 }
-function defineProjection(name, input) {
-  if (typeof name !== "string" || name.length === 0) {
-    throw new Error("defineProjection(name, input): `name` must be a non-empty string.");
-  }
-  if (input.pattern !== void 0 && input.pattern !== "externalProjection") {
-    throw new Error(
-      `defineProjection('${name}'): \`pattern\` must be 'externalProjection' (got ${JSON.stringify(input.pattern)}).`
-    );
-  }
-  const via = input.via ?? "stream";
-  if (via !== "stream") {
-    throw new Error(
-      `defineProjection('${name}'): \`via\` must be 'stream' (the only supported transport this phase; got ${JSON.stringify(via)}). An external projection is maintained asynchronously off the CDC stream.`
-    );
-  }
-  if (typeof input.idempotencyKey !== "string" || input.idempotencyKey.length === 0) {
-    throw new Error(
-      `defineProjection('${name}'): \`idempotencyKey\` must be a non-empty source attribute name (e.g. 'resultId'). It folds at-least-once delivery to one sink upsert per genuine source event.`
-    );
+function assertVersionedDiscriminator(ownerLogical, rels) {
+  const latests = rels.filter((r) => r.mode === "latest");
+  const histories = rels.filter((r) => r.mode === "history");
+  if (latests.length === 0 || histories.length === 0) return;
+  for (const latest of latests) {
+    const latestKeyFields = new Set(latest.keyFields);
+    for (const history of histories) {
+      const discriminators = history.keyFields.filter((f) => !latestKeyFields.has(f));
+      if (discriminators.length === 0) {
+        const latestName = latest.targetClass.name ?? "<latest>";
+        const historyName = history.targetClass.name ?? "<history>";
+        throw new Error(
+          `Versioned relation pair on '${ownerLogical}': the \`versionedHistory\` target '${historyName}' (\`${history.propertyName}\`) is keyed by [${history.keyFields.map((f) => `'${f}'`).join(", ")}], which carries NO version discriminator beyond the \`versionedLatest\` target '${latestName}' (\`${latest.propertyName}\`) keyed by [${[...latestKeyFields].map((f) => `'${f}'`).join(", ")}]. The history row must be keyed by a per-version field (e.g. add a \`version\` segment to '${historyName}'s \`@key\`) so each revision is a NEW row; otherwise every revision overwrites one row (a latest pointer, not an append-only history).`
+        );
+      }
+    }
   }
-  const on = input.on ?? ["created", "updated", "removed"];
-  const project = input.fields ? buildProjection(name, input.fields) : {};
-  return {
-    [PROJECTION_DEFINITION_MARKER]: true,
-    name,
-    pattern: "externalProjection",
-    sourceClass: resolveSourceClass(input.source),
-    via,
-    idempotencyKey: input.idempotencyKey,
-    on: [...on],
-    project
-  };
 }
-function defineProjections(definitions) {
-  for (const [name, def] of Object.entries(definitions)) {
-    if (!isProjectionDefinition(def)) {
-      throw new Error(
-        `defineProjections: '${name}' is not a projection definition. Use defineProjection(name, { pattern: 'externalProjection', source, via, idempotencyKey }) to build entries.`
-      );
+function collectViewDefinitions(registry) {
+  const resolved = registry ?? MetadataRegistry.getAll();
+  const out = [];
+  for (const [klass, meta] of resolved) {
+    const kind = meta.kind ?? "entity";
+    if (kind === "materializedView" || kind === "sparseView") {
+      out.push(viewFromMaintainedFrom(klass, meta, kind));
+    }
+    if (meta.relations?.some((r) => r.options?.versioned)) {
+      out.push(...versionedViews(klass, meta));
     }
   }
-  return definitions;
+  return out;
 }
 
 // src/relation/maintenance-graph.ts
@@ -3803,7 +3764,7 @@ var COUNT_DELTA_FOR_EVENT = {
   updated: 0
 };
 var MAINTAIN_EVENTS = ["created", "updated", "removed"];
-function isPathRooted2(value) {
+function isPathRooted(value) {
   return value.startsWith("$.input.") || value.startsWith("$.entity.");
 }
 function sourceAttributeOf(path) {
@@ -3812,7 +3773,7 @@ function sourceAttributeOf(path) {
 }
 function normalizeProjectionEntry(value) {
   if (typeof value === "string") {
-    const path = isPathRooted2(value) ? value : `$.entity.${value}`;
+    const path = isPathRooted(value) ? value : `$.entity.${value}`;
     return identity(path);
   }
   return value;
@@ -3879,7 +3840,7 @@ function assertMaintenanceRoundTrips(args) {
     }
   }
   for (const [attr, transform] of Object.entries(projection)) {
-    if (!isPathRooted2(transform.path)) {
+    if (!isPathRooted(transform.path)) {
       throw new Error(
         `Maintenance projection for relation '${relationProperty}' on '${ownerEntity}' captures attribute '${attr}' from '${transform.path}', which is not a payload-rooted source path (\`$.input.*\` / \`$.entity.*\`). The maintenance graph projects only from the source payload (payload \u540C\u68B1) \u2014 there is no fetch / re-projection.`
       );
@@ -3926,12 +3887,12 @@ function assertCounterRoundTrips(args) {
     }
   }
 }
-function logicalNameOf(meta) {
+function logicalNameOf2(meta) {
   return meta.prefix.endsWith("#") ? meta.prefix.slice(0, -1) : meta.prefix;
 }
 function resolveEntityByName(name, registry) {
   for (const [klass, meta] of registry) {
-    if (logicalNameOf(meta) === name) return klass;
+    if (logicalNameOf2(meta) === name) return klass;
   }
   return void 0;
 }
@@ -3999,12 +3960,12 @@ function resolveCollectionOrder(relation, sourceMeta, ownerEntity, project) {
   const orderField = skFields[skFields.length - 1];
   if (orderField === void 0) {
     throw new Error(
-      `Relation '${relation.propertyName}' on '${ownerEntity}' declares \`read.order: '${order}'\` for its maintained collection, but its source entity '${logicalNameOf(sourceMeta)}' has no sort key to order by. A maintained collection orders by the source's sort-key field (the field the live read sorts on); declare a sort key on '${logicalNameOf(sourceMeta)}' or drop \`read.order\`.`
+      `Relation '${relation.propertyName}' on '${ownerEntity}' declares \`read.order: '${order}'\` for its maintained collection, but its source entity '${logicalNameOf2(sourceMeta)}' has no sort key to order by. A maintained collection orders by the source's sort-key field (the field the live read sorts on); declare a sort key on '${logicalNameOf2(sourceMeta)}' or drop \`read.order\`.`
     );
   }
   if (!Object.prototype.hasOwnProperty.call(project, orderField)) {
     throw new Error(
-      `Relation '${relation.propertyName}' on '${ownerEntity}' declares \`read.order: '${order}'\` for its maintained collection, which orders by the source entity '${logicalNameOf(sourceMeta)}'s sort-key field '${orderField}', but that field is not in the relation's \`projection\` (projected: ${Object.keys(project).map((a) => `'${a}'`).join(", ")}). The maintained collection sorts its projected items, so the order field must be projected \u2014 add '${orderField}' to the projection (e.g. \`{ ${orderField}: '${orderField}', \u2026 }\`) or drop \`read.order\`.`
+      `Relation '${relation.propertyName}' on '${ownerEntity}' declares \`read.order: '${order}'\` for its maintained collection, which orders by the source entity '${logicalNameOf2(sourceMeta)}'s sort-key field '${orderField}', but that field is not in the relation's \`projection\` (projected: ${Object.keys(project).map((a) => `'${a}'`).join(", ")}). The maintained collection sorts its projected items, so the order field must be projected \u2014 add '${orderField}' to the projection (e.g. \`{ ${orderField}: '${orderField}', \u2026 }\`) or drop \`read.order\`.`
     );
   }
   return { orderBy: `$.entity.${orderField}`, orderDir: order };
@@ -4075,16 +4036,15 @@ function assertNoCycle(items) {
   }
 }
 function buildMaintenanceGraph(registry, views) {
-  const useGlobal = registry === void 0;
   const resolvedRegistry = registry ?? MetadataRegistry.getAll();
-  const resolvedViews = views ?? (useGlobal ? ViewRegistry.getAll() : []);
+  const resolvedViews = views ?? collectViewDefinitions(resolvedRegistry);
   return buildMaintenanceGraphImpl(resolvedRegistry, resolvedViews);
 }
 function buildMaintenanceGraphImpl(registry, views) {
   const items = [];
   const owners = [...registry.entries()].map(([klass, meta]) => ({ klass, meta })).sort((a, b) => a.klass.name < b.klass.name ? -1 : a.klass.name > b.klass.name ? 1 : 0);
   for (const { klass: ownerClass, meta: ownerMeta } of owners) {
-    const ownerEntity = logicalNameOf(ownerMeta);
+    const ownerEntity = logicalNameOf2(ownerMeta);
     const relations = [...ownerMeta.relations].sort(
       (a, b) => a.propertyName < b.propertyName ? -1 : a.propertyName > b.propertyName ? 1 : 0
     );
@@ -4093,7 +4053,7 @@ function buildMaintenanceGraphImpl(registry, views) {
       if (!maintainedOn || maintainedOn.length === 0) continue;
       const sourceClass = relation.targetFactory();
       const sourceMeta = MetadataRegistry.get(sourceClass);
-      const relationTargetEntity = logicalNameOf(sourceMeta);
+      const relationTargetEntity = logicalNameOf2(sourceMeta);
       const project = buildProjectionMap(
         relation.options?.projection,
         ownerEntity,
@@ -4159,7 +4119,7 @@ function buildMaintenanceGraphImpl(registry, views) {
       if (!maintainedOn || maintainedOn.length === 0) continue;
       const sourceClass = agg.targetFactory();
       const sourceMeta = MetadataRegistry.get(sourceClass);
-      const aggSourceEntity = logicalNameOf(sourceMeta);
+      const aggSourceEntity = logicalNameOf2(sourceMeta);
       const { keys, sourceFields } = buildDestinationKeys(agg.keyBinding);
       const destinationKeyFields = Object.keys(keys);
       const valueSourceFields = agg.options.value.op === "max" ? [agg.options.value.field] : [];
@@ -4216,11 +4176,11 @@ function buildMaintenanceGraphImpl(registry, views) {
   for (const view of [...views].sort((a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : 0)) {
     const ownerClass = view.viewClass;
     const ownerMeta = MetadataRegistry.get(ownerClass);
-    const ownerEntity = logicalNameOf(ownerMeta);
+    const ownerEntity = logicalNameOf2(ownerMeta);
     view.slices.forEach((slice, sliceIndex) => {
       const sourceClass = slice.sourceClass;
       const sourceMeta = MetadataRegistry.get(sourceClass);
-      const sourceEntity = logicalNameOf(sourceMeta);
+      const sourceEntity = logicalNameOf2(sourceMeta);
       const keys = slice.keys;
       const destinationKeyFields = Object.keys(keys);
       const keyBindingSourceFields = Object.values(keys).map((p) => sourceAttributeOf(p));
@@ -4242,7 +4202,7 @@ function buildMaintenanceGraphImpl(registry, views) {
           projection: slice.project
         });
         if (slice.predicate) {
-          if (!isPathRooted2(slice.predicate.path)) {
+          if (!isPathRooted(slice.predicate.path)) {
             throw new Error(
               `defineView '${view.name}': sparse-view predicate path ${JSON.stringify(slice.predicate.path)} is not a payload-rooted source path (\`$.input.*\` / \`$.entity.*\`). The drain evaluates the predicate against the source image \u2014 use a source attribute path.`
             );
@@ -4368,14 +4328,6 @@ export {
   entityWrites,
   getEntityWrites,
   lifecyclePhaseForIntent,
-  whenMember,
-  ViewRegistry,
-  isViewDefinition,
-  defineView,
-  defineViews,
-  defineVersioned,
-  isProjectionDefinition,
-  defineProjection,
-  defineProjections,
+  collectViewDefinitions,
   buildMaintenanceGraph
 };