graphddb 0.1.0

package/dist/chunk-UNRQ5YJT.js

@@ -0,0 +1,461 @@
+import {
+  ChangeCaptureRegistry,
+  resolveModelClass
+} from "./chunk-347U24SB.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);
+}
+
+export {
+  CdcEmulator,
+  createCdcEmulator
+};

package/dist/cli.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node