graphddb 0.2.4 → 0.3.0

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

@@ -4,17 +4,22 @@ import {
   ClientManager,
   MAX_TRANSACT_ITEMS,
   MetadataRegistry,
+  NO_MIDDLEWARE,
   TableMapping,
   attachHiddenKey,
   attachModelClass,
   buildConditionExpression,
   buildDeleteInput,
   buildPutInput,
+  buildReadRuntime,
   buildUpdateInput,
+  buildWriteRuntime,
   captureWrite,
+  chunkArray,
   commitTransaction,
   compileRawCondition,
   createColumnMap,
+  ctxModelFor,
   execItemKeySignature,
   executeDelete,
   executePut,
@@ -32,7 +37,7 @@ import {
   serializeFieldValue,
   serializeRawCondition,
   skTemplate
-} from "./chunk-GCPEUPAA.js";
+} from "./chunk-6AIAHP3A.js";
 
 // src/spec/types.ts
 var SPEC_VERSION = "1.0";
@@ -810,23 +815,71 @@ async function executeListInternal(modelClass, key, selectSpec, options = {}) {
     updatable: options.updatable ?? false
   });
   const operation = executionPlan.operations[0];
-  const result = await execute(
-    operation,
-    options.retry !== void 0 ? { retry: options.retry } : void 0
+  const mw = options.mw ?? NO_MIDDLEWARE;
+  const sendList = (op) => execute(op, options.retry !== void 0 ? { retry: options.retry } : void 0).then(
+    (r) => r
   );
-  const rawItems = result.items;
+  let lastEvaluatedKey;
+  let rawItems;
+  if (mw.active) {
+    let captured;
+    const opModel = ctxModelFor(modelClass);
+    rawItems = await mw.runOp(
+      operation,
+      options.relationPath ?? [],
+      opModel,
+      async (op) => {
+        captured = await sendList(op);
+        return captured.items;
+      }
+    );
+    lastEvaluatedKey = captured?.lastEvaluatedKey;
+  } else {
+    const result = await sendList(operation);
+    rawItems = result.items;
+    lastEvaluatedKey = result.lastEvaluatedKey;
+  }
   const hydrated = hydrate(rawItems, select, metadata, options.updatable ?? false);
-  const cursor = result.lastEvaluatedKey ? encodeCursor(result.lastEvaluatedKey) : null;
+  const cursor = lastEvaluatedKey ? encodeCursor(lastEvaluatedKey) : null;
   return { items: hydrated, rawItems, cursor };
 }
 async function executeList(modelClass, key, selectSpec, options = {}) {
-  const { items, cursor } = await executeListInternal(
-    modelClass,
-    key,
-    selectSpec,
-    options
-  );
-  return { items, cursor };
+  const mw = buildReadRuntime(options.context);
+  if (!mw.active) {
+    const { items, cursor } = await executeListInternal(
+      modelClass,
+      key,
+      selectSpec,
+      options
+    );
+    return { items, cursor };
+  }
+  const ctxModel = ctxModelFor(modelClass);
+  const opts = { ...options };
+  const params = {
+    key: { ...key },
+    select: selectSpec && typeof selectSpec === "object" ? selectSpec : {},
+    options: opts
+  };
+  let reqCtx;
+  try {
+    reqCtx = await mw.runRequestBefore("list", ctxModel, params);
+    const { items, cursor } = await executeListInternal(
+      modelClass,
+      params.key,
+      params.select,
+      // Thread the SAME runtime + an empty (root) relation path so R2/R3 fire on
+      // the partition Query; carry the (possibly R1-mutated) per-call options.
+      { ...params.options, mw, relationPath: [] }
+    );
+    const result = { items, cursor };
+    return await mw.runRequestAfter(reqCtx, result);
+  } catch (err) {
+    return mw.runRequestError(
+      reqCtx ?? mw.requestCtx("list", ctxModel, params),
+      err
+    );
+  }
 }
 
 // src/planner/relation-planner.ts
@@ -1174,12 +1227,23 @@ async function fetchBelongsToHasOneBatch(rel, rawParentItems, selectSpec, target
   );
   const executor = ClientManager.getExecutor();
   const queryKeyToRaw = /* @__PURE__ */ new Map();
+  const mw = options.mw ?? NO_MIDDLEWARE;
+  const opPath = [...options.relationPath ?? [], rel.propertyName];
+  const opModel = mw.active ? ctxModelFor(rel.targetFactory()) : void 0;
   for (const operation of batchOps) {
-    const batchResult = await executor.batchGet(
+    const items = mw.active ? await mw.runOp(
+      operation,
+      opPath,
+      opModel,
+      (op) => executor.batchGet(
+        op,
+        options.retry !== void 0 ? { retry: options.retry } : void 0
+      ).then((r) => r.items)
+    ) : (await executor.batchGet(
       operation,
       options.retry !== void 0 ? { retry: options.retry } : void 0
-    );
-    for (const item of batchResult.items) {
+    )).items;
+    for (const item of items) {
       for (const queryKey of queryKeys) {
         if (!matchesQueryKey(item, queryKey)) {
           continue;
@@ -1265,9 +1329,11 @@ async function resolveRelations(parentItem, rawParentItem, select, metadata, opt
   const relations = detectRelationFields(select, metadata);
   const plan2 = options.plan ?? (currentPath === "$" ? buildRelationExecutionPlan(select, metadata) : void 0);
   const opts = plan2 === options.plan ? options : { ...options, plan: plan2 };
+  const basePath = opts.relationPath ?? [];
   await runStaged(relations, currentPath, opts.plan, async (rel) => {
     const selectSpec = relationSpec(select[rel.propertyName]);
     const ownPath = relationResultPath(currentPath, rel);
+    const relPath = [...basePath, rel.propertyName];
     if (rel.type === "hasMany") {
       const targetClass2 = rel.targetFactory();
       const queryKey = buildRelationQueryKey(rel, rawParentItem);
@@ -1279,7 +1345,9 @@ async function resolveRelations(parentItem, rawParentItem, select, metadata, opt
         order,
         filter: selectSpec.filter,
         updatable: opts.updatable,
-        retry: opts.retry
+        retry: opts.retry,
+        mw: opts.mw,
+        relationPath: relPath
       });
       let items = listResult.items;
       const rawItems = listResult.rawItems;
@@ -1291,7 +1359,7 @@ async function resolveRelations(parentItem, rawParentItem, select, metadata, opt
           rawItems,
           selectSpec.select,
           targetMeta2,
-          opts,
+          { ...opts, relationPath: relPath },
           currentDepth + 1,
           ownPath
         );
@@ -1320,6 +1388,36 @@ async function resolveRelations(parentItem, rawParentItem, select, metadata, opt
 
 // src/operations/query.ts
 async function executeQuery(modelClass, key, selectSpec, options) {
+  const mw = buildReadRuntime(options?.context);
+  if (!mw.active) {
+    return executeQueryInner(modelClass, key, selectSpec, options, mw);
+  }
+  const ctxModel = ctxModelFor(modelClass);
+  const opts = { ...options ?? {} };
+  const params = {
+    key: { ...key },
+    select: selectSpec && typeof selectSpec === "object" ? selectSpec : {},
+    options: opts
+  };
+  let reqCtx;
+  try {
+    reqCtx = await mw.runRequestBefore("query", ctxModel, params);
+    const result = await executeQueryInner(
+      modelClass,
+      params.key,
+      params.select,
+      params.options,
+      mw
+    );
+    return await mw.runRequestAfter(reqCtx, result);
+  } catch (err) {
+    return mw.runRequestError(
+      reqCtx ?? mw.requestCtx("query", ctxModel, params),
+      err
+    );
+  }
+}
+async function executeQueryInner(modelClass, key, selectSpec, options, mw) {
   const metadata = MetadataRegistry.get(modelClass);
   const queryFields = Object.keys(key);
   const resolved = resolveKey(queryFields, metadata);
@@ -1353,11 +1451,25 @@ async function executeQuery(modelClass, key, selectSpec, options) {
     )
   );
   const retry = options?.retry;
-  const parentPromise = execute(
-    operation,
-    retry !== void 0 ? { retry } : void 0
-  );
-  const relationPromise = canParallelizeRelations ? resolveRelations({}, key, select, metadata, { maxDepth, updatable, retry }, 1) : null;
+  const sendRoot = () => execute(operation, retry !== void 0 ? { retry } : void 0);
+  const parentPromise = mw.active ? (() => {
+    const opModel = ctxModelFor(modelClass);
+    return mw.runOp(operation, [], opModel, async (op) => {
+      const r = await execute(
+        op,
+        retry !== void 0 ? { retry } : void 0
+      );
+      return r.items;
+    }).then((items) => ({ items }));
+  })() : sendRoot();
+  const relationPromise = canParallelizeRelations ? resolveRelations(
+    {},
+    key,
+    select,
+    metadata,
+    { maxDepth, updatable, retry, mw, relationPath: [] },
+    1
+  ) : null;
   let result;
   try {
     result = await parentPromise;
@@ -1384,7 +1496,7 @@ async function executeQuery(modelClass, key, selectSpec, options) {
         rawItem,
         select,
         metadata,
-        { maxDepth, updatable, retry },
+        { maxDepth, updatable, retry, mw, relationPath: [] },
         1
       );
       if (hydratedItem && updatable) {
@@ -1465,16 +1577,37 @@ function hydrateBatchItems(rawItems, metadata) {
     return merged;
   });
 }
-async function executeBatchGetForTable(tableName, entries) {
+async function executeBatchGetForTable(tableName, entries, mw, opModel) {
   const groups = /* @__PURE__ */ new Map();
   if (entries.length === 0) {
     return groups;
   }
   const keys = entries.map((entry) => entry.dynamoKey);
-  const { items: rawItems } = await ClientManager.getExecutor().batchGet({
-    tableName,
-    keys
-  });
+  const sendChunk = (op) => execute(op).then((r) => r.items);
+  let rawItems;
+  if (mw.active) {
+    rawItems = [];
+    for (const chunk of chunkArray(keys, BATCH_GET_MAX_KEYS)) {
+      const operation = {
+        type: "BatchGetItem",
+        tableName,
+        keys: chunk
+      };
+      const chunkItems = await mw.runOp(
+        operation,
+        [],
+        opModel,
+        (op) => sendChunk(op)
+      );
+      rawItems.push(...chunkItems);
+    }
+  } else {
+    const { items } = await ClientManager.getExecutor().batchGet({
+      tableName,
+      keys
+    });
+    rawItems = items;
+  }
   const entriesByModel = /* @__PURE__ */ new Map();
   for (const entry of entries) {
     const existing = entriesByModel.get(entry.modelClass) ?? [];
@@ -1495,12 +1628,42 @@ async function executeBatchGetForTable(tableName, entries) {
   }
   return groups;
 }
-async function executeBatchGet(requests) {
+async function executeBatchGet(requests, options) {
+  const mw = buildReadRuntime(options?.context);
+  if (!mw.active || requests.length === 0) {
+    return executeBatchGetInner(requests, mw);
+  }
+  const firstModel = ctxModelFor(resolveModelClass(requests[0].model));
+  const reqList = [...requests];
+  const params = {
+    key: {},
+    select: {},
+    options: {},
+    requests: reqList
+  };
+  let reqCtx;
+  try {
+    reqCtx = await mw.runRequestBefore("batchGet", firstModel, params);
+    const effectiveRequests = params.requests;
+    const result = await executeBatchGetInner(effectiveRequests, mw);
+    return await mw.runRequestAfter(reqCtx, result);
+  } catch (err) {
+    return mw.runRequestError(
+      reqCtx ?? mw.requestCtx("batchGet", firstModel, params),
+      err
+    );
+  }
+}
+async function executeBatchGetInner(requests, mw) {
   const entriesByTable = /* @__PURE__ */ new Map();
+  const firstModelClassByTable = /* @__PURE__ */ new Map();
   for (const request of requests) {
     const modelClass = resolveModelClass(request.model);
     const metadata = MetadataRegistry.get(modelClass);
     const tableName = TableMapping.resolve(metadata.tableName);
+    if (!firstModelClassByTable.has(tableName)) {
+      firstModelClassByTable.set(tableName, modelClass);
+    }
     for (const keyObj of request.keys) {
       const entry = {
         modelClass,
@@ -1515,7 +1678,13 @@ async function executeBatchGet(requests) {
   const mergedGroups = /* @__PURE__ */ new Map();
   for (const [, entries] of entriesByTable) {
     const tableName = TableMapping.resolve(entries[0].metadata.tableName);
-    const tableGroups = await executeBatchGetForTable(tableName, entries);
+    const opModel = mw.active ? ctxModelFor(firstModelClassByTable.get(tableName) ?? entries[0].modelClass) : void 0;
+    const tableGroups = await executeBatchGetForTable(
+      tableName,
+      entries,
+      mw,
+      opModel
+    );
     for (const [modelClass, items] of tableGroups) {
       const existing = mergedGroups.get(modelClass) ?? [];
       mergedGroups.set(modelClass, existing.concat(items));
@@ -1588,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"
 );
@@ -1630,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 };
   },
@@ -1817,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];
@@ -2076,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) {
+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;
@@ -2099,13 +2806,15 @@ async function executeReferentialTransaction(writes, edgeItems, updateItems, gua
       ...guardItemsRaw,
       ...outboxItems,
       ...idempotencyItems,
+      ...maintainItems,
       ...checkItems
     ],
     {
       modelBySignature,
       ...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.`
       )
     }
   );
@@ -2165,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(
@@ -2187,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];
@@ -2226,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,
@@ -2241,6 +2960,7 @@ async function executeCommandMethod(contract, methodName, keyOrKeys, params = {}
         guardItems,
         outboxItems,
         idempotencyItems,
+        maintainItems,
         checks,
         methodName,
         modelBySignature
@@ -2269,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));
@@ -2287,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,
@@ -2298,6 +3024,7 @@ function renderCompiledOp(op, ctx) {
     guardItems,
     outboxItems,
     idempotencyItems,
+    maintainItems,
     checkItems,
     modelBySignature,
     hasDerivedEffects
@@ -2317,7 +3044,24 @@ function readBackForCompiledOp(op, write) {
 }
 async function executeCompiledWriteOp(ops, options) {
   const label = options.label;
-  const renderedOps = ops.map((op, i) => renderCompiledOp(op, `${label} (op #${i})`));
+  const writeMw = buildWriteRuntime(options.context);
+  const writeCtxs = [];
+  const txId = { id: /* @__PURE__ */ Symbol("graphddb.mutate") };
+  let rewrites = [];
+  if (writeMw.active) {
+    const w1ed = [];
+    for (const op of ops) {
+      const r = await runEnvelopeW1(op, writeMw, txId, writeCtxs);
+      w1ed.push(r.op);
+      rewrites.push(r.rewritten ?? null);
+    }
+    ops = w1ed;
+  } else {
+    rewrites = ops.map(() => null);
+  }
+  const renderedOps = ops.map(
+    (op, i) => rewrites[i] !== null ? rewrittenCompiledOp(rewrites[i]) : renderCompiledOp(op, `${label} (op #${i})`)
+  );
   const rendered = renderedOps.map((r) => r.write);
   const modelBySignature = /* @__PURE__ */ new Map();
   const edgeItems = [];
@@ -2325,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);
@@ -2333,11 +3078,17 @@ 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);
+  const origins = writeMw.active ? rendered.map((w) => ({ model: ctxModelFor(w.modelClass), kind: w.operation })) : [];
   if (rendered.length === 1 && !hasDerivedEffects) {
-    await executeSingleWrite(rendered[0], options.retry);
+    if (writeMw.active) {
+      await persistSingleWriteWithHooks(rendered[0], writeMw, origins, txId, options.retry);
+    } else {
+      await executeSingleWrite(rendered[0], options.retry);
+    }
   } else {
     await executeReferentialTransaction(
       rendered,
@@ -2346,26 +3097,120 @@ async function executeCompiledWriteOp(ops, options) {
       guardItems,
       outboxItems,
       idempotencyItems,
+      maintainItems,
       checkItems,
       label,
       modelBySignature,
-      options.retry
+      options.retry,
+      writeMw.active ? { runtime: writeMw, origins, transaction: txId } : void 0
     );
   }
+  if (writeMw.active) {
+    for (let i = writeCtxs.length - 1; i >= 0; i--) {
+      await writeMw.runWriteAfter(writeCtxs[i], {});
+    }
+  }
   const readBacks = await Promise.all(
     ops.map((op, i) => readBackForCompiledOp(op, rendered[i]))
   );
   return { readBacks };
 }
+async function persistSingleWriteWithHooks(w, runtime, origins, transaction, retry) {
+  const options = w.condition !== void 0 || retry !== void 0 ? {
+    ...w.condition !== void 0 ? { condition: w.condition } : {},
+    ...retry !== void 0 ? { retry } : {}
+  } : void 0;
+  let item;
+  if (w.operation === "put") {
+    item = { Put: buildPutInput(w.modelClass, w.item ?? {}, options) };
+  } else if (w.operation === "update") {
+    item = { Update: buildUpdateInput(w.modelClass, w.key, w.changes ?? {}, options) };
+  } else {
+    item = { Delete: buildDeleteInput(w.modelClass, w.key, options) };
+  }
+  const persistCtx = runtime.persistCtx([item], origins, transaction);
+  await runtime.runPersist(persistCtx, async (items) => {
+    const sent = items[0];
+    const sendOpts = retry !== void 0 ? { retry } : void 0;
+    const exec = ClientManager.getExecutor();
+    if ("Put" in sent) return exec.put(sent.Put, sendOpts);
+    if ("Update" in sent) return exec.update(sent.Update, sendOpts);
+    if ("Delete" in sent) return exec.delete(sent.Delete, sendOpts);
+    throw new Error("graphddb middleware: a single-op persist received a ConditionCheck.");
+  });
+}
+async function runEnvelopeW1(op, runtime, transaction, writeCtxs) {
+  const kind = op.fragment.op.operation;
+  const keyFields = new Set(op.fragment.keyFields);
+  const input = {};
+  if (kind === "put") {
+    input.item = { ...op.params };
+  } else {
+    const key = {};
+    const changes = {};
+    for (const [k, v] of Object.entries(op.params)) {
+      if (keyFields.has(k)) key[k] = v;
+      else changes[k] = v;
+    }
+    input.key = key;
+    input.changes = changes;
+  }
+  const modelClass = op.fragment.op.entity.modelClass;
+  const ctx = runtime.writeCtx(kind, ctxModelFor(modelClass), input, transaction);
+  await runtime.runWriteBefore(ctx);
+  writeCtxs.push(ctx);
+  if (ctx.kind !== kind) {
+    return { op, rewritten: renderRewrittenWrite(modelClass, ctx) };
+  }
+  const merged = ctx.kind === "put" ? { ...ctx.input.item ?? {} } : { ...ctx.input.key ?? {}, ...ctx.input.changes ?? {} };
+  return { op: { ...op, params: merged } };
+}
+function renderRewrittenWrite(modelClass, ctx) {
+  const modelStatic = modelClass.asModel();
+  const condition = ctx.input.options?.condition;
+  const base = {
+    modelClass,
+    modelStatic,
+    ...condition !== void 0 ? { condition } : {}
+  };
+  if (ctx.kind === "put") {
+    const item = ctx.input.item ?? {};
+    return { ...base, operation: "put", key: item, item };
+  }
+  if (ctx.kind === "update") {
+    return {
+      ...base,
+      operation: "update",
+      key: ctx.input.key ?? {},
+      changes: ctx.input.changes ?? {}
+    };
+  }
+  return { ...base, operation: "delete", key: ctx.input.key ?? {} };
+}
+function rewrittenCompiledOp(write) {
+  return {
+    write,
+    edgeItems: [],
+    updateItems: [],
+    guardItems: [],
+    outboxItems: [],
+    idempotencyItems: [],
+    maintainItems: [],
+    checkItems: [],
+    modelBySignature: /* @__PURE__ */ new Map(),
+    hasDerivedEffects: false
+  };
+}
 async function executeCompiledParallelWrites(ops, options) {
   const label = options.label;
   const results = new Array(ops.length);
   const renderedOps = ops.map((op, i) => renderCompiledOp(op, `${label} (op #${i})`));
   const coalescibleIdx = [];
   const individualIdx = [];
+  const hooksActive = buildWriteRuntime(options.context).active;
   renderedOps.forEach((r, i) => {
     const w = r.write;
-    if (!r.hasDerivedEffects && w.condition === void 0 && (w.operation === "put" || w.operation === "delete")) {
+    if (!hooksActive && !r.hasDerivedEffects && w.condition === void 0 && (w.operation === "put" || w.operation === "delete")) {
       coalescibleIdx.push(i);
     } else {
       individualIdx.push(i);
@@ -2397,7 +3242,8 @@ async function executeCompiledParallelWrites(ops, options) {
       try {
         const { readBacks } = await executeCompiledWriteOp([ops[i]], {
           label: `${label} (op #${i})`,
-          ...options.retry !== void 0 ? { retry: options.retry } : {}
+          ...options.retry !== void 0 ? { retry: options.retry } : {},
+          ...options.context !== void 0 ? { context: options.context } : {}
         });
         results[i] = { ok: true, value: readBacks[0] };
       } catch (e) {
@@ -2455,14 +3301,16 @@ async function executeReadRoute(alias, route) {
   if (isQuery) {
     return executeQuery(modelClass, route.key, route.select, {
       consistentRead: opt.consistentRead,
-      maxDepth: opt.maxDepth
+      maxDepth: opt.maxDepth,
+      context: opt.context
     });
   }
   return executeList(modelClass, route.key, route.select, {
     limit: opt.limit,
     after: opt.after,
     order: opt.order,
-    filter: opt.filter
+    filter: opt.filter,
+    context: opt.context
   });
 }
 var INTENT_KEYS = ["create", "update", "remove"];
@@ -2476,9 +3324,9 @@ async function executeWriteEnvelope(envelope, options = {}) {
   }
   const ops = aliases.flatMap((alias) => normalizeWriteOp(alias, envelope[alias]));
   if (mode === "transaction") {
-    return executeTransactionMode(ops, options.retry);
+    return executeTransactionMode(ops, options.retry, options.context);
   }
-  return executeParallelMode(ops, options.retry);
+  return executeParallelMode(ops, options.retry, options.context);
 }
 function normalizeWriteOp(alias, d) {
   if (d === null || typeof d !== "object") {
@@ -2551,11 +3399,12 @@ function mapToRefs($, fields) {
   for (const f of fields) out[f] = $[f];
   return out;
 }
-async function executeTransactionMode(ops, retry) {
+async function executeTransactionMode(ops, retry, context) {
   const compiled = ops.map(compileWriteOp);
   const { readBacks } = await executeCompiledWriteOp(compiled, {
     label: "DDBModel.mutate",
-    ...retry !== void 0 ? { retry } : {}
+    ...retry !== void 0 ? { retry } : {},
+    ...context !== void 0 ? { context } : {}
   });
   const out = {};
   ops.forEach((op, i) => {
@@ -2570,11 +3419,12 @@ async function executeTransactionMode(ops, retry) {
   });
   return out;
 }
-async function executeParallelMode(ops, retry) {
+async function executeParallelMode(ops, retry, context) {
   const compiled = ops.map(compileWriteOp);
   const settled = await executeCompiledParallelWrites(compiled, {
     label: "DDBModel.mutate",
-    ...retry !== void 0 ? { retry } : {}
+    ...retry !== void 0 ? { retry } : {},
+    ...context !== void 0 ? { context } : {}
   });
   const out = {};
   ops.forEach((op, i) => {
@@ -2634,8 +3484,36 @@ var DDBModel = class {
   static setRetryPolicy(policy) {
     ClientManager.setRetryPolicy(policy);
   }
-  static async transaction(fn) {
-    await executeTransaction(fn);
+  /**
+   * Register a {@link Middleware} (issue #50; read path #138, write path #139).
+   * One registered object may carry read and/or write hooks.
+   *
+   * - **Read** R1–R5 — request entry (`read.before`), each physical op before send
+   *   / after raw fetch (`read.op.before` / `read.op.afterFetch`, INCLUDING every
+   *   relation fan-out fetch), the final hydrated result (`read.afterFetch`), and on
+   *   error (`read.op.onError` / `read.onError`).
+   * - **Write** W1–W5 — the logical write before effect derivation (`write.before`,
+   *   may mutate `ctx.input` / `ctx.kind` incl. a delete→update rewrite), after commit
+   *   (`write.after`), the physical persist on the fully composed batch
+   *   (`write.persist.before` / `write.persist.after`, fires ONCE per atomic
+   *   transaction), and on error (`write.persist.onError` / `write.onError`).
+   *
+   * Hooks may observe, mutate `ctx`, `throw` to cancel, or (on `onError`) recover by
+   * returning a value; the library imposes no semantics. Ordering: `before*` runs
+   * first-registered-first (FIFO); `after*` / `onError` run last-registered-first
+   * (LIFO). Mirrors {@link setRetryPolicy} — a host-runtime global stored on
+   * {@link ClientManager}; never serialized (the bridge #48 is unaffected). Per-call
+   * host context flows in via the read's / write's `{ context }` option.
+   */
+  static use(mw) {
+    ClientManager.use(mw);
+  }
+  /** Remove every registered middleware (read AND write; teardown / tests). See {@link use}. */
+  static clearMiddleware() {
+    ClientManager.clearMiddleware();
+  }
+  static async transaction(fn, options) {
+    await executeTransaction(fn, options);
   }
   /**
    * In-process multi-route READ (issue #101 — the unified envelope). Each alias
@@ -2650,8 +3528,20 @@ var DDBModel = class {
   static mutate(envelope, options) {
     return executeWriteEnvelope(envelope, options);
   }
-  static async batchGet(requests) {
-    return executeBatchGet(requests);
+  /**
+   * Multi-key, multi-model batch read. Each {@link BatchGetRequest} contributes its
+   * keys to a chunked `BatchGetItem` per physical table; results are re-grouped by
+   * model on the returned {@link BatchGetResult}.
+   *
+   * Fires the read hooks (issue #142): request-level R1/R4/R5 with kind
+   * `'batchGet'`, and op-level R2/R3/R5 for each underlying physical `BatchGetItem`
+   * op. The optional `{ context }` is exposed to every hook as `ctx.context` and
+   * threaded UNCHANGED to every op (absent ⇒ `{}`), so a global hook (e.g. a
+   * tenant-scope R2 FilterExpression) applies across the whole batch. With no
+   * middleware registered the read path is unchanged (zero-overhead fast path).
+   */
+  static async batchGet(requests, options) {
+    return executeBatchGet(requests, options);
   }
   static async batchWrite(requests) {
     return executeBatchWrite(requests);
@@ -3188,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,
@@ -3198,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`).
@@ -3485,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) {
@@ -3703,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];
@@ -3759,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,
@@ -3768,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) {
@@ -5814,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 = {};
@@ -5846,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);
@@ -5864,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))) {
@@ -5886,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;
   }
@@ -5897,6 +7023,7 @@ function synthesizeMutationTransaction(contractName, methodName, ops, checks, ed
     ...guardItems,
     ...outboxItems,
     ...idempotencyItems,
+    ...maintainItems,
     ...checkItems
   ];
   if (items.length > MAX_TRANSACT_ITEMS) {
@@ -6002,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) {
@@ -6020,7 +7148,8 @@ function serializeCommandContract(contractName, contract, commandSpecs, transact
           derivedUpdates,
           uniqueGuards,
           outboxEvents,
-          idempotencyGuard
+          idempotencyGuard,
+          maintainWrites
         )
       ) : (
         // #90: writes only.
@@ -6186,6 +7315,10 @@ export {
   BatchGetResult,
   executeBatchGet,
   executeBatchWrite,
+  maintainTrigger,
+  isMaintainTrigger,
+  preview,
+  identity,
   LIFECYCLE_CONTRACT_MARKER,
   isLifecycleContract,
   ENTITY_WRITES_MARKER,
@@ -6201,6 +7334,7 @@ export {
   deriveEdgeWriteItems,
   getEdgeWrites,
   deriveModelEdgeWriteItems,
+  buildMaintenanceGraph,
   resolveLifecycle,
   compileFragment,
   compileSingleFragmentPlan,