graphddb 0.3.0 → 0.3.1

package/dist/chunk-PNIZS37E.js

@@ -0,0 +1,916 @@
+import {
+  ChangeCaptureRegistry,
+  ClientManager,
+  MetadataRegistry,
+  buildConditionExpression,
+  buildDeleteInput,
+  buildMaintenanceGraph,
+  buildPutInput,
+  isProjectionDefinition,
+  resolveModelClass
+} from "./chunk-YIXXTGZ6.js";
+
+// src/cdc/prng.ts
+var SeededRandom = class {
+  state;
+  constructor(seed) {
+    this.state = seed >>> 0 || 2654435769;
+  }
+  /** Next float in [0, 1). */
+  next() {
+    this.state |= 0;
+    this.state = this.state + 1831565813 | 0;
+    let t = Math.imul(this.state ^ this.state >>> 15, 1 | this.state);
+    t = t + Math.imul(t ^ t >>> 7, 61 | t) ^ t;
+    return ((t ^ t >>> 14) >>> 0) / 4294967296;
+  }
+  /** Integer in [min, max] inclusive. */
+  int(min, max) {
+    return min + Math.floor(this.next() * (max - min + 1));
+  }
+  /** Bernoulli trial: true with probability `p`. */
+  chance(p) {
+    if (p <= 0) return false;
+    if (p >= 1) return true;
+    return this.next() < p;
+  }
+  /** In-place Fisher–Yates shuffle, deterministic for the seed state. */
+  shuffle(items) {
+    for (let i = items.length - 1; i > 0; i--) {
+      const j = this.int(0, i);
+      const tmp = items[i];
+      items[i] = items[j];
+      items[j] = tmp;
+    }
+    return items;
+  }
+};
+function hashString(value) {
+  let h = 2166136261;
+  for (let i = 0; i < value.length; i++) {
+    h ^= value.charCodeAt(i);
+    h = Math.imul(h, 16777619);
+  }
+  return h >>> 0;
+}
+function shardIdFor(pk, shardCount) {
+  const index = hashString(pk) % shardCount;
+  return `shard-${String(index).padStart(4, "0")}`;
+}
+
+// src/cdc/emulator.ts
+function resolveToClass(model) {
+  try {
+    return resolveModelClass(model);
+  } catch {
+    return model;
+  }
+}
+var EPOCH = Date.parse("2020-01-01T00:00:00.000Z");
+var CdcEmulator = class {
+  mode;
+  clockMode;
+  batchSize;
+  maxRetries;
+  startingPosition;
+  shardCount;
+  seed;
+  rng;
+  faultSpec = {};
+  concurrentRecompute = null;
+  concurrentRecomputeHook = null;
+  /** Per-shard monotonic sequence counter. */
+  seqCounters = /* @__PURE__ */ new Map();
+  /** Per-shard delivery queue (queued/replay modes). */
+  queues = /* @__PURE__ */ new Map();
+  /** Per-shard last successfully checkpointed sequence number. */
+  checkpointMap = /* @__PURE__ */ new Map();
+  /**
+   * Per-shard set of acked sequence numbers (as ints) not yet folded into the
+   * checkpoint. The checkpoint advances over the contiguous prefix of acked
+   * sequences (ReportBatchItemFailures semantics): a sequence is checkpointed
+   * only once every sequence at or before it has been acked.
+   */
+  ackedSeqs = /* @__PURE__ */ new Map();
+  /** Per-shard count of sequences ever assigned, to bound the prefix scan. */
+  maxSeqSeen = /* @__PURE__ */ new Map();
+  /** Recorded event log (record mode and always, for replay()). */
+  log = [];
+  /** Dead-letter buffer. */
+  dlq = [];
+  handler = null;
+  /** Virtual clock (ms since EPOCH). */
+  clockMs = 0;
+  /** Pending async work from inline-mode captures, awaited by callers. */
+  inflight = Promise.resolve();
+  detachCapture = null;
+  models;
+  constructor(opts = {}) {
+    this.mode = opts.mode ?? "inline";
+    this.clockMode = opts.clock ?? (this.mode === "queued" ? "virtual" : "real");
+    this.batchSize = opts.batchSize ?? 100;
+    this.maxRetries = opts.maxRetries ?? 3;
+    this.startingPosition = opts.startingPosition ?? "TRIM_HORIZON";
+    this.shardCount = opts.shardCount ?? 8;
+    this.seed = opts.seed ?? 1;
+    this.rng = new SeededRandom(this.seed);
+    this.models = (opts.models ?? []).map(resolveToClass);
+    for (const model of this.models) {
+      ChangeCaptureRegistry.enableStream(model);
+    }
+    this.detachCapture = ChangeCaptureRegistry.register((record) => {
+      this.onRawWrite(record);
+    });
+  }
+  // ── seam → ChangeEvent mapping (spec §4, §5) ─────────────────────────────
+  onRawWrite(record) {
+    if (record.model && this.models.length > 0) {
+      const enabled = this.models.some((m) => m.name === record.model);
+      if (!enabled) return;
+    }
+    const event = this.toChangeEvent(record);
+    this.log.push(event);
+    if (this.mode === "record" || this.mode === "replay") {
+      return;
+    }
+    this.enqueue(event);
+    if (this.mode === "inline") {
+      this.inflight = this.inflight.then(() => this.pump());
+    }
+  }
+  toChangeEvent(record) {
+    const shardId = shardIdFor(record.keys.pk, this.shardCount);
+    const seq = (this.seqCounters.get(shardId) ?? 0) + 1;
+    this.seqCounters.set(shardId, seq);
+    this.maxSeqSeen.set(shardId, seq);
+    const eventName = this.deriveEventName(record);
+    const newImage = eventName === "REMOVE" ? void 0 : record.newItem ?? void 0;
+    const oldImage = record.oldItem ?? void 0;
+    return {
+      eventName,
+      table: record.table,
+      ...record.model ? { model: record.model } : {},
+      keys: { pk: record.keys.pk, sk: record.keys.sk },
+      ...oldImage ? { oldImage } : {},
+      ...newImage ? { newImage } : {},
+      approximateCreationTime: this.nowIso(),
+      sequenceNumber: String(seq).padStart(20, "0"),
+      shardId
+    };
+  }
+  /** Parse a zero-padded sequence string back to its integer value. */
+  seqToInt(seq) {
+    return Number.parseInt(seq, 10);
+  }
+  /** Render an integer sequence as the zero-padded string form. */
+  intToSeq(n) {
+    return String(n).padStart(20, "0");
+  }
+  /**
+   * Advance a shard's checkpoint over the contiguous prefix of acked sequence
+   * numbers. Starting just past the current checkpoint, consume every
+   * consecutive acked sequence; stop at the first gap (an un-acked sequence
+   * still pending redelivery). Consumed sequences are removed from the acked
+   * set to bound its size.
+   */
+  advanceCheckpoint(shardId) {
+    const acked = this.ackedSeqs.get(shardId);
+    if (!acked || acked.size === 0) return;
+    const current = this.checkpointMap.get(shardId);
+    let next = current === void 0 ? 0 : this.seqToInt(current);
+    const maxSeq = this.maxSeqSeen.get(shardId) ?? 0;
+    let advanced = false;
+    while (next + 1 <= maxSeq && acked.has(next + 1)) {
+      next += 1;
+      acked.delete(next);
+      advanced = true;
+    }
+    if (advanced) this.checkpointMap.set(shardId, this.intToSeq(next));
+  }
+  deriveEventName(record) {
+    if (record.op === "delete") return "REMOVE";
+    return record.oldItem ? "MODIFY" : "INSERT";
+  }
+  nowIso() {
+    if (this.clockMode === "virtual") {
+      return new Date(EPOCH + this.clockMs).toISOString();
+    }
+    return (/* @__PURE__ */ new Date()).toISOString();
+  }
+  // ── enqueue + delivery (spec §6) ─────────────────────────────────────────
+  enqueue(event) {
+    const queue = this.queues.get(event.shardId) ?? [];
+    let dueAt = this.clockMode === "virtual" ? this.clockMs : 0;
+    if (this.faultSpec.delay) {
+      const { min, max } = this.faultSpec.delay;
+      dueAt += this.rng.int(min, max);
+    }
+    queue.push({ event, dueAt, attempts: 0, droppedOnce: false });
+    this.queues.set(event.shardId, queue);
+  }
+  /**
+   * Deliver buffered, due records to the consumer, advancing per-shard
+   * checkpoints on success and redelivering failures. In `queued`/`replay`
+   * modes call this (or {@link advanceClock}) to drive delivery; `inline` calls
+   * it automatically after each capture.
+   */
+  async pump(maxBatches = Number.POSITIVE_INFINITY) {
+    if (!this.handler) return;
+    let delivered = 0;
+    let madeProgress = true;
+    while (madeProgress && delivered < maxBatches) {
+      madeProgress = false;
+      for (const shardId of [...this.queues.keys()]) {
+        const batch = this.collectBatch(shardId);
+        if (batch.length === 0) continue;
+        await this.deliverBatch(shardId, batch);
+        delivered += 1;
+        madeProgress = true;
+        if (delivered >= maxBatches) break;
+      }
+    }
+  }
+  /**
+   * Pull up to `batchSize` due records from a shard, preserving ascending
+   * sequence order (spec §6). When the `reorder` fault is on, the within-shard
+   * order is deliberately shuffled to exercise invariant detection.
+   */
+  collectBatch(shardId) {
+    const queue = this.queues.get(shardId);
+    if (!queue || queue.length === 0) return [];
+    const ready = [];
+    const now = this.clockMode === "virtual" ? this.clockMs : Number.POSITIVE_INFINITY;
+    const remaining = [];
+    for (const pd of queue) {
+      if (ready.length < this.batchSize && pd.dueAt <= now) {
+        ready.push(pd);
+      } else {
+        remaining.push(pd);
+      }
+    }
+    this.queues.set(shardId, remaining);
+    if (this.faultSpec.reorder && ready.length > 1) {
+      this.rng.shuffle(ready);
+    }
+    return ready;
+  }
+  async deliverBatch(shardId, pending) {
+    const delivered = [];
+    const droppedThisRound = [];
+    for (const pd of pending) {
+      if (!pd.droppedOnce && this.faultSpec.dropThenRedeliver && this.rng.chance(this.faultSpec.dropThenRedeliver)) {
+        pd.droppedOnce = true;
+        droppedThisRound.push(pd);
+        continue;
+      }
+      delivered.push(pd);
+      if (this.faultSpec.duplicate && this.rng.chance(this.faultSpec.duplicate)) {
+        delivered.push(pd);
+      }
+    }
+    if (droppedThisRound.length > 0) {
+      const queue = this.queues.get(shardId) ?? [];
+      queue.unshift(...droppedThisRound);
+      this.queues.set(shardId, queue);
+    }
+    if (delivered.length === 0) return;
+    const records = delivered.map((pd) => pd.event);
+    if (this.concurrentRecompute && this.concurrentRecomputeHook) {
+      for (const event of records) {
+        await this.concurrentRecomputeHook(this.concurrentRecompute, event);
+      }
+    }
+    const batch = { records };
+    const result = await this.handler(batch) ?? {};
+    const failures = new Set(result.batchItemFailures ?? []);
+    if (this.faultSpec.partialBatchFailure) {
+      for (const pd of delivered) {
+        if (this.rng.chance(this.faultSpec.partialBatchFailure)) {
+          failures.add(pd.event.sequenceNumber);
+        }
+      }
+    }
+    const requeue = [];
+    const seen = /* @__PURE__ */ new Set();
+    const acked = this.ackedSeqs.get(shardId) ?? /* @__PURE__ */ new Set();
+    for (const pd of delivered) {
+      const seq = pd.event.sequenceNumber;
+      if (failures.has(seq)) {
+        pd.attempts += 1;
+        if (pd.attempts > this.maxRetries) {
+          this.dlq.push(pd.event);
+        } else if (!seen.has(seq)) {
+          requeue.push(pd);
+          seen.add(seq);
+        }
+      } else {
+        acked.add(this.seqToInt(seq));
+      }
+    }
+    this.ackedSeqs.set(shardId, acked);
+    this.advanceCheckpoint(shardId);
+    if (requeue.length > 0) {
+      const queue = this.queues.get(shardId) ?? [];
+      requeue.sort(
+        (a, b) => a.event.sequenceNumber < b.event.sequenceNumber ? -1 : 1
+      );
+      queue.unshift(...requeue);
+      this.queues.set(shardId, queue);
+    }
+  }
+  // ── public API (spec §10) ────────────────────────────────────────────────
+  /** Register the consumer. Returns an unsubscribe handle. */
+  subscribe(handler) {
+    this.handler = handler;
+    if (this.startingPosition === "LATEST") {
+      this.queues.clear();
+    }
+    return () => {
+      if (this.handler === handler) this.handler = null;
+    };
+  }
+  /** Await any inline-mode async deliveries triggered by writes. */
+  async flush() {
+    await this.inflight;
+  }
+  /**
+   * Advance the virtual clock by `ms` and deliver records whose due-time has
+   * arrived (spec §7). Reproduces throttle T / sweep period / staleness S time
+   * behavior deterministically (AC4).
+   */
+  async advanceClock(ms) {
+    if (this.clockMode !== "virtual") {
+      throw new Error('advanceClock requires clock: "virtual"');
+    }
+    this.clockMs += ms;
+    await this.pump();
+  }
+  /** Current virtual time (ms since the emulator epoch). */
+  now() {
+    return this.clockMs;
+  }
+  /** Configure fault injection (spec §8). Merges into the current spec. */
+  fault(spec) {
+    this.faultSpec = { ...this.faultSpec, ...spec };
+  }
+  /**
+   * Force a recompute to race a mark for the given ref (spec §8, §7). The
+   * harness supplies the actual recompute via {@link onConcurrentRecompute};
+   * this records which ref to race and arms the hook.
+   */
+  injectConcurrentRecompute(ref) {
+    this.concurrentRecompute = ref;
+  }
+  /**
+   * Register the callback the emulator invokes (before each record reaches the
+   * consumer) when a concurrent recompute has been injected. This is how the
+   * test harness wires its recompute into the delivery race.
+   */
+  onConcurrentRecompute(hook) {
+    this.concurrentRecomputeHook = hook;
+  }
+  /** Snapshot the recorded event log (spec §10). */
+  record() {
+    return { seed: this.seed, events: this.log.map((e) => ({ ...e })) };
+  }
+  /**
+   * Replay an event log through the delivery pipeline, optionally shuffled and
+   * duplicated (spec §10, AC5). Used to prove **replay equivalence**: starting
+   * from any global order plus duplicates, a consumer that respects the
+   * per-shard ordering contract (spec §6) reaches a final aggregate equal to a
+   * full recompute from source.
+   *
+   * The shuffle models cross-shard reordering and at-least-once chaos at the
+   * delivery boundary. It must NOT, however, break the within-shard ordering
+   * guarantee that real DynamoDB Streams provides and that incremental
+   * aggregation depends on — so after shuffling/duplicating, each shard's queue
+   * is re-sorted into ascending original `sequenceNumber` order before delivery.
+   * The original `sequenceNumber` (assigned at record time) is preserved so it
+   * remains the source-of-truth ordering the consumer can rely on.
+   */
+  async replay(log, opts = {}) {
+    const replayRng = new SeededRandom(log.seed ?? this.seed);
+    let events = log.events.map((e) => ({ ...e }));
+    if (opts.shuffle) {
+      events = replayRng.shuffle(events);
+    }
+    const expanded = [];
+    for (const e of events) {
+      expanded.push(e);
+      if (opts.duplicate && replayRng.chance(opts.duplicate)) {
+        expanded.push({ ...e });
+      }
+    }
+    this.queues.clear();
+    this.seqCounters.clear();
+    this.ackedSeqs.clear();
+    this.maxSeqSeen.clear();
+    this.checkpointMap.clear();
+    for (const e of expanded) {
+      const shardId = shardIdFor(e.keys.pk, this.shardCount);
+      const resequenced = { ...e, shardId };
+      const queue = this.queues.get(shardId) ?? [];
+      queue.push({ event: resequenced, dueAt: 0, attempts: 0, droppedOnce: false });
+      this.queues.set(shardId, queue);
+      const seqInt = this.seqToInt(resequenced.sequenceNumber);
+      if (seqInt > (this.maxSeqSeen.get(shardId) ?? 0)) {
+        this.maxSeqSeen.set(shardId, seqInt);
+      }
+    }
+    for (const [shardId, queue] of this.queues) {
+      queue.sort(
+        (a, b) => a.event.sequenceNumber < b.event.sequenceNumber ? -1 : a.event.sequenceNumber > b.event.sequenceNumber ? 1 : 0
+      );
+      this.queues.set(shardId, queue);
+    }
+    await this.pump();
+  }
+  /** Per-shard checkpoints (last acked sequence number). */
+  checkpoints() {
+    return Object.fromEntries(this.checkpointMap);
+  }
+  /** Dead-lettered events (exceeded maxRetries). */
+  deadLetters() {
+    return this.dlq.map((e) => ({ ...e }));
+  }
+  /** Reset delivery state and re-seed (keeps the subscription + model opt-in). */
+  reset() {
+    this.seqCounters.clear();
+    this.queues.clear();
+    this.checkpointMap.clear();
+    this.ackedSeqs.clear();
+    this.maxSeqSeen.clear();
+    this.log = [];
+    this.dlq = [];
+    this.clockMs = 0;
+    this.inflight = Promise.resolve();
+    this.faultSpec = {};
+    this.concurrentRecompute = null;
+    this.rng = new SeededRandom(this.seed);
+  }
+  /** Tear down: detach from the core seam and disable model streaming. */
+  close() {
+    this.detachCapture?.();
+    this.detachCapture = null;
+    for (const model of this.models) {
+      ChangeCaptureRegistry.disableStream(model);
+    }
+    this.handler = null;
+  }
+};
+function createCdcEmulator(opts = {}) {
+  return new CdcEmulator(opts);
+}
+
+// src/relation/maintenance-projection.ts
+var PATH_FIELD_RE = /^\$\.(?:entity|input)\.([A-Za-z_$][\w$]*)$/;
+function pathField(path) {
+  const m = PATH_FIELD_RE.exec(path);
+  if (m !== null) return m[1];
+  return path;
+}
+function applyTransform(op, args, value) {
+  if (op === "identity") return value;
+  if (op === "preview") {
+    const n = args[0];
+    if (typeof n !== "number" || !Number.isInteger(n) || n <= 0) {
+      throw new Error(
+        `maintenance projection: a 'preview' projection has a non-positive-integer length bound (${JSON.stringify(n)}).`
+      );
+    }
+    if (value === null || value === void 0) return value;
+    return String(value).slice(0, n);
+  }
+  throw new Error(`maintenance projection: unknown projection transform op '${op}'.`);
+}
+function projectFrom(project, source) {
+  const out = {};
+  for (const [attr, transform] of Object.entries(project)) {
+    const field = pathField(transform.path);
+    out[attr] = applyTransform(transform.op, transform.args, source[field]);
+  }
+  return out;
+}
+function compareDesc(a, b) {
+  if (a === b) return 0;
+  if (a === void 0 || a === null) return 1;
+  if (b === void 0 || b === null) return -1;
+  return a > b ? -1 : 1;
+}
+function orderAndTrimCollection(items, collection) {
+  let next = [...items];
+  const orderBy = collection.orderBy;
+  if (orderBy !== void 0) {
+    const orderField = pathField(orderBy);
+    const dir = collection.orderDir ?? "DESC";
+    next.sort(
+      (a, b) => dir === "ASC" ? compareDesc(b[orderField], a[orderField]) : compareDesc(a[orderField], b[orderField])
+    );
+    if (collection.maxItems !== void 0 && next.length > collection.maxItems) {
+      next = next.slice(0, collection.maxItems);
+    }
+  } else if (collection.maxItems !== void 0 && next.length > collection.maxItems) {
+    next = next.slice(next.length - collection.maxItems);
+  }
+  return next;
+}
+function collectionIdentityAttr(effect) {
+  return Object.keys(effect.project)[0];
+}
+
+// src/cdc/maintenance-drain.ts
+var MAINT_OUTBOX_PK_PREFIX = "OUTBOX#MAINT#";
+var OWNER_ATTR = "__maintOwner__";
+var RELATION_ATTR = "__maintRelation__";
+var TRIGGER_ATTR = "__maintTrigger__";
+function ownerKey(ownerClass, effect, source) {
+  const keyInput = {};
+  for (const [ownerField, srcPath] of Object.entries(effect.keys)) {
+    keyInput[ownerField] = source[pathField(srcPath)];
+  }
+  const { TableName, Key } = buildDeleteInput(
+    ownerClass,
+    keyInput
+  );
+  return { TableName, Key };
+}
+var MaintenanceDrain = class {
+  graph;
+  /** Owner entity name → its model class (for the owner-row key derivation). */
+  ownerByName = /* @__PURE__ */ new Map();
+  /** Per-event-id de-dup within a single handler invocation (at-least-once). */
+  appliedSeq = /* @__PURE__ */ new Set();
+  /** Count of owner-row writes applied (test/diagnostic). */
+  applied = 0;
+  constructor(opts = {}) {
+    const classes = (opts.models ?? []).map((m) => {
+      try {
+        return resolveModelClass(m);
+      } catch {
+        return m;
+      }
+    });
+    const views = opts.views ?? [];
+    const allClasses = [...classes, ...views.map((v) => v.viewClass)];
+    const scoped = allClasses.length > 0 ? new Map(allClasses.map((c) => [c, MetadataRegistry.get(c)])) : void 0;
+    this.graph = buildMaintenanceGraph(scoped, views);
+    for (const item of this.graph.items) {
+      this.ownerByName.set(item.ownerEntity, item.ownerClass);
+    }
+  }
+  /** The CDC {@link ChangeHandler} to subscribe to an emulator / Streams source. */
+  handler = async (batch) => {
+    const failures = [];
+    for (const event of batch.records) {
+      if (!event.keys.pk.startsWith(MAINT_OUTBOX_PK_PREFIX)) continue;
+      if (event.eventName === "REMOVE") continue;
+      const image = event.newImage;
+      if (image === void 0) continue;
+      try {
+        await this.applyOne(event, image);
+      } catch (e) {
+        failures.push(event.sequenceNumber);
+        if (process.env.GRAPHDDB_DRAIN_DEBUG) {
+          console.error("DRAIN ERROR", event.keys.pk, e);
+        }
+      }
+    }
+    return failures.length > 0 ? { batchItemFailures: failures } : {};
+  };
+  /** Resolve one maintenance-outbox event to its effect and apply the owner-row write. */
+  async applyOne(event, image) {
+    const eventId = `${event.shardId}#${event.sequenceNumber}`;
+    if (this.appliedSeq.has(eventId)) return;
+    const ownerEntity = String(image[OWNER_ATTR] ?? "");
+    const relationProperty = String(image[RELATION_ATTR] ?? "");
+    const trigger = String(image[TRIGGER_ATTR] ?? "");
+    const item = this.resolve(trigger, ownerEntity, relationProperty);
+    if (item === void 0) {
+      this.appliedSeq.add(eventId);
+      return;
+    }
+    const effect = item.effect;
+    const ownerClass = item.ownerClass;
+    const { TableName, Key } = ownerKey(ownerClass, effect, image);
+    const executor = ClientManager.getExecutor();
+    if (effect.kind === "counter") {
+      if (effect.value.op === "count") {
+        await executor.update({
+          TableName,
+          Key,
+          UpdateExpression: "ADD #a0 :a0",
+          ExpressionAttributeNames: { "#a0": effect.attribute },
+          ExpressionAttributeValues: { ":a0": effect.delta ?? 0 }
+        });
+      } else {
+        await this.applyMax(TableName, Key, effect.attribute, effect.value.field, image);
+      }
+    } else if (effect.kind === "membership") {
+      await this.applyMembership(TableName, Key, item, effect, image);
+    } else if (effect.kind === "snapshot") {
+      const projection = projectFrom(effect.project, image);
+      await this.applySnapshot(TableName, Key, projection);
+    } else {
+      await this.applyCollection(TableName, Key, item, image);
+    }
+    this.appliedSeq.add(eventId);
+    this.applied += 1;
+  }
+  /** Resolve a maintenance-outbox event back to the declared {@link MaintainItem}. */
+  resolve(trigger, ownerEntity, relationProperty) {
+    for (const item of this.graph.effectsFor(trigger)) {
+      const itemOwnerName = item.ownerClass.name;
+      if ((itemOwnerName === ownerEntity || item.ownerEntity === ownerEntity) && item.relationProperty === relationProperty) {
+        return item;
+      }
+    }
+    return void 0;
+  }
+  /** A `snapshot` SET of each projected attribute onto the owner row (idempotent). */
+  async applySnapshot(TableName, Key, projection) {
+    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 ClientManager.getExecutor().update({
+      TableName,
+      Key,
+      UpdateExpression: `SET ${sets.join(", ")}`,
+      ExpressionAttributeNames: names,
+      ExpressionAttributeValues: values
+    });
+  }
+  /**
+   * A sparse-view **membership** write (#133): evaluate the membership predicate against
+   * the source image; PUT the view row (its projection + key fields) when the predicate
+   * holds, DELETE it when it flips false. A source `removed` event always deletes (the
+   * source no longer exists, so its view row must disappear regardless of the predicate).
+   *
+   * Both ops are idempotent under at-least-once redelivery: a repeated PUT writes the same
+   * row, a repeated DELETE is a no-op. The view row is keyed by the source identity
+   * (`effect.keys`), so the PUT/DELETE always targets the SAME physical row the predicate
+   * gates.
+   */
+  async applyMembership(TableName, Key, item, effect, image) {
+    void TableName;
+    const ownerClass = item.ownerClass;
+    const isRemoved = item.trigger.endsWith(".removed");
+    const holds = !isRemoved && evaluateMembership(effect.predicate, image);
+    if (holds) {
+      const keyInput2 = {};
+      for (const [ownerField, srcPath] of Object.entries(effect.keys)) {
+        keyInput2[ownerField] = image[pathField(srcPath)];
+      }
+      const projection = projectFrom(effect.project, image);
+      const putItem = { ...keyInput2, ...projection };
+      const putInput = buildPutInput(ownerClass, putItem);
+      await ClientManager.getExecutor().put(putInput);
+      return;
+    }
+    const keyInput = {};
+    for (const [ownerField, srcPath] of Object.entries(effect.keys)) {
+      keyInput[ownerField] = image[pathField(srcPath)];
+    }
+    const deleteInput = buildDeleteInput(ownerClass, keyInput);
+    await ClientManager.getExecutor().delete(deleteInput);
+  }
+  /**
+   * A running `max`: read the owner row, and `SET` the attribute to the source value
+   * only when it is greater (or absent). Implemented as a conditional update so a
+   * redelivered / out-of-order older value never regresses the stored max — idempotent
+   * and commutative under at-least-once delivery.
+   */
+  async applyMax(TableName, Key, attribute, sourceField, image) {
+    const candidate = image[sourceField];
+    if (candidate === void 0 || candidate === null) return;
+    const cond = buildConditionExpression({ attributeNotExists: attribute });
+    try {
+      await ClientManager.getExecutor().update({
+        TableName,
+        Key,
+        UpdateExpression: "SET #a0 = :v",
+        ConditionExpression: `attribute_not_exists(#a0) OR #a0 < :v`,
+        ExpressionAttributeNames: { "#a0": attribute },
+        ExpressionAttributeValues: { ":v": candidate }
+      });
+    } catch (e) {
+      void cond;
+      if (isConditionFailure(e)) return;
+      throw e;
+    }
+  }
+  /**
+   * A bounded `collection`: read the current list, apply the event (append for a
+   * `created`/`updated` source, splice for a `removed`), de-duplicate by the projected
+   * identity key, order by `orderBy` (in `orderDir`, default DESC), trim to `maxItems`, and write the whole
+   * list back. The read-modify-write is exactly what a single synchronous
+   * `UpdateExpression` cannot do — the reason a bounded/ordered collection is a stream
+   * maintainer (Phase 1 sync was append-only).
+   */
+  async applyCollection(TableName, Key, item, image) {
+    const effect = item.effect;
+    if (effect.kind !== "collection") return;
+    const field = effect.collection.field;
+    const executor = ClientManager.getExecutor();
+    const res = await executor.execute({
+      type: "GetItem",
+      tableName: TableName,
+      keyCondition: Key,
+      consistentRead: true
+    });
+    const current = res.items[0];
+    const existing = Array.isArray(current?.[field]) ? [...current[field]] : [];
+    const projected = projectFrom(effect.project, image);
+    const idAttr = collectionIdentityAttr(effect);
+    const idOf = (row) => idAttr ? row[idAttr] : void 0;
+    const isRemoved = item.trigger.endsWith(".removed");
+    let next;
+    if (isRemoved) {
+      next = existing.filter((row) => idOf(row) !== idOf(projected));
+    } else {
+      next = existing.filter((row) => idOf(row) !== idOf(projected));
+      next.push(projected);
+    }
+    next = orderAndTrimCollection(next, effect.collection);
+    await executor.update({
+      TableName,
+      Key,
+      UpdateExpression: "SET #c = :list",
+      ExpressionAttributeNames: { "#c": field },
+      ExpressionAttributeValues: { ":list": next }
+    });
+  }
+  /** Owner-row writes applied so far (test/diagnostic). */
+  appliedCount() {
+    return this.applied;
+  }
+  /** Clear the per-delivery de-dup set + counters (test reset). */
+  reset() {
+    this.appliedSeq = /* @__PURE__ */ new Set();
+    this.applied = 0;
+  }
+};
+function evaluateMembership(predicate, image) {
+  const field = pathField(predicate.path);
+  const present = Object.prototype.hasOwnProperty.call(image, field);
+  const value = image[field];
+  switch (predicate.op) {
+    case "exists":
+      return present && value !== null && value !== void 0;
+    case "notExists":
+      return !present || value === null || value === void 0;
+    case "truthy":
+      return Boolean(value);
+    case "falsy":
+      return !value;
+    case "eq":
+      return value === predicate.value;
+    case "ne":
+      return value !== predicate.value;
+    default:
+      return false;
+  }
+}
+function isConditionFailure(e) {
+  const name = e?.name ?? "";
+  const msg = e instanceof Error ? e.message : String(e);
+  return name === "ConditionalCheckFailedException" || /ConditionalCheckFailed|condition/i.test(msg);
+}
+function createMaintenanceDrain(opts = {}) {
+  return new MaintenanceDrain(opts);
+}
+function createMaintenanceDrainHandler(opts = {}) {
+  return createMaintenanceDrain(opts).handler;
+}
+
+// src/cdc/projection-sink.ts
+var EVENT_FOR_CHANGE = {
+  INSERT: "created",
+  MODIFY: "updated",
+  REMOVE: "removed"
+};
+var InMemoryProjectionSink = class {
+  /** The current sink contents, keyed by the idempotency key. */
+  records = /* @__PURE__ */ new Map();
+  /** Total upsert CALLS (including redelivered ones) — distinguishes calls from records. */
+  upserts = 0;
+  upsert(key, record) {
+    this.records.set(key, record);
+    this.upserts += 1;
+  }
+  delete(key) {
+    this.records.delete(key);
+  }
+  /** The number of distinct sink records (the converged projection size). */
+  size() {
+    return this.records.size;
+  }
+  /** The total upsert calls (≥ size when redelivery occurred). */
+  upsertCount() {
+    return this.upserts;
+  }
+  /** Reset the sink (test). */
+  reset() {
+    this.records.clear();
+    this.upserts = 0;
+  }
+};
+var ProjectionSinkDrain = class {
+  sink;
+  /** Source-entity CLASS name (the `event.model` the capture seam records) → projections. */
+  bySource = /* @__PURE__ */ new Map();
+  /** Per-(shard,seq) de-dup within one handler invocation (at-least-once). */
+  applied = /* @__PURE__ */ new Set();
+  constructor(opts) {
+    this.sink = opts.sink;
+    for (const proj of opts.projections) {
+      if (!isProjectionDefinition(proj)) {
+        throw new Error(
+          "ProjectionSinkDrain: a non-projection definition was supplied. Build projections with defineProjection(...)."
+        );
+      }
+      const sourceName = proj.sourceClass.name;
+      const bucket = this.bySource.get(sourceName);
+      if (bucket) bucket.push(proj);
+      else this.bySource.set(sourceName, [proj]);
+    }
+  }
+  /** The CDC {@link ChangeHandler} to subscribe to an emulator / Streams source. */
+  handler = async (batch) => {
+    const failures = [];
+    for (const event of batch.records) {
+      try {
+        await this.applyOne(event);
+      } catch (e) {
+        failures.push(event.sequenceNumber);
+        if (process.env.GRAPHDDB_PROJECTION_DEBUG) {
+          console.error("PROJECTION SINK ERROR", event.keys.pk, e);
+        }
+      }
+    }
+    return failures.length > 0 ? { batchItemFailures: failures } : {};
+  };
+  /** Project one source event into the sink for every matching projection. */
+  async applyOne(event) {
+    const sourceName = event.model;
+    if (sourceName === void 0) return;
+    const projections = this.bySource.get(sourceName);
+    if (projections === void 0 || projections.length === 0) return;
+    const lifecycleEvent = EVENT_FOR_CHANGE[event.eventName];
+    const image = event.eventName === "REMOVE" ? event.oldImage : event.newImage;
+    if (image === void 0) return;
+    const eventId = `${event.shardId}#${event.sequenceNumber}`;
+    if (this.applied.has(eventId)) return;
+    for (const proj of projections) {
+      if (!proj.on.includes(lifecycleEvent)) continue;
+      const key = image[proj.idempotencyKey];
+      if (key === void 0 || key === null) {
+        throw new Error(
+          `defineProjection '${proj.name}': source event carries no idempotency key attribute '${proj.idempotencyKey}'. Every projected source row must carry it (it folds at-least-once delivery to one sink upsert).`
+        );
+      }
+      const keyStr = String(key);
+      if (lifecycleEvent === "removed") {
+        await this.sink.delete?.(keyStr);
+        continue;
+      }
+      const record = Object.keys(proj.project).length === 0 ? image : projectFrom(proj.project, image);
+      await this.sink.upsert(keyStr, record);
+    }
+    this.applied.add(eventId);
+  }
+  /** Clear the per-delivery de-dup set (test reset). */
+  reset() {
+    this.applied = /* @__PURE__ */ new Set();
+  }
+};
+function createProjectionSinkDrain(opts) {
+  return new ProjectionSinkDrain(opts);
+}
+function createProjectionSinkHandler(opts) {
+  return createProjectionSinkDrain(opts).handler;
+}
+
+export {
+  CdcEmulator,
+  createCdcEmulator,
+  pathField,
+  projectFrom,
+  compareDesc,
+  orderAndTrimCollection,
+  MAINT_OUTBOX_PK_PREFIX,
+  MaintenanceDrain,
+  createMaintenanceDrain,
+  createMaintenanceDrainHandler,
+  InMemoryProjectionSink,
+  ProjectionSinkDrain,
+  createProjectionSinkDrain,
+  createProjectionSinkHandler
+};