graphddb 0.2.5 → 0.3.1

package/dist/{chunk-4TYK3AV6.js → chunk-YIXXTGZ6.js}

@@ -411,6 +411,437 @@ var relationDepthRule = {
   }
 };
 
+// src/linter/rules/same-partition-preset.ts
+var samePartitionPresetRule = {
+  id: "same-partition-preset",
+  severity: "error",
+  check(metadata, registry) {
+    const results = [];
+    for (const relation of metadata.relations) {
+      if (relation.options?.pattern !== "samePartition") continue;
+      results.push(...checkRelation(metadata, relation, registry));
+    }
+    return results;
+  }
+};
+function err(metadata, relation, message) {
+  return {
+    ruleId: "same-partition-preset",
+    severity: "error",
+    message: `Relation '${relation.propertyName}' on entity '${metadata.prefix}' declares pattern 'samePartition' but ${message}`,
+    entity: metadata.prefix,
+    field: relation.propertyName
+  };
+}
+function checkRelation(metadata, relation, registry) {
+  if (relation.type !== "hasMany") {
+    return [
+      err(
+        metadata,
+        relation,
+        `is a '${relation.type}'. 'samePartition' lowers a parent\u2192children collection read (begins_with on a segmented sort key) and is only valid on @hasMany.`
+      )
+    ];
+  }
+  const results = [];
+  const maintenanceOptions = ["read", "write", "projection"].filter(
+    (k2) => relation.options?.[k2] !== void 0
+  );
+  if (maintenanceOptions.length > 0) {
+    results.push(
+      err(
+        metadata,
+        relation,
+        `also sets [${maintenanceOptions.join(", ")}]. 'samePartition' has no maintained materialisation \u2014 children are read live by begins_with, so it carries no read/write/projection effect. Drop these options (or use a maintained preset such as 'embeddedSnapshot').`
+      )
+    );
+  }
+  const targetFields = Object.keys(relation.keyBinding);
+  if (targetFields.length === 0) {
+    results.push(
+      err(metadata, relation, `has an empty keyBinding; nothing to lower.`)
+    );
+    return results;
+  }
+  let targetMeta;
+  try {
+    const targetClass = relation.targetFactory();
+    targetMeta = registry.get(targetClass);
+  } catch {
+    results.push(
+      err(
+        metadata,
+        relation,
+        `targets an entity that is not registered in MetadataRegistry.`
+      )
+    );
+    return results;
+  }
+  let resolved;
+  try {
+    resolved = resolveKey(targetFields, targetMeta);
+  } catch {
+    results.push(
+      err(
+        metadata,
+        relation,
+        `binds [${targetFields.join(", ")}] on target '${targetMeta.prefix}', which matches no access pattern. A same-partition relation must bind a contiguous prefix of the target's primary key.`
+      )
+    );
+    return results;
+  }
+  if (resolved.type !== "pk") {
+    results.push(
+      err(
+        metadata,
+        relation,
+        `binds [${targetFields.join(", ")}] to a ${resolved.type.toUpperCase()} on target '${targetMeta.prefix}'. A GSI is a different partition; 'samePartition' requires the binding to resolve on the target's primary key (same PK, segmented-SK begins_with).`
+      )
+    );
+    return results;
+  }
+  if (!resolved.partial) {
+    results.push(
+      err(
+        metadata,
+        relation,
+        `binds the target's full primary key on '${targetMeta.prefix}', which is a point read of a single item, not a child collection. 'samePartition' requires a partial key \u2014 the parent fields fully supply the PK and a proper prefix of the segmented SK, leaving a begins_with boundary for the children.`
+      )
+    );
+  }
+  return results;
+}
+
+// src/linter/rules/maintenance-shared.ts
+function isMaintainedRelation(relation) {
+  const triggers = relation.options?.write?.maintainedOn;
+  return Array.isArray(triggers) && triggers.length > 0;
+}
+function maintainedRelations(metadata) {
+  return metadata.relations.filter(isMaintainedRelation);
+}
+function logicalName(metadata) {
+  return metadata.prefix.endsWith("#") ? metadata.prefix.slice(0, -1) : metadata.prefix;
+}
+function payloadAttributes(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 gsi2 of meta.gsiDefinitions) {
+    for (const f of segmentFieldNames(gsi2.segmented.pkSegments)) attrs.add(f);
+    for (const f of segmentFieldNames(gsi2.segmented.skSegments)) attrs.add(f);
+  }
+  return attrs;
+}
+function isPayloadRooted(value) {
+  return value.startsWith("$.input.") || value.startsWith("$.entity.");
+}
+function projectionSourceAttribute(value) {
+  const path = typeof value === "string" ? value : value.path;
+  if (typeof value === "string") {
+    if (!isPayloadRooted(path)) return path;
+  } else if (!isPayloadRooted(path)) {
+    return null;
+  }
+  const stripped = path.replace(/^\$\.(input|entity)\./, "");
+  return stripped.split(".")[0] ?? stripped;
+}
+function projectionEntries(projection) {
+  return projection ? Object.entries(projection) : [];
+}
+
+// src/linter/rules/missing-context.ts
+var missingContextRule = {
+  id: "missing-context",
+  severity: "error",
+  check(metadata, registry) {
+    const results = [];
+    for (const relation of maintainedRelations(metadata)) {
+      results.push(...checkRelation2(metadata, relation, registry));
+    }
+    return results;
+  }
+};
+function err2(metadata, relation, message) {
+  return {
+    ruleId: "missing-context",
+    severity: "error",
+    message: `Maintained relation '${relation.propertyName}' on '${logicalName(metadata)}' ${message}`,
+    entity: metadata.prefix,
+    field: relation.propertyName
+  };
+}
+function checkRelation2(metadata, relation, registry) {
+  let sourceMeta;
+  try {
+    sourceMeta = registry.get(relation.targetFactory());
+  } catch {
+    return [];
+  }
+  const sourceName = logicalName(sourceMeta);
+  const payload = payloadAttributes(sourceMeta);
+  const available = `available: ${[...payload].sort().map((f) => `'${f}'`).join(", ")}`;
+  const results = [];
+  for (const sourceField of Object.keys(relation.keyBinding)) {
+    if (!payload.has(sourceField)) {
+      results.push(
+        err2(
+          metadata,
+          relation,
+          `resolves its destination row from source field '${sourceField}', but the source entity '${sourceName}' carries no such attribute on its write payload (${available}). Phase 1 maintenance is payload \u540C\u68B1 only (no write-time fetch) \u2014 include '${sourceField}' on '${sourceName}' or bind a key field it does carry.`
+        )
+      );
+    }
+  }
+  for (const [attr, value] of projectionEntries(relation.options?.projection)) {
+    const path = typeof value === "string" ? value : value.path;
+    const srcAttr = projectionSourceAttribute(value);
+    if (srcAttr === null || typeof value !== "string" && !isPayloadRooted(path)) {
+      results.push(
+        err2(
+          metadata,
+          relation,
+          `projects '${attr}' from '${path}', which is not a payload-rooted source path (\`$.input.*\` / \`$.entity.*\`). Phase 1 maintenance projects only from the source payload (payload \u540C\u68B1); there is no fetch / re-projection.`
+        )
+      );
+      continue;
+    }
+    if (!payload.has(srcAttr)) {
+      results.push(
+        err2(
+          metadata,
+          relation,
+          `projects '${attr}' from source attribute '${srcAttr}', but the source entity '${sourceName}' carries no such attribute on its write payload (${available}). Phase 1 maintenance is payload \u540C\u68B1 only (no write-time fetch / re-projection) \u2014 an attribute the source row does not carry cannot be projected.`
+        )
+      );
+    }
+  }
+  return results;
+}
+
+// src/linter/rules/embedded-snapshot-size.ts
+var ITEM_LIMIT_BYTES = 400 * 1024;
+var SOFT_BUDGET_BYTES = ITEM_LIMIT_BYTES / 2;
+var DEFAULT_STRING_BYTES = 256;
+var ATTR_NAME_OVERHEAD_BYTES = 16;
+var embeddedSnapshotSizeRule = {
+  id: "400kb",
+  severity: "warning",
+  check(metadata, _registry) {
+    const results = [];
+    for (const relation of maintainedRelations(metadata)) {
+      const result = checkRelation3(metadata, relation);
+      if (result) results.push(result);
+    }
+    return results;
+  }
+};
+function estimateItemBytes(relation) {
+  let bytes = 0;
+  for (const [attr, value] of projectionEntries(relation.options?.projection)) {
+    bytes += ATTR_NAME_OVERHEAD_BYTES + attr.length;
+    bytes += attributeValueBytes(value);
+  }
+  return bytes;
+}
+function attributeValueBytes(value) {
+  if (typeof value !== "string" && value.op === "preview") {
+    const [n] = value.args;
+    if (typeof n === "number" && Number.isFinite(n)) return n;
+  }
+  return DEFAULT_STRING_BYTES;
+}
+function checkRelation3(metadata, relation) {
+  const itemBytes = estimateItemBytes(relation);
+  if (itemBytes === 0) return null;
+  const isCollection = relation.type === "hasMany";
+  const maxItems = relation.options?.read?.maxItems;
+  if (isCollection && maxItems === void 0) return null;
+  const count = isCollection ? maxItems : 1;
+  const estimate = itemBytes * count;
+  const shape = isCollection ? `${count} item(s) \xD7 ~${itemBytes} B` : `~${itemBytes} B snapshot`;
+  if (estimate >= ITEM_LIMIT_BYTES) {
+    return {
+      ruleId: "400kb",
+      severity: "error",
+      message: `Maintained relation '${relation.propertyName}' on '${logicalName(metadata)}' materializes ${shape} \u2248 ${estimate} B onto the owner row, which meets or exceeds DynamoDB's 400 KB item limit (${ITEM_LIMIT_BYTES} B). The maintenance write would fail once the collection fills \u2014 reduce \`read.maxItems\` or the projected attributes (e.g. tighter \`preview(n)\` bounds).`,
+      entity: metadata.prefix,
+      field: relation.propertyName
+    };
+  }
+  if (estimate >= SOFT_BUDGET_BYTES) {
+    return {
+      ruleId: "400kb",
+      severity: "warning",
+      message: `Maintained relation '${relation.propertyName}' on '${logicalName(metadata)}' materializes ${shape} \u2248 ${estimate} B onto the owner row, over half of DynamoDB's 400 KB item limit (${ITEM_LIMIT_BYTES} B). Little headroom remains for the rest of the item \u2014 consider a tighter \`read.maxItems\` / projection.`,
+      entity: metadata.prefix,
+      field: relation.propertyName
+    };
+  }
+  return null;
+}
+
+// src/linter/rules/hot-partition.ts
+var HOT_TRIGGER_FANIN = 2;
+var hotPartitionRule = {
+  id: "hot-partition",
+  severity: "warning",
+  check(metadata, _registry) {
+    const results = [];
+    const maintained = maintainedRelations(metadata);
+    for (const relation of maintained) {
+      if (relation.type !== "hasMany") continue;
+      if (relation.options?.read?.maxItems === void 0) {
+        results.push(unboundedWarning(metadata, relation));
+      }
+    }
+    const byTrigger = /* @__PURE__ */ new Map();
+    for (const relation of maintained) {
+      for (const trigger of relation.options?.write?.maintainedOn ?? []) {
+        const bucket = byTrigger.get(trigger);
+        if (bucket) bucket.push(relation.propertyName);
+        else byTrigger.set(trigger, [relation.propertyName]);
+      }
+    }
+    for (const [trigger, props] of byTrigger) {
+      if (props.length > HOT_TRIGGER_FANIN) {
+        results.push(fanInWarning(metadata, trigger, props));
+      }
+    }
+    return results;
+  }
+};
+function unboundedWarning(metadata, relation) {
+  return {
+    ruleId: "hot-partition",
+    severity: "warning",
+    message: `Maintained collection '${relation.propertyName}' on '${logicalName(metadata)}' has no \`read.maxItems\` bound: every maintained source row appends to the same owner ("root") item, so that single partition takes unbounded write traffic and the item trends toward the 400 KB limit. Declare a \`read.maxItems\` window (e.g. latest-N) or read the children from their own partition (\`samePartition\`) instead of inlining a snapshot.`,
+    entity: metadata.prefix,
+    field: relation.propertyName
+  };
+}
+function fanInWarning(metadata, trigger, props) {
+  return {
+    ruleId: "hot-partition",
+    severity: "warning",
+    message: `${props.length} maintained relations on '${logicalName(metadata)}' ([${props.map((p) => `'${p}'`).join(", ")}]) all fire on trigger '${trigger}', concentrating that many maintenance writes onto the single owner ("root") row in one mutation. This amplifies per-source-row write cost on one partition \u2014 consider splitting the maintained shapes across rows / partitions.`,
+    entity: metadata.prefix
+  };
+}
+
+// src/linter/rules/fan-out.ts
+var MAX_MAINTENANCE_HOPS = 1;
+var fanOutRule = {
+  id: "fan-out",
+  severity: "warning",
+  check(metadata, registry) {
+    const results = [];
+    for (const relation of maintainedRelations(metadata)) {
+      const point = checkDestinationFanOut(metadata, relation);
+      if (point) results.push(point);
+    }
+    const chain = maintenanceChain(metadata, registry, /* @__PURE__ */ new Set([modelKey(metadata)]));
+    if (chain.hops > MAX_MAINTENANCE_HOPS) {
+      results.push({
+        ruleId: "fan-out",
+        severity: "warning",
+        message: `Entity '${chain.root}' is the root of a maintenance chain ${chain.hops} hops deep, terminating at '${logicalName(metadata)}': a single '${chain.root}' lifecycle event cascades through ${chain.hops} maintenance writes \u2014 each maintained row is itself the trigger source of the next hop \u2014 until it reaches '${logicalName(metadata)}'. A multi-step maintenance fan-out amplifies one write into many; flatten the chain or move downstream hops to a stream (\`updateMode: 'stream'\`).`,
+        entity: metadata.prefix
+      });
+    }
+    return results;
+  }
+};
+function checkDestinationFanOut(metadata, relation) {
+  const ownerKeyFields = Object.values(relation.keyBinding);
+  if (ownerKeyFields.length === 0) return null;
+  let resolved;
+  try {
+    resolved = resolveKey(ownerKeyFields, metadata);
+  } catch {
+    return null;
+  }
+  const isPoint = !resolved.partial && (resolved.type === "pk" || resolved.type === "gsi" && resolved.unique);
+  if (isPoint) return null;
+  const shape = resolved.partial ? `a partial ${resolved.type.toUpperCase()} (a begins_with range of rows)` : `a non-unique ${resolved.type.toUpperCase()} (many matching rows)`;
+  return {
+    ruleId: "fan-out",
+    severity: "warning",
+    message: `Maintained relation '${relation.propertyName}' on '${logicalName(metadata)}' binds its destination row by [${ownerKeyFields.map((f) => `'${f}'`).join(", ")}], which resolves to ${shape} on '${logicalName(metadata)}'. A single source event then fans its maintenance write out across every matching destination row in one mutation (unbounded fan-out). Bind the destination's full primary key (or a unique GSI) so each source event maintains exactly one row.`,
+    entity: metadata.prefix,
+    field: relation.propertyName
+  };
+}
+function modelKey(metadata) {
+  return logicalName(metadata);
+}
+function maintenanceChain(metadata, registry, visited) {
+  const maintained = maintainedRelations(metadata);
+  if (maintained.length === 0) return { hops: 0, root: logicalName(metadata) };
+  let best = { hops: 0, root: logicalName(metadata) };
+  for (const relation of maintained) {
+    let targetMeta;
+    try {
+      targetMeta = registry.get(relation.targetFactory());
+    } catch {
+      continue;
+    }
+    const key2 = modelKey(targetMeta);
+    if (visited.has(key2)) continue;
+    const next = new Set(visited);
+    next.add(key2);
+    const upstream = maintenanceChain(targetMeta, registry, next);
+    if (1 + upstream.hops > best.hops) {
+      best = { hops: 1 + upstream.hops, root: upstream.root };
+    }
+  }
+  return best;
+}
+
+// src/linter/rules/multi-maintainer-same-row.ts
+var multiMaintainerSameRowRule = {
+  id: "multi-maintainer-same-row",
+  severity: "error",
+  check(metadata, _registry) {
+    const maintained = maintainedRelations(metadata);
+    if (maintained.length < 2) return [];
+    const owner = logicalName(metadata);
+    const groups = /* @__PURE__ */ new Map();
+    for (const relation of maintained) {
+      const rowKey = destinationRowKey(owner, relation);
+      for (const trigger of relation.options?.write?.maintainedOn ?? []) {
+        const groupKey = `${trigger} ${rowKey}`;
+        const group = groups.get(groupKey);
+        if (group) group.props.push(relation.propertyName);
+        else groups.set(groupKey, { trigger, props: [relation.propertyName] });
+      }
+    }
+    const results = [];
+    for (const { trigger, props } of groups.values()) {
+      if (props.length < 2) continue;
+      results.push({
+        ruleId: "multi-maintainer-same-row",
+        severity: "error",
+        message: `Maintained relations [${props.map((p) => `'${p}'`).join(", ")}] on '${owner}' all fire on trigger '${trigger}' and write the SAME destination row. Phase 1 maintenance is "1 mutation \xD7 1 target row = 1 effect" (\u8AD6\u70B92 = b): a single mutation cannot touch one row with ${props.length} maintain effects \u2014 DynamoDB rejects two writes to the same key in one TransactWriteItems (cf. #96). Merge the projections into one maintained relation, or split them onto distinct destination rows / triggers.`,
+        entity: metadata.prefix,
+        field: props[0]
+      });
+    }
+    return results;
+  }
+};
+function destinationRowKey(owner, relation) {
+  const parts = Object.entries(relation.keyBinding).map(([sourceField, ownerField]) => `${ownerField}=$.entity.${sourceField}`).sort();
+  return `${owner}#${parts.join("&")}`;
+}
+
 // src/linter/default-linter.ts
 function createDefaultLinter() {
   const linter = new Linter();
@@ -419,6 +850,12 @@ function createDefaultLinter() {
   linter.addRule(gsiAmbiguityRule);
   linter.addRule(missingGsiRule);
   linter.addRule(relationDepthRule);
+  linter.addRule(samePartitionPresetRule);
+  linter.addRule(missingContextRule);
+  linter.addRule(embeddedSnapshotSizeRule);
+  linter.addRule(hotPartitionRule);
+  linter.addRule(fanOutRule);
+  linter.addRule(multiMaintainerSameRowRule);
   return linter;
 }
 
@@ -426,8 +863,27 @@ function createDefaultLinter() {
 var MetadataRegistry = class {
   static store = /* @__PURE__ */ new Map();
   static _linter = createDefaultLinter();
+  /**
+   * A monotonically-increasing counter bumped on every change to the set of
+   * registered models ({@link register} / {@link clear}). It lets a consumer that
+   * caches a structure derived from the whole registry (e.g. the maintenance graph
+   * in `src/spec/mutation-command.ts`) detect that the registry has changed since
+   * the cache was built and rebuild — closing the silent-drop window where a model
+   * registered after a cache build would be invisible to it. Only the membership
+   * of {@link store} changes here; per-model lazy finalize ({@link finalize}) does
+   * not bump it (it adds no relations/triggers, so it cannot change the graph).
+   */
+  static _generation = 0;
+  /**
+   * The current registry generation (see {@link _generation}). A consumer caches
+   * the value it built against and rebuilds when it no longer matches.
+   */
+  static get generation() {
+    return this._generation;
+  }
   static register(target, metadata) {
     this.store.set(target, { ...metadata, _finalized: false });
+    this._generation++;
   }
   static get(target) {
     const meta = this.store.get(target);
@@ -466,6 +922,7 @@ var MetadataRegistry = class {
   static clear() {
     this.store.clear();
     this._linter = new Linter();
+    this._generation++;
   }
   static finalize(target, meta) {
     for (const name of Object.getOwnPropertyNames(target)) {
@@ -1858,14 +2315,14 @@ var MiddlewareRuntime = class {
    * is the host's responsibility — a hook recovering a `query` should return an
    * item / `null`, one recovering a `list` a `{ items, cursor }`.
    */
-  async runRequestError(ctx, err) {
+  async runRequestError(ctx, err3) {
     for (let i = this.chain.length - 1; i >= 0; i--) {
       const onError = this.chain[i].read?.onError;
       if (!onError) continue;
-      const recovered = await onError(ctx, err);
+      const recovered = await onError(ctx, err3);
       if (recovered !== void 0) return recovered;
     }
-    throw err;
+    throw err3;
   }
   /**
    * Drive ONE physical op (root read or any fan-out fetch) through R2 → send →
@@ -1905,14 +2362,14 @@ var MiddlewareRuntime = class {
         if (afterFetch) items = await afterFetch(ctx, items);
       }
       return items;
-    } catch (err) {
+    } catch (err3) {
       for (let i = this.chain.length - 1; i >= 0; i--) {
         const onError = this.chain[i].read?.op?.onError;
         if (!onError) continue;
-        const recovered = await onError(ctx, err);
+        const recovered = await onError(ctx, err3);
         if (recovered !== void 0) return recovered;
       }
-      throw err;
+      throw err3;
     }
   }
 };
@@ -1976,14 +2433,14 @@ var WriteRuntime = class {
    * short-circuits the chain); the value becomes the write's resolved value.
    * Otherwise the original error rethrows (symmetric with the read `onError`).
    */
-  async runWriteError(ctx, err) {
+  async runWriteError(ctx, err3) {
     for (let i = this.chain.length - 1; i >= 0; i--) {
       const onError = this.chain[i].write?.onError;
       if (!onError) continue;
-      const recovered = await onError(ctx, err);
+      const recovered = await onError(ctx, err3);
       if (recovered !== void 0) return recovered;
     }
-    throw err;
+    throw err3;
   }
   /** Build a W3/W4/W5 persist context (pure — no hooks run). */
   persistCtx(items, origins, transaction) {
@@ -2012,20 +2469,20 @@ var WriteRuntime = class {
         if (before) await before(ctx);
       }
       results = await send(ctx.items);
-    } catch (err) {
+    } catch (err3) {
       let recovered;
       let didRecover = false;
       for (let i = this.chain.length - 1; i >= 0; i--) {
         const onError = this.chain[i].write?.persist?.onError;
         if (!onError) continue;
-        const r = await onError(ctx, err);
+        const r = await onError(ctx, err3);
         if (r !== void 0) {
           recovered = r;
           didRecover = true;
           break;
         }
       }
-      if (!didRecover) throw err;
+      if (!didRecover) throw err3;
       results = recovered;
     }
     for (let i = this.chain.length - 1; i >= 0; i--) {
@@ -2246,8 +2703,8 @@ async function executeSingleWriteWithHooks(req, mw) {
     await mw.runWriteBefore(ctx);
     const change2 = await persistRewrittenWrite(req.modelClass, ctx, mw);
     await mw.runWriteAfter(ctx, change2);
-  } catch (err) {
-    await mw.runWriteError(ctx, err);
+  } catch (err3) {
+    await mw.runWriteError(ctx, err3);
   }
 }
 async function persistRewrittenWrite(modelClass, ctx, mw) {
@@ -2961,6 +3418,882 @@ function buildLogicalItem(modelClass, ctx) {
   return { Delete: buildDeleteInput(modelClass, ctx.input.key ?? {}, opts) };
 }
 
+// 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 preview(path, n) {
+  return makeProjectionTransform(path, "preview", [n]);
+}
+function identity(path) {
+  return makeProjectionTransform(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 };
+  },
+  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/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 };
+}
+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 resolveSourceClass(factory) {
+  const resolved = factory();
+  try {
+    return resolveModelClass(resolved);
+  } catch {
+    return resolved;
+  }
+}
+function isPathRooted(value) {
+  return value.startsWith("$.input.") || value.startsWith("$.entity.");
+}
+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;
+    }
+  }
+  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 (!src.maintainedOn || src.maintainedOn.length === 0) {
+      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']\`).`
+      );
+    }
+    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) {
+      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.`
+      );
+    }
+    if (pattern === "sparseView" && !predicate) {
+      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.`
+      );
+    }
+    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.`
+      );
+    }
+    slices.push({
+      sourceClass: resolveSourceClass(src.entity),
+      maintainedOn,
+      keys,
+      project,
+      ...collection ? { collection } : {},
+      ...predicate ? { predicate } : {}
+    });
+  }
+  const def = {
+    [VIEW_DEFINITION_MARKER]: true,
+    name,
+    viewClass,
+    pattern,
+    slices,
+    ...input.write?.updateMode !== void 0 ? { updateMode: input.write.updateMode } : {},
+    ...input.write?.consistency !== void 0 ? { consistency: input.write.consistency } : {}
+  };
+  ViewRegistry.register(def);
+  return def;
+}
+function defineViews(definitions) {
+  for (const [name, def] of Object.entries(definitions)) {
+    if (!isViewDefinition(def)) {
+      throw new Error(
+        `defineViews: '${name}' is not a view definition. Use defineView(name, { pattern: 'materializedView', source, keys, fields }) to build entries.`
+      );
+    }
+  }
+  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).`
+    );
+  }
+  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;
+}
+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.`
+    );
+  }
+  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.`
+      );
+    }
+  }
+  return definitions;
+}
+
+// src/relation/maintenance-graph.ts
+var COUNT_DELTA_FOR_EVENT = {
+  created: 1,
+  removed: -1,
+  updated: 0
+};
+var MAINTAIN_EVENTS = ["created", "updated", "removed"];
+function isPathRooted2(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 = isPathRooted2(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 gsi2 of meta.gsiDefinitions) {
+    for (const f of segmentFieldNames(gsi2.segmented.pkSegments)) attrs.add(f);
+    for (const f of segmentFieldNames(gsi2.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 (!isPathRooted2(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 logicalNameOf(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;
+  }
+  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 '${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\`.`
+    );
+  }
+  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\`.`
+    );
+  }
+  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 useGlobal = registry === void 0;
+  const resolvedRegistry = registry ?? MetadataRegistry.getAll();
+  const resolvedViews = views ?? (useGlobal ? ViewRegistry.getAll() : []);
+  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 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 = logicalNameOf(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 = logicalNameOf(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 = logicalNameOf(ownerMeta);
+    view.slices.forEach((slice, sliceIndex) => {
+      const sourceClass = slice.sourceClass;
+      const sourceMeta = MetadataRegistry.get(sourceClass);
+      const sourceEntity = logicalNameOf(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 (!isPathRooted2(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
+  };
+}
+
 export {
   isColumn,
   createColumnMap,
@@ -3023,5 +4356,26 @@ export {
   attachModelClass,
   resolveModelClass,
   TransactionContext,
-  executeTransaction
+  executeTransaction,
+  maintainTrigger,
+  isMaintainTrigger,
+  preview,
+  identity,
+  LIFECYCLE_CONTRACT_MARKER,
+  isLifecycleContract,
+  ENTITY_WRITES_MARKER,
+  isEntityWritesDefinition,
+  entityWrites,
+  getEntityWrites,
+  lifecyclePhaseForIntent,
+  whenMember,
+  ViewRegistry,
+  isViewDefinition,
+  defineView,
+  defineViews,
+  defineVersioned,
+  isProjectionDefinition,
+  defineProjection,
+  defineProjections,
+  buildMaintenanceGraph
 };