graphddb 0.3.0 → 0.3.1

package/dist/{chunk-QEOFIXTN.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-6AIAHP3A.js";
+} from "./chunk-YIXXTGZ6.js";
 
 // src/spec/types.ts
 var SPEC_VERSION = "1.0";
@@ -1756,137 +1762,6 @@ 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"
-);
-function isLifecycleContract(value) {
-  return typeof value === "object" && value !== null && value[LIFECYCLE_CONTRACT_MARKER] === true;
-}
-var ENTITY_WRITES_MARKER = /* @__PURE__ */ Symbol("graphddb:entityWrites");
-function isEntityWritesDefinition(value) {
-  return typeof value === "object" && value !== null && value[ENTITY_WRITES_MARKER] === true;
-}
-function freezeEffects(effects) {
-  const out = {};
-  if (effects.requires !== void 0) out.requires = effects.requires;
-  if (effects.unique !== void 0) out.unique = effects.unique;
-  if (effects.edges !== void 0) out.edges = effects.edges;
-  if (effects.derive !== void 0) out.derive = effects.derive;
-  if (effects.emits !== void 0) out.emits = effects.emits;
-  if (effects.idempotency !== void 0) out.idempotency = effects.idempotency;
-  return out;
-}
-var recorder = {
-  lifecycle(effects = {}) {
-    return {
-      [LIFECYCLE_CONTRACT_MARKER]: true,
-      effects: freezeEffects(effects)
-    };
-  },
-  exists(targetFactory, keys) {
-    return { kind: "requires", targetFactory, keys };
-  },
-  unique(spec) {
-    return { kind: "unique", name: spec.name, scope: spec.scope, fields: spec.fields };
-  },
-  putEdge(targetFactory, relationProperty) {
-    return { kind: "putEdge", targetFactory, relationProperty };
-  },
-  deleteEdge(targetFactory, relationProperty) {
-    return { kind: "deleteEdge", targetFactory, relationProperty };
-  },
-  increment(targetFactory, keys, attribute, amount) {
-    return { kind: "derive", targetFactory, keys, attribute, amount };
-  },
-  transform(path, op, ...args) {
-    return makeProjectionTransform(path, op, args);
-  },
-  event(name, payload) {
-    return { kind: "event", name, payload };
-  },
-  idempotentBy(token) {
-    return { kind: "idempotency", token };
-  }
-};
-function entityWrites(builder) {
-  const shape = builder(recorder);
-  for (const phase of ["create", "update", "remove"]) {
-    const contract = shape[phase];
-    if (contract !== void 0 && !isLifecycleContract(contract)) {
-      throw new Error(
-        `entityWrites: the '${phase}' lifecycle must be built with \`w.lifecycle({...})\` (it carries the \xA72 effect arrays), but received ${JSON.stringify(contract)}.`
-      );
-    }
-  }
-  if (shape.create === void 0 && shape.update === void 0 && shape.remove === void 0) {
-    throw new Error(
-      "entityWrites(...) must declare at least one lifecycle (`create` / `update` / `remove`); an empty save contract declares nothing."
-    );
-  }
-  return {
-    [ENTITY_WRITES_MARKER]: true,
-    ...shape.create !== void 0 ? { create: shape.create } : {},
-    ...shape.update !== void 0 ? { update: shape.update } : {},
-    ...shape.remove !== void 0 ? { remove: shape.remove } : {}
-  };
-}
-function getEntityWrites(modelClass) {
-  for (const name of Object.getOwnPropertyNames(modelClass)) {
-    let value;
-    try {
-      value = modelClass[name];
-    } catch {
-      continue;
-    }
-    if (isEntityWritesDefinition(value)) return value;
-  }
-  return void 0;
-}
-function lifecyclePhaseForIntent(intent) {
-  return intent;
-}
-
 // src/relation/edge-write.ts
 var OLD_VALUE_NAMESPACE = "old";
 var EDGE_WRITES_MARKER = /* @__PURE__ */ Symbol("graphddb:edgeWrites");
@@ -1896,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."
@@ -1944,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()) {
@@ -1962,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(
@@ -2029,387 +1939,6 @@ 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];
@@ -2658,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`);
@@ -2727,6 +2263,11 @@ function renderMaintainWriteItem(maintain, key, params, contextLabel, modelBySig
         `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,
@@ -2738,6 +2279,11 @@ function renderMaintainWriteItem(maintain, key, params, contextLabel, modelBySig
     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;
@@ -2783,7 +2329,7 @@ function renderMaintainWriteItem(maintain, key, params, contextLabel, modelBySig
   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) {
+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;
@@ -2807,6 +2353,7 @@ async function executeReferentialTransaction(writes, edgeItems, updateItems, gua
       ...outboxItems,
       ...idempotencyItems,
       ...maintainItems,
+      ...maintainOutboxItems,
       ...checkItems
     ],
     {
@@ -2874,7 +2421,7 @@ 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.maintainWrites !== void 0 && method.maintainWrites.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 / 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.`
@@ -2897,7 +2444,8 @@ async function executeCommandMethod(contract, methodName, keyOrKeys, params = {}
   const outboxEvents = method.outboxEvents ?? [];
   const idempotencyGuard = method.idempotencyGuard;
   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 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];
@@ -2945,6 +2493,9 @@ async function executeCommandMethod(contract, methodName, keyOrKeys, params = {}
           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,
@@ -2961,6 +2512,7 @@ async function executeCommandMethod(contract, methodName, keyOrKeys, params = {}
         outboxItems,
         idempotencyItems,
         maintainItems,
+        maintainOutboxItems,
         checks,
         methodName,
         modelBySignature
@@ -2990,6 +2542,7 @@ function renderCompiledOp(op, ctx) {
   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));
@@ -3013,10 +2566,15 @@ function renderCompiledOp(op, ctx) {
       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 || maintainItems.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,
@@ -3025,6 +2583,7 @@ function renderCompiledOp(op, ctx) {
     outboxItems,
     idempotencyItems,
     maintainItems,
+    maintainOutboxItems,
     checkItems,
     modelBySignature,
     hasDerivedEffects
@@ -3070,6 +2629,7 @@ async function executeCompiledWriteOp(ops, options) {
   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);
@@ -3079,6 +2639,7 @@ async function executeCompiledWriteOp(ops, options) {
     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);
@@ -3098,6 +2659,7 @@ async function executeCompiledWriteOp(ops, options) {
       outboxItems,
       idempotencyItems,
       maintainItems,
+      maintainOutboxItems,
       checkItems,
       label,
       modelBySignature,
@@ -3196,6 +2758,7 @@ function rewrittenCompiledOp(write) {
     outboxItems: [],
     idempotencyItems: [],
     maintainItems: [],
+    maintainOutboxItems: [],
     checkItems: [],
     modelBySignature: /* @__PURE__ */ new Map(),
     hasDerivedEffects: false
@@ -4080,6 +3643,7 @@ 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,
@@ -4091,6 +3655,7 @@ function buildPlannedCommandMethod(name, planned) {
     ...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`).
@@ -4387,8 +3952,9 @@ 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 };
+  const viewGeneration = ViewRegistry.generation;
+  if (cachedMaintenanceGraph?.generation !== generation || cachedMaintenanceGraph?.viewGeneration !== viewGeneration) {
+    cachedMaintenanceGraph = { graph: buildMaintenanceGraph(), generation, viewGeneration };
   }
   return cachedMaintenanceGraph.graph;
 }
@@ -4453,11 +4019,7 @@ function assertNoCrossFragmentMaintainCollision(methodName, writes) {
 }
 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 updateMode = effect.updateMode === "stream" ? "stream" : "mutation";
   const ownerClass = effect.targetFactory();
   const ownerMeta = MetadataRegistry.get(
     ownerClass
@@ -4473,7 +4035,7 @@ function deriveOneMaintainWrite(fragment, item) {
     );
   }
   if (effect.kind === "counter") {
-    return deriveOneCounterWrite(fragment, item, effect, ownerClass, ownerMeta, ownerName, keyBinding);
+    return deriveOneCounterWrite(fragment, item, effect, ownerClass, ownerMeta, ownerName, keyBinding, updateMode);
   }
   const projection = {};
   for (const [attr, transform] of Object.entries(effect.project)) {
@@ -4494,9 +4056,32 @@ function deriveOneMaintainWrite(fragment, item) {
     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 {
@@ -4505,17 +4090,35 @@ function deriveOneMaintainWrite(fragment, item) {
       collection: {
         field: effect.collection.field,
         ...effect.collection.maxItems !== void 0 ? { maxItems: effect.collection.maxItems } : {},
-        ...orderBy !== void 0 ? { orderBy } : {}
+        ...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) {
+function deriveOneCounterWrite(fragment, item, effect, ownerClass, ownerMeta, ownerName, keyBinding, updateMode) {
   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 (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(
@@ -4537,10 +4140,11 @@ function deriveOneCounterWrite(fragment, item, effect, ownerClass, ownerMeta, ow
     entity: { name: ownerName, modelClass: ownerClass },
     relationProperty: item.relationProperty,
     trigger: item.trigger,
+    updateMode,
     kind: "counter",
     keyBinding,
     projection: {},
-    counter: { attribute: effect.attribute, delta: effect.delta }
+    counter: { attribute: effect.attribute, op: "count", delta: effect.delta }
   };
 }
 var UNIQUE_GUARD_PK_PREFIX = "UNIQUE#";
@@ -4722,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;
@@ -4818,7 +4483,10 @@ function compileFragment(fragment, index = 0, resolveEntityRef = null, maintenan
   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;
+  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,
@@ -4829,7 +4497,8 @@ function compileFragment(fragment, index = 0, resolveEntityRef = null, maintenan
     ...uniqueGuards !== void 0 ? { uniqueGuards } : {},
     ...outboxEvents !== void 0 ? { outboxEvents } : {},
     ...idempotencyGuard !== void 0 ? { idempotencyGuard } : {},
-    ...maintainWrites !== void 0 ? { maintainWrites } : {}
+    ...maintainWrites !== void 0 ? { maintainWrites } : {},
+    ...maintainOutbox !== void 0 ? { maintainOutbox } : {}
   };
 }
 function compileSingleFragmentPlan(plan2) {
@@ -5356,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",
@@ -5449,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) {
@@ -6897,6 +6566,11 @@ function buildMaintainWriteItems(maintainWrites) {
     );
     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] = {
@@ -6914,13 +6588,14 @@ function buildMaintainWriteItems(maintainWrites) {
         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 ? { 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.kind === "counter" && maintain.counter !== void 0 && maintain.counter.op === "count" ? {
         counter: {
           attribute: maintain.counter.attribute,
           delta: String(maintain.counter.delta)
@@ -6961,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 = {};
@@ -6970,7 +6656,7 @@ function buildIdempotencyGuardItems(guard, entityMetadata) {
   }
   return { items, params };
 }
-function synthesizeMutationTransaction(contractName, methodName, ops, checks, edgeWrites2, derivedUpdates, uniqueGuards, outboxEvents, idempotencyGuard, maintainWrites) {
+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);
@@ -6989,6 +6675,7 @@ function synthesizeMutationTransaction(contractName, methodName, ops, checks, ed
   );
   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))) {
@@ -7012,7 +6699,8 @@ function synthesizeMutationTransaction(contractName, methodName, ops, checks, ed
     guardParams,
     outboxParams,
     idempotencyParams,
-    maintainParams
+    maintainParams,
+    maintainOutboxParams
   ]) {
     for (const [name, spec] of Object.entries(source)) params[name] = spec;
   }
@@ -7024,6 +6712,7 @@ function synthesizeMutationTransaction(contractName, methodName, ops, checks, ed
     ...outboxItems,
     ...idempotencyItems,
     ...maintainItems,
+    ...maintainOutboxItems,
     ...checkItems
   ];
   if (items.length > MAX_TRANSACT_ITEMS) {
@@ -7130,7 +6819,8 @@ function serializeCommandContract(contractName, contract, commandSpecs, transact
     const outboxEvents = method.outboxEvents ?? [];
     const idempotencyGuard = method.idempotencyGuard;
     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 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) {
@@ -7149,7 +6839,8 @@ function serializeCommandContract(contractName, contract, commandSpecs, transact
           uniqueGuards,
           outboxEvents,
           idempotencyGuard,
-          maintainWrites
+          maintainWrites,
+          maintainOutbox
         )
       ) : (
         // #90: writes only.
@@ -7315,17 +7006,6 @@ export {
   BatchGetResult,
   executeBatchGet,
   executeBatchWrite,
-  maintainTrigger,
-  isMaintainTrigger,
-  preview,
-  identity,
-  LIFECYCLE_CONTRACT_MARKER,
-  isLifecycleContract,
-  ENTITY_WRITES_MARKER,
-  isEntityWritesDefinition,
-  entityWrites,
-  getEntityWrites,
-  lifecyclePhaseForIntent,
   OLD_VALUE_NAMESPACE,
   EDGE_WRITES_MARKER,
   isEdgeWritesDefinition,
@@ -7334,7 +7014,6 @@ export {
   deriveEdgeWriteItems,
   getEdgeWrites,
   deriveModelEdgeWriteItems,
-  buildMaintenanceGraph,
   resolveLifecycle,
   compileFragment,
   compileSingleFragmentPlan,