graphddb 0.2.5 → 0.3.1

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

@@ -6,10 +6,12 @@ import {
   MetadataRegistry,
   NO_MIDDLEWARE,
   TableMapping,
+  ViewRegistry,
   attachHiddenKey,
   attachModelClass,
   buildConditionExpression,
   buildDeleteInput,
+  buildMaintenanceGraph,
   buildPutInput,
   buildReadRuntime,
   buildUpdateInput,
@@ -25,9 +27,13 @@ import {
   executePut,
   executeTransaction,
   executeUpdate,
+  getEntityWrites,
   isColumn,
+  isEntityWritesDefinition,
+  isLifecycleContract,
   isParam,
   isRawCondition,
+  lifecyclePhaseForIntent,
   param,
   pkTemplate,
   resolveKey,
@@ -37,7 +43,7 @@ import {
   serializeFieldValue,
   serializeRawCondition,
   skTemplate
-} from "./chunk-4TYK3AV6.js";
+} from "./chunk-YIXXTGZ6.js";
 
 // src/spec/types.ts
 var SPEC_VERSION = "1.0";
@@ -1756,94 +1762,6 @@ async function executeBatchWrite(requests) {
   }
 }
 
-// src/define/entity-writes.ts
-var LIFECYCLE_CONTRACT_MARKER = /* @__PURE__ */ Symbol(
-  "graphddb:lifecycleContract"
-);
-function isLifecycleContract(value) {
-  return typeof value === "object" && value !== null && value[LIFECYCLE_CONTRACT_MARKER] === true;
-}
-var ENTITY_WRITES_MARKER = /* @__PURE__ */ Symbol("graphddb:entityWrites");
-function isEntityWritesDefinition(value) {
-  return typeof value === "object" && value !== null && value[ENTITY_WRITES_MARKER] === true;
-}
-function freezeEffects(effects) {
-  const out = {};
-  if (effects.requires !== void 0) out.requires = effects.requires;
-  if (effects.unique !== void 0) out.unique = effects.unique;
-  if (effects.edges !== void 0) out.edges = effects.edges;
-  if (effects.derive !== void 0) out.derive = effects.derive;
-  if (effects.emits !== void 0) out.emits = effects.emits;
-  if (effects.idempotency !== void 0) out.idempotency = effects.idempotency;
-  return out;
-}
-var recorder = {
-  lifecycle(effects = {}) {
-    return {
-      [LIFECYCLE_CONTRACT_MARKER]: true,
-      effects: freezeEffects(effects)
-    };
-  },
-  exists(targetFactory, keys) {
-    return { kind: "requires", targetFactory, keys };
-  },
-  unique(spec) {
-    return { kind: "unique", name: spec.name, scope: spec.scope, fields: spec.fields };
-  },
-  putEdge(targetFactory, relationProperty) {
-    return { kind: "putEdge", targetFactory, relationProperty };
-  },
-  deleteEdge(targetFactory, relationProperty) {
-    return { kind: "deleteEdge", targetFactory, relationProperty };
-  },
-  increment(targetFactory, keys, attribute, amount) {
-    return { kind: "derive", targetFactory, keys, attribute, amount };
-  },
-  event(name, payload) {
-    return { kind: "event", name, payload };
-  },
-  idempotentBy(token) {
-    return { kind: "idempotency", token };
-  }
-};
-function entityWrites(builder) {
-  const shape = builder(recorder);
-  for (const phase of ["create", "update", "remove"]) {
-    const contract = shape[phase];
-    if (contract !== void 0 && !isLifecycleContract(contract)) {
-      throw new Error(
-        `entityWrites: the '${phase}' lifecycle must be built with \`w.lifecycle({...})\` (it carries the \xA72 effect arrays), but received ${JSON.stringify(contract)}.`
-      );
-    }
-  }
-  if (shape.create === void 0 && shape.update === void 0 && shape.remove === void 0) {
-    throw new Error(
-      "entityWrites(...) must declare at least one lifecycle (`create` / `update` / `remove`); an empty save contract declares nothing."
-    );
-  }
-  return {
-    [ENTITY_WRITES_MARKER]: true,
-    ...shape.create !== void 0 ? { create: shape.create } : {},
-    ...shape.update !== void 0 ? { update: shape.update } : {},
-    ...shape.remove !== void 0 ? { remove: shape.remove } : {}
-  };
-}
-function getEntityWrites(modelClass) {
-  for (const name of Object.getOwnPropertyNames(modelClass)) {
-    let value;
-    try {
-      value = modelClass[name];
-    } catch {
-      continue;
-    }
-    if (isEntityWritesDefinition(value)) return value;
-  }
-  return void 0;
-}
-function lifecyclePhaseForIntent(intent) {
-  return intent;
-}
-
 // src/relation/edge-write.ts
 var OLD_VALUE_NAMESPACE = "old";
 var EDGE_WRITES_MARKER = /* @__PURE__ */ Symbol("graphddb:edgeWrites");
@@ -1853,13 +1771,22 @@ function isEdgeWritesDefinition(value) {
 function declaration(target, relationProperty) {
   return { targetFactory: target, relationProperty };
 }
-var recorder2 = {
+var recorder = {
   putEdge: declaration,
   deleteEdge: declaration,
-  updateKeyChangeEdge: declaration
+  updateKeyChangeEdge: declaration,
+  dualEdge: (forward, inverse) => ({
+    targetFactory: forward.target,
+    relationProperty: forward.relationProperty,
+    inverse: {
+      adjacencyFactory: inverse.adjacency,
+      targetFactory: inverse.target,
+      relationProperty: inverse.relationProperty
+    }
+  })
 };
 function edgeWrites(builder) {
-  const edges = builder(recorder2);
+  const edges = builder(recorder);
   if (edges.length === 0) {
     throw new Error(
       "edgeWrites(...) must declare at least one edge (w.putEdge / w.deleteEdge / w.updateKeyChangeEdge); an empty declaration writes nothing."
@@ -1901,6 +1828,13 @@ function assertRelationRoundTrips(entity, edgeFields, decl) {
   }
   return relation;
 }
+function assertDualEdge(forwardAdjacency, inverseAdjacency, decl) {
+  if (inverseAdjacency === forwardAdjacency) {
+    throw new Error(
+      `Dual-edge declaration for forward relation '${decl.relationProperty}' on adjacency entity '${forwardAdjacency.name}' points its inverse edge at the SAME adjacency model. A dual edge is TWO physical rows (forward + inverse); both directions resolving to one model would write the same key twice in a transaction (cf. #96). Declare the inverse on a DISTINCT adjacency model, or drop \`inverse\` for the single-row (base PK + inverse GSI) bidirectional edge.`
+    );
+  }
+}
 function templateRecord(fields) {
   const out = {};
   for (const field of [...fields].sort()) {
@@ -1919,6 +1853,25 @@ function putItemTemplate(edgeFields) {
   return templateRecord(edgeFields);
 }
 function deriveEdgeWriteItemsFor(adjacencyClass, decl, lifecycle) {
+  const forward = deriveOneEdgeRow(
+    adjacencyClass,
+    { targetFactory: decl.targetFactory, relationProperty: decl.relationProperty },
+    lifecycle
+  );
+  if (decl.inverse === void 0) return forward;
+  const inverseAdjacency = decl.inverse.adjacencyFactory();
+  assertDualEdge(adjacencyClass, inverseAdjacency, decl);
+  const inverse = deriveOneEdgeRow(
+    inverseAdjacency,
+    {
+      targetFactory: decl.inverse.targetFactory,
+      relationProperty: decl.inverse.relationProperty
+    },
+    lifecycle
+  );
+  return [...forward, ...inverse];
+}
+function deriveOneEdgeRow(adjacencyClass, decl, lifecycle) {
   const entity = MetadataRegistry.get(adjacencyClass);
   if (!entity.primaryKey) {
     throw new Error(
@@ -2234,6 +2187,13 @@ function renderOutboxEventItems(event, key, params, contextLabel) {
     return { Put: put };
   });
 }
+function renderMaintainOutboxItems(outbox, key, params, contextLabel) {
+  return outbox.items.map((item) => {
+    const Item = renderTemplateRecord(item.item, key, params, `${contextLabel} maintain-outbox Put`);
+    const put = { TableName: TableMapping.resolve(item.tableName), Item };
+    return { Put: put };
+  });
+}
 function renderIdempotencyGuardItems(guard, key, params, contextLabel) {
   return guard.items.map((item) => {
     const Item = renderTemplateRecord(item.item, key, params, `${contextLabel} idempotency Put`);
@@ -2245,7 +2205,131 @@ 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.`
+      );
+    }
+    if (counter.op !== "count") {
+      throw new Error(
+        `Contract runtime: ${contextLabel} is a 'counter' maintenance write with op '${counter.op}', which is the asynchronous stream path (#130) and must not be composed into a synchronous TransactWriteItems \u2014 the compiler should divert it to a maintenance-outbox row.`
+      );
+    }
+    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;
+  }
+  if (maintain.kind === "membership") {
+    throw new Error(
+      `Contract runtime: ${contextLabel} is a 'membership' (sparse-view) maintenance write, which is stream-only (#133) and must not be composed into a synchronous TransactWriteItems \u2014 the compiler should divert it to a maintenance-outbox row.`
+    );
+  }
+  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, maintainOutboxItems, 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 +2352,8 @@ async function executeReferentialTransaction(writes, edgeItems, updateItems, gua
       ...guardItemsRaw,
       ...outboxItems,
       ...idempotencyItems,
+      ...maintainItems,
+      ...maintainOutboxItems,
       ...checkItems
     ],
     {
@@ -2275,7 +2361,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 +2421,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.maintainOutbox !== void 0 && method.maintainOutbox.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 +2443,9 @@ 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 maintainOutbox = method.maintainOutbox ?? [];
+  const hasDerivedEffects = conditionChecks.length > 0 || edgeWrites2.length > 0 || derivedUpdates.length > 0 || uniqueGuards.length > 0 || outboxEvents.length > 0 || maintainWrites.length > 0 || maintainOutbox.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 +2484,18 @@ 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 maintainOutboxItems = maintainOutbox.flatMap(
+        (mo, i) => renderMaintainOutboxItems(mo, key, params, `command method '${methodName}' (maintain-outbox #${i})`)
+      );
       const checks = conditionChecks.map((check, i) => ({
         check: renderConditionCheck(
           check,
@@ -2411,6 +2511,8 @@ async function executeCommandMethod(contract, methodName, keyOrKeys, params = {}
         guardItems,
         outboxItems,
         idempotencyItems,
+        maintainItems,
+        maintainOutboxItems,
         checks,
         methodName,
         modelBySignature
@@ -2439,6 +2541,8 @@ function renderCompiledOp(op, ctx) {
   const guardItems = [];
   const outboxItems = [];
   const idempotencyItems = [];
+  const maintainItems = [];
+  const maintainOutboxItems = [];
   const checkItems = [];
   for (const edge of fragment.edgeWrites ?? []) {
     edgeItems.push(...renderEdgeWriteItems(edge, op.params, op.params, `${ctx} edge`, modelBySignature));
@@ -2457,10 +2561,20 @@ 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 mo of fragment.maintainOutbox ?? []) {
+    maintainOutboxItems.push(
+      ...renderMaintainOutboxItems(mo, op.params, op.params, `${ctx} maintain-outbox`)
+    );
+  }
   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 || maintainOutboxItems.length > 0 || checkItems.length > 0;
   return {
     write,
     edgeItems,
@@ -2468,6 +2582,8 @@ function renderCompiledOp(op, ctx) {
     guardItems,
     outboxItems,
     idempotencyItems,
+    maintainItems,
+    maintainOutboxItems,
     checkItems,
     modelBySignature,
     hasDerivedEffects
@@ -2512,6 +2628,8 @@ async function executeCompiledWriteOp(ops, options) {
   const guardItems = [];
   const outboxItems = [];
   const idempotencyItems = [];
+  const maintainItems = [];
+  const maintainOutboxItems = [];
   const checkItems = [];
   for (const r of renderedOps) {
     for (const [sig, name] of r.modelBySignature) modelBySignature.set(sig, name);
@@ -2520,6 +2638,8 @@ async function executeCompiledWriteOp(ops, options) {
     guardItems.push(...r.guardItems);
     outboxItems.push(...r.outboxItems);
     idempotencyItems.push(...r.idempotencyItems);
+    maintainItems.push(...r.maintainItems);
+    maintainOutboxItems.push(...r.maintainOutboxItems);
     checkItems.push(...r.checkItems);
   }
   const hasDerivedEffects = renderedOps.some((r) => r.hasDerivedEffects);
@@ -2538,6 +2658,8 @@ async function executeCompiledWriteOp(ops, options) {
       guardItems,
       outboxItems,
       idempotencyItems,
+      maintainItems,
+      maintainOutboxItems,
       checkItems,
       label,
       modelBySignature,
@@ -2635,6 +2757,8 @@ function rewrittenCompiledOp(write) {
     guardItems: [],
     outboxItems: [],
     idempotencyItems: [],
+    maintainItems: [],
+    maintainOutboxItems: [],
     checkItems: [],
     modelBySignature: /* @__PURE__ */ new Map(),
     hasDerivedEffects: false
@@ -3517,6 +3641,9 @@ function buildPlannedCommandMethod(name, planned) {
     );
   }
   const idempotencyGuard = idempotencyGuards[0];
+  const maintainWrites = plan2.fragments.flatMap((f) => f.maintainWrites ?? []);
+  assertNoCrossFragmentMaintainCollision(name, maintainWrites);
+  const maintainOutbox = plan2.fragments.flatMap((f) => f.maintainOutbox ?? []);
   return {
     __methodKind: "command",
     op,
@@ -3527,6 +3654,8 @@ function buildPlannedCommandMethod(name, planned) {
     ...uniqueGuards.length > 0 ? { uniqueGuards } : {},
     ...outboxEvents.length > 0 ? { outboxEvents } : {},
     ...idempotencyGuard !== void 0 ? { idempotencyGuard } : {},
+    ...maintainWrites.length > 0 ? { maintainWrites } : {},
+    ...maintainOutbox.length > 0 ? { maintainOutbox } : {},
     inputArity: "either",
     // A return projection means the method returns the read-back entity; otherwise
     // it is a fire-and-forget write (`void`).
@@ -3814,6 +3943,210 @@ 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;
+  const viewGeneration = ViewRegistry.generation;
+  if (cachedMaintenanceGraph?.generation !== generation || cachedMaintenanceGraph?.viewGeneration !== viewGeneration) {
+    cachedMaintenanceGraph = { graph: buildMaintenanceGraph(), generation, viewGeneration };
+  }
+  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;
+  const updateMode = effect.updateMode === "stream" ? "stream" : "mutation";
+  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, updateMode);
+  }
+  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,
+    updateMode,
+    keyBinding,
+    projection
+  };
+  if (effect.kind === "membership") {
+    if (updateMode !== "stream") {
+      throw new Error(
+        `mutation: the '${fragment.intent}' fragment on '${fragment.entity.name}' fires a sparse-view membership effect (view '${item.ownerEntity}', relation '${item.relationProperty}') on the SYNCHRONOUS \`mutation\` path. A membership row is PUT when its predicate holds and DELETED when it flips false; a single atomic transaction cannot branch an item between Put and Delete on a runtime predicate. Declare \`write: { updateMode: 'stream' }\` so the host-side drain applies the put/delete (#133 sparse view is the asynchronous stream path).`
+      );
+    }
+    const predInput = maintainPathToInputField(
+      fragment,
+      item,
+      "membership predicate",
+      effect.predicate.path
+    );
+    return {
+      ...base,
+      kind: "membership",
+      membership: {
+        op: effect.predicate.op,
+        inputField: predInput,
+        ...effect.predicate.value !== void 0 ? { value: effect.predicate.value } : {}
+      }
+    };
+  }
+  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 } : {},
+        ...orderBy !== void 0 && effect.collection.orderDir !== void 0 ? { orderDir: effect.collection.orderDir } : {}
+      }
+    };
+  }
+  return { ...base, kind: "snapshot" };
+}
+function deriveOneCounterWrite(fragment, item, effect, ownerClass, ownerMeta, ownerName, keyBinding, updateMode) {
+  if (effect.value.op === "max") {
+    if (updateMode !== "stream") {
+      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}')\` on the SYNCHRONOUS \`mutation\` path. 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). Use \`value: count()\` for a synchronous counter, or declare \`updateMode: 'stream'\` on the \`@aggregate\` to realize the running max.`
+      );
+    }
+    if (!ownerMeta.primaryKey) {
+      throw new Error(
+        `mutation: the '${fragment.intent}' fragment on '${fragment.entity.name}' fires a max counter maintenance effect on '${ownerName}', which has no primary key.`
+      );
+    }
+    return {
+      entity: { name: ownerName, modelClass: ownerClass },
+      relationProperty: item.relationProperty,
+      trigger: item.trigger,
+      updateMode,
+      kind: "counter",
+      keyBinding,
+      projection: {},
+      counter: { attribute: effect.attribute, op: "max", field: effect.value.field }
+    };
+  }
+  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,
+    updateMode,
+    kind: "counter",
+    keyBinding,
+    projection: {},
+    counter: { attribute: effect.attribute, op: "count", delta: effect.delta }
+  };
+}
 var UNIQUE_GUARD_PK_PREFIX = "UNIQUE#";
 var UNIQUE_GUARD_SK_PREFIX = "VALUE#";
 function deriveUniqueGuards(fragment, unique) {
@@ -3993,6 +4326,67 @@ function deriveIdempotencyGuard(fragment, effect) {
     ]
   };
 }
+var MAINT_OUTBOX_PK_PREFIX = "OUTBOX#MAINT#";
+var MAINT_OUTBOX_SK_PREFIX = "MAINT#";
+var MAINT_OUTBOX_OWNER_ATTR = "__maintOwner__";
+var MAINT_OUTBOX_RELATION_ATTR = "__maintRelation__";
+var MAINT_OUTBOX_TRIGGER_ATTR = "__maintTrigger__";
+var MAINT_OUTBOX_EVENT_VALUE = "maint";
+function deriveMaintainOutbox(fragment, write) {
+  const keyFields = primaryKeyFields(fragment);
+  const discriminator = `${write.entity.name}#${write.relationProperty}`;
+  const keySegments = keyFields.map((f) => `#{${f}}`).join("");
+  const pk = MAINT_OUTBOX_PK_PREFIX + discriminator + keySegments;
+  const sk = MAINT_OUTBOX_SK_PREFIX + keyFields.map((f) => `{${f}}`).join("#");
+  const item = {
+    PK: pk,
+    SK: sk,
+    [OUTBOX_EVENT_NAME_ATTR]: MAINT_OUTBOX_EVENT_VALUE,
+    [MAINT_OUTBOX_OWNER_ATTR]: write.entity.name,
+    [MAINT_OUTBOX_RELATION_ATTR]: write.relationProperty,
+    [MAINT_OUTBOX_TRIGGER_ATTR]: write.trigger
+  };
+  const sourceFields = /* @__PURE__ */ new Set();
+  for (const inputField of Object.values(write.keyBinding)) sourceFields.add(inputField);
+  for (const transform of Object.values(write.projection)) sourceFields.add(transform.inputField);
+  if (write.collection?.orderBy !== void 0) sourceFields.add(write.collection.orderBy);
+  if (write.counter !== void 0 && write.counter.op === "max") {
+    sourceFields.add(write.counter.field);
+  }
+  if (write.membership !== void 0) sourceFields.add(write.membership.inputField);
+  for (const field of sourceFields) {
+    item[field] = `{${field}}`;
+  }
+  return {
+    ownerEntity: write.entity.name,
+    relationProperty: write.relationProperty,
+    trigger: write.trigger,
+    items: [
+      {
+        type: "Put",
+        tableName: tableNameOf(fragment),
+        entity: MARKER_ROW_ENTITY,
+        item,
+        // No `attribute_not_exists`: the row keys off the source entity key, which the
+        // source `Put`'s own create guard already makes unique — the maintenance intent
+        // is recorded atomically with the source row it derives from.
+        literalKey: true
+      }
+    ]
+  };
+}
+function splitMaintainByMode(fragment, writes) {
+  const sync = [];
+  const outbox = [];
+  for (const write of writes) {
+    if (write.updateMode === "stream") {
+      outbox.push(deriveMaintainOutbox(fragment, write));
+    } else {
+      sync.push(write);
+    }
+  }
+  return { sync, outbox };
+}
 function resolveLifecycle(fragment) {
   const writes = fragment.use ?? getEntityWrites(fragment.entity.modelClass);
   if (writes === void 0) return void 0;
@@ -4032,7 +4426,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 +4482,11 @@ 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 allMaintainWrites = maintainers.length > 0 ? deriveMaintainItems(fragment, maintainers) : void 0;
+  const { sync: syncMaintainWrites, outbox: maintainOutboxAll } = allMaintainWrites !== void 0 ? splitMaintainByMode(fragment, allMaintainWrites) : { sync: [], outbox: [] };
+  const maintainWrites = syncMaintainWrites.length > 0 ? syncMaintainWrites : void 0;
+  const maintainOutbox = maintainOutboxAll.length > 0 ? maintainOutboxAll : void 0;
   return {
     op,
     keyFields,
@@ -4097,7 +4496,9 @@ 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 } : {},
+    ...maintainOutbox !== void 0 ? { maintainOutbox } : {}
   };
 }
 function compileSingleFragmentPlan(plan2) {
@@ -4624,7 +5025,7 @@ function runBuildPass(params, build, scalarFields, arrayParams, pass, accessed,
   const recordWrite = (instr) => {
     currentBody.push(instr);
   };
-  const recorder3 = {
+  const recorder2 = {
     put(model, item, options) {
       recordWrite({
         kind: "write",
@@ -4717,7 +5118,7 @@ function runBuildPass(params, build, scalarFields, arrayParams, pass, accessed,
       currentBody.push(block);
     }
   };
-  build(recorder3, pProxy);
+  build(recorder2, pProxy);
   return instructions;
 }
 function defineTransaction(params, build) {
@@ -6143,6 +6544,75 @@ 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;
+    if (maintain.kind === "membership") {
+      throw new Error(
+        `maintenance write: a sparse-view membership maintainer ('${maintain.relationProperty}' on '${maintain.entity.name}') reached the synchronous transaction spec builder. Membership is stream-only (#133) \u2014 it should have been diverted to a maintenance-outbox row. This is a compiler defect.`
+      );
+    }
+    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 } : {},
+          ...maintain.collection.orderBy !== void 0 && maintain.collection.orderDir !== void 0 ? { orderDir: maintain.collection.orderDir } : {}
+        }
+      } : {},
+      // #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 && maintain.counter.op === "count" ? {
+        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 = {};
@@ -6166,6 +6636,17 @@ function buildOutboxEventItems(outboxEvents, entityMetadata) {
   }
   return { items, params };
 }
+function buildMaintainOutboxItems(maintainOutbox, entityMetadata) {
+  const items = [];
+  const params = {};
+  for (const outbox of maintainOutbox) {
+    for (const item of outbox.items) {
+      items.push({ ...item, tableName: TableMapping.resolve(item.tableName) });
+      collectTemplateParams(item.item, entityMetadata, params);
+    }
+  }
+  return { items, params };
+}
 function buildIdempotencyGuardItems(guard, entityMetadata) {
   const items = [];
   const params = {};
@@ -6175,7 +6656,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, maintainOutbox) {
   const label = opRefName(contractName, methodName);
   const base = composeFragmentTransaction(contractName, methodName, ops);
   const { items: edgeItemsRaw, params: edgeParams } = buildEdgeWriteItems(edgeWrites2);
@@ -6193,6 +6674,8 @@ 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 { items: maintainOutboxItems, params: maintainOutboxParams } = buildMaintainOutboxItems(maintainOutbox, primaryMetadata);
   const baseKeys = new Set(base.items.map(itemKeySignature));
   for (const update of updateItems) {
     if (baseKeys.has(itemKeySignature(update))) {
@@ -6215,7 +6698,9 @@ function synthesizeMutationTransaction(contractName, methodName, ops, checks, ed
     checkParams,
     guardParams,
     outboxParams,
-    idempotencyParams
+    idempotencyParams,
+    maintainParams,
+    maintainOutboxParams
   ]) {
     for (const [name, spec] of Object.entries(source)) params[name] = spec;
   }
@@ -6226,6 +6711,8 @@ function synthesizeMutationTransaction(contractName, methodName, ops, checks, ed
     ...guardItems,
     ...outboxItems,
     ...idempotencyItems,
+    ...maintainItems,
+    ...maintainOutboxItems,
     ...checkItems
   ];
   if (items.length > MAX_TRANSACT_ITEMS) {
@@ -6331,7 +6818,9 @@ 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 maintainOutbox = method.maintainOutbox ?? [];
+    const hasDerivedEffects = conditionChecks.length > 0 || edgeWrites2.length > 0 || derivedUpdates.length > 0 || uniqueGuards.length > 0 || outboxEvents.length > 0 || idempotencyGuard !== void 0 || maintainWrites.length > 0 || maintainOutbox.length > 0;
     const isMultiFragment = method.ops !== void 0 && method.ops.length > 1;
     const promotedToTransaction = isMultiFragment || hasDerivedEffects;
     if (promotedToTransaction) {
@@ -6349,7 +6838,9 @@ function serializeCommandContract(contractName, contract, commandSpecs, transact
           derivedUpdates,
           uniqueGuards,
           outboxEvents,
-          idempotencyGuard
+          idempotencyGuard,
+          maintainWrites,
+          maintainOutbox
         )
       ) : (
         // #90: writes only.
@@ -6515,13 +7006,6 @@ export {
   BatchGetResult,
   executeBatchGet,
   executeBatchWrite,
-  LIFECYCLE_CONTRACT_MARKER,
-  isLifecycleContract,
-  ENTITY_WRITES_MARKER,
-  isEntityWritesDefinition,
-  entityWrites,
-  getEntityWrites,
-  lifecyclePhaseForIntent,
   OLD_VALUE_NAMESPACE,
   EDGE_WRITES_MARKER,
   isEdgeWritesDefinition,