@sekiban/dcb-runtime 0.2.0

package/dist/mv/MaterializedViewRuntime.js

@@ -0,0 +1,328 @@
+import { safeWindowCeilingExceeded, safeWindowMs } from "../projection/ProjectionRuntime";
+import { isSortableUniqueIdSafeAt } from "../safeWindow";
+import { assertSortableUniqueId } from "../allocator/SortableUniqueId";
+const MAX_CHECKPOINT_CAS_RETRIES = 8;
+/** A failed change operation is never represented as a successful no-op. */
+export class MaterializedViewOperationError extends Error {
+    operation;
+    code;
+    constructor(operation, code, message) {
+        super(message);
+        this.operation = operation;
+        this.code = code;
+        this.name = "MaterializedViewOperationError";
+    }
+}
+function compareSuid(left, right) {
+    const leftBytes = new TextEncoder().encode(left);
+    const rightBytes = new TextEncoder().encode(right);
+    const sharedLength = Math.min(leftBytes.length, rightBytes.length);
+    for (let index = 0; index < sharedLength; index += 1) {
+        const difference = leftBytes[index] - rightBytes[index];
+        if (difference !== 0) {
+            return difference;
+        }
+    }
+    return leftBytes.length - rightBytes.length;
+}
+function nonEmpty(value) {
+    return value.length > 0;
+}
+/** Stable durable namespace for the promoted materialized view. */
+export function materializedViewId(definitionId) {
+    return `mv:${definitionId}`;
+}
+/** Durable namespace for a rebuild candidate that has not yet been promoted. */
+export function materializedViewCandidateId(definitionId, rebuildId) {
+    return `${materializedViewId(definitionId)}:rebuild:${rebuildId}`;
+}
+/**
+ * A materialized view consumes the same read-only global SUID source and
+ * SafeWindow as a live projection. Its state and source position share one
+ * durable checkpoint transaction, so a restart cannot double-apply a source
+ * event that has already changed state.
+ */
+export class MaterializedViewRuntime {
+    store;
+    constructor(store) {
+        this.store = store;
+    }
+    async read(serviceId, definition) {
+        const viewId = this.checkedViewId(definition, "follow");
+        const checkpoint = await this.store.readProjectionCheckpoint(serviceId, viewId);
+        return checkpoint === undefined ? undefined : this.snapshot(serviceId, viewId, checkpoint, definition, "follow");
+    }
+    /** Creates the initial durable state then follows through the SafeWindow. */
+    async build(serviceId, definition, nowMs, hooks = {}) {
+        try {
+            const viewId = this.checkedViewId(definition, "build");
+            await this.ensureInitialCheckpoint(serviceId, viewId, definition, nowMs, "build", true);
+            return await this.followCheckpoint(serviceId, viewId, definition, nowMs, "build", hooks);
+        }
+        catch (error) {
+            throw this.typedFailure("build", error);
+        }
+    }
+    /** Continues the promoted durable view from its own global SUID checkpoint. */
+    async follow(serviceId, definition, nowMs, hooks = {}) {
+        try {
+            const viewId = this.checkedViewId(definition, "follow");
+            await this.ensureInitialCheckpoint(serviceId, viewId, definition, nowMs, "follow", false);
+            return await this.followCheckpoint(serviceId, viewId, definition, nowMs, "follow", hooks);
+        }
+        catch (error) {
+            throw this.typedFailure("follow", error);
+        }
+    }
+    /**
+     * Builds a separate durable candidate from the beginning of the global
+     * source. The caller must explicitly promote it; no rebuild silently swaps
+     * production state.
+     */
+    async rebuild(serviceId, definition, rebuildId, nowMs, hooks = {}) {
+        try {
+            const definitionId = this.checkedDefinitionId(definition, "rebuild");
+            if (!nonEmpty(rebuildId)) {
+                throw this.failure("rebuild", "MV_REBUILD_ID_INVALID", "Materialized-view rebuildId is required");
+            }
+            const candidateId = materializedViewCandidateId(definitionId, rebuildId);
+            await this.ensureInitialCheckpoint(serviceId, candidateId, definition, nowMs, "rebuild", true);
+            return {
+                candidateId,
+                result: await this.followCheckpoint(serviceId, candidateId, definition, nowMs, "rebuild", hooks),
+            };
+        }
+        catch (error) {
+            throw this.typedFailure("rebuild", error);
+        }
+    }
+    /** Resets the promoted view to a durable initial state, never a no-op. */
+    async reset(serviceId, definition, nowMs) {
+        try {
+            const viewId = this.checkedViewId(definition, "reset");
+            const existing = await this.store.readProjectionCheckpoint(serviceId, viewId);
+            if (existing === undefined) {
+                throw this.failure("reset", "MV_RESET_MISSING", "Cannot reset a materialized view that was never built");
+            }
+            const initial = this.checkpointFor(serviceId, viewId, "", this.initialState(definition, "reset"), definition, nowMs, "reset");
+            if (existing.lastSuid === initial.lastSuid
+                && existing.stateJson === initial.stateJson
+                && existing.version === initial.version) {
+                throw this.failure("reset", "MV_RESET_NOTHING_TO_RESET", "Materialized view is already at its durable initial state");
+            }
+            const advanced = await this.store.advanceProjectionCheckpoint({
+                ...initial,
+                expectedLastSuid: existing.lastSuid,
+            });
+            if (!advanced) {
+                throw this.failure("reset", "MV_RESET_CONFLICT", "Materialized-view checkpoint changed before reset could commit");
+            }
+            return this.snapshot(serviceId, viewId, initial, definition, "reset");
+        }
+        catch (error) {
+            throw this.typedFailure("reset", error);
+        }
+    }
+    /** Promotes a previously rebuilt durable candidate with a compare-and-swap. */
+    async promote(serviceId, definition, rebuildId, nowMs) {
+        try {
+            const definitionId = this.checkedDefinitionId(definition, "promote");
+            if (!nonEmpty(rebuildId)) {
+                throw this.failure("promote", "MV_REBUILD_ID_INVALID", "Materialized-view rebuildId is required");
+            }
+            const viewId = materializedViewId(definitionId);
+            const candidateId = materializedViewCandidateId(definitionId, rebuildId);
+            const candidate = await this.store.readProjectionCheckpoint(serviceId, candidateId);
+            if (candidate === undefined) {
+                throw this.failure("promote", "MV_PROMOTE_CANDIDATE_MISSING", "Materialized-view rebuild candidate does not exist");
+            }
+            const candidateSnapshot = this.snapshot(serviceId, candidateId, candidate, definition, "promote");
+            const current = await this.store.readProjectionCheckpoint(serviceId, viewId);
+            if (current !== undefined
+                && current.lastSuid === candidate.lastSuid
+                && current.stateJson === candidate.stateJson
+                && current.version === candidate.version) {
+                throw this.failure("promote", "MV_PROMOTE_NOTHING_TO_PROMOTE", "Materialized-view candidate is already promoted");
+            }
+            const promoted = {
+                ...candidateSnapshot.checkpoint,
+                projectionId: viewId,
+                updatedAt: nowMs,
+            };
+            const advanced = await this.store.advanceProjectionCheckpoint({
+                ...promoted,
+                expectedLastSuid: current?.lastSuid ?? null,
+            });
+            if (!advanced) {
+                throw this.failure("promote", "MV_PROMOTE_CONFLICT", "Materialized-view checkpoint changed before candidate promotion could commit");
+            }
+            return this.snapshot(serviceId, viewId, promoted, definition, "promote");
+        }
+        catch (error) {
+            throw this.typedFailure("promote", error);
+        }
+    }
+    async ensureInitialCheckpoint(serviceId, viewId, definition, nowMs, operation, failIfPresent) {
+        const existing = await this.store.readProjectionCheckpoint(serviceId, viewId);
+        if (existing !== undefined) {
+            if (failIfPresent) {
+                throw this.failure(operation, operation === "build" ? "MV_BUILD_ALREADY_EXISTS" : "MV_REBUILD_CANDIDATE_EXISTS", operation === "build"
+                    ? "Materialized view already has durable state; use follow or rebuild"
+                    : "Materialized-view rebuild candidate already exists");
+            }
+            return existing;
+        }
+        const initial = this.checkpointFor(serviceId, viewId, "", this.initialState(definition, operation), definition, nowMs, operation);
+        const advanced = await this.store.advanceProjectionCheckpoint({
+            ...initial,
+            expectedLastSuid: null,
+        });
+        if (advanced) {
+            return initial;
+        }
+        if (failIfPresent) {
+            throw this.failure(operation, operation === "build" ? "MV_BUILD_CONFLICT" : "MV_REBUILD_CONFLICT", "Materialized-view checkpoint appeared before the requested durable operation could commit");
+        }
+        const raced = await this.store.readProjectionCheckpoint(serviceId, viewId);
+        if (raced === undefined) {
+            throw this.failure("follow", "MV_FOLLOW_CHECKPOINT_UNAVAILABLE", "Materialized-view checkpoint could not be established");
+        }
+        return raced;
+    }
+    async followCheckpoint(serviceId, viewId, definition, nowMs, operation, hooks) {
+        const dynamicLagBoundMs = await this.store.currentLagBound(serviceId, nowMs);
+        const windowMs = safeWindowMs(dynamicLagBoundMs);
+        for (let retry = 0; retry < MAX_CHECKPOINT_CAS_RETRIES; retry += 1) {
+            const checkpoint = await this.store.readProjectionCheckpoint(serviceId, viewId);
+            if (checkpoint === undefined) {
+                throw this.failure("follow", "MV_FOLLOW_CHECKPOINT_UNAVAILABLE", "Materialized-view checkpoint disappeared during follow");
+            }
+            if (safeWindowCeilingExceeded(dynamicLagBoundMs)) {
+                return {
+                    ...this.snapshot(serviceId, viewId, checkpoint, definition, operation),
+                    dynamicLagBoundMs,
+                    safeWindowMs: windowMs,
+                    advancedSourceEvents: 0,
+                    appliedEvents: 0,
+                };
+            }
+            let currentCheckpoint = checkpoint;
+            let state = this.stateFrom(definition, checkpoint, operation);
+            const sourceEvents = await this.store.readAllEvents(serviceId, checkpoint.lastSuid);
+            let validatedPreviousSuid = checkpoint.lastSuid;
+            for (const event of sourceEvents) {
+                assertSortableUniqueId(event.suid);
+                if (compareSuid(validatedPreviousSuid, event.suid) >= 0) {
+                    throw this.failure(operation, "MV_SOURCE_NOT_STRICTLY_SUID_ORDERED", "Materialized-view source was not strictly SUID ordered");
+                }
+                validatedPreviousSuid = event.suid;
+            }
+            let advancedSourceEvents = 0;
+            let appliedEvents = 0;
+            let casConflict = false;
+            for (const event of sourceEvents) {
+                // SafeWindow is deliberately read-only: stopping at the first unsafe
+                // SUID preserves convergence when a lower SUID is delivered late.
+                if (!isSortableUniqueIdSafeAt(event.suid, nowMs, dynamicLagBoundMs)) {
+                    return {
+                        ...this.snapshot(serviceId, viewId, currentCheckpoint, definition, operation),
+                        dynamicLagBoundMs,
+                        safeWindowMs: windowMs,
+                        advancedSourceEvents,
+                        appliedEvents,
+                    };
+                }
+                const nextState = this.apply(definition, state, event, operation);
+                const nextCheckpoint = this.checkpointFor(serviceId, viewId, event.suid, nextState, definition, nowMs, operation);
+                await hooks.beforeCheckpoint?.(event, nextCheckpoint);
+                const advanced = await this.store.advanceProjectionCheckpoint({
+                    ...nextCheckpoint,
+                    expectedLastSuid: currentCheckpoint.lastSuid,
+                });
+                if (!advanced) {
+                    casConflict = true;
+                    break;
+                }
+                currentCheckpoint = nextCheckpoint;
+                state = nextState;
+                advancedSourceEvents += 1;
+                appliedEvents += 1;
+                await hooks.afterCheckpoint?.(event, nextCheckpoint);
+            }
+            if (!casConflict) {
+                return {
+                    ...this.snapshot(serviceId, viewId, currentCheckpoint, definition, operation),
+                    dynamicLagBoundMs,
+                    safeWindowMs: windowMs,
+                    advancedSourceEvents,
+                    appliedEvents,
+                };
+            }
+        }
+        throw this.failure(operation, "MV_CHECKPOINT_CONFLICT", "Materialized-view checkpoint did not converge after concurrent updates");
+    }
+    checkedViewId(definition, operation) {
+        return materializedViewId(this.checkedDefinitionId(definition, operation));
+    }
+    checkedDefinitionId(definition, operation) {
+        if (!nonEmpty(definition.id)) {
+            throw this.failure(operation, "MV_DEFINITION_INVALID", "Materialized-view definition id is required");
+        }
+        return definition.id;
+    }
+    stateFrom(definition, checkpoint, operation) {
+        try {
+            return definition.deserializeState(checkpoint.stateJson);
+        }
+        catch (error) {
+            throw this.failure(operation, "MV_STATE_INVALID", `Materialized-view durable state was invalid: ${String(error)}`);
+        }
+    }
+    initialState(definition, operation) {
+        try {
+            return definition.initialState();
+        }
+        catch (error) {
+            throw this.failure(operation, "MV_STATE_INVALID", `Materialized-view initial state was invalid: ${String(error)}`);
+        }
+    }
+    apply(definition, state, event, operation) {
+        try {
+            return definition.apply(state, event);
+        }
+        catch (error) {
+            throw this.failure(operation, "MV_STATE_INVALID", `Materialized-view reducer failed: ${String(error)}`);
+        }
+    }
+    checkpointFor(serviceId, viewId, lastSuid, state, definition, nowMs, operation) {
+        try {
+            return {
+                serviceId,
+                projectionId: viewId,
+                lastSuid,
+                stateJson: definition.serializeState(state),
+                version: definition.version(state),
+                updatedAt: nowMs,
+            };
+        }
+        catch (error) {
+            throw this.failure(operation, "MV_STATE_INVALID", `Materialized-view state could not be persisted: ${String(error)}`);
+        }
+    }
+    snapshot(serviceId, viewId, checkpoint, definition, operation) {
+        return {
+            serviceId,
+            viewId,
+            checkpoint,
+            state: this.stateFrom(definition, checkpoint, operation),
+        };
+    }
+    failure(operation, code, message) {
+        return new MaterializedViewOperationError(operation, code, message);
+    }
+    typedFailure(operation, error) {
+        return error instanceof MaterializedViewOperationError
+            ? error
+            : this.failure(operation, "MV_OPERATION_FAILED", `Materialized-view ${operation} failed: ${String(error)}`);
+    }
+}

package/dist/mv/MaterializedViewStore.d.ts

@@ -0,0 +1,257 @@
+import { type JsonValue, type MaterializedViewIndexValueType, type MaterializedViewMutationPlan } from "@sekiban/dcb-core";
+import { UnsafeWindowMaterializedViewStore, type UnsafeComposedPage } from "./UnsafeWindowMaterializedView";
+export type MaterializedViewStoreOperation = "initialize" | "create-active" | "create-candidate" | "apply" | "promote";
+export type MaterializedViewStoreErrorCode = "MV_STORE_NOT_INITIALIZED" | "MV_INSTANCE_EXISTS" | "MV_INSTANCE_MISSING" | "MV_CAS_MISMATCH" | "MV_PROMOTION_CAS_MISMATCH" | "MV_GENERATION_INVALID" | "MV_PATCH_ROW_MISSING" | "MV_VALUE_INVALID" | "MV_ORDERING_QUARANTINED" | "MV_REBUILD_NOT_VERIFIED" | "MV_STORE_OPERATION_FAILED";
+export declare class MaterializedViewStoreError extends Error {
+    readonly operation: MaterializedViewStoreOperation;
+    readonly code: MaterializedViewStoreErrorCode;
+    constructor(operation: MaterializedViewStoreOperation, code: MaterializedViewStoreErrorCode, message: string, options?: ErrorOptions);
+}
+/** A stale MV checkpoint is a failed atomic call, never a successful no-op. */
+export declare class MaterializedViewCasError extends MaterializedViewStoreError {
+    constructor(message?: string);
+}
+export declare class MaterializedViewPromotionCasError extends MaterializedViewStoreError {
+    constructor(message?: string);
+}
+export declare class MaterializedViewPatchError extends MaterializedViewStoreError {
+    constructor(message?: string);
+}
+export interface MaterializedViewInstance {
+    readonly serviceId: string;
+    readonly viewId: string;
+    readonly generation: number;
+    readonly status: "active" | "candidate" | "retired";
+    readonly lastSuid: string;
+    readonly definitionVersion: number;
+    readonly updatedAt: number;
+    /** Non-null only after a complete, explicit rebuild proof for this generation. */
+    readonly rebuildVerifiedAt: number | null;
+    readonly rebuildRecoveryId: string | null;
+    readonly rebuildIncidentIdentity: string | null;
+    readonly rebuildIncidentGeneration: number | null;
+    readonly rebuildSourceEventCount: number | null;
+    readonly rebuildSourceMaxSuid: string | null;
+    readonly rebuildSourceHistoryDigest: string | null;
+}
+export interface MaterializedViewRow {
+    readonly serviceId: string;
+    readonly viewId: string;
+    readonly generation: number;
+    readonly rowKey: string;
+    readonly value: JsonValue;
+    readonly rowVersion: number;
+    readonly sourceSuid: string;
+}
+export interface MaterializedViewIndexEntry {
+    readonly serviceId: string;
+    readonly viewId: string;
+    readonly generation: number;
+    readonly indexId: string;
+    readonly valueType: MaterializedViewIndexValueType;
+    readonly value: string | number;
+    readonly rowKey: string;
+}
+export interface MaterializedViewCreateInput {
+    readonly serviceId: string;
+    readonly viewId: string;
+    readonly generation?: number;
+    readonly definitionVersion: number;
+    readonly updatedAt: number;
+    readonly lastSuid?: string;
+}
+export interface MaterializedViewCandidateInput extends MaterializedViewCreateInput {
+    readonly generation: number;
+}
+export interface MaterializedViewApplyInput {
+    readonly serviceId: string;
+    readonly viewId: string;
+    readonly generation: number;
+    readonly expectedLastSuid: string | null;
+    readonly lastSuid: string;
+    readonly definitionVersion: number;
+    readonly updatedAt: number;
+    readonly mutations: MaterializedViewMutationPlan;
+}
+export interface MaterializedViewApplyResult {
+    readonly instance: MaterializedViewInstance;
+    readonly rowUpserts: number;
+    readonly rowDeletes: number;
+    readonly rowPatches: number;
+    readonly indexEntries: number;
+}
+export interface MaterializedViewPromoteInput {
+    readonly serviceId: string;
+    readonly viewId: string;
+    readonly candidateGeneration: number;
+    readonly expectedActiveGeneration: number | null;
+    readonly updatedAt: number;
+}
+export interface MaterializedViewQueryOptions {
+    readonly generation?: number;
+    readonly indexId?: string;
+    readonly valueType?: MaterializedViewIndexValueType;
+    /** `null` means unbounded; omitted retains the port's 100-row default. */
+    readonly limit?: number | null;
+    readonly offset?: number;
+    /** Fixed boolean order selector; request data never becomes a SQL fragment. */
+    readonly descending?: boolean;
+}
+/** The list surface must choose whether it can see the exceptional unsafe lane. */
+export type MaterializedViewListConsistency = "safe" | "unsafe";
+export interface MaterializedViewListOptions extends MaterializedViewQueryOptions {
+    /** Omitted is deliberately safe; unsafe visibility is never an accidental fallback. */
+    readonly consistency?: MaterializedViewListConsistency;
+}
+/** A server-paged list response and the watermark that actually backs that response. */
+export interface MaterializedViewListPage {
+    readonly rows: readonly MaterializedViewRow[];
+    readonly totalCount: number;
+    readonly readHead: string;
+}
+/**
+ * One active-generation snapshot used by the SDT-G31 d1-mv waitFor path.
+ * `targetReceipt` is deliberately separate from `safeContiguousHead`: the
+ * latter can only complete a wait after the source target has been proved
+ * unique by the paired PipelineStore point lookup.
+ */
+export interface MaterializedViewWaitForState {
+    readonly activeGeneration: number | undefined;
+    readonly activeDefinitionVersion: number | undefined;
+    readonly safeContiguousHead: string;
+    readonly targetReceipt: boolean;
+    readonly checkpointAhead: boolean;
+    readonly rebuildRequired: boolean;
+    readonly poison: boolean;
+}
+export type MaterializedViewOrderingQuarantineClassification = "LATE_LOWER_SUID" | "ORDER_VIOLATION";
+export interface MaterializedViewOrderingQuarantine {
+    readonly serviceId: string;
+    readonly viewId: string;
+    readonly generation: number;
+    readonly checkpointSuid: string;
+    readonly lateSuid: string;
+    readonly eventId: string;
+    readonly classification: MaterializedViewOrderingQuarantineClassification;
+    readonly status: "open" | "resolved";
+    readonly observedAt: number;
+    readonly resolvedAt: number | null;
+    readonly incidentIdentity: string | null;
+}
+/**
+ * Production D1 persistence for row-backed materialized views.  Every apply
+ * call is a single predeclared D1 batch.  The NOT NULL guard statement is
+ * deliberately first: if the expected checkpoint is stale it aborts the
+ * batch, so row/index/checkpoint regions cannot partially advance.
+ */
+export declare class D1MaterializedViewStore {
+    private readonly database;
+    private initialized;
+    private readonly unsafe;
+    constructor(database: D1Database);
+    initialize(): Promise<void>;
+    createActive(input: MaterializedViewCreateInput): Promise<MaterializedViewInstance>;
+    createCandidate(input: MaterializedViewCandidateInput): Promise<MaterializedViewInstance>;
+    beginRebuild(input: Omit<MaterializedViewCandidateInput, "generation"> & {
+        readonly generation?: number;
+    }): Promise<MaterializedViewInstance>;
+    nextGeneration(serviceId: string, viewId: string): Promise<number>;
+    readInstance(serviceId: string, viewId: string, generation: number): Promise<MaterializedViewInstance | undefined>;
+    readActive(serviceId: string, viewId: string): Promise<MaterializedViewInstance | undefined>;
+    readRows(serviceId: string, viewId: string, generation?: number): Promise<MaterializedViewRow[]>;
+    readIndexEntries(serviceId: string, viewId: string, generation?: number): Promise<MaterializedViewIndexEntry[]>;
+    /** Read rows through a declared index without exposing SQL identifiers to callers. */
+    queryRows(serviceId: string, viewId: string, options?: MaterializedViewQueryOptions): Promise<MaterializedViewRow[]>;
+    /** SDT-G23 composed server page; count and page rows share one statement. */
+    queryRowsWithTotal(serviceId: string, viewId: string, options?: MaterializedViewQueryOptions): Promise<UnsafeComposedPage>;
+    /**
+     * SDT-G55's explicit list-read port.  Existing composed reads intentionally
+     * keep their G23 semantics; only this port can include unsafe rows, and it
+     * can include only rows newer than the active safe checkpoint.
+     */
+    readListPage(serviceId: string, viewId: string, options?: MaterializedViewListOptions): Promise<MaterializedViewListPage>;
+    /** Explicit unsafe port: callers must choose this exceptional immediate lane. */
+    unsafeWindow(): UnsafeWindowMaterializedViewStore;
+    /** Runs repairable unsafe GC after an idle or advancing safe catch-up pass. */
+    collectUnsafeGarbage(serviceId: string, viewId: string, generation: number, definitionVersion: number, safeHead: string): Promise<number>;
+    hasTargetReceipt(serviceId: string, viewId: string, eventId: string, suid: string): Promise<boolean>;
+    /**
+     * Read all G31 wait facts in one static D1 statement. Every table access is
+     * keyed by service/view/active generation (and target identity where
+     * applicable); no row or source-history scan is permitted on this path.
+     */
+    readWaitForState(serviceId: string, viewId: string, target: {
+        readonly eventId?: string;
+        readonly suid: string;
+    }): Promise<MaterializedViewWaitForState>;
+    /** Idempotent operational fact: a stored Queue event needs unsafe retry/DLQ attention. */
+    recordUnsafeFailureFinding(input: {
+        readonly serviceId: string;
+        readonly viewId: string;
+        /** The failed view generation when known; omitted binds the active one. */
+        readonly generation?: number;
+        readonly eventId: string;
+        readonly suid: string;
+        readonly observedAt: number;
+    }): Promise<void>;
+    /**
+     * Persist the source-reset observation exactly once for the affected
+     * generation.  This deliberately never rewinds `mv_instances.last_suid`.
+     */
+    recordCheckpointAhead(input: {
+        readonly serviceId: string;
+        readonly viewId: string;
+        readonly generation: number;
+        readonly checkpointSuid: string;
+        readonly storeMaxSuid: string;
+        readonly observedAt: number;
+    }): Promise<void>;
+    /** An open finding on the active generation fail-closes composed MV reads. */
+    hasCheckpointAheadFinding(serviceId: string, viewId: string): Promise<boolean>;
+    /** Open quarantine is keyed to the active generation; old generations are not a public read gate. */
+    readOrderingQuarantine(serviceId: string, viewId: string): Promise<MaterializedViewOrderingQuarantine | undefined>;
+    readActiveGeneration(serviceId: string, viewId: string): Promise<number | undefined>;
+    /** Persist the detector result before stopping the safe pass. Repeated observations are idempotent. */
+    recordOrderingQuarantine(input: {
+        readonly serviceId: string;
+        readonly viewId: string;
+        readonly generation: number;
+        readonly checkpointSuid: string;
+        readonly lateSuid: string;
+        readonly eventId: string;
+        readonly classification: MaterializedViewOrderingQuarantineClassification;
+        readonly observedAt: number;
+    }): Promise<void>;
+    /**
+     * Mark a candidate only after the real rebuild path observed the complete
+     * source history. The proof is incident-bound when an ordering quarantine is
+     * open, and an empty row set is valid when the source history itself is
+     * complete (for example, a rebuild whose materializer deletes every row).
+     */
+    markGenerationRebuilt(input: {
+        readonly serviceId: string;
+        readonly viewId: string;
+        readonly generation: number;
+        readonly verifiedAt: number;
+        readonly rebuildId: string;
+        readonly sourceEventCount: number;
+        readonly sourceEventIds: readonly string[];
+        readonly sourceSuids: readonly string[];
+        readonly sourceMaxSuid: string;
+        readonly sourceHistoryDigest: string;
+    }): Promise<void>;
+    /**
+     * Apply rows/index entries and advance one generation checkpoint atomically.
+     * The guard row intentionally uses a NOT NULL failure to abort a stale CAS.
+     */
+    applyMutationsAndAdvanceCheckpoint(input: MaterializedViewApplyInput): Promise<MaterializedViewApplyResult>;
+    promoteGeneration(input: MaterializedViewPromoteInput): Promise<MaterializedViewInstance>;
+    /** Short aliases make the port convenient for runtime composition and tests. */
+    readonly apply: (input: MaterializedViewApplyInput) => Promise<MaterializedViewApplyResult>;
+    readonly promote: (input: MaterializedViewPromoteInput) => Promise<MaterializedViewInstance>;
+    private rowFrom;
+    private indexFrom;
+    private validateGeneration;
+    private ready;
+}
+export type MaterializedViewStore = Pick<D1MaterializedViewStore, "initialize" | "createActive" | "createCandidate" | "beginRebuild" | "nextGeneration" | "readInstance" | "readActive" | "readRows" | "readIndexEntries" | "queryRows" | "queryRowsWithTotal" | "readListPage" | "hasTargetReceipt" | "readOrderingQuarantine" | "recordOrderingQuarantine" | "markGenerationRebuilt" | "readWaitForState" | "recordCheckpointAhead" | "hasCheckpointAheadFinding" | "applyMutationsAndAdvanceCheckpoint" | "promoteGeneration">;