graphddb 0.3.0 → 0.3.1

package/dist/{chunk-6AIAHP3A.js → chunk-YIXXTGZ6.js}

@@ -3418,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,
@@ -3480,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
 };