graphddb 0.7.8 → 0.7.10

package/dist/chunk-DFUKGU2Q.js

@@ -0,0 +1,1197 @@
+import {
+  MetadataRegistry,
+  attachHiddenKey
+} from "./chunk-3ZU2VW3L.js";
+import {
+  resolveKey,
+  segmentFieldNames
+} from "./chunk-PDUVTYC5.js";
+
+// src/types/select-builder.ts
+var SELECT_BUILDER = /* @__PURE__ */ Symbol.for("graphddb.selectBuilder");
+var SELECT_SPEC = /* @__PURE__ */ Symbol.for("graphddb.selectSpec");
+
+// src/select/builder.ts
+var BuilderImpl = class _BuilderImpl {
+  [SELECT_BUILDER] = true;
+  /** The resolved spec, exposed (non-method) so normalizers can read it. */
+  [SELECT_SPEC];
+  constructor(spec) {
+    this[SELECT_SPEC] = spec;
+  }
+  clone(patch) {
+    return new _BuilderImpl({ ...this[SELECT_SPEC], ...patch });
+  }
+  filter(filter) {
+    return this.clone({ filter });
+  }
+  limit(limit) {
+    return this.clone({ limit });
+  }
+  after(cursor) {
+    return this.clone({ after: cursor });
+  }
+  order(order) {
+    return this.clone({ order });
+  }
+};
+function isSelectBuilder(value) {
+  return typeof value === "object" && value !== null && value[SELECT_BUILDER] === true;
+}
+function fromBuilder(value) {
+  const spec = value[SELECT_SPEC];
+  return {
+    select: spec.select,
+    filter: spec.filter,
+    limit: spec.limit,
+    after: spec.after,
+    order: spec.order
+  };
+}
+function normalizeSelectSpec(value) {
+  if (isSelectBuilder(value)) {
+    return fromBuilder(value);
+  }
+  const obj = value;
+  return {
+    select: obj.select,
+    filter: obj.filter,
+    limit: obj.limit,
+    after: obj.after,
+    order: obj.order
+  };
+}
+function normalizeTopLevelSelect(value) {
+  if (isSelectBuilder(value)) {
+    return fromBuilder(value);
+  }
+  return { select: value ?? {} };
+}
+function buildProject(select) {
+  return new BuilderImpl({
+    [SELECT_BUILDER]: true,
+    select
+  });
+}
+function buildRelation(select) {
+  return new BuilderImpl({
+    [SELECT_BUILDER]: true,
+    select
+  });
+}
+
+// src/relation/detect.ts
+function isRelationSpec(value) {
+  if (typeof value !== "object" || value === null) return false;
+  return "select" in value || isSelectBuilder(value);
+}
+function isInlineSnapshotSpec(value) {
+  return typeof value === "object" && value !== null && !isSelectBuilder(value) && value.inline === true && !("select" in value);
+}
+function detectRelationFields(select, metadata) {
+  const result = [];
+  for (const [fieldName, value] of Object.entries(select)) {
+    if (isRelationSpec(value)) {
+      const rel = metadata.relations.find((r) => r.propertyName === fieldName);
+      if (rel) {
+        result.push(rel);
+      }
+    }
+  }
+  return result;
+}
+function validateInlineSnapshotSelect(select, metadata, resolveTargetMeta) {
+  for (const [fieldName, value] of Object.entries(select)) {
+    if (isInlineSnapshotSpec(value)) {
+      const rel = metadata.relations.find((r) => r.propertyName === fieldName);
+      if (!rel) {
+        throw new Error(
+          `Inline read '{ ${fieldName}: { inline: true } }' is only valid on an embeddedSnapshot relation, but '${fieldName}' is not a relation on '${metadata.prefix}'. Use '${fieldName}: true' for a scalar / embedded field.`
+        );
+      }
+      if (rel.options?.pattern !== "embeddedSnapshot") {
+        throw new Error(
+          `Inline read '{ ${fieldName}: { inline: true } }' is only valid on an embeddedSnapshot relation. '${fieldName}' is a plain '${rel.type}' relation (no 'pattern: embeddedSnapshot'); use '{ ${fieldName}: { select: \u2026 } }' to traverse to its child rows instead.`
+        );
+      }
+      continue;
+    }
+    if (typeof value === "object" && value !== null && isRelationSpec(value)) {
+      const rel = metadata.relations.find((r) => r.propertyName === fieldName);
+      if (!rel) continue;
+      const targetMeta = resolveTargetMeta(rel);
+      const nested = normalizeSelectSpec(value).select;
+      if (nested) {
+        validateInlineSnapshotSelect(nested, targetMeta, resolveTargetMeta);
+      }
+    }
+  }
+}
+function getImplicitKeyFields(select, metadata) {
+  const relations = detectRelationFields(select, metadata);
+  const needed = /* @__PURE__ */ new Set();
+  for (const rel of relations) {
+    if (rel.type === "refs" && rel.refs) {
+      const listField = rel.refs.from;
+      if (!(listField in select) || select[listField] !== true) {
+        needed.add(listField);
+      }
+      continue;
+    }
+    for (const sourceField of Object.values(rel.keyBinding)) {
+      if (!(sourceField in select) || select[sourceField] !== true) {
+        needed.add(sourceField);
+      }
+    }
+  }
+  return [...needed];
+}
+
+// src/hydrator/hydrator.ts
+function hydrate(rawItems, select, metadata, updatable = false) {
+  return rawItems.map((item) => hydrateItem(item, select, metadata, updatable));
+}
+function hydrateItem(raw, select, metadata, updatable = false) {
+  const fieldMap = new Map(
+    metadata.fields.map((f) => [f.propertyName, f])
+  );
+  const embeddedMap = new Map(
+    metadata.embeddedFields.map((e) => [e.propertyName, e])
+  );
+  const result = {};
+  for (const [fieldName, selectValue] of Object.entries(select)) {
+    if (selectValue === true) {
+      const value = raw[fieldName];
+      if (value !== void 0) {
+        const fieldMeta = fieldMap.get(fieldName);
+        result[fieldName] = deserializeValue(value, fieldMeta);
+      }
+    } else if (isInlineSnapshotSpec(selectValue)) {
+      const value = raw[fieldName];
+      if (value !== void 0) {
+        result[fieldName] = value;
+      }
+    } else if (typeof selectValue === "object" && selectValue !== null) {
+      if ("select" in selectValue || isSelectBuilder(selectValue)) {
+        continue;
+      }
+      const rawEmb = raw[fieldName];
+      if (rawEmb && typeof rawEmb === "object") {
+        result[fieldName] = hydrateEmbedded(
+          rawEmb,
+          selectValue,
+          metadata,
+          fieldName
+        );
+      }
+    }
+  }
+  if (updatable) {
+    attachHiddenKey(result, raw);
+  }
+  return result;
+}
+function hydrateEmbedded(raw, select, _metadata, _fieldName) {
+  const result = {};
+  for (const [key, selectValue] of Object.entries(select)) {
+    if (selectValue === true) {
+      if (raw[key] !== void 0) {
+        result[key] = raw[key];
+      }
+    } else if (typeof selectValue === "object" && selectValue !== null && !("select" in selectValue)) {
+      const nested = raw[key];
+      if (nested && typeof nested === "object") {
+        result[key] = hydrateEmbedded(
+          nested,
+          selectValue,
+          _metadata,
+          key
+        );
+      }
+    }
+  }
+  return result;
+}
+function deserializeValue(value, fieldMeta) {
+  if (!fieldMeta) return value;
+  if (fieldMeta.options?.deserialize) {
+    return fieldMeta.options.deserialize(value);
+  }
+  if (fieldMeta.options?.format === "datetime" && typeof value === "string") {
+    return new Date(value);
+  }
+  if (fieldMeta.options?.format === "date" && typeof value === "string") {
+    return /* @__PURE__ */ new Date(value + "T00:00:00.000Z");
+  }
+  return value;
+}
+
+// src/define/entity-writes.ts
+var MAINTAIN_TRIGGER_RE = /^[^.\s$[\]*]+\.(?:created|updated|removed)$/;
+function maintainTrigger(value) {
+  if (typeof value !== "string" || !MAINTAIN_TRIGGER_RE.test(value)) {
+    throw new Error(
+      `maintainTrigger: a maintenance trigger must be an \`Entity.event\` string where event is one of \`created\` / \`updated\` / \`removed\` (e.g. \`"Post.created"\`), but received ${JSON.stringify(value)}.`
+    );
+  }
+  return value;
+}
+function isMaintainTrigger(value) {
+  return typeof value === "string" && MAINTAIN_TRIGGER_RE.test(value);
+}
+function makeProjectionTransform(path, op, args) {
+  if (op === "preview") {
+    const [n] = args;
+    if (typeof n !== "number" || !Number.isInteger(n) || n <= 0) {
+      throw new Error(
+        `transform: the \`preview\` op requires a positive integer length bound (e.g. \`preview('$.body', 200)\`), but received ${JSON.stringify(n)}.`
+      );
+    }
+    return { kind: "transform", path, op, args: [n] };
+  }
+  if (op === "identity") {
+    if (args.length > 0) {
+      throw new Error(
+        `transform: the \`identity\` op takes no arguments, but received ${JSON.stringify(args)}.`
+      );
+    }
+    return { kind: "transform", path, op, args: [] };
+  }
+  throw new Error(
+    `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(pathOf(path), "preview", [n]);
+}
+function identity(path) {
+  return makeProjectionTransform(pathOf(path), "identity", []);
+}
+var LIFECYCLE_CONTRACT_MARKER = /* @__PURE__ */ Symbol(
+  "graphddb:lifecycleContract"
+);
+function isLifecycleContract(value) {
+  return typeof value === "object" && value !== null && value[LIFECYCLE_CONTRACT_MARKER] === true;
+}
+var ENTITY_WRITES_MARKER = /* @__PURE__ */ Symbol("graphddb:entityWrites");
+function isEntityWritesDefinition(value) {
+  return typeof value === "object" && value !== null && value[ENTITY_WRITES_MARKER] === true;
+}
+function freezeEffects(effects) {
+  const out = {};
+  if (effects.requires !== void 0) out.requires = effects.requires;
+  if (effects.unique !== void 0) out.unique = effects.unique;
+  if (effects.edges !== void 0) out.edges = effects.edges;
+  if (effects.derive !== void 0) out.derive = effects.derive;
+  if (effects.emits !== void 0) out.emits = effects.emits;
+  if (effects.idempotency !== void 0) out.idempotency = effects.idempotency;
+  return out;
+}
+var recorder = {
+  lifecycle(effects = {}) {
+    return {
+      [LIFECYCLE_CONTRACT_MARKER]: true,
+      effects: freezeEffects(effects)
+    };
+  },
+  exists(targetFactory, keys) {
+    return { kind: "requires", targetFactory, keys };
+  },
+  unique(spec) {
+    return { kind: "unique", name: spec.name, scope: spec.scope, fields: spec.fields };
+  },
+  putEdge(targetFactory, relationProperty) {
+    return { kind: "putEdge", targetFactory, relationProperty };
+  },
+  deleteEdge(targetFactory, relationProperty) {
+    return { kind: "deleteEdge", targetFactory, relationProperty };
+  },
+  dualEdge(forward, inverse) {
+    return {
+      kind: "putEdge",
+      targetFactory: forward.target,
+      relationProperty: forward.relationProperty,
+      inverse: {
+        adjacencyFactory: inverse.adjacency,
+        targetFactory: inverse.target,
+        relationProperty: inverse.relationProperty
+      }
+    };
+  },
+  increment(targetFactory, keys, attribute, amount) {
+    return { kind: "derive", targetFactory, keys, attribute, amount };
+  },
+  transform(path, op, ...args) {
+    return makeProjectionTransform(path, op, args);
+  },
+  event(name, payload) {
+    return { kind: "event", name, payload };
+  },
+  idempotentBy(token) {
+    return { kind: "idempotency", token };
+  }
+};
+function entityWrites(builder) {
+  const shape = builder(recorder);
+  for (const phase of ["create", "update", "remove"]) {
+    const contract = shape[phase];
+    if (contract !== void 0 && !isLifecycleContract(contract)) {
+      throw new Error(
+        `entityWrites: the '${phase}' lifecycle must be built with \`w.lifecycle({...})\` (it carries the \xA72 effect arrays), but received ${JSON.stringify(contract)}.`
+      );
+    }
+  }
+  if (shape.create === void 0 && shape.update === void 0 && shape.remove === void 0) {
+    throw new Error(
+      "entityWrites(...) must declare at least one lifecycle (`create` / `update` / `remove`); an empty save contract declares nothing."
+    );
+  }
+  return {
+    [ENTITY_WRITES_MARKER]: true,
+    ...shape.create !== void 0 ? { create: shape.create } : {},
+    ...shape.update !== void 0 ? { update: shape.update } : {},
+    ...shape.remove !== void 0 ? { remove: shape.remove } : {}
+  };
+}
+function getEntityWrites(modelClass) {
+  for (const name of Object.getOwnPropertyNames(modelClass)) {
+    let value;
+    try {
+      value = modelClass[name];
+    } catch {
+      continue;
+    }
+    if (isEntityWritesDefinition(value)) return value;
+  }
+  return void 0;
+}
+function lifecyclePhaseForIntent(intent) {
+  return intent;
+}
+
+// src/relation/maintenance-view-adapter.ts
+function logicalNameOf(meta) {
+  return meta.prefix.endsWith("#") ? meta.prefix.slice(0, -1) : meta.prefix;
+}
+function resolveClass(factory) {
+  return factory();
+}
+function sourceLogicalName(sourceClass) {
+  const meta = MetadataRegistry.get(sourceClass);
+  return logicalNameOf(meta);
+}
+function triggersFor(sourceLogical, on) {
+  return on.map((ev) => `${sourceLogical}.${ev}`);
+}
+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);
+    }
+    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);
+    }
+    const shape = Object.keys(d.keyBind).slice().sort().join(",");
+    if (keyFieldShape === void 0) {
+      keyFieldShape = shape;
+    } else if (keyFieldShape !== shape) {
+      throw new Error(
+        `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.`
+      );
+    }
+  });
+}
+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(
+        `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 (kind !== "sparseView" && d.when) {
+      throw new Error(
+        `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.`
+      );
+    }
+  }
+  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;
+    }
+  }
+  const slices = decls.map((d) => sliceFromDeclaration(d));
+  return {
+    name: viewName,
+    viewClass,
+    pattern,
+    slices,
+    ...updateMode !== void 0 ? { updateMode } : {},
+    ...consistency !== void 0 ? { consistency } : {}
+  };
+}
+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(
+        `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
+    });
+  }
+  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 } : {}
+    });
+  }
+  return out;
+}
+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).`
+        );
+      }
+    }
+  }
+}
+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 out;
+}
+
+// src/relation/maintenance-graph.ts
+var COUNT_DELTA_FOR_EVENT = {
+  created: 1,
+  removed: -1,
+  updated: 0
+};
+var MAINTAIN_EVENTS = ["created", "updated", "removed"];
+function isPathRooted(value) {
+  return value.startsWith("$.input.") || value.startsWith("$.entity.");
+}
+function sourceAttributeOf(path) {
+  const stripped = path.replace(/^\$\.(input|entity)\./, "");
+  return stripped.split(".")[0] ?? stripped;
+}
+function normalizeProjectionEntry(value) {
+  if (typeof value === "string") {
+    const path = isPathRooted(value) ? value : `$.entity.${value}`;
+    return identity(path);
+  }
+  return value;
+}
+function buildProjectionMap(projection, ownerEntity, relationProperty) {
+  const entries = projection ? Object.entries(projection) : [];
+  if (entries.length === 0) {
+    throw new Error(
+      `Relation '${relationProperty}' on '${ownerEntity}' declares maintenance (\`write.maintainedOn\`) but no \`projection\`: a maintained snapshot / collection with no captured attributes projects nothing. Declare a \`projection\` map (e.g. \`{ postId: 'postId', textPreview: preview('body', 120) }\`).`
+    );
+  }
+  const out = {};
+  for (const [attr, value] of entries) {
+    out[attr] = normalizeProjectionEntry(value);
+  }
+  return out;
+}
+function buildDestinationKeys(keyBinding) {
+  const keys = {};
+  const sourceFields = [];
+  for (const [sourceField, ownerField] of Object.entries(keyBinding)) {
+    keys[ownerField] = `$.entity.${sourceField}`;
+    sourceFields.push(sourceField);
+  }
+  return { keys, sourceFields };
+}
+function sourcePayloadAttributes(meta) {
+  const attrs = /* @__PURE__ */ new Set();
+  for (const f of meta.fields) attrs.add(f.propertyName);
+  if (meta.primaryKey) {
+    for (const f of segmentFieldNames(meta.primaryKey.segmented.pkSegments)) attrs.add(f);
+    for (const f of segmentFieldNames(meta.primaryKey.segmented.skSegments)) attrs.add(f);
+  }
+  for (const gsi of meta.gsiDefinitions) {
+    for (const f of segmentFieldNames(gsi.segmented.pkSegments)) attrs.add(f);
+    for (const f of segmentFieldNames(gsi.segmented.skSegments)) attrs.add(f);
+  }
+  return attrs;
+}
+function assertMaintenanceRoundTrips(args) {
+  const {
+    ownerEntity,
+    relationProperty,
+    ownerMeta,
+    sourceEntity,
+    sourceMeta,
+    destinationKeyFields,
+    keyBindingSourceFields,
+    projection
+  } = args;
+  const sourceAttrs = sourcePayloadAttributes(sourceMeta);
+  try {
+    resolveKey([...destinationKeyFields], ownerMeta);
+  } catch (cause) {
+    throw new Error(
+      `Maintenance declaration for relation '${relationProperty}' on '${ownerEntity}' binds destination-key fields [${destinationKeyFields.map((f) => `'${f}'`).join(", ")}], which cover no access-pattern partition of the maintained entity '${ownerEntity}'. The maintained snapshot / collection row could not be resolved, so the snapshot key would not point at a real target row \u2014 bind the partition-key field(s) of the index the maintained row lives on. (${cause.message})`
+    );
+  }
+  for (const field of keyBindingSourceFields) {
+    if (!sourceAttrs.has(field)) {
+      throw new Error(
+        `Maintenance key binding for relation '${relationProperty}' on '${ownerEntity}' reads source field '${field}' to resolve the destination row, but the source entity '${sourceEntity}' carries no attribute '${field}' on its payload (available: ${[...sourceAttrs].sort().map((f) => `'${f}'`).join(", ")}). The destination key could not be built from the source payload \u2014 reject.`
+      );
+    }
+  }
+  for (const [attr, transform] of Object.entries(projection)) {
+    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.`
+      );
+    }
+    const srcAttr = sourceAttributeOf(transform.path);
+    if (!sourceAttrs.has(srcAttr)) {
+      throw new Error(
+        `Maintenance projection for relation '${relationProperty}' on '${ownerEntity}' captures '${attr}' from '${transform.path}', but the source entity '${sourceEntity}' carries no attribute '${srcAttr}' on its payload (available: ${[...sourceAttrs].sort().map((f) => `'${f}'`).join(", ")}). Projection is payload \u540C\u68B1 only (no fetch / re-projection): an attribute the source row does not carry cannot be projected \u2014 reject.`
+      );
+    }
+  }
+}
+function assertCounterRoundTrips(args) {
+  const {
+    ownerEntity,
+    aggregateField,
+    ownerMeta,
+    sourceEntity,
+    sourceMeta,
+    destinationKeyFields,
+    keyBindingSourceFields,
+    valueSourceFields
+  } = args;
+  const sourceAttrs = sourcePayloadAttributes(sourceMeta);
+  try {
+    resolveKey([...destinationKeyFields], ownerMeta);
+  } catch (cause) {
+    throw new Error(
+      `Counter aggregate '${aggregateField}' on '${ownerEntity}' binds destination-key fields [${destinationKeyFields.map((f) => `'${f}'`).join(", ")}], which cover no access-pattern partition of the maintained entity '${ownerEntity}'. The counter row could not be resolved \u2014 bind the partition-key field(s) of the index the counter row lives on. (${cause.message})`
+    );
+  }
+  for (const field of keyBindingSourceFields) {
+    if (!sourceAttrs.has(field)) {
+      throw new Error(
+        `Counter aggregate '${aggregateField}' on '${ownerEntity}' reads source field '${field}' to resolve the counter row, but the source entity '${sourceEntity}' carries no attribute '${field}' on its payload (available: ${[...sourceAttrs].sort().map((f) => `'${f}'`).join(", ")}). The destination key could not be built from the source payload \u2014 reject.`
+      );
+    }
+  }
+  for (const field of valueSourceFields) {
+    if (!sourceAttrs.has(field)) {
+      throw new Error(
+        `Counter aggregate '${aggregateField}' on '${ownerEntity}' tracks \`max('${field}')\`, but the source entity '${sourceEntity}' carries no attribute '${field}' on its payload (available: ${[...sourceAttrs].sort().map((f) => `'${f}'`).join(", ")}). A counter aggregates only the source payload (payload \u540C\u68B1) \u2014 reject.`
+      );
+    }
+  }
+}
+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 (logicalNameOf2(meta) === name) return klass;
+  }
+  return void 0;
+}
+function parseTrigger(raw) {
+  const idx = raw.lastIndexOf(".");
+  return { entity: raw.slice(0, idx), event: raw.slice(idx + 1) };
+}
+function buildEffect(relation, ownerFactory, trigger, keys, project, sourceMeta, ownerEntity) {
+  const write = relation.options?.write;
+  const updateMode = write?.updateMode;
+  const consistency = write?.consistency;
+  const base = {
+    trigger,
+    targetFactory: ownerFactory,
+    keys,
+    project,
+    ...updateMode !== void 0 ? { updateMode } : {},
+    ...consistency !== void 0 ? { consistency } : {}
+  };
+  if (relation.type === "hasMany") {
+    const read = relation.options?.read;
+    const order = resolveCollectionOrder(relation, sourceMeta, ownerEntity, project);
+    const collection = {
+      field: relation.propertyName,
+      ...read?.maxItems !== void 0 ? { maxItems: read.maxItems } : {},
+      ...order !== void 0 ? { orderBy: order.orderBy, orderDir: order.orderDir } : {}
+    };
+    return { kind: "collection", ...base, collection };
+  }
+  return { kind: "snapshot", ...base };
+}
+function viewSliceProperty(viewName, sliceIndex, slice) {
+  return slice.collection ? `${viewName}#${slice.collection.field}` : `${viewName}#${sliceIndex}`;
+}
+function buildViewEffect(view, slice, trigger) {
+  const targetFactory = () => view.viewClass;
+  const base = {
+    trigger,
+    targetFactory,
+    keys: slice.keys,
+    project: slice.project,
+    ...view.updateMode !== void 0 ? { updateMode: view.updateMode } : {},
+    ...view.consistency !== void 0 ? { consistency: view.consistency } : {}
+  };
+  if (slice.predicate) {
+    return { kind: "membership", ...base, predicate: slice.predicate };
+  }
+  if (slice.collection) {
+    const collection = {
+      field: slice.collection.field,
+      ...slice.collection.maxItems !== void 0 ? { maxItems: slice.collection.maxItems } : {},
+      ...slice.collection.orderBy !== void 0 ? {
+        orderBy: slice.collection.orderBy,
+        orderDir: slice.collection.orderDir ?? "DESC"
+      } : {}
+    };
+    return { kind: "collection", ...base, collection };
+  }
+  return { kind: "snapshot", ...base };
+}
+function resolveCollectionOrder(relation, sourceMeta, ownerEntity, project) {
+  const order = relation.options?.read?.order;
+  if (order === void 0) return void 0;
+  const skFields = sourceMeta.primaryKey ? segmentFieldNames(sourceMeta.primaryKey.segmented.skSegments) : [];
+  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 '${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 '${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 };
+}
+function buildCounterEffect(aggregate, ownerFactory, trigger, event, keys) {
+  const write = aggregate.options.write;
+  const updateMode = write?.updateMode;
+  const consistency = write?.consistency;
+  const value = aggregate.options.value.op === "count" ? { op: "count" } : { op: "max", field: aggregate.options.value.field };
+  return {
+    kind: "counter",
+    trigger,
+    targetFactory: ownerFactory,
+    keys,
+    attribute: aggregate.propertyName,
+    value,
+    ...value.op === "count" ? { delta: COUNT_DELTA_FOR_EVENT[event] } : {},
+    ...updateMode !== void 0 ? { updateMode } : {},
+    ...consistency !== void 0 ? { consistency } : {}
+  };
+}
+function destinationRowKeyOf(ownerEntity, keys) {
+  const parts = Object.entries(keys).map(([field, path]) => `${field}=${path}`).sort();
+  return `${ownerEntity}#${parts.join("&")}`;
+}
+function assertNoCycle(items) {
+  const adjacency = /* @__PURE__ */ new Map();
+  for (const item of items) {
+    if (!adjacency.has(item.sourceEntity)) adjacency.set(item.sourceEntity, /* @__PURE__ */ new Set());
+    adjacency.get(item.sourceEntity).add(item.ownerEntity);
+  }
+  const WHITE = 0;
+  const GRAY = 1;
+  const BLACK = 2;
+  const color = /* @__PURE__ */ new Map();
+  for (const node of adjacency.keys()) color.set(node, WHITE);
+  for (const start of adjacency.keys()) {
+    if (color.get(start) !== WHITE) continue;
+    const stack = [];
+    const path = [];
+    color.set(start, GRAY);
+    path.push(start);
+    stack.push({ node: start, iter: (adjacency.get(start) ?? /* @__PURE__ */ new Set()).values() });
+    while (stack.length > 0) {
+      const top = stack[stack.length - 1];
+      const next = top.iter.next();
+      if (next.done) {
+        color.set(top.node, BLACK);
+        stack.pop();
+        path.pop();
+        continue;
+      }
+      const child = next.value;
+      const childColor = color.get(child) ?? WHITE;
+      if (childColor === GRAY) {
+        const from = path.indexOf(child);
+        const cycle = [...path.slice(from), child].join(" \u2192 ");
+        throw new Error(
+          `Maintenance dependency cycle detected: ${cycle}. A maintenance trigger chain that loops back on itself is an unbounded cascade \u2014 break the cycle (an entity's maintained shape must not, transitively, be triggered by its own maintenance).`
+        );
+      }
+      if (childColor === WHITE) {
+        color.set(child, GRAY);
+        path.push(child);
+        stack.push({ node: child, iter: (adjacency.get(child) ?? /* @__PURE__ */ new Set()).values() });
+      }
+    }
+  }
+}
+function buildMaintenanceGraph(registry, views) {
+  const resolvedRegistry = registry ?? MetadataRegistry.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 = logicalNameOf2(ownerMeta);
+    const relations = [...ownerMeta.relations].sort(
+      (a, b) => a.propertyName < b.propertyName ? -1 : a.propertyName > b.propertyName ? 1 : 0
+    );
+    for (const relation of relations) {
+      const maintainedOn = relation.options?.write?.maintainedOn;
+      if (!maintainedOn || maintainedOn.length === 0) continue;
+      const sourceClass = relation.targetFactory();
+      const sourceMeta = MetadataRegistry.get(sourceClass);
+      const relationTargetEntity = logicalNameOf2(sourceMeta);
+      const project = buildProjectionMap(
+        relation.options?.projection,
+        ownerEntity,
+        relation.propertyName
+      );
+      const { keys, sourceFields } = buildDestinationKeys(relation.keyBinding);
+      const destinationKeyFields = Object.keys(keys);
+      for (const raw of maintainedOn) {
+        if (!isMaintainTrigger(raw)) {
+          const { event } = parseTrigger(raw);
+          throw new Error(
+            `Maintenance trigger ${JSON.stringify(raw)} on relation '${relation.propertyName}' of '${ownerEntity}' is not a well-formed \`Entity.event\` trigger (event must be one of ${MAINTAIN_EVENTS.map((e) => `'${e}'`).join(" / ")}; got '${event}'). Fix the \`write.maintainedOn\` entry.`
+          );
+        }
+        const trigger = raw;
+        const { entity: triggerEntity } = parseTrigger(trigger);
+        if (!resolveEntityByName(triggerEntity, registry)) {
+          throw new Error(
+            `Maintenance trigger '${trigger}' on relation '${relation.propertyName}' of '${ownerEntity}' names source entity '${triggerEntity}', which is not a registered model. Declare a model named '${triggerEntity}' or fix the trigger's entity segment.`
+          );
+        }
+        if (triggerEntity !== relationTargetEntity) {
+          throw new Error(
+            `Maintenance trigger '${trigger}' on relation '${relation.propertyName}' of '${ownerEntity}' names source entity '${triggerEntity}', but the relation's target (the projected source) is '${relationTargetEntity}'. #124 projects only from the relation target's payload (payload \u540C\u68B1); a trigger on a different entity needs a write-time context fetch, which is Phase 2 \u2014 restrict \`maintainedOn\` to '${relationTargetEntity}.*' triggers.`
+          );
+        }
+        assertMaintenanceRoundTrips({
+          ownerEntity,
+          relationProperty: relation.propertyName,
+          ownerMeta,
+          sourceEntity: triggerEntity,
+          sourceMeta,
+          destinationKeyFields,
+          keyBindingSourceFields: sourceFields,
+          projection: project
+        });
+        const effect = buildEffect(
+          relation,
+          () => ownerClass,
+          trigger,
+          keys,
+          project,
+          sourceMeta,
+          ownerEntity
+        );
+        items.push({
+          trigger,
+          sourceEntity: triggerEntity,
+          sourceClass,
+          ownerEntity,
+          ownerClass,
+          relationProperty: relation.propertyName,
+          destinationRowKey: destinationRowKeyOf(ownerEntity, keys),
+          effect
+        });
+      }
+    }
+    const aggregates = [...ownerMeta.aggregates].sort(
+      (a, b) => a.propertyName < b.propertyName ? -1 : a.propertyName > b.propertyName ? 1 : 0
+    );
+    for (const agg of aggregates) {
+      const maintainedOn = agg.options.write?.maintainedOn;
+      if (!maintainedOn || maintainedOn.length === 0) continue;
+      const sourceClass = agg.targetFactory();
+      const sourceMeta = MetadataRegistry.get(sourceClass);
+      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] : [];
+      for (const raw of maintainedOn) {
+        if (!isMaintainTrigger(raw)) {
+          const { event: event2 } = parseTrigger(raw);
+          throw new Error(
+            `Maintenance trigger ${JSON.stringify(raw)} on \`@aggregate\` field '${agg.propertyName}' of '${ownerEntity}' is not a well-formed \`Entity.event\` trigger (event must be one of ${MAINTAIN_EVENTS.map((e) => `'${e}'`).join(" / ")}; got '${event2}'). Fix the \`write.maintainedOn\` entry.`
+          );
+        }
+        const trigger = raw;
+        const parsed = parseTrigger(trigger);
+        const triggerEntity = parsed.entity;
+        const event = parsed.event;
+        if (!resolveEntityByName(triggerEntity, registry)) {
+          throw new Error(
+            `Maintenance trigger '${trigger}' on \`@aggregate\` field '${agg.propertyName}' of '${ownerEntity}' names source entity '${triggerEntity}', which is not a registered model. Declare a model named '${triggerEntity}' or fix the trigger's entity segment.`
+          );
+        }
+        if (triggerEntity !== aggSourceEntity) {
+          throw new Error(
+            `Maintenance trigger '${trigger}' on \`@aggregate\` field '${agg.propertyName}' of '${ownerEntity}' names source entity '${triggerEntity}', but the aggregate's source (the entity being counted) is '${aggSourceEntity}'. A counter aggregates only the rows of its own source (payload \u540C\u68B1); a trigger on a different entity is Phase 2 \u2014 restrict \`maintainedOn\` to '${aggSourceEntity}.*' triggers.`
+          );
+        }
+        if (agg.options.value.op === "count" && COUNT_DELTA_FOR_EVENT[event] === 0) {
+          throw new Error(
+            `\`@aggregate\` field '${agg.propertyName}' of '${ownerEntity}' is a \`count()\` counter maintained on '${trigger}', but a 'updated' event does not change a row count (it adds 0). A \`count()\` counter is maintained on 'created' (+1) and 'removed' (-1); drop the 'updated' trigger.`
+          );
+        }
+        assertCounterRoundTrips({
+          ownerEntity,
+          aggregateField: agg.propertyName,
+          ownerMeta,
+          sourceEntity: triggerEntity,
+          sourceMeta,
+          destinationKeyFields,
+          keyBindingSourceFields: sourceFields,
+          valueSourceFields
+        });
+        const effect = buildCounterEffect(agg, () => ownerClass, trigger, event, keys);
+        items.push({
+          trigger,
+          sourceEntity: triggerEntity,
+          sourceClass,
+          ownerEntity,
+          ownerClass,
+          relationProperty: agg.propertyName,
+          destinationRowKey: destinationRowKeyOf(ownerEntity, keys),
+          effect
+        });
+      }
+    }
+  }
+  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 = logicalNameOf2(ownerMeta);
+    view.slices.forEach((slice, sliceIndex) => {
+      const sourceClass = slice.sourceClass;
+      const sourceMeta = MetadataRegistry.get(sourceClass);
+      const sourceEntity = logicalNameOf2(sourceMeta);
+      const keys = slice.keys;
+      const destinationKeyFields = Object.keys(keys);
+      const keyBindingSourceFields = Object.values(keys).map((p) => sourceAttributeOf(p));
+      for (const trigger of slice.maintainedOn) {
+        const { entity: triggerEntity } = parseTrigger(trigger);
+        if (triggerEntity !== sourceEntity) {
+          throw new Error(
+            `defineView '${view.name}': source slice trigger '${trigger}' names entity '${triggerEntity}', but the slice's source entity is '${sourceEntity}'. A view source projects only from its own payload (payload \u540C\u68B1); a trigger on a different entity needs a write-time context fetch (RFC \xA74.A.6), which is a deferred follow-up \u2014 restrict the slice's \`maintainedOn\` to '${sourceEntity}.*' triggers.`
+          );
+        }
+        assertMaintenanceRoundTrips({
+          ownerEntity,
+          relationProperty: viewSliceProperty(view.name, sliceIndex, slice),
+          ownerMeta,
+          sourceEntity,
+          sourceMeta,
+          destinationKeyFields,
+          keyBindingSourceFields,
+          projection: slice.project
+        });
+        if (slice.predicate) {
+          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.`
+            );
+          }
+          const predAttr = sourceAttributeOf(slice.predicate.path);
+          if (!sourcePayloadAttributes(sourceMeta).has(predAttr)) {
+            throw new Error(
+              `defineView '${view.name}': sparse-view predicate reads source attribute '${predAttr}' (from '${slice.predicate.path}'), but the source entity '${sourceEntity}' carries no such attribute on its payload (available: ${[...sourcePayloadAttributes(sourceMeta)].sort().map((f) => `'${f}'`).join(", ")}). A membership predicate is payload \u540C\u68B1 only \u2014 reject.`
+            );
+          }
+        }
+        const effect = buildViewEffect(view, slice, trigger);
+        items.push({
+          trigger,
+          sourceEntity,
+          sourceClass,
+          ownerEntity,
+          ownerClass,
+          relationProperty: viewSliceProperty(view.name, sliceIndex, slice),
+          destinationRowKey: destinationRowKeyOf(ownerEntity, keys),
+          effect
+        });
+      }
+    });
+  }
+  assertNoCycle(items);
+  const byTrigger = /* @__PURE__ */ new Map();
+  const sameRow = /* @__PURE__ */ new Map();
+  for (const item of items) {
+    const triggerBucket = byTrigger.get(item.trigger);
+    if (triggerBucket) triggerBucket.push(item);
+    else byTrigger.set(item.trigger, [item]);
+    const rowKey = `${item.trigger}\0${item.destinationRowKey}`;
+    const rowBucket = sameRow.get(rowKey);
+    if (rowBucket) rowBucket.push(item);
+    else sameRow.set(rowKey, [item]);
+  }
+  const multiMaintainerTargets = /* @__PURE__ */ new Map();
+  for (const [rowKey, bucket] of sameRow) {
+    if (bucket.length > 1) multiMaintainerTargets.set(rowKey, bucket);
+  }
+  return {
+    items,
+    byTrigger,
+    effectsFor(trigger) {
+      return byTrigger.get(trigger) ?? [];
+    },
+    multiMaintainerTargets
+  };
+}
+
+// src/cdc/from-change.ts
+function buildFullSelect(metadata) {
+  const select = {};
+  for (const field of metadata.fields) {
+    select[field.propertyName] = true;
+  }
+  return select;
+}
+function eventOwnedBy(event, metadata, modelName) {
+  if (event.model !== void 0) {
+    return event.model === modelName;
+  }
+  return metadata.prefix.length > 0 && event.keys.pk.startsWith(metadata.prefix);
+}
+function hydrateImage(image, select, metadata, modelClass) {
+  if (image === void 0) return null;
+  const [hydrated] = hydrate([image], select, metadata);
+  const instance = new modelClass();
+  Object.assign(instance, hydrated);
+  for (const emb of metadata.embeddedFields) {
+    const rawEmb = image[emb.propertyName];
+    if (rawEmb !== void 0 && rawEmb !== null) {
+      instance[emb.propertyName] = rawEmb;
+    }
+  }
+  return instance;
+}
+function parseChange(event, metadata, modelName, modelClass) {
+  if (!eventOwnedBy(event, metadata, modelName)) {
+    return [null, null];
+  }
+  const select = buildFullSelect(metadata);
+  const oldRecord = hydrateImage(event.oldImage, select, metadata, modelClass);
+  const newRecord = hydrateImage(event.newImage, select, metadata, modelClass);
+  return [oldRecord, newRecord];
+}
+
+// src/cdc/subscribe.ts
+function resolveRoutableModels(handlers) {
+  const byName = /* @__PURE__ */ new Map();
+  for (const [cls, meta] of MetadataRegistry.getAll()) {
+    byName.set(cls.name, { cls, meta });
+  }
+  const routable = /* @__PURE__ */ new Map();
+  for (const modelName of Object.keys(handlers)) {
+    const entry = byName.get(modelName);
+    if (!entry) {
+      throw new Error(
+        `DDBModel.subscribe: no model named '${modelName}' is registered. Did you import the model module (so its @model decorator ran) and spell the handler key exactly as the class name?`
+      );
+    }
+    if (!entry.meta.cdcProjected) {
+      throw new Error(
+        `DDBModel.subscribe: model '${modelName}' is not @cdcProjected, so its change events cannot be parsed. Add @cdcProjected() to the model, or remove its handler.`
+      );
+    }
+    routable.set(modelName, {
+      modelClass: entry.cls,
+      metadata: entry.meta,
+      modelName
+    });
+  }
+  return routable;
+}
+async function dispatchEvent(event, routable, handlers) {
+  for (const { modelClass, metadata, modelName } of routable.values()) {
+    const [oldRecord, newRecord] = parseChange(
+      event,
+      metadata,
+      modelName,
+      modelClass
+    );
+    if (oldRecord === null && newRecord === null) continue;
+    const handler = handlers[modelName];
+    await handler(oldRecord, newRecord);
+    return true;
+  }
+  return false;
+}
+function buildSubscribeHandler(handlers) {
+  const routable = resolveRoutableModels(handlers);
+  return async (batch) => {
+    const batchItemFailures = [];
+    for (const event of batch.records) {
+      try {
+        await dispatchEvent(event, routable, handlers);
+      } catch {
+        batchItemFailures.push(event.sequenceNumber);
+      }
+    }
+    return { batchItemFailures };
+  };
+}
+
+export {
+  SELECT_SPEC,
+  isSelectBuilder,
+  normalizeSelectSpec,
+  normalizeTopLevelSelect,
+  buildProject,
+  buildRelation,
+  isInlineSnapshotSpec,
+  detectRelationFields,
+  validateInlineSnapshotSelect,
+  getImplicitKeyFields,
+  hydrate,
+  maintainTrigger,
+  isMaintainTrigger,
+  preview,
+  identity,
+  LIFECYCLE_CONTRACT_MARKER,
+  isLifecycleContract,
+  ENTITY_WRITES_MARKER,
+  isEntityWritesDefinition,
+  entityWrites,
+  getEntityWrites,
+  lifecyclePhaseForIntent,
+  collectViewDefinitions,
+  buildMaintenanceGraph,
+  parseChange,
+  buildSubscribeHandler
+};