graphddb 0.2.5 → 0.3.0

package/dist/{chunk-SGYBE2OV.js → chunk-QEOFIXTN.js}

@@ -37,7 +37,7 @@ import {
   serializeFieldValue,
   serializeRawCondition,
   skTemplate
-} from "./chunk-4TYK3AV6.js";
+} from "./chunk-6AIAHP3A.js";
 
 // src/spec/types.ts
 var SPEC_VERSION = "1.0";
@@ -1757,6 +1757,46 @@ async function executeBatchWrite(requests) {
 }
 
 // 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"
 );
@@ -1799,6 +1839,9 @@ var recorder = {
   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 };
   },
@@ -1986,6 +2029,387 @@ function deriveModelEdgeWriteItems(modelClass, lifecycle) {
   return deriveEdgeWriteItems(modelClass, writes, lifecycle);
 }
 
+// src/relation/maintenance-graph.ts
+var COUNT_DELTA_FOR_EVENT = {
+  created: 1,
+  removed: -1,
+  updated: 0
+};
+var MAINTAIN_EVENTS = ["created", "updated", "removed"];
+function isPathRooted(value) {
+  return value.startsWith("$.input.") || value.startsWith("$.entity.");
+}
+function sourceAttributeOf(path) {
+  const stripped = path.replace(/^\$\.(input|entity)\./, "");
+  return stripped.split(".")[0] ?? stripped;
+}
+function normalizeProjectionEntry(value) {
+  if (typeof value === "string") {
+    const path = isPathRooted(value) ? value : `$.entity.${value}`;
+    return identity(path);
+  }
+  return value;
+}
+function buildProjectionMap(projection, ownerEntity, relationProperty) {
+  const entries = projection ? Object.entries(projection) : [];
+  if (entries.length === 0) {
+    throw new Error(
+      `Relation '${relationProperty}' on '${ownerEntity}' declares maintenance (\`write.maintainedOn\`) but no \`projection\`: a maintained snapshot / collection with no captured attributes projects nothing. Declare a \`projection\` map (e.g. \`{ postId: 'postId', textPreview: preview('body', 120) }\`).`
+    );
+  }
+  const out = {};
+  for (const [attr, value] of entries) {
+    out[attr] = normalizeProjectionEntry(value);
+  }
+  return out;
+}
+function buildDestinationKeys(keyBinding) {
+  const keys = {};
+  const sourceFields = [];
+  for (const [sourceField, ownerField] of Object.entries(keyBinding)) {
+    keys[ownerField] = `$.entity.${sourceField}`;
+    sourceFields.push(sourceField);
+  }
+  return { keys, sourceFields };
+}
+function sourcePayloadAttributes(meta) {
+  const attrs = /* @__PURE__ */ new Set();
+  for (const f of meta.fields) attrs.add(f.propertyName);
+  if (meta.primaryKey) {
+    for (const f of segmentFieldNames(meta.primaryKey.segmented.pkSegments)) attrs.add(f);
+    for (const f of segmentFieldNames(meta.primaryKey.segmented.skSegments)) attrs.add(f);
+  }
+  for (const gsi of meta.gsiDefinitions) {
+    for (const f of segmentFieldNames(gsi.segmented.pkSegments)) attrs.add(f);
+    for (const f of segmentFieldNames(gsi.segmented.skSegments)) attrs.add(f);
+  }
+  return attrs;
+}
+function assertMaintenanceRoundTrips(args) {
+  const {
+    ownerEntity,
+    relationProperty,
+    ownerMeta,
+    sourceEntity,
+    sourceMeta,
+    destinationKeyFields,
+    keyBindingSourceFields,
+    projection
+  } = args;
+  const sourceAttrs = sourcePayloadAttributes(sourceMeta);
+  try {
+    resolveKey([...destinationKeyFields], ownerMeta);
+  } catch (cause) {
+    throw new Error(
+      `Maintenance declaration for relation '${relationProperty}' on '${ownerEntity}' binds destination-key fields [${destinationKeyFields.map((f) => `'${f}'`).join(", ")}], which cover no access-pattern partition of the maintained entity '${ownerEntity}'. The maintained snapshot / collection row could not be resolved, so the snapshot key would not point at a real target row \u2014 bind the partition-key field(s) of the index the maintained row lives on. (${cause.message})`
+    );
+  }
+  for (const field of keyBindingSourceFields) {
+    if (!sourceAttrs.has(field)) {
+      throw new Error(
+        `Maintenance key binding for relation '${relationProperty}' on '${ownerEntity}' reads source field '${field}' to resolve the destination row, but the source entity '${sourceEntity}' carries no attribute '${field}' on its payload (available: ${[...sourceAttrs].sort().map((f) => `'${f}'`).join(", ")}). The destination key could not be built from the source payload \u2014 reject.`
+      );
+    }
+  }
+  for (const [attr, transform] of Object.entries(projection)) {
+    if (!isPathRooted(transform.path)) {
+      throw new Error(
+        `Maintenance projection for relation '${relationProperty}' on '${ownerEntity}' captures attribute '${attr}' from '${transform.path}', which is not a payload-rooted source path (\`$.input.*\` / \`$.entity.*\`). The maintenance graph projects only from the source payload (payload \u540C\u68B1) \u2014 there is no fetch / re-projection.`
+      );
+    }
+    const srcAttr = sourceAttributeOf(transform.path);
+    if (!sourceAttrs.has(srcAttr)) {
+      throw new Error(
+        `Maintenance projection for relation '${relationProperty}' on '${ownerEntity}' captures '${attr}' from '${transform.path}', but the source entity '${sourceEntity}' carries no attribute '${srcAttr}' on its payload (available: ${[...sourceAttrs].sort().map((f) => `'${f}'`).join(", ")}). Projection is payload \u540C\u68B1 only (no fetch / re-projection): an attribute the source row does not carry cannot be projected \u2014 reject.`
+      );
+    }
+  }
+}
+function assertCounterRoundTrips(args) {
+  const {
+    ownerEntity,
+    aggregateField,
+    ownerMeta,
+    sourceEntity,
+    sourceMeta,
+    destinationKeyFields,
+    keyBindingSourceFields,
+    valueSourceFields
+  } = args;
+  const sourceAttrs = sourcePayloadAttributes(sourceMeta);
+  try {
+    resolveKey([...destinationKeyFields], ownerMeta);
+  } catch (cause) {
+    throw new Error(
+      `Counter aggregate '${aggregateField}' on '${ownerEntity}' binds destination-key fields [${destinationKeyFields.map((f) => `'${f}'`).join(", ")}], which cover no access-pattern partition of the maintained entity '${ownerEntity}'. The counter row could not be resolved \u2014 bind the partition-key field(s) of the index the counter row lives on. (${cause.message})`
+    );
+  }
+  for (const field of keyBindingSourceFields) {
+    if (!sourceAttrs.has(field)) {
+      throw new Error(
+        `Counter aggregate '${aggregateField}' on '${ownerEntity}' reads source field '${field}' to resolve the counter row, but the source entity '${sourceEntity}' carries no attribute '${field}' on its payload (available: ${[...sourceAttrs].sort().map((f) => `'${f}'`).join(", ")}). The destination key could not be built from the source payload \u2014 reject.`
+      );
+    }
+  }
+  for (const field of valueSourceFields) {
+    if (!sourceAttrs.has(field)) {
+      throw new Error(
+        `Counter aggregate '${aggregateField}' on '${ownerEntity}' tracks \`max('${field}')\`, but the source entity '${sourceEntity}' carries no attribute '${field}' on its payload (available: ${[...sourceAttrs].sort().map((f) => `'${f}'`).join(", ")}). A counter aggregates only the source payload (payload \u540C\u68B1) \u2014 reject.`
+      );
+    }
+  }
+}
+function 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) {
+  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 collection = {
+      field: relation.propertyName,
+      ...read?.maxItems !== void 0 ? { maxItems: read.maxItems } : {}
+    };
+    return { kind: "collection", ...base, collection };
+  }
+  return { kind: "snapshot", ...base };
+}
+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 from2 = path.indexOf(child);
+        const cycle = [...path.slice(from2), 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 = MetadataRegistry.getAll()) {
+  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);
+        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
+        });
+      }
+    }
+  }
+  assertNoCycle(items);
+  const byTrigger = /* @__PURE__ */ new Map();
+  const sameRow = /* @__PURE__ */ new Map();
+  for (const item of items) {
+    const triggerBucket = byTrigger.get(item.trigger);
+    if (triggerBucket) triggerBucket.push(item);
+    else byTrigger.set(item.trigger, [item]);
+    const rowKey = `${item.trigger}\0${item.destinationRowKey}`;
+    const rowBucket = sameRow.get(rowKey);
+    if (rowBucket) rowBucket.push(item);
+    else sameRow.set(rowKey, [item]);
+  }
+  const multiMaintainerTargets = /* @__PURE__ */ new Map();
+  for (const [rowKey, bucket] of sameRow) {
+    if (bucket.length > 1) multiMaintainerTargets.set(rowKey, bucket);
+  }
+  return {
+    items,
+    byTrigger,
+    effectsFor(trigger) {
+      return byTrigger.get(trigger) ?? [];
+    },
+    multiMaintainerTargets
+  };
+}
+
 // src/runtime/command-runtime.ts
 function resolveCommandMethod(contract, methodName) {
   const method = contract.methods[methodName];
@@ -2245,7 +2669,121 @@ function renderIdempotencyGuardItems(guard, key, params, contextLabel) {
     return { Put: put };
   });
 }
-async function executeReferentialTransaction(writes, edgeItems, updateItems, guardItemsRaw, outboxItems, idempotencyItems, checks, methodName, modelBySignature = /* @__PURE__ */ new Map(), retry, middleware) {
+function applyProjectionTransform(op, args, value, contextLabel) {
+  if (op === "identity") return value;
+  if (op === "preview") {
+    const n = args[0];
+    if (typeof n !== "number" || !Number.isInteger(n) || n <= 0) {
+      throw new Error(
+        `Contract runtime: ${contextLabel} declares a \`preview\` projection with a non-positive-integer length bound (${JSON.stringify(n)}). A preview length must be a positive integer.`
+      );
+    }
+    if (value === null || value === void 0) return value;
+    return String(value).slice(0, n);
+  }
+  throw new Error(
+    `Contract runtime: ${contextLabel} declares an unknown projection transform op '${String(op)}' (expected 'identity' or 'preview').`
+  );
+}
+function buildMaintainProjection(maintain, key, params, contextLabel) {
+  const out = {};
+  for (const [attr, transform] of Object.entries(maintain.projection)) {
+    const value = renderTemplate(
+      `{${transform.inputField}}`,
+      key,
+      params,
+      `${contextLabel} projection '${attr}'`
+    );
+    out[attr] = applyProjectionTransform(transform.op, transform.args, value, `${contextLabel} '${attr}'`);
+  }
+  return out;
+}
+function renderMaintainWriteItem(maintain, key, params, contextLabel, modelBySignature) {
+  const ownerClass = maintain.entity.modelClass;
+  const metadata = MetadataRegistry.get(ownerClass);
+  if (!metadata.primaryKey) {
+    throw new Error(
+      `Contract runtime: ${contextLabel} maintains a snapshot / collection on '${maintain.entity.name}', which has no primary key.`
+    );
+  }
+  const keyInput = {};
+  for (const [ownerField, inputField] of Object.entries(maintain.keyBinding)) {
+    keyInput[ownerField] = renderTemplate(
+      `{${inputField}}`,
+      key,
+      params,
+      `${contextLabel} maintain key`
+    );
+  }
+  const { TableName, Key } = buildDeleteInput(
+    ownerClass,
+    keyInput
+  );
+  let updateInput;
+  if (maintain.kind === "counter") {
+    const counter = maintain.counter;
+    if (counter === void 0) {
+      throw new Error(
+        `Contract runtime: ${contextLabel} is a 'counter' maintenance write with no \`counter\` payload \u2014 the compiler (#141) should have set it.`
+      );
+    }
+    updateInput = {
+      TableName,
+      Key,
+      UpdateExpression: "ADD #a0 :a0",
+      ExpressionAttributeNames: { "#a0": counter.attribute },
+      ExpressionAttributeValues: { ":a0": counter.delta }
+    };
+    const out2 = { Update: updateInput };
+    modelBySignature?.set(execItemKeySignature(out2), ownerClass.name);
+    return out2;
+  }
+  const projection = buildMaintainProjection(maintain, key, params, contextLabel);
+  if (maintain.kind === "collection") {
+    const field = maintain.collection?.field;
+    if (field === void 0) {
+      throw new Error(
+        `Contract runtime: ${contextLabel} is a 'collection' maintenance write with no \`collection.field\` \u2014 the compiler (#125) should have set it.`
+      );
+    }
+    updateInput = {
+      TableName,
+      Key,
+      UpdateExpression: "SET #c = list_append(if_not_exists(#c, :empty), :item)",
+      ExpressionAttributeNames: { "#c": field },
+      ExpressionAttributeValues: { ":empty": [], ":item": [projection] }
+    };
+  } else {
+    const setClauses = [];
+    const names = {};
+    const values = {};
+    let i = 0;
+    for (const [attr, value] of Object.entries(projection)) {
+      const nameTok = `#m${i}`;
+      const valTok = `:m${i}`;
+      setClauses.push(`${nameTok} = ${valTok}`);
+      names[nameTok] = attr;
+      values[valTok] = value;
+      i += 1;
+    }
+    if (setClauses.length === 0) {
+      throw new Error(
+        `Contract runtime: ${contextLabel} is a 'snapshot' maintenance write with an empty projection \u2014 nothing to mirror onto '${maintain.entity.name}'.`
+      );
+    }
+    updateInput = {
+      TableName,
+      Key,
+      UpdateExpression: `SET ${setClauses.join(", ")}`,
+      ExpressionAttributeNames: names,
+      ExpressionAttributeValues: values
+    };
+  }
+  const out = { Update: updateInput };
+  modelBySignature?.set(execItemKeySignature(out), ownerClass.name);
+  return out;
+}
+async function executeReferentialTransaction(writes, edgeItems, updateItems, guardItemsRaw, outboxItems, idempotencyItems, maintainItems, checks, methodName, modelBySignature = /* @__PURE__ */ new Map(), retry, middleware) {
   const writeItems = writes.map((w) => {
     const options = w.condition !== void 0 ? { condition: w.condition } : void 0;
     let item;
@@ -2268,6 +2806,7 @@ async function executeReferentialTransaction(writes, edgeItems, updateItems, gua
       ...guardItemsRaw,
       ...outboxItems,
       ...idempotencyItems,
+      ...maintainItems,
       ...checkItems
     ],
     {
@@ -2275,7 +2814,7 @@ async function executeReferentialTransaction(writes, edgeItems, updateItems, gua
       ...retry !== void 0 ? { retry } : {},
       ...middleware !== void 0 ? { middleware } : {},
       limitError: (count) => new Error(
-        `Contract runtime: command method '${methodName}' composes ${count} items (writes + edges + derived updates + uniqueness guards + outbox events + idempotency guard + ConditionChecks) into one TransactWriteItems, but DynamoDB caps a transaction at ${MAX_TRANSACT_ITEMS} items and a transaction is atomic \u2014 it cannot be split. Reduce the fragment / effect count.`
+        `Contract runtime: command method '${methodName}' composes ${count} items (writes + edges + derived updates + uniqueness guards + outbox events + idempotency guard + maintenance writes + ConditionChecks) into one TransactWriteItems, but DynamoDB caps a transaction at ${MAX_TRANSACT_ITEMS} items and a transaction is atomic \u2014 it cannot be split. Reduce the fragment / effect count.`
       )
     }
   );
@@ -2335,10 +2874,10 @@ async function executeCommandMethod(contract, methodName, keyOrKeys, params = {}
         `Contract runtime: command method '${methodName}' is a multi-fragment mutation (it composes ${method.ops.length} fragments into one atomic TransactWriteItems) and accepts a single key only. Call it once per target, not with a key array.`
       );
     }
-    const hasDerivedEffects2 = method.conditionChecks !== void 0 && method.conditionChecks.length > 0 || method.edgeWrites !== void 0 && method.edgeWrites.length > 0 || method.derivedUpdates !== void 0 && method.derivedUpdates.length > 0 || method.uniqueGuards !== void 0 && method.uniqueGuards.length > 0 || method.outboxEvents !== void 0 && method.outboxEvents.length > 0 || method.idempotencyGuard !== void 0;
+    const hasDerivedEffects2 = method.conditionChecks !== void 0 && method.conditionChecks.length > 0 || method.edgeWrites !== void 0 && method.edgeWrites.length > 0 || method.derivedUpdates !== void 0 && method.derivedUpdates.length > 0 || method.uniqueGuards !== void 0 && method.uniqueGuards.length > 0 || method.outboxEvents !== void 0 && method.outboxEvents.length > 0 || method.maintainWrites !== void 0 && method.maintainWrites.length > 0 || method.idempotencyGuard !== void 0;
     if (hasDerivedEffects2) {
       throw new Error(
-        `Contract runtime: command method '${methodName}' carries derived effects (referential integrity / edge writes / derived counters / uniqueness guards / outbox events / idempotency guard \u2014 it composes its write + those items into one atomic TransactWriteItems) and accepts a single key only. Call it once per target, not with a key array.`
+        `Contract runtime: command method '${methodName}' carries derived effects (referential integrity / edge writes / derived counters / uniqueness guards / outbox events / idempotency guard / maintenance writes \u2014 it composes its write + those items into one atomic TransactWriteItems) and accepts a single key only. Call it once per target, not with a key array.`
       );
     }
     const writes = keys.map(
@@ -2357,7 +2896,8 @@ async function executeCommandMethod(contract, methodName, keyOrKeys, params = {}
   const uniqueGuards = method.uniqueGuards ?? [];
   const outboxEvents = method.outboxEvents ?? [];
   const idempotencyGuard = method.idempotencyGuard;
-  const hasDerivedEffects = conditionChecks.length > 0 || edgeWrites2.length > 0 || derivedUpdates.length > 0 || uniqueGuards.length > 0 || outboxEvents.length > 0 || idempotencyGuard !== void 0;
+  const maintainWrites = method.maintainWrites ?? [];
+  const hasDerivedEffects = conditionChecks.length > 0 || edgeWrites2.length > 0 || derivedUpdates.length > 0 || uniqueGuards.length > 0 || outboxEvents.length > 0 || maintainWrites.length > 0 || idempotencyGuard !== void 0;
   const isMultiFragment = method.ops !== void 0 && method.ops.length > 1;
   if (isMultiFragment || hasDerivedEffects) {
     const ops = method.ops ?? [method.op];
@@ -2396,6 +2936,15 @@ async function executeCommandMethod(contract, methodName, keyOrKeys, params = {}
         params,
         `command method '${methodName}' (idempotency)`
       ) : [];
+      const maintainItems = maintainWrites.map(
+        (m, i) => renderMaintainWriteItem(
+          m,
+          key,
+          params,
+          `command method '${methodName}' (maintain #${i})`,
+          modelBySignature
+        )
+      );
       const checks = conditionChecks.map((check, i) => ({
         check: renderConditionCheck(
           check,
@@ -2411,6 +2960,7 @@ async function executeCommandMethod(contract, methodName, keyOrKeys, params = {}
         guardItems,
         outboxItems,
         idempotencyItems,
+        maintainItems,
         checks,
         methodName,
         modelBySignature
@@ -2439,6 +2989,7 @@ function renderCompiledOp(op, ctx) {
   const guardItems = [];
   const outboxItems = [];
   const idempotencyItems = [];
+  const maintainItems = [];
   const checkItems = [];
   for (const edge of fragment.edgeWrites ?? []) {
     edgeItems.push(...renderEdgeWriteItems(edge, op.params, op.params, `${ctx} edge`, modelBySignature));
@@ -2457,10 +3008,15 @@ function renderCompiledOp(op, ctx) {
       ...renderIdempotencyGuardItems(fragment.idempotencyGuard, op.params, op.params, `${ctx} idempotency`)
     );
   }
+  for (const m of fragment.maintainWrites ?? []) {
+    maintainItems.push(
+      renderMaintainWriteItem(m, op.params, op.params, `${ctx} maintain`, modelBySignature)
+    );
+  }
   for (const c of fragment.conditionChecks ?? []) {
     checkItems.push({ check: renderConditionCheck(c, op.params, op.params, `${ctx} requires`) });
   }
-  const hasDerivedEffects = edgeItems.length > 0 || updateItems.length > 0 || guardItems.length > 0 || outboxItems.length > 0 || idempotencyItems.length > 0 || checkItems.length > 0;
+  const hasDerivedEffects = edgeItems.length > 0 || updateItems.length > 0 || guardItems.length > 0 || outboxItems.length > 0 || idempotencyItems.length > 0 || maintainItems.length > 0 || checkItems.length > 0;
   return {
     write,
     edgeItems,
@@ -2468,6 +3024,7 @@ function renderCompiledOp(op, ctx) {
     guardItems,
     outboxItems,
     idempotencyItems,
+    maintainItems,
     checkItems,
     modelBySignature,
     hasDerivedEffects
@@ -2512,6 +3069,7 @@ async function executeCompiledWriteOp(ops, options) {
   const guardItems = [];
   const outboxItems = [];
   const idempotencyItems = [];
+  const maintainItems = [];
   const checkItems = [];
   for (const r of renderedOps) {
     for (const [sig, name] of r.modelBySignature) modelBySignature.set(sig, name);
@@ -2520,6 +3078,7 @@ async function executeCompiledWriteOp(ops, options) {
     guardItems.push(...r.guardItems);
     outboxItems.push(...r.outboxItems);
     idempotencyItems.push(...r.idempotencyItems);
+    maintainItems.push(...r.maintainItems);
     checkItems.push(...r.checkItems);
   }
   const hasDerivedEffects = renderedOps.some((r) => r.hasDerivedEffects);
@@ -2538,6 +3097,7 @@ async function executeCompiledWriteOp(ops, options) {
       guardItems,
       outboxItems,
       idempotencyItems,
+      maintainItems,
       checkItems,
       label,
       modelBySignature,
@@ -2635,6 +3195,7 @@ function rewrittenCompiledOp(write) {
     guardItems: [],
     outboxItems: [],
     idempotencyItems: [],
+    maintainItems: [],
     checkItems: [],
     modelBySignature: /* @__PURE__ */ new Map(),
     hasDerivedEffects: false
@@ -3517,6 +4078,8 @@ function buildPlannedCommandMethod(name, planned) {
     );
   }
   const idempotencyGuard = idempotencyGuards[0];
+  const maintainWrites = plan2.fragments.flatMap((f) => f.maintainWrites ?? []);
+  assertNoCrossFragmentMaintainCollision(name, maintainWrites);
   return {
     __methodKind: "command",
     op,
@@ -3527,6 +4090,7 @@ function buildPlannedCommandMethod(name, planned) {
     ...uniqueGuards.length > 0 ? { uniqueGuards } : {},
     ...outboxEvents.length > 0 ? { outboxEvents } : {},
     ...idempotencyGuard !== void 0 ? { idempotencyGuard } : {},
+    ...maintainWrites.length > 0 ? { maintainWrites } : {},
     inputArity: "either",
     // A return projection means the method returns the read-back entity; otherwise
     // it is a fire-and-forget write (`void`).
@@ -3814,6 +4378,171 @@ function deriveOneUpdate(fragment, effect) {
     amount: effect.amount
   };
 }
+var INTENT_MAINTAIN_EVENT = {
+  create: "created",
+  update: "updated",
+  remove: "removed"
+};
+var MAINTAIN_ENTITY_PATH_RE = /^\$\.entity\.([A-Za-z_$][\w$]*)$/;
+var cachedMaintenanceGraph;
+function globalMaintenanceGraph() {
+  const generation = MetadataRegistry.generation;
+  if (cachedMaintenanceGraph?.generation !== generation) {
+    cachedMaintenanceGraph = { graph: buildMaintenanceGraph(), generation };
+  }
+  return cachedMaintenanceGraph.graph;
+}
+function logicalEntityName(fragment) {
+  const meta = MetadataRegistry.get(
+    fragment.entity.modelClass
+  );
+  return meta.prefix.endsWith("#") ? meta.prefix.slice(0, -1) : meta.prefix;
+}
+function resolveMaintainers(fragment, graph) {
+  const g = graph ?? globalMaintenanceGraph();
+  const event = INTENT_MAINTAIN_EVENT[fragment.intent];
+  const trigger = `${logicalEntityName(fragment)}.${event}`;
+  return g.effectsFor(trigger);
+}
+function maintainPathToInputField(fragment, item, role, path) {
+  const entityMatch = MAINTAIN_ENTITY_PATH_RE.exec(path);
+  if (entityMatch !== null) return entityMatch[1];
+  const inputMatch = INPUT_PATH_RE.exec(path);
+  if (inputMatch !== null) return inputMatch[1];
+  throw new Error(
+    `mutation: the '${fragment.intent}' fragment on '${fragment.entity.name}' fires a maintenance effect (relation '${item.relationProperty}' on '${item.ownerEntity}') whose ${role} binds to ${JSON.stringify(path)}, which is not a payload-rooted \`$.entity.<field>\` / \`$.input.<field>\` source. A maintenance write projects only from the written source row (payload \u540C\u68B1) \u2014 fix the relation's projection / key binding.`
+  );
+}
+function deriveMaintainItems(fragment, items) {
+  const byRow = /* @__PURE__ */ new Map();
+  for (const item of items) {
+    const prior = byRow.get(item.destinationRowKey);
+    if (prior !== void 0) {
+      const bothCounter = item.effect.kind === "counter" && prior.effect.kind === "counter";
+      if (!bothCounter) {
+        throw new Error(
+          `mutation: the '${fragment.intent}' fragment on '${fragment.entity.name}' fires TWO maintenance effects that target the SAME row (relation '${prior.relationProperty}' and '${item.relationProperty}' on '${item.ownerEntity}', destination '${item.destinationRowKey}'). Phase 1 constrains a mutation to ONE non-counter maintenance effect per target row (\u8AD6\u70B92 = b) \u2014 a \`TransactWriteItems\` may not touch one key twice with a snapshot/collection write, and merging those is a separate future issue. (Counter ADDs are exempt \u2014 they merge. Consistent with the #96 same-row reject.)`
+        );
+      }
+    } else {
+      byRow.set(item.destinationRowKey, item);
+    }
+  }
+  return items.map((item) => deriveOneMaintainWrite(fragment, item));
+}
+function maintainWriteRowKey(write) {
+  const parts = Object.entries(write.keyBinding).map(([field, inputField]) => `${field}=${inputField}`).sort();
+  return `${write.entity.name}#${parts.join("&")}`;
+}
+function assertNoCrossFragmentMaintainCollision(methodName, writes) {
+  const byRow = /* @__PURE__ */ new Map();
+  for (const write of writes) {
+    const rowKey = maintainWriteRowKey(write);
+    const prior = byRow.get(rowKey);
+    if (prior !== void 0) {
+      const bothCounter = write.kind === "counter" && prior.kind === "counter";
+      if (!bothCounter) {
+        throw new Error(
+          `publicCommandModel: planned method '${methodName}' aggregates TWO maintenance effects that resolve to the SAME owner row (relation '${prior.relationProperty}' and '${write.relationProperty}' on '${write.entity.name}', destination '${rowKey}'), across different mutation fragments. Phase 1 constrains a mutation to ONE non-counter maintenance effect per target row (\u8AD6\u70B92 = b) \u2014 this holds for the WHOLE mutation, not just within a single fragment. Multiple snapshot/collection maintain effects resolving to one owner row is the true cause here (NOT a derived-counter merge failure); a \`TransactWriteItems\` may not touch one key twice with a snapshot/collection write, and merging those is a separate future issue. (Counter ADDs are exempt \u2014 they merge. Consistent with the intra-fragment reject and the #96 same-row reject.)`
+        );
+      }
+    } else {
+      byRow.set(rowKey, write);
+    }
+  }
+}
+function deriveOneMaintainWrite(fragment, item) {
+  const effect = item.effect;
+  if (effect.updateMode === "stream") {
+    throw new Error(
+      `mutation: the '${fragment.intent}' fragment on '${fragment.entity.name}' fires a maintenance effect (relation '${item.relationProperty}' on '${item.ownerEntity}') declared \`updateMode: 'stream'\` (asynchronous). Phase 1 (#125) lowers only the SYNCHRONOUS \`mutation\` path (the same TransactWriteItems as the source write); the stream path (outbox \u2192 CDC drain) is #130 (Phase 2). Use \`updateMode: 'mutation'\` (the default) for a synchronous maintenance, or wait for #130.`
+    );
+  }
+  const ownerClass = effect.targetFactory();
+  const ownerMeta = MetadataRegistry.get(
+    ownerClass
+  );
+  const ownerName = ownerClass.name;
+  const keyBinding = {};
+  for (const [ownerField, source] of Object.entries(effect.keys)) {
+    keyBinding[ownerField] = maintainPathToInputField(
+      fragment,
+      item,
+      `destination-key field '${ownerField}'`,
+      source
+    );
+  }
+  if (effect.kind === "counter") {
+    return deriveOneCounterWrite(fragment, item, effect, ownerClass, ownerMeta, ownerName, keyBinding);
+  }
+  const projection = {};
+  for (const [attr, transform] of Object.entries(effect.project)) {
+    const inputField = maintainPathToInputField(
+      fragment,
+      item,
+      `projection attribute '${attr}'`,
+      transform.path
+    );
+    projection[attr] = { op: transform.op, args: transform.args, inputField };
+  }
+  if (!ownerMeta.primaryKey) {
+    throw new Error(
+      `mutation: the '${fragment.intent}' fragment on '${fragment.entity.name}' fires a maintenance effect on '${ownerName}', which has no primary key \u2014 a maintenance write keys a single target row, so the maintained model must declare one.`
+    );
+  }
+  const base = {
+    entity: { name: ownerName, modelClass: ownerClass },
+    relationProperty: item.relationProperty,
+    trigger: item.trigger,
+    keyBinding,
+    projection
+  };
+  if (effect.kind === "collection") {
+    const orderBy = effect.collection.orderBy !== void 0 ? maintainPathToInputField(fragment, item, "collection `orderBy`", effect.collection.orderBy) : void 0;
+    return {
+      ...base,
+      kind: "collection",
+      collection: {
+        field: effect.collection.field,
+        ...effect.collection.maxItems !== void 0 ? { maxItems: effect.collection.maxItems } : {},
+        ...orderBy !== void 0 ? { orderBy } : {}
+      }
+    };
+  }
+  return { ...base, kind: "snapshot" };
+}
+function deriveOneCounterWrite(fragment, item, effect, ownerClass, ownerMeta, ownerName, keyBinding) {
+  if (effect.value.op === "max") {
+    throw new Error(
+      `mutation: the '${fragment.intent}' fragment on '${fragment.entity.name}' fires a counter maintenance effect (\`@aggregate\` field '${item.relationProperty}' on '${item.ownerEntity}') declared \`value: max('${effect.value.field}')\`. Phase 1 (#141) realizes only \`count()\` synchronously: a \`max\` needs a conditional \`SET\` whose failed guard would roll back the SOURCE write that legitimately happened, so a running max is the asynchronous stream path (#130, Phase 2). Use \`value: count()\` for a synchronous counter, or wait for #130.`
+    );
+  }
+  if (effect.delta === void 0) {
+    throw new Error(
+      `mutation: the '${fragment.intent}' fragment on '${fragment.entity.name}' fires a counter maintenance effect (\`@aggregate\` field '${item.relationProperty}' on '${item.ownerEntity}') with no \`delta\` \u2014 the maintenance graph (#141) should set it from the trigger event.`
+    );
+  }
+  if (!ownerMeta.primaryKey) {
+    throw new Error(
+      `mutation: the '${fragment.intent}' fragment on '${fragment.entity.name}' fires a counter maintenance effect on '${ownerName}', which has no primary key \u2014 a counter \`UpdateItem\` keys a single row, so the maintained model must declare one.`
+    );
+  }
+  const isField = ownerMeta.fields.some((f) => f.propertyName === effect.attribute) || ownerMeta.aggregates.some((a) => a.propertyName === effect.attribute);
+  if (!isField) {
+    throw new Error(
+      `mutation: the '${fragment.intent}' fragment on '${fragment.entity.name}' derives a counter on '${ownerName}.${effect.attribute}', which is not a field of '${ownerName}'.`
+    );
+  }
+  return {
+    entity: { name: ownerName, modelClass: ownerClass },
+    relationProperty: item.relationProperty,
+    trigger: item.trigger,
+    kind: "counter",
+    keyBinding,
+    projection: {},
+    counter: { attribute: effect.attribute, delta: effect.delta }
+  };
+}
 var UNIQUE_GUARD_PK_PREFIX = "UNIQUE#";
 var UNIQUE_GUARD_SK_PREFIX = "VALUE#";
 function deriveUniqueGuards(fragment, unique) {
@@ -4032,7 +4761,7 @@ function renderInputLeaf(leaf, isKeyFieldInPut, consumerIndex, consumerField, re
   }
   return leaf;
 }
-function compileFragment(fragment, index = 0, resolveEntityRef = null) {
+function compileFragment(fragment, index = 0, resolveEntityRef = null, maintenanceGraph) {
   const keyFields = primaryKeyFields(fragment);
   const keyFieldSet = new Set(keyFields);
   const operation = INTENT_OPERATION[fragment.intent];
@@ -4088,6 +4817,8 @@ function compileFragment(fragment, index = 0, resolveEntityRef = null) {
   const uniqueGuards = lifecycle?.effects.unique !== void 0 && lifecycle.effects.unique.length > 0 ? deriveUniqueGuards(fragment, lifecycle.effects.unique) : void 0;
   const outboxEvents = lifecycle?.effects.emits !== void 0 && lifecycle.effects.emits.length > 0 ? deriveOutboxEvents(fragment, lifecycle.effects.emits) : void 0;
   const idempotencyGuard = lifecycle?.effects.idempotency !== void 0 ? deriveIdempotencyGuard(fragment, lifecycle.effects.idempotency) : void 0;
+  const maintainers = resolveMaintainers(fragment, maintenanceGraph);
+  const maintainWrites = maintainers.length > 0 ? deriveMaintainItems(fragment, maintainers) : void 0;
   return {
     op,
     keyFields,
@@ -4097,7 +4828,8 @@ function compileFragment(fragment, index = 0, resolveEntityRef = null) {
     ...derivedUpdates !== void 0 ? { derivedUpdates } : {},
     ...uniqueGuards !== void 0 ? { uniqueGuards } : {},
     ...outboxEvents !== void 0 ? { outboxEvents } : {},
-    ...idempotencyGuard !== void 0 ? { idempotencyGuard } : {}
+    ...idempotencyGuard !== void 0 ? { idempotencyGuard } : {},
+    ...maintainWrites !== void 0 ? { maintainWrites } : {}
   };
 }
 function compileSingleFragmentPlan(plan2) {
@@ -6143,6 +6875,69 @@ function buildDerivedUpdateItems(derivedUpdates) {
   }
   return { items, params };
 }
+function buildMaintainWriteItems(maintainWrites) {
+  const items = [];
+  const params = {};
+  for (const maintain of maintainWrites) {
+    const metadata = MetadataRegistry.get(
+      maintain.entity.modelClass
+    );
+    if (!metadata.primaryKey) {
+      throw new Error(
+        `maintenance write: the maintained entity '${maintain.entity.name}' has no primary key, so a maintenance \`UpdateItem\` cannot be keyed.`
+      );
+    }
+    const tableName = TableMapping.resolve(metadata.tableName);
+    const present = new Set(Object.keys(maintain.keyBinding));
+    const { pk, sk } = evaluateKey(
+      metadata.primaryKey.segmented,
+      "param",
+      present,
+      (field) => maintain.keyBinding[field] ?? field
+    );
+    const keyCondition = { PK: pk };
+    if (sk !== void 0) keyCondition.SK = sk;
+    const projection = {};
+    for (const [attr, transform] of Object.entries(maintain.projection)) {
+      projection[attr] = {
+        op: transform.op,
+        args: [...transform.args],
+        inputField: transform.inputField
+      };
+    }
+    const maintainSpec = {
+      kind: maintain.kind,
+      relationProperty: maintain.relationProperty,
+      trigger: maintain.trigger,
+      projection,
+      ...maintain.kind === "collection" && maintain.collection !== void 0 ? {
+        collection: {
+          field: maintain.collection.field,
+          ...maintain.collection.maxItems !== void 0 ? { maxItems: maintain.collection.maxItems } : {},
+          ...maintain.collection.orderBy !== void 0 ? { orderBy: maintain.collection.orderBy } : {}
+        }
+      } : {},
+      // #141: a counter carries its scalar `ADD` (attribute + literal numeric delta);
+      // the runtimes render `ADD #attr :delta` exactly as the self-lifecycle derived
+      // counter (#85) does, so a same-row counter merge stays consistent across paths.
+      ...maintain.kind === "counter" && maintain.counter !== void 0 ? {
+        counter: {
+          attribute: maintain.counter.attribute,
+          delta: String(maintain.counter.delta)
+        }
+      } : {}
+    };
+    items.push({
+      type: "Update",
+      tableName,
+      entity: maintain.entity.name,
+      keyCondition,
+      maintain: maintainSpec
+    });
+    collectTemplateParams(keyCondition, metadata, params);
+  }
+  return { items, params };
+}
 function buildUniqueGuardItems(uniqueGuards, entityMetadata) {
   const items = [];
   const params = {};
@@ -6175,7 +6970,7 @@ function buildIdempotencyGuardItems(guard, entityMetadata) {
   }
   return { items, params };
 }
-function synthesizeMutationTransaction(contractName, methodName, ops, checks, edgeWrites2, derivedUpdates, uniqueGuards, outboxEvents, idempotencyGuard) {
+function synthesizeMutationTransaction(contractName, methodName, ops, checks, edgeWrites2, derivedUpdates, uniqueGuards, outboxEvents, idempotencyGuard, maintainWrites) {
   const label = opRefName(contractName, methodName);
   const base = composeFragmentTransaction(contractName, methodName, ops);
   const { items: edgeItemsRaw, params: edgeParams } = buildEdgeWriteItems(edgeWrites2);
@@ -6193,6 +6988,7 @@ function synthesizeMutationTransaction(contractName, methodName, ops, checks, ed
     primaryMetadata
   );
   const { items: idempotencyItems, params: idempotencyParams } = idempotencyGuard !== void 0 ? buildIdempotencyGuardItems(idempotencyGuard, primaryMetadata) : { items: [], params: {} };
+  const { items: maintainItems, params: maintainParams } = buildMaintainWriteItems(maintainWrites);
   const baseKeys = new Set(base.items.map(itemKeySignature));
   for (const update of updateItems) {
     if (baseKeys.has(itemKeySignature(update))) {
@@ -6215,7 +7011,8 @@ function synthesizeMutationTransaction(contractName, methodName, ops, checks, ed
     checkParams,
     guardParams,
     outboxParams,
-    idempotencyParams
+    idempotencyParams,
+    maintainParams
   ]) {
     for (const [name, spec] of Object.entries(source)) params[name] = spec;
   }
@@ -6226,6 +7023,7 @@ function synthesizeMutationTransaction(contractName, methodName, ops, checks, ed
     ...guardItems,
     ...outboxItems,
     ...idempotencyItems,
+    ...maintainItems,
     ...checkItems
   ];
   if (items.length > MAX_TRANSACT_ITEMS) {
@@ -6331,7 +7129,8 @@ function serializeCommandContract(contractName, contract, commandSpecs, transact
     const uniqueGuards = method.uniqueGuards ?? [];
     const outboxEvents = method.outboxEvents ?? [];
     const idempotencyGuard = method.idempotencyGuard;
-    const hasDerivedEffects = conditionChecks.length > 0 || edgeWrites2.length > 0 || derivedUpdates.length > 0 || uniqueGuards.length > 0 || outboxEvents.length > 0 || idempotencyGuard !== void 0;
+    const maintainWrites = method.maintainWrites ?? [];
+    const hasDerivedEffects = conditionChecks.length > 0 || edgeWrites2.length > 0 || derivedUpdates.length > 0 || uniqueGuards.length > 0 || outboxEvents.length > 0 || idempotencyGuard !== void 0 || maintainWrites.length > 0;
     const isMultiFragment = method.ops !== void 0 && method.ops.length > 1;
     const promotedToTransaction = isMultiFragment || hasDerivedEffects;
     if (promotedToTransaction) {
@@ -6349,7 +7148,8 @@ function serializeCommandContract(contractName, contract, commandSpecs, transact
           derivedUpdates,
           uniqueGuards,
           outboxEvents,
-          idempotencyGuard
+          idempotencyGuard,
+          maintainWrites
         )
       ) : (
         // #90: writes only.
@@ -6515,6 +7315,10 @@ export {
   BatchGetResult,
   executeBatchGet,
   executeBatchWrite,
+  maintainTrigger,
+  isMaintainTrigger,
+  preview,
+  identity,
   LIFECYCLE_CONTRACT_MARKER,
   isLifecycleContract,
   ENTITY_WRITES_MARKER,
@@ -6530,6 +7334,7 @@ export {
   deriveEdgeWriteItems,
   getEdgeWrites,
   deriveModelEdgeWriteItems,
+  buildMaintenanceGraph,
   resolveLifecycle,
   compileFragment,
   compileSingleFragmentPlan,