graphddb 0.7.9 → 0.8.0

package/dist/from-change-DanwjE5b.d.ts

@@ -1,327 +0,0 @@
-import { C as CdcEmulatorOptions, e as ChangeHandler, U as Unsubscribe, F as FaultSpec, g as ConcurrentRecomputeRef, c as ChangeEvent, E as EventLog, R as ReplayOptions, S as ShardId, V as ViewDefinition, m as EntityMetadata } from './maintenance-view-adapter-BATUh_I8.js';
-
-/**
- * CDC emulator (issue #72). Subscribes to the core write-capture seam
- * ({@link ChangeCaptureRegistry}) and turns each {@link RawWriteRecord} into a
- * DynamoDB-Streams-equivalent {@link ChangeEvent}, then delivers events to a
- * consumer under a deterministic delivery contract (spec §6): per-shard ordered,
- * batched, at-least-once, with checkpoint/resume, partial-batch failure, and a
- * dead-letter queue. Faults (duplicate / reorder / delay / dropThenRedeliver /
- * partialBatchFailure) and a concurrent-recompute race are injectable and
- * seeded for deterministic reproduction (spec §8).
- *
- * The emulator is dev/test only. The {@link ChangeEvent} type and delivery
- * contract match real Streams so a consumer is portable to production (spec §1).
- */
-
-/**
- * The CDC emulator (spec §10 API). Construct via {@link createCdcEmulator}.
- */
-declare class CdcEmulator {
-    private readonly mode;
-    private readonly clockMode;
-    private readonly batchSize;
-    private readonly maxRetries;
-    private readonly startingPosition;
-    private readonly shardCount;
-    private readonly seed;
-    private rng;
-    private faultSpec;
-    private concurrentRecompute;
-    private concurrentRecomputeHook;
-    /** Per-shard monotonic sequence counter. */
-    private seqCounters;
-    /** Per-shard delivery queue (queued/replay modes). */
-    private queues;
-    /** Per-shard last successfully checkpointed sequence number. */
-    private checkpointMap;
-    /**
-     * 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.
-     */
-    private ackedSeqs;
-    /** Per-shard count of sequences ever assigned, to bound the prefix scan. */
-    private maxSeqSeen;
-    /** Recorded event log (record mode and always, for replay()). */
-    private log;
-    /** Dead-letter buffer. */
-    private dlq;
-    private handler;
-    /** Virtual clock (ms since EPOCH). */
-    private clockMs;
-    /** Pending async work from inline-mode captures, awaited by callers. */
-    private inflight;
-    private detachCapture;
-    private readonly models;
-    constructor(opts?: CdcEmulatorOptions);
-    private onRawWrite;
-    private toChangeEvent;
-    /** Parse a zero-padded sequence string back to its integer value. */
-    private seqToInt;
-    /** Render an integer sequence as the zero-padded string form. */
-    private intToSeq;
-    /**
-     * 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.
-     */
-    private advanceCheckpoint;
-    private deriveEventName;
-    private nowIso;
-    private enqueue;
-    /**
-     * 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.
-     */
-    pump(maxBatches?: number): Promise<void>;
-    /**
-     * 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.
-     */
-    private collectBatch;
-    private deliverBatch;
-    /** Register the consumer. Returns an unsubscribe handle. */
-    subscribe(handler: ChangeHandler): Unsubscribe;
-    /** Await any inline-mode async deliveries triggered by writes. */
-    flush(): Promise<void>;
-    /**
-     * 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).
-     */
-    advanceClock(ms: number): Promise<void>;
-    /** Current virtual time (ms since the emulator epoch). */
-    now(): number;
-    /** Configure fault injection (spec §8). Merges into the current spec. */
-    fault(spec: FaultSpec): void;
-    /**
-     * 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: ConcurrentRecomputeRef): void;
-    /**
-     * 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: (ref: ConcurrentRecomputeRef, event: ChangeEvent) => void | Promise<void>): void;
-    /** Snapshot the recorded event log (spec §10). */
-    record(): EventLog;
-    /**
-     * 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.
-     */
-    replay(log: EventLog, opts?: ReplayOptions): Promise<void>;
-    /** Per-shard checkpoints (last acked sequence number). */
-    checkpoints(): Record<ShardId, string>;
-    /** Dead-lettered events (exceeded maxRetries). */
-    deadLetters(): ChangeEvent[];
-    /** Reset delivery state and re-seed (keeps the subscription + model opt-in). */
-    reset(): void;
-    /** Tear down: detach from the core seam and disable model streaming. */
-    close(): void;
-}
-/** Create a CDC emulator (spec §10). */
-declare function createCdcEmulator(opts?: CdcEmulatorOptions): CdcEmulator;
-
-/**
- * CDC **maintenance drain** (issue #130) — the asynchronous lower for
- * `updateMode: 'stream'` maintainers (Epic #118 §5.1).
- *
- * A synchronous (`updateMode: 'mutation'`) maintainer composes its owner-row write
- * into the SAME atomic `TransactWriteItems` as the source write (#127). A
- * `updateMode: 'stream'` maintainer instead emits a **maintenance-outbox** marker row
- * (`OUTBOX#MAINT#…`) ATOMICALLY with the source write (the #130 compile lowering in
- * `src/spec/mutation-command.ts`), and THIS consumer — driven by the {@link
- * import('./emulator.js').CdcEmulator} (or, in production, real DynamoDB Streams +
- * a Lambda built around {@link createMaintenanceDrainHandler}) — applies the owner-row
- * write asynchronously.
- *
- * ## Why a separate async path exists (not just "do it later synchronously")
- *
- * The async path realizes the maintenance operations a single synchronous
- * `UpdateExpression` cannot express against an unread item:
- *
- * - **collection `maxItems` trim** — keeping a bounded, ordered list requires reading
- *   the current list, appending, sorting, and trimming (a read-modify-write); a
- *   synchronous `list_append` can only append (Phase 1 was append-only, #127).
- * - **`removed`-driven splice** — removing an entry from a maintained collection on a
- *   source `removed` event likewise needs the current list.
- * - **running `max(field)`** — a conditional `SET` (`#a = :v` guarded by
- *   `attribute_not_exists(#a) OR #a < :v`) whose failed guard, if run synchronously,
- *   would roll back the legitimate source write.
- *
- * ## Delivery guarantees (reused from the CDC substrate)
- *
- * The maintenance-outbox row is recorded ATOMICALLY with the source write, so the
- * intent can never be lost ("wrote the row, lost the maintenance" is impossible). The
- * CDC substrate then delivers it **at-least-once**, **per-shard ordered** (a shard is
- * `hash(pk)`, and the outbox row's `pk` is keyed off the SOURCE row's key, so all
- * maintenance events for one source entity land on one shard in source-write order),
- * with a **DLQ** for poison events. This consumer is therefore written to be
- * **idempotent / commutative** wherever at-least-once redelivery could double-apply:
- *
- * - a `snapshot` `SET` is naturally idempotent (re-applying the same projection is a
- *   no-op);
- * - a `collection` rebuild de-duplicates by the projected item's identity key, so a
- *   redelivered append does not grow the list twice;
- * - a `max` conditional `SET` is idempotent (the guard rejects a non-greater value);
- * - a `count` `ADD` is the ONE non-idempotent op — but the source-row create guard
- *   (`attribute_not_exists`) means a given source `created` event is emitted at most
- *   once into the outbox, and the per-shard checkpoint advances only over acked events,
- *   so a `count` is applied once per genuine source lifecycle. (A duplicate DELIVERY of
- *   the same event is folded by the consumer's per-event de-dup set within a drain.)
- */
-
-/**
- * The PK prefix a maintenance-outbox row keys on — the single source of truth shared
- * with the compiler ({@link import('../spec/mutation-command.js')}'s
- * `MAINT_OUTBOX_PK_PREFIX`). The drain selects its events by `keys.pk.startsWith` of
- * this. Kept as a local literal (rather than importing a non-exported compiler const)
- * so the cdc module does not depend on the spec module; the value is asserted equal by
- * the integration tests that round-trip a real stream maintainer through both.
- */
-declare const MAINT_OUTBOX_PK_PREFIX = "OUTBOX#MAINT#";
-/** Options for {@link createMaintenanceDrain}. */
-interface MaintenanceDrainOptions {
-    /**
-     * The model classes (or `ModelStatic`s) whose stream maintainers this drain
-     * applies. The drain builds a scoped {@link MaintenanceGraph} over them to resolve
-     * each maintenance-outbox event back to its declared effect. Defaults to the GLOBAL
-     * registry when omitted.
-     */
-    readonly models?: readonly Function[];
-    /**
-     * The {@link ViewDefinition}s (`defineView`) whose maintainers this drain applies
-     * (issue #132). A view's destination is its dedicated view model; its source
-     * classes should also be in {@link models} so the drain can resolve their
-     * maintenance-outbox events. Defaults to none.
-     */
-    readonly views?: readonly ViewDefinition[];
-}
-/**
- * A maintenance drain: a CDC consumer ({@link ChangeHandler}) that applies the
- * owner-row writes for `updateMode: 'stream'` maintainers. Construct via
- * {@link createMaintenanceDrain}, then `subscribe` its {@link handler} to a
- * {@link import('./emulator.js').CdcEmulator} (dev/test) or wire it into a real
- * Streams Lambda (production).
- */
-declare class MaintenanceDrain {
-    private readonly graph;
-    /** Owner entity name → its model class (for the owner-row key derivation). */
-    private readonly ownerByName;
-    /** Per-event-id de-dup within a single handler invocation (at-least-once). */
-    private appliedSeq;
-    /** Count of owner-row writes applied (test/diagnostic). */
-    private applied;
-    constructor(opts?: MaintenanceDrainOptions);
-    /** The CDC {@link ChangeHandler} to subscribe to an emulator / Streams source. */
-    readonly handler: ChangeHandler;
-    /** Resolve one maintenance-outbox event to its effect and apply the owner-row write. */
-    private applyOne;
-    /** Resolve a maintenance-outbox event back to the declared {@link MaintainItem}. */
-    private resolve;
-    /** A `snapshot` SET of each projected attribute onto the owner row (idempotent). */
-    private applySnapshot;
-    /**
-     * 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.
-     */
-    private applyMembership;
-    /**
-     * 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.
-     */
-    private applyMax;
-    /**
-     * 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).
-     */
-    private applyCollection;
-    /** Owner-row writes applied so far (test/diagnostic). */
-    appliedCount(): number;
-    /** Clear the per-delivery de-dup set + counters (test reset). */
-    reset(): void;
-}
-/** Create a {@link MaintenanceDrain} (issue #130). */
-declare function createMaintenanceDrain(opts?: MaintenanceDrainOptions): MaintenanceDrain;
-/**
- * Create just the CDC {@link ChangeHandler} for a maintenance drain — the form to
- * subscribe to an emulator or wire into a production Streams Lambda. A thin wrapper
- * over {@link createMaintenanceDrain} for callers that only need the handler.
- */
-declare function createMaintenanceDrainHandler(opts?: MaintenanceDrainOptions): ChangeHandler;
-
-/**
- * `fromChange` — the pure `(event) => [old, new]` typed mapper (issue #153).
- *
- * This is graphddb's HALF of the CDC-projection boundary (see
- * `docs/cdc-projection.md`): it parses a raw {@link ChangeEvent}'s `oldImage` /
- * `newImage` into typed model instances and does nothing downstream of that (no
- * sink write, no dedup, no subscription). `Model.fromChange(event)` on `DDBModel`
- * delegates here.
- *
- * The two responsibilities packed into one call are **routing** and **parse**:
- *
- * - Routing — an event that is not for `modelClass` yields `[null, null]`. A valid
- *   event for the class always has at least one non-null image, so `[null, null]`
- *   is an unambiguous "not for this model" signal and no separate `owns()` guard is
- *   needed. The match is by `event.model` (the resolved model name the write path /
- *   emulator stamps) when present, falling back to the model's PK prefix
- *   (`keys.pk` begins with `<prefix>`) when the event carries no `model`.
- * - Parse — each present image is hydrated via the existing {@link hydrate}
- *   (raw item → typed value, INCLUDING ISO 8601 → `Date` for `@datetime` and
- *   embedded reconstruction), returning ALL fields (no projection — narrowing does
- *   not reduce network cost since the image is already on the stream). The hydrated
- *   plain record is then loaded onto a fresh model instance so the result is a
- *   genuine `InstanceType` (like the read path's `{ hydrate }` factory option).
- *
- * The image side present per event kind mirrors DynamoDB Streams:
- *
- * - INSERT → `[null,      new ]`
- * - MODIFY → `[old,       new ]`
- * - REMOVE → `[old,       null]`
- */
-
-/**
- * Parse a {@link ChangeEvent} into the `[oldRecord, newRecord]` tuple for the given
- * model. Returns `[null, null]` when the event is not for this model (routing). The
- * caller (`DDBModel.fromChange`) supplies the resolved metadata + class; this
- * function is the runtime core and is deliberately model-name-string driven so
- * `DDBModel.subscribe` can reuse it when routing a batch.
- */
-declare function parseChange<T extends object>(event: ChangeEvent, metadata: EntityMetadata, modelName: string, modelClass: new () => T): [T | null, T | null];
-
-export { CdcEmulator as C, MAINT_OUTBOX_PK_PREFIX as M, MaintenanceDrain as a, type MaintenanceDrainOptions as b, createCdcEmulator as c, createMaintenanceDrain as d, createMaintenanceDrainHandler as e, parseChange as p };