@sekiban/dcb-runtime 0.2.0

package/dist/store/D1EventStore.d.ts

@@ -0,0 +1,111 @@
+import type { WaitForTargetLookup, WaitForTargetSourcePort } from "../query/ProjectionQueryStore";
+import type { DeliverySource, DownstreamOutboxMessage } from "../downstream/types";
+import { CanonicalEventIdentityConflictError, type DeliveryIncident, type DeliveryAttemptContext, type DeliveryOutcome, type DetectorStore, type EventStore, type GlobalReceiptJoin, type InconsistencyClassification, type InconsistencyFinding, type PendingArrivalRecord, type ProjectionCheckpoint, type ProjectionCheckpointAdvance, type ProjectionLag, type ProjectionStore, type StoredEvent } from "./types";
+/** Write batches exposed only as a test fault-injection seam. */
+export type D1BatchOperation = "recordDelivery" | "upsertPending";
+/** Single-statement write boundaries exposed only to fault tests. */
+export type D1WriteOperation = "advanceProjectionCheckpoint" | "appendFinding" | "appendDeliveryIncident";
+export interface D1StoreOptions {
+    /**
+     * Test-only hook. It may append a failing prepared statement to prove that
+     * D1 rolls the predeclared batch back atomically. Production composition
+     * leaves this unset.
+     */
+    readonly beforeBatch?: (operation: D1BatchOperation, statements: readonly D1PreparedStatement[], database: D1Database) => readonly D1PreparedStatement[] | Promise<readonly D1PreparedStatement[]>;
+    /**
+     * Test-only replacement for a single durable statement. Production leaves
+     * this unset; each such statement is already atomic in D1.
+     */
+    readonly beforeWrite?: (operation: D1WriteOperation, statement: D1PreparedStatement, database: D1Database) => D1PreparedStatement;
+    /**
+     * Test-only delay seam for proving G69 evidence never gates core admission.
+     * Production composition leaves this unset.
+     */
+    readonly beforeG69AdmissionAttempt?: () => void | Promise<void>;
+}
+/** A contradictory EventId identity is a typed fail-closed outcome. */
+export declare class D1IdentityConflictError extends CanonicalEventIdentityConflictError {
+    readonly beforeMutation: boolean;
+    constructor(message: string, beforeMutation?: boolean);
+}
+/** V1 SUIDs and path names are opaque bytewise ordinals, never locale/numeric values. */
+export declare function binaryCompare(left: string, right: string): number;
+/**
+ * Cloudflare D1 PipelineStore implementation.
+ *
+ * All schema changes live in migrations/d1. Writes that span several tables
+ * are one predeclared D1 batch; there is no interactive transaction or
+ * TypeScript read/branch between statements in the durable mutation.
+ */
+export declare class D1EventStore implements EventStore, DetectorStore, ProjectionStore, WaitForTargetSourcePort {
+    private readonly database;
+    private readonly options;
+    private initialized;
+    constructor(database: D1Database, options?: D1StoreOptions);
+    initialize(): Promise<void>;
+    recordDelivery(message: DownstreamOutboxMessage, arrivedAt: number, deliverySource?: DeliverySource, attemptContext?: DeliveryAttemptContext): Promise<DeliveryOutcome>;
+    private recordDeliveryCore;
+    readGlobalReceiptJoin(message: DownstreamOutboxMessage): Promise<GlobalReceiptJoin | undefined>;
+    readAllEvents(serviceId: string, since: string): Promise<StoredEvent[]>;
+    /**
+     * G69 strict-order detector: find an event admitted after a projection
+     * checkpoint whose opaque SUID is lower than that checkpoint. A replay of
+     * an event already known before the checkpoint is deliberately excluded by
+     * FirstArrivedAt, so the detector reports new lower-SUID admission rather
+     * than ordinary Queue redelivery.
+     */
+    findLateLowerSuid(serviceId: string, checkpointSuid: string, checkpointUpdatedAt: number): Promise<StoredEvent | undefined>;
+    findLateLowerSuidEvidence(serviceId: string, checkpointSuid: string, checkpointUpdatedAt: number, generation?: number): Promise<{
+        readonly kind: "late-lower-suid" | "replay" | "miss" | "unknown";
+        readonly event?: StoredEvent;
+        readonly reason?: string;
+        readonly durationMs?: number;
+    }>;
+    /**
+     * G31 source proof: one indexed target-SUID lookup distinguishes pending,
+     * unique stored, and contradictory/incident states. It intentionally never
+     * delegates to readAllEvents, which would make waitFor history-size bound.
+     */
+    readWaitForTarget(serviceId: string, suid: string): Promise<WaitForTargetLookup>;
+    currentLagBound(serviceId: string, nowMs?: number): Promise<number>;
+    lagBoundDiagnostics(serviceId: string, nowMs: number): Promise<{
+        serviceIdUsed: string;
+        dynamicLagBoundMs: number;
+        rowFound: boolean;
+        rawEstimateMs: null;
+        rawObservedAt: null;
+        nowMs: number;
+    } | {
+        serviceIdUsed: string;
+        dynamicLagBoundMs: number;
+        rowFound: boolean;
+        rawEstimateMs: number;
+        rawObservedAt: number;
+        nowMs: number;
+    }>;
+    listProjectionTags(serviceId: string): Promise<string[]>;
+    readProjectionCheckpoint(serviceId: string, projectionId: string): Promise<ProjectionCheckpoint | undefined>;
+    advanceProjectionCheckpoint(input: ProjectionCheckpointAdvance): Promise<boolean>;
+    projectionLag(serviceId: string, projectionId: string, tag: string): Promise<ProjectionLag>;
+    upsertPending(message: DownstreamOutboxMessage, firstObservedAt: number, lagBoundMs: number): Promise<PendingArrivalRecord>;
+    listPending(serviceId?: string): Promise<PendingArrivalRecord[]>;
+    appendFinding(finding: InconsistencyFinding): Promise<void>;
+    hasFinding(serviceId: string, eventId: string, path: string, classification: InconsistencyClassification): Promise<boolean>;
+    listFindings(serviceId?: string, eventId?: string): Promise<InconsistencyFinding[]>;
+    appendDeliveryIncident(incident: DeliveryIncident): Promise<void>;
+    hasDeliveryIncident(serviceId: string, identityKey: string): Promise<boolean>;
+    listDeliveryIncidents(serviceId?: string): Promise<DeliveryIncident[]>;
+    private batch;
+    private write;
+    private rows;
+    private eventById;
+    private eventFromRow;
+    private pendingById;
+    private lineageBinding;
+    private collisionEvent;
+    private incidentByIdentity;
+    private eventArrivalOps;
+    private admissionMutationEvidence;
+    private bestEffortG69AdmissionAttempt;
+    private ready;
+}