graphddb 0.3.0 → 0.4.0

package/dist/index.js

@@ -2,8 +2,6 @@ import {
   BatchGetResult,
   DDBModel,
   EDGE_WRITES_MARKER,
-  ENTITY_WRITES_MARKER,
-  LIFECYCLE_CONTRACT_MARKER,
   MARKER_ROW_ENTITY,
   OLD_VALUE_NAMESPACE,
   RELATION_TRAVERSAL_CONCURRENCY,
@@ -16,7 +14,6 @@ import {
   buildBridgeBundle,
   buildContexts,
   buildContracts,
-  buildMaintenanceGraph,
   buildManifest,
   buildOperations,
   buildProjection,
@@ -42,7 +39,6 @@ import {
   detectRelationFields,
   edgeWrites,
   encodeCursor,
-  entityWrites,
   evaluateFilter,
   execute,
   executeBatchGet,
@@ -54,10 +50,8 @@ import {
   executeQuery,
   from,
   getEdgeWrites,
-  getEntityWrites,
   getImplicitKeyFields,
   hydrate,
-  identity,
   isCommandModelContract,
   isCommandPlan,
   isContractComposeNode,
@@ -66,23 +60,17 @@ import {
   isContractKeyRef,
   isContractParamRef,
   isEdgeWritesDefinition,
-  isEntityWritesDefinition,
-  isLifecycleContract,
-  isMaintainTrigger,
   isMutationFragment,
   isMutationInputRef,
   isPlannedCommandMethod,
   isQueryModelContract,
   isSelectBuilder,
   isTransactionRef,
-  lifecyclePhaseForIntent,
-  maintainTrigger,
   mapWithConcurrency,
   mintContractKeyFieldRef,
   mintContractParamRef,
   mutation,
   plan,
-  preview,
   publicCommandModel,
   publicQueryModel,
   query,
@@ -91,11 +79,19 @@ import {
   validateDepth,
   when,
   wholeKeysSentinel
-} from "./chunk-QEOFIXTN.js";
+} from "./chunk-PC54CW5P.js";
 import {
   CdcEmulator,
-  createCdcEmulator
-} from "./chunk-QQNP43JL.js";
+  MAINT_OUTBOX_PK_PREFIX,
+  MaintenanceDrain,
+  compareDesc,
+  createCdcEmulator,
+  createMaintenanceDrain,
+  createMaintenanceDrainHandler,
+  orderAndTrimCollection,
+  pathField,
+  projectFrom
+} from "./chunk-GWFZVNAV.js";
 import {
   BATCH_GET_MAX_KEYS,
   BATCH_WRITE_MAX_ITEMS,
@@ -103,6 +99,8 @@ import {
   DEFAULT_MAX_ATTEMPTS,
   DEFAULT_RETRY_POLICY,
   DynamoExecutor,
+  ENTITY_WRITES_MARKER,
+  LIFECYCLE_CONTRACT_MARKER,
   Linter,
   MAX_TRANSACT_ITEMS,
   MetadataRegistry,
@@ -112,39 +110,51 @@ import {
   attachModelClass,
   buildConditionExpression,
   buildDeleteInput,
+  buildMaintenanceGraph,
   buildPutInput,
   buildUpdateExpression,
   buildUpdateInput,
   collapseSameKeyItems,
   collectRawConditionParams,
+  collectViewDefinitions,
   commitTransaction,
   cond,
   createDefaultLinter,
+  entityWrites,
   execItemKeySignature,
   executeDelete,
   executePut,
   executeTransaction,
   executeUpdate,
+  getEntityWrites,
   gsi,
   gsiAmbiguityRule,
+  identity,
   isColumn,
+  isEntityWritesDefinition,
   isKeySegment,
+  isLifecycleContract,
+  isMaintainTrigger,
   isParam,
   isRawCondition,
   isRetryableError,
   isRetryableTransactionCancellation,
   k,
   key,
+  lifecyclePhaseForIntent,
+  maintainTrigger,
   missingGsiRule,
   noScanRule,
   param,
+  preview,
   relationDepthRule,
   requireLimitRule,
   resolveConditionTree,
   resolveKey,
   resolveModelClass,
+  segmentFieldNames,
   serializeFieldValue
-} from "./chunk-6AIAHP3A.js";
+} from "./chunk-72VZYOSG.js";
 
 // src/metadata/prefix.ts
 function derivePrefix(customPrefix, className) {
@@ -195,6 +205,7 @@ var pendingFields = [];
 var pendingEmbedded = [];
 var pendingRelations = [];
 var pendingAggregates = [];
+var pendingMaintainedFrom = [];
 function collectField(field2) {
   pendingFields.push(field2);
 }
@@ -207,6 +218,9 @@ function collectRelation(relation) {
 function collectAggregate(aggregate2) {
   pendingAggregates.push(aggregate2);
 }
+function collectMaintainedFrom(decl) {
+  pendingMaintainedFrom.push(decl);
+}
 function drainFields() {
   const result = pendingFields;
   pendingFields = [];
@@ -227,6 +241,11 @@ function drainAggregates() {
   pendingAggregates = [];
   return result;
 }
+function drainMaintainedFrom() {
+  const result = pendingMaintainedFrom;
+  pendingMaintainedFrom = [];
+  return result;
+}
 
 // src/decorators/model.ts
 function model(options) {
@@ -235,7 +254,19 @@ function model(options) {
     const embeddedFields = drainEmbedded();
     const relations = drainRelations();
     const aggregates = drainAggregates();
+    const maintainedFrom2 = drainMaintainedFrom();
     const prefix = derivePrefix(options.prefix, context.name);
+    const kind = options.kind ?? "entity";
+    if (kind === "entity" && maintainedFrom2.length > 0) {
+      throw new Error(
+        `@model on '${String(context.name)}': ${maintainedFrom2.length} \`@maintainedFrom\` declaration(s) are present but \`kind\` is 'entity' (the default). A maintained view must declare \`@model({ kind: 'materializedView' | 'sparseView' })\` \u2014 a plain entity does not carry view maintainers.`
+      );
+    }
+    if (kind !== "entity" && maintainedFrom2.length === 0) {
+      throw new Error(
+        `@model on '${String(context.name)}': \`kind: '${kind}'\` declares a maintained view but no \`@maintainedFrom(...)\` source is stacked. A view with no source is maintained by nothing \u2014 add at least one \`@maintainedFrom\` decorator.`
+      );
+    }
     MetadataRegistry.register(target, {
       tableName: options.table,
       prefix,
@@ -244,7 +275,9 @@ function model(options) {
       gsiDefinitions: [],
       relations,
       aggregates,
-      embeddedFields
+      embeddedFields,
+      kind,
+      maintainedFrom: maintainedFrom2
     });
   };
 }
@@ -314,7 +347,95 @@ function embedded(modelFactory) {
   };
 }
 
+// src/decorators/maintained-symbolic.ts
+var SOURCE_REF = /* @__PURE__ */ Symbol("graphddb:maintainedSourceRef");
+var SELF_REF = /* @__PURE__ */ Symbol("graphddb:maintainedSelfRef");
+function isSourceRef(value) {
+  return typeof value === "object" && value !== null && value[SOURCE_REF] === true;
+}
+function isSelfRef(value) {
+  return typeof value === "object" && value !== null && value[SELF_REF] === true;
+}
+function createSourceProxy() {
+  const cache = /* @__PURE__ */ new Map();
+  return new Proxy(
+    {},
+    {
+      get(_t, prop) {
+        if (typeof prop !== "string") return void 0;
+        let ref = cache.get(prop);
+        if (!ref) {
+          ref = { [SOURCE_REF]: true, field: prop, path: `$.entity.${prop}` };
+          cache.set(prop, ref);
+        }
+        return ref;
+      }
+    }
+  );
+}
+function createSelfProxy() {
+  const cache = /* @__PURE__ */ new Map();
+  return new Proxy(
+    {},
+    {
+      get(_t, prop) {
+        if (typeof prop !== "string") return void 0;
+        let ref = cache.get(prop);
+        if (!ref) {
+          ref = { [SELF_REF]: true, field: prop };
+          cache.set(prop, ref);
+        }
+        return ref;
+      }
+    }
+  );
+}
+
 // src/decorators/relation.ts
+function lowerVersionedProjectionValue(propertyName, attr, value) {
+  if (isSourceRef(value)) return identity(value.path);
+  if (value && typeof value === "object" && value.kind === "transform") {
+    return value;
+  }
+  throw new Error(
+    `@hasOne/@hasMany versioned relation '${propertyName}': projection target '${attr}' must be a \`source.<field>\` reference or a transform (e.g. \`preview(source.body, 120)\`), got ${JSON.stringify(value)}.`
+  );
+}
+function lowerVersionedOptions(propertyName, opts) {
+  if (!opts || typeof opts !== "object" || opts.pattern !== "versionedLatest" && opts.pattern !== "versionedHistory") {
+    throw new Error(
+      `@hasOne/@hasMany versioned relation '${propertyName}': the (self, source) => options callback must return \`{ pattern: 'versionedLatest' | 'versionedHistory', on, project }\`.`
+    );
+  }
+  if (!Array.isArray(opts.on) || opts.on.length === 0) {
+    throw new Error(
+      `@hasOne/@hasMany versioned relation '${propertyName}': \`on\` must be a non-empty array of lifecycle events (e.g. \`['created', 'updated']\`).`
+    );
+  }
+  const projectEntries = Object.entries(opts.project ?? {});
+  if (projectEntries.length === 0) {
+    throw new Error(
+      `@hasOne/@hasMany versioned relation '${propertyName}': \`project\` is empty \u2014 a versioned row with no captured attributes projects nothing.`
+    );
+  }
+  const project = {};
+  for (const [attr, value] of projectEntries) {
+    project[attr] = lowerVersionedProjectionValue(propertyName, attr, value);
+  }
+  return {
+    pattern: opts.pattern,
+    versioned: {
+      mode: opts.pattern === "versionedLatest" ? "latest" : "history",
+      on: [...opts.on],
+      project,
+      ...opts.consistency !== void 0 ? { consistency: opts.consistency } : {},
+      ...opts.updateMode !== void 0 ? { updateMode: opts.updateMode } : {}
+    }
+  };
+}
+function isVersionedCallback(arg) {
+  return typeof arg === "function";
+}
 var RESERVED_RELATION_PROPERTY_NAMES = /* @__PURE__ */ new Set([
   "items"
 ]);
@@ -325,15 +446,34 @@ function assertRelationPropertyNameAllowed(propertyName) {
     );
   }
 }
-function hasMany(targetFactory, keyBinding, options) {
+function hasMany(targetFactory, keyBindingOrCallback, options) {
   return function(_value, context) {
     const propertyName = String(context.name);
     assertRelationPropertyNameAllowed(propertyName);
+    if (isVersionedCallback(keyBindingOrCallback)) {
+      const opts = keyBindingOrCallback(
+        createSelfProxy(),
+        createSourceProxy()
+      );
+      if (opts.pattern !== "versionedHistory") {
+        throw new Error(
+          `@hasMany versioned relation '${propertyName}': a \`@hasMany\` maintains an append-only HISTORY, so its pattern must be 'versionedHistory' (got '${opts.pattern}'). Use \`@hasOne\` for 'versionedLatest' (the single overwritten pointer).`
+        );
+      }
+      collectRelation({
+        type: "hasMany",
+        propertyName,
+        targetFactory,
+        keyBinding: {},
+        options: lowerVersionedOptions(propertyName, opts)
+      });
+      return;
+    }
     collectRelation({
       type: "hasMany",
       propertyName,
       targetFactory,
-      keyBinding,
+      keyBinding: keyBindingOrCallback,
       options
     });
   };
@@ -351,15 +491,34 @@ function belongsTo(targetFactory, keyBinding, options) {
     });
   };
 }
-function hasOne(targetFactory, keyBinding) {
+function hasOne(targetFactory, keyBindingOrCallback) {
   return function(_value, context) {
     const propertyName = String(context.name);
     assertRelationPropertyNameAllowed(propertyName);
+    if (isVersionedCallback(keyBindingOrCallback)) {
+      const opts = keyBindingOrCallback(
+        createSelfProxy(),
+        createSourceProxy()
+      );
+      if (opts.pattern !== "versionedLatest") {
+        throw new Error(
+          `@hasOne versioned relation '${propertyName}': a \`@hasOne\` maintains a single LATEST pointer (overwritten per revision), so its pattern must be 'versionedLatest' (got '${opts.pattern}'). Use \`@hasMany\` for 'versionedHistory' (append-only per-version rows).`
+        );
+      }
+      collectRelation({
+        type: "hasOne",
+        propertyName,
+        targetFactory,
+        keyBinding: {},
+        options: lowerVersionedOptions(propertyName, opts)
+      });
+      return;
+    }
     collectRelation({
       type: "hasOne",
       propertyName,
       targetFactory,
-      keyBinding
+      keyBinding: keyBindingOrCallback
     });
   };
 }
@@ -387,6 +546,118 @@ function max(field2) {
   return { op: "max", field: field2 };
 }
 
+// src/decorators/maintained.ts
+function whenMember(operand, op, value) {
+  const raw = isSourceRef(operand) ? operand.path : operand;
+  const path = raw.startsWith("$.input.") || raw.startsWith("$.entity.") ? raw : `$.entity.${raw}`;
+  const needsValue = op === "eq" || op === "ne";
+  if (needsValue && value === void 0) {
+    throw new Error(
+      `whenMember(source.\u2026, '${op}', \u2026): the '${op}' op requires a comparand value (e.g. \`whenMember(source.status, '${op}', 'active')\`).`
+    );
+  }
+  return needsValue ? { path, op, value } : { path, op };
+}
+function lowerProjectionValue(modelName, attr, value) {
+  if (isSourceRef(value)) return identity(value.path);
+  if (value && typeof value === "object" && value.kind === "transform") {
+    return value;
+  }
+  throw new Error(
+    `@maintainedFrom on '${modelName}': projection target '${attr}' must be a \`source.<field>\` reference or a transform (e.g. \`preview(source.body, 120)\`), got ${JSON.stringify(value)}. A maintained projection captures only symbolic source references \u2014 a literal / computed value is not allowed.`
+  );
+}
+function lowerKeyBind(modelName, keyBind) {
+  const out = {};
+  const entries = Object.entries(keyBind);
+  if (entries.length === 0) {
+    throw new Error(
+      `@maintainedFrom on '${modelName}': \`keyBind\` is empty. The view-row key binding (view-key field \u2192 \`source.<field>\`) is required to resolve which view row a source event maintains.`
+    );
+  }
+  for (const [viewKeyField, ref] of entries) {
+    if (!isSourceRef(ref)) {
+      throw new Error(
+        `@maintainedFrom on '${modelName}': \`keyBind.${viewKeyField}\` must be a \`source.<field>\` reference (e.g. \`{ ${viewKeyField}: source.${viewKeyField} }\`), got ${JSON.stringify(ref)}.`
+      );
+    }
+    out[viewKeyField] = ref.path;
+  }
+  return out;
+}
+function maintainedFrom(source, callback) {
+  return function(target, context) {
+    const modelName = String(context.name ?? target.name ?? "(anonymous)");
+    const selfProxy = createSelfProxy();
+    const sourceProxy = createSourceProxy();
+    const opts = callback(selfProxy, sourceProxy);
+    if (!opts || typeof opts !== "object") {
+      throw new Error(
+        `@maintainedFrom on '${modelName}': the (self, source) => options callback must return an options object.`
+      );
+    }
+    if (!Array.isArray(opts.on) || opts.on.length === 0) {
+      throw new Error(
+        `@maintainedFrom on '${modelName}': \`on\` must be a non-empty array of lifecycle events (e.g. \`['created', 'removed']\`).`
+      );
+    }
+    for (const ev of opts.on) {
+      if (ev !== "created" && ev !== "updated" && ev !== "removed") {
+        throw new Error(
+          `@maintainedFrom on '${modelName}': \`on\` event ${JSON.stringify(ev)} is not one of 'created' / 'updated' / 'removed'.`
+        );
+      }
+    }
+    const keyBind = lowerKeyBind(modelName, opts.keyBind);
+    const projectEntries = Object.entries(opts.project ?? {});
+    if (projectEntries.length === 0) {
+      throw new Error(
+        `@maintainedFrom on '${modelName}': \`project\` is empty. A maintained view with no captured attributes projects nothing \u2014 declare a \`project\` map (e.g. \`{ title: source.title, textPreview: preview(source.body, 120) }\`).`
+      );
+    }
+    const project = {};
+    for (const [attr, value] of projectEntries) {
+      project[attr] = lowerProjectionValue(modelName, attr, value);
+    }
+    if (opts.collection && opts.when) {
+      throw new Error(
+        `@maintainedFrom on '${modelName}': a declaration carries both \`collection\` and \`when\`. They are mutually exclusive \u2014 a collection slice holds a maintained list; a membership (\`when\`) row appears/disappears as a whole.`
+      );
+    }
+    let collection;
+    if (opts.collection) {
+      const c = opts.collection;
+      if (!isSelfRef(c.field)) {
+        throw new Error(
+          `@maintainedFrom on '${modelName}': \`collection.field\` must be a \`self.<field>\` reference (the view attribute holding the list, e.g. \`self.latestPosts\`), got ${JSON.stringify(c.field)}.`
+        );
+      }
+      if (c.orderBy !== void 0 && !isSourceRef(c.orderBy)) {
+        throw new Error(
+          `@maintainedFrom on '${modelName}': \`collection.orderBy\` must be a \`source.<field>\` reference, got ${JSON.stringify(c.orderBy)}.`
+        );
+      }
+      collection = {
+        field: c.field.field,
+        ...c.maxItems !== void 0 ? { maxItems: c.maxItems } : {},
+        ...c.order !== void 0 ? { order: c.order } : {},
+        ...c.orderBy !== void 0 ? { orderBy: c.orderBy.path } : {}
+      };
+    }
+    const metadata = {
+      sourceFactory: source,
+      on: [...opts.on],
+      keyBind,
+      project,
+      ...collection ? { collection } : {},
+      ...opts.when ? { when: opts.when } : {},
+      ...opts.consistency !== void 0 ? { consistency: opts.consistency } : {},
+      ...opts.updateMode !== void 0 ? { updateMode: opts.updateMode } : {}
+    };
+    collectMaintainedFrom(metadata);
+  };
+}
+
 // src/operations/declarative-transaction.ts
 var PLACEHOLDER_RE = /\{[^{}]+\}/g;
 function resolveTemplate(template, params, element) {
@@ -955,6 +1226,363 @@ var queryBoundaryRule = {
   }
 };
 
+// src/relation/maintenance-rebuild.ts
+function toClass(m) {
+  try {
+    return resolveModelClass(m);
+  } catch {
+    return m;
+  }
+}
+var MaintenanceRebuilder = class {
+  graph;
+  constructor(opts = {}) {
+    const classes = (opts.models ?? []).map(toClass);
+    const explicitViews = opts.views;
+    const allClasses = [
+      ...classes,
+      ...(explicitViews ?? []).map((v) => v.viewClass)
+    ];
+    const scoped = allClasses.length > 0 ? new Map(allClasses.map((c) => [c, MetadataRegistry.get(c)])) : void 0;
+    this.graph = buildMaintenanceGraph(scoped, explicitViews);
+  }
+  /**
+   * Re-derive the materialized value for one owner row × maintainer from the source
+   * rows and report whether it differs from what the owner row currently stores. Does
+   * NOT write anything (a read-only drift probe).
+   *
+   * @param owner The owner model class declaring the maintainer.
+   * @param relationProperty The relation / `@aggregate` property the value lives under.
+   * @param ownerKeyInput The owner row's key input (e.g. `{ threadId: 't1' }`).
+   */
+  async detectDrift(owner, relationProperty, ownerKeyInput) {
+    const { item, ownerMeta, ownerKey } = this.resolve(owner, relationProperty);
+    const expected = await this.recompute(item, ownerMeta, ownerKeyInput);
+    const ownerRow = await this.readOwnerRow(ownerMeta, ownerKey(ownerKeyInput));
+    const actual = this.actualValue(item.effect, ownerRow);
+    const ownerAbsentAndEmpty = ownerRow === void 0 && isEmptyMaintained(item.effect, expected);
+    return {
+      relationProperty,
+      ownerEntity: item.ownerEntity,
+      ownerKey: ownerKey(ownerKeyInput),
+      kind: item.effect.kind,
+      drifted: !ownerAbsentAndEmpty && !deepEqual(normalize(expected), normalize(actual)),
+      expected,
+      actual
+    };
+  }
+  /**
+   * Re-derive the materialized value for one owner row × maintainer from the source
+   * rows and WRITE the absolute re-derived value onto the owner row when it drifts (or
+   * always, when `force`). Returns the drift verdict plus whether a repair write ran.
+   *
+   * @param options.force Write even when no drift is detected (default: write only on drift).
+   */
+  async rebuild(owner, relationProperty, ownerKeyInput, options = {}) {
+    const report = await this.detectDrift(owner, relationProperty, ownerKeyInput);
+    if (!report.drifted && options.force !== true) {
+      return { ...report, repaired: false };
+    }
+    const { item, ownerMeta } = this.resolve(owner, relationProperty);
+    await this.writeValue(item.effect, ownerMeta, report.ownerKey, report.expected);
+    return { ...report, repaired: true };
+  }
+  /** Resolve an owner model + property to its {@link MaintainItem} + owner-key builder. */
+  resolve(owner, relationProperty) {
+    const ownerClass = toClass(owner);
+    const ownerMeta = MetadataRegistry.get(ownerClass);
+    const item = this.graph.items.find(
+      (i) => i.relationProperty === relationProperty && (i.ownerClass === ownerClass || i.ownerClass.name === ownerClass.name)
+    );
+    if (item === void 0) {
+      throw new Error(
+        `Maintenance rebuild: no maintainer found for property '${relationProperty}' on '${ownerClass.name}'. The rebuilder repairs declared \`maintainedOn\` maintainers (snapshot / collection / counter); '${relationProperty}' declares none, or its model is not in this rebuilder's scope.`
+      );
+    }
+    const ownerKey = (input) => {
+      const { Key } = buildDeleteInput(
+        ownerClass,
+        input
+      );
+      return Key;
+    };
+    return { item, ownerMeta, ownerKey };
+  }
+  /**
+   * Scan every source row bound to this owner row and re-derive the maintained value:
+   *
+   *  - **collection** — project each source row, order + trim by the SAME read-side
+   *    rules (`orderBy` / `orderDir` / `maxItems`) the drain uses, return the list;
+   *  - **snapshot** — project the single bound source row (or `undefined` when none);
+   *  - **counter `count`** — the COUNT of source rows (absolute, not an ADD);
+   *  - **counter `max`** — the maximum source value of the tracked field.
+   */
+  async recompute(item, _ownerMeta, ownerKeyInput) {
+    const effect = item.effect;
+    if (effect.kind === "membership") {
+      throw new Error(
+        `Maintenance rebuild: sparse-view membership maintainer '${item.relationProperty}' on '${item.ownerEntity}' is not yet supported by the rebuild planner (#133 follow-up). A membership row appears/disappears per source row by predicate; rebuild it by re-running the source events through the drain.`
+      );
+    }
+    const sources = await this.scanSourceRows(item, ownerKeyInput);
+    if (effect.kind === "collection") {
+      return this.recomputeCollection(effect, sources);
+    }
+    if (effect.kind === "snapshot") {
+      return this.recomputeSnapshot(effect, sources);
+    }
+    return this.recomputeCounter(effect, sources);
+  }
+  /**
+   * The source rows bound to one owner row. The maintenance key binding is
+   * `{ ownerField: '$.entity.<sourceField>' }` (the destination owner-key field ← the
+   * source row's field). INVERTED for a rebuild: the owner row supplies the value, and
+   * the source partition is queried for rows whose `<sourceField>` matches — exactly the
+   * set the live `hasMany` / `@aggregate` read aggregates. Queries the source via the
+   * same {@link plan} the read planner uses (a partition Query), paginating fully.
+   */
+  async scanSourceRows(item, ownerKeyInput) {
+    const sourceMeta = MetadataRegistry.get(item.sourceClass);
+    const queryKey = {};
+    for (const [ownerField, srcPath] of Object.entries(item.effect.keys)) {
+      const sourceField = pathField(srcPath);
+      queryKey[sourceField] = ownerKeyInput[ownerField];
+    }
+    const executor = ClientManager.getExecutor();
+    const rows = [];
+    let after;
+    do {
+      const execPlan = plan(sourceMeta, {
+        key: queryKey,
+        // Select all declared source fields so every projection / value source path
+        // and the sort-key leaf is present on the scanned row.
+        select: selectAll(sourceMeta),
+        consistentRead: false,
+        ...after ? { after } : {}
+      });
+      const op = execPlan.operations[0];
+      const res = await executor.execute(op);
+      for (const it of res.items) rows.push(it);
+      after = res.lastEvaluatedKey;
+    } while (after !== void 0);
+    return rows;
+  }
+  /** Re-derive a bounded collection: project, then order + trim by the read-side rules. */
+  recomputeCollection(effect, sources) {
+    if (effect.collection.orderBy === void 0 && effect.collection.maxItems !== void 0) {
+      throw new Error(
+        `Maintenance rebuild: relation '${effect.collection.field}' maintains an UNORDERED bounded collection (\`maxItems: ${effect.collection.maxItems}\` with no \`read.order\`). Its trimmed contents depend on stream ARRIVAL order, which the source rows do not record, so the value cannot be faithfully rebuilt from source \u2014 a rebuild would keep a different subset than the drain converged to. Declare a \`read.order\` on the relation so the maintained collection orders by the source's sort-key field (then the rebuild and the drain agree), or rebuild it unbounded.`
+      );
+    }
+    const projected = sources.map((row) => projectFrom(effect.project, row));
+    return orderAndTrimCollection(projected, effect.collection);
+  }
+  /**
+   * Re-derive a single-row snapshot. A snapshot mirrors ONE source row (a `belongsTo` /
+   * `hasOne`, normally 1:1). In the unusual case where MORE THAN ONE source row binds, the
+   * live single-value read takes the FIRST row in the source's natural query order
+   * (`ScanIndexForward`, default ASC = the smallest sort-key leaf), so re-derive the same
+   * row — {@link pickFirst} — for a verdict consistent with the live read. Returns
+   * `undefined` when no source row is bound (the snapshot should be absent).
+   */
+  recomputeSnapshot(effect, sources) {
+    if (sources.length === 0) return void 0;
+    const chosen = sources.length === 1 ? sources[0] : pickFirst(sources, this.sourceMetaOf(effect));
+    return projectFrom(effect.project, chosen);
+  }
+  /** The source entity metadata a maintain effect projects from (its relation target). */
+  sourceMetaOf(effect) {
+    const item = this.graph.items.find((i) => i.effect === effect);
+    return item ? MetadataRegistry.get(item.sourceClass) : void 0;
+  }
+  /** Re-derive a counter: the absolute COUNT of source rows, or the MAX of the tracked field. */
+  recomputeCounter(effect, sources) {
+    if (effect.value.op === "count") {
+      return sources.length;
+    }
+    const field2 = effect.value.field;
+    let best;
+    for (const row of sources) {
+      const v = row[field2];
+      if (v === void 0 || v === null) continue;
+      if (best === void 0 || compareDesc(v, best) < 0) best = v;
+    }
+    return best;
+  }
+  /** Read the owner row (consistent) for the drift comparison / actual value. */
+  async readOwnerRow(ownerMeta, ownerKey) {
+    const res = await ClientManager.getExecutor().execute({
+      type: "GetItem",
+      tableName: TableMapping.resolve(ownerMeta.tableName),
+      keyCondition: ownerKey,
+      consistentRead: true
+    });
+    return res.items[0];
+  }
+  /** The value currently stored on the owner row for this maintainer. */
+  actualValue(effect, ownerRow) {
+    if (ownerRow === void 0) return void 0;
+    if (effect.kind === "collection") {
+      return ownerRow[effect.collection.field];
+    }
+    if (effect.kind === "counter") {
+      return ownerRow[effect.attribute];
+    }
+    const out = {};
+    let anyPresent = false;
+    for (const attr of Object.keys(effect.project)) {
+      if (Object.prototype.hasOwnProperty.call(ownerRow, attr)) {
+        out[attr] = ownerRow[attr];
+        anyPresent = true;
+      }
+    }
+    return anyPresent ? out : void 0;
+  }
+  /** Write the re-derived ABSOLUTE value onto the owner row (the repair). */
+  async writeValue(effect, ownerMeta, ownerKey, expected) {
+    const TableName = TableMapping.resolve(ownerMeta.tableName);
+    const executor = ClientManager.getExecutor();
+    if (effect.kind === "collection") {
+      await executor.update({
+        TableName,
+        Key: ownerKey,
+        UpdateExpression: "SET #c = :list",
+        ExpressionAttributeNames: { "#c": effect.collection.field },
+        ExpressionAttributeValues: { ":list": expected ?? [] }
+      });
+      return;
+    }
+    if (effect.kind === "counter") {
+      if (expected === void 0 || expected === null) {
+        if (effect.value.op === "count") {
+          await executor.update({
+            TableName,
+            Key: ownerKey,
+            UpdateExpression: "SET #a = :v",
+            ExpressionAttributeNames: { "#a": effect.attribute },
+            ExpressionAttributeValues: { ":v": 0 }
+          });
+        } else {
+          await executor.update({
+            TableName,
+            Key: ownerKey,
+            UpdateExpression: "REMOVE #a",
+            ExpressionAttributeNames: { "#a": effect.attribute }
+          });
+        }
+        return;
+      }
+      await executor.update({
+        TableName,
+        Key: ownerKey,
+        UpdateExpression: "SET #a = :v",
+        ExpressionAttributeNames: { "#a": effect.attribute },
+        ExpressionAttributeValues: { ":v": expected }
+      });
+      return;
+    }
+    if (expected === void 0) {
+      const names2 = {};
+      const removes = [];
+      let i2 = 0;
+      for (const attr of Object.keys(effect.project)) {
+        names2[`#m${i2}`] = attr;
+        removes.push(`#m${i2}`);
+        i2 += 1;
+      }
+      if (removes.length === 0) return;
+      await executor.update({
+        TableName,
+        Key: ownerKey,
+        UpdateExpression: `REMOVE ${removes.join(", ")}`,
+        ExpressionAttributeNames: names2
+      });
+      return;
+    }
+    const projection = expected;
+    const names = {};
+    const values = {};
+    const sets = [];
+    let i = 0;
+    for (const [attr, value] of Object.entries(projection)) {
+      names[`#m${i}`] = attr;
+      values[`:m${i}`] = value;
+      sets.push(`#m${i} = :m${i}`);
+      i += 1;
+    }
+    if (sets.length === 0) return;
+    await executor.update({
+      TableName,
+      Key: ownerKey,
+      UpdateExpression: `SET ${sets.join(", ")}`,
+      ExpressionAttributeNames: names,
+      ExpressionAttributeValues: values
+    });
+  }
+};
+function selectAll(meta) {
+  const select = {};
+  for (const f of meta.fields) select[f.propertyName] = true;
+  return select;
+}
+function pickFirst(sources, sourceMeta) {
+  const skFields = sourceMeta?.primaryKey ? segmentFieldNames(sourceMeta.primaryKey.segmented.skSegments) : [];
+  const orderField = skFields[skFields.length - 1];
+  if (orderField === void 0) return sources[0];
+  return [...sources].sort((a, b) => compareDesc(b[orderField], a[orderField]))[0];
+}
+function normalize(value) {
+  if (value === void 0 || value === null) return void 0;
+  if (typeof value === "number") return value;
+  if (typeof value === "string" && /^-?\d+$/.test(value)) {
+    const n = Number(value);
+    if (Number.isSafeInteger(n)) return n;
+  }
+  if (Array.isArray(value)) return value.map(normalize);
+  if (typeof value === "object") {
+    const out = {};
+    for (const [k2, v] of Object.entries(value)) {
+      const nv = normalize(v);
+      if (nv === void 0) continue;
+      out[k2] = nv;
+    }
+    return out;
+  }
+  return value;
+}
+function isEmptyMaintained(effect, expected) {
+  if (effect.kind === "collection") {
+    return Array.isArray(expected) && expected.length === 0;
+  }
+  if (effect.kind === "counter") {
+    return effect.value.op === "count" ? expected === 0 : expected === void 0 || expected === null;
+  }
+  return expected === void 0;
+}
+function deepEqual(a, b) {
+  if (a === b) return true;
+  if (a === void 0 || b === void 0 || a === null || b === null) return a === b;
+  if (Array.isArray(a) && Array.isArray(b)) {
+    if (a.length !== b.length) return false;
+    return a.every((v, i) => deepEqual(v, b[i]));
+  }
+  if (typeof a === "object" && typeof b === "object") {
+    const ka = Object.keys(a);
+    const kb = Object.keys(b);
+    if (ka.length !== kb.length) return false;
+    return ka.every(
+      (k2) => deepEqual(
+        a[k2],
+        b[k2]
+      )
+    );
+  }
+  return false;
+}
+function createMaintenanceRebuilder(opts = {}) {
+  return new MaintenanceRebuilder(opts);
+}
+
 // src/define/define.ts
 function collectParams(structure, out = {}) {
   if (structure === null || typeof structure !== "object") return out;
@@ -1172,7 +1800,10 @@ export {
   ENTITY_WRITES_MARKER,
   LIFECYCLE_CONTRACT_MARKER,
   Linter,
+  MAINT_OUTBOX_PK_PREFIX,
   MAX_TRANSACT_ITEMS,
+  MaintenanceDrain,
+  MaintenanceRebuilder,
   MetadataRegistry,
   OLD_VALUE_NAMESPACE,
   RetryingExecutor,
@@ -1206,6 +1837,7 @@ export {
   buildUpdateInput,
   collectContractBoundaryViolations,
   collectContractN1Violations,
+  collectViewDefinitions,
   compileFilterExpression,
   compileFragment,
   compileMutationPlan,
@@ -1215,6 +1847,9 @@ export {
   count,
   createCdcEmulator,
   createDefaultLinter,
+  createMaintenanceDrain,
+  createMaintenanceDrainHandler,
+  createMaintenanceRebuilder,
   datetime,
   decodeCursor,
   decodePerKeyCursor,
@@ -1294,6 +1929,7 @@ export {
   list,
   literal,
   maintainTrigger,
+  maintainedFrom,
   map,
   max,
   mintContractKeyFieldRef,
@@ -1323,5 +1959,6 @@ export {
   validateDepth,
   validateGsiAmbiguity,
   when,
+  whenMember,
   wholeKeysSentinel
 };