@sekiban/dcb-runtime 0.2.0

package/dist/journal/types.js

@@ -0,0 +1,52 @@
+export const JOURNAL_STATES = [
+    "ADMITTED",
+    "RESERVED",
+    "ALLOCATED",
+    "WRITING",
+    "SEALING",
+    "COMPLETE",
+    "REFUSED",
+    "FAILED",
+    "PARTIAL",
+    "ABANDONED",
+];
+export const TERMINAL_JOURNAL_STATES = new Set([
+    "COMPLETE",
+    "REFUSED",
+    "FAILED",
+    "PARTIAL",
+    "ABANDONED",
+]);
+/**
+ * Persisted fault points used by the commit-worker recovery tests. They are
+ * consumed one at a time, so an at-least-once alarm can resume safely.
+ */
+export const ALARM_FAULT_POINTS = [
+    "handler-entry",
+    "after-rearm-before-seal",
+    "after-partial-seal",
+    "after-full-seal-before-requery",
+    "after-fence-before-cancel",
+    "before-outcome-cas",
+];
+export function isTerminalState(state) {
+    return TERMINAL_JOURNAL_STATES.has(state);
+}
+export function isJournalState(value) {
+    return typeof value === "string" && JOURNAL_STATES.includes(value);
+}
+export function isAllowedTransition(from, to) {
+    const allowed = {
+        ADMITTED: ["RESERVED", "ALLOCATED", "SEALING", "ABANDONED"],
+        RESERVED: ["ALLOCATED", "SEALING", "REFUSED", "FAILED", "ABANDONED"],
+        ALLOCATED: ["WRITING", "SEALING", "COMPLETE"],
+        WRITING: ["SEALING", "COMPLETE"],
+        SEALING: ["COMPLETE", "REFUSED", "FAILED", "PARTIAL"],
+        COMPLETE: [],
+        REFUSED: [],
+        FAILED: [],
+        PARTIAL: [],
+        ABANDONED: [],
+    };
+    return allowed[from].includes(to);
+}

package/dist/mv/MaterializedViewCatchUp.d.ts

@@ -0,0 +1,60 @@
+import type { MaterializedViewRowMaterializer } from "@sekiban/dcb-core";
+import type { ProjectionStore, StoredEvent } from "../store/types";
+import { type MaterializedViewApplyResult, type MaterializedViewInstance } from "./MaterializedViewStore";
+import type { D1MaterializedViewStore } from "./MaterializedViewStore";
+export interface MaterializedViewCatchUpResult {
+    readonly instance: MaterializedViewInstance;
+    readonly dynamicLagBoundMs: number;
+    readonly safeWindowMs: number;
+    readonly advancedSourceEvents: number;
+    readonly appliedEvents: number;
+    /** Bounded late-lower detector query cost for this catch-up pass. */
+    readonly lateLowerQueryDurationMs: number;
+    readonly indeterminate: boolean;
+    /** The first source event withheld by the current safe-lane boundary. */
+    readonly deferredEventSuid: string | null;
+    readonly deferredEventLastArrivedAt: number | null;
+    readonly deferredDeadlineAt: number | null;
+    readonly stopReason: "safe_window_fence" | "safe_window_ceiling" | "frontier_fence" | null;
+}
+export interface MaterializedViewCatchUpHooks {
+    /** Test-only crash boundary; never part of production persistence. */
+    readonly beforeApply?: (event: StoredEvent) => Promise<void> | void;
+    /** Test-only crash boundary after the atomic MV call. */
+    readonly afterApply?: (event: StoredEvent, result: MaterializedViewApplyResult) => Promise<void> | void;
+}
+/**
+ * An optional scanner-proven high-water mark for a safe-lane pass. `null`
+ * means that no FULL snapshot exists yet, so this pass may perform GC but
+ * cannot advance a source checkpoint. `undefined` retains the existing
+ * ungated caller behaviour.
+ */
+export interface MaterializedViewCatchUpOptions {
+    readonly maximumSuid?: string | null;
+    /** Run the bounded late-lower detector only from scheduled maintenance. */
+    readonly runOrderingDetector?: boolean;
+}
+/**
+ * SafeWindow-aware row materializer runtime.  It keeps the memory projection
+ * runtime untouched while allowing the same event source to feed a separate
+ * D1 MV database.
+ */
+export declare class MaterializedViewCatchUpRuntime {
+    private readonly source;
+    private readonly materializedViews;
+    constructor(source: ProjectionStore, materializedViews: D1MaterializedViewStore);
+    build<TEvent = StoredEvent>(serviceId: string, materializer: MaterializedViewRowMaterializer<TEvent>, nowMs: number, hooks?: MaterializedViewCatchUpHooks, options?: MaterializedViewCatchUpOptions): Promise<MaterializedViewCatchUpResult>;
+    follow<TEvent = StoredEvent>(serviceId: string, materializer: MaterializedViewRowMaterializer<TEvent>, nowMs: number, hooks?: MaterializedViewCatchUpHooks, options?: MaterializedViewCatchUpOptions): Promise<MaterializedViewCatchUpResult>;
+    rebuild<TEvent = StoredEvent>(serviceId: string, materializer: MaterializedViewRowMaterializer<TEvent>, nowMs: number, rebuildId?: string, hooks?: MaterializedViewCatchUpHooks, options?: MaterializedViewCatchUpOptions): Promise<MaterializedViewCatchUpResult & {
+        readonly candidateGeneration: number;
+        readonly rebuildId?: string;
+    }>;
+    promote(serviceId: string, materializer: MaterializedViewRowMaterializer, candidateGeneration: number, nowMs: number): Promise<MaterializedViewInstance>;
+    read(serviceId: string, materializer: MaterializedViewRowMaterializer): Promise<{
+        readonly instance: MaterializedViewInstance;
+        readonly rows: Awaited<ReturnType<D1MaterializedViewStore["readRows"]>>;
+    } | undefined>;
+    private followGeneration;
+    private detectLateLowerSuid;
+    private assertSourceBatchOrder;
+}

package/dist/mv/MaterializedViewCatchUp.js

@@ -0,0 +1,353 @@
+import { safeWindowCeilingExceeded, safeWindowMs } from "../projection/ProjectionRuntime";
+import { assertSortableUniqueId } from "../allocator/SortableUniqueId";
+import { MaterializedViewCasError, MaterializedViewStoreError, } from "./MaterializedViewStore";
+const MAX_CAS_RETRIES = 8;
+/**
+ * SafeWindow-aware row materializer runtime.  It keeps the memory projection
+ * runtime untouched while allowing the same event source to feed a separate
+ * D1 MV database.
+ */
+export class MaterializedViewCatchUpRuntime {
+    source;
+    materializedViews;
+    constructor(source, materializedViews) {
+        this.source = source;
+        this.materializedViews = materializedViews;
+    }
+    async build(serviceId, materializer, nowMs, hooks = {}, options = {}) {
+        const existing = await this.materializedViews.readActive(serviceId, materializer.id);
+        if (existing !== undefined) {
+            throw new MaterializedViewStoreError("create-active", "MV_INSTANCE_EXISTS", "Active materialized view already exists");
+        }
+        await this.materializedViews.createActive({
+            serviceId,
+            viewId: materializer.id,
+            generation: 0,
+            definitionVersion: materializer.version,
+            updatedAt: nowMs,
+        });
+        return this.follow(serviceId, materializer, nowMs, hooks, options);
+    }
+    async follow(serviceId, materializer, nowMs, hooks = {}, options = {}) {
+        const active = await this.materializedViews.readActive(serviceId, materializer.id);
+        if (active === undefined) {
+            throw new MaterializedViewStoreError("apply", "MV_INSTANCE_MISSING", "Materialized-view must be built before follow");
+        }
+        return this.followGeneration(serviceId, materializer, active.generation, nowMs, "apply", hooks, options);
+    }
+    async rebuild(serviceId, materializer, nowMs, rebuildId, hooks = {}, options = {}) {
+        const effectiveRebuildId = rebuildId ?? `g69-rebuild-${crypto.randomUUID()}`;
+        const sourceBefore = await this.source.readAllEvents(serviceId, "");
+        const sourceBeforeProof = await sourceHistoryProof(sourceBefore);
+        const candidate = await this.materializedViews.beginRebuild({
+            serviceId,
+            viewId: materializer.id,
+            definitionVersion: materializer.version,
+            updatedAt: nowMs,
+        });
+        const result = await this.followGeneration(serviceId, materializer, candidate.generation, nowMs, "apply", hooks, options);
+        const sourceAfter = await this.source.readAllEvents(serviceId, "");
+        const sourceAfterProof = await sourceHistoryProof(sourceAfter);
+        if (result.stopReason === null &&
+            !result.indeterminate &&
+            result.advancedSourceEvents === sourceBefore.length &&
+            sourceBeforeProof.digest === sourceAfterProof.digest) {
+            await this.materializedViews.markGenerationRebuilt({
+                serviceId,
+                viewId: materializer.id,
+                generation: candidate.generation,
+                verifiedAt: nowMs,
+                rebuildId: effectiveRebuildId,
+                sourceEventCount: sourceBeforeProof.eventIds.length,
+                sourceEventIds: sourceBeforeProof.eventIds,
+                sourceSuids: sourceBeforeProof.suids,
+                sourceMaxSuid: sourceBeforeProof.maxSuid,
+                sourceHistoryDigest: sourceBeforeProof.digest,
+            });
+        }
+        return { ...result, candidateGeneration: candidate.generation, rebuildId: effectiveRebuildId };
+    }
+    async promote(serviceId, materializer, candidateGeneration, nowMs) {
+        const active = await this.materializedViews.readActive(serviceId, materializer.id);
+        return this.materializedViews.promoteGeneration({
+            serviceId,
+            viewId: materializer.id,
+            candidateGeneration,
+            expectedActiveGeneration: active?.generation ?? null,
+            updatedAt: nowMs,
+        });
+    }
+    async read(serviceId, materializer) {
+        const instance = await this.materializedViews.readActive(serviceId, materializer.id);
+        if (instance === undefined)
+            return undefined;
+        return { instance, rows: await this.materializedViews.readRows(serviceId, materializer.id, instance.generation) };
+    }
+    async followGeneration(serviceId, materializer, generation, nowMs, _operation, hooks, options) {
+        for (let attempt = 0; attempt < MAX_CAS_RETRIES; attempt += 1) {
+            const instance = await this.materializedViews.readInstance(serviceId, materializer.id, generation);
+            if (instance === undefined) {
+                throw new MaterializedViewStoreError("apply", "MV_INSTANCE_MISSING", "Materialized-view generation is missing");
+            }
+            // `readAllEvents(serviceId, checkpoint)` is empty both for a caught-up
+            // source and for a reset source that is now behind the checkpoint. Read
+            // the source head separately so the latter can never freeze silently.
+            const sourceForHead = await this.source.readAllEvents(serviceId, "");
+            for (const event of sourceForHead)
+                assertSortableUniqueId(event.suid);
+            const storeMaxSuid = sourceForHead.reduce((maximum, event) => compareSuid(maximum, event.suid) >= 0 ? maximum : event.suid, "");
+            if (instance.lastSuid.length > 0 && compareSuid(storeMaxSuid, instance.lastSuid) < 0) {
+                await this.materializedViews.recordCheckpointAhead({
+                    serviceId,
+                    viewId: materializer.id,
+                    generation,
+                    checkpointSuid: instance.lastSuid,
+                    storeMaxSuid,
+                    observedAt: nowMs,
+                });
+                throw new MaterializedViewStoreError("apply", "MV_STORE_OPERATION_FAILED", "CHECKPOINT_AHEAD: materialized-view checkpoint is ahead of the source store; rebuild and promote a generation");
+            }
+            const dynamicLagBoundMs = await this.source.currentLagBound(serviceId, nowMs);
+            const windowMs = safeWindowMs(dynamicLagBoundMs);
+            if (safeWindowCeilingExceeded(dynamicLagBoundMs)) {
+                return {
+                    instance,
+                    dynamicLagBoundMs,
+                    safeWindowMs: windowMs,
+                    advancedSourceEvents: 0,
+                    appliedEvents: 0,
+                    lateLowerQueryDurationMs: 0,
+                    indeterminate: true,
+                    deferredEventSuid: null,
+                    deferredEventLastArrivedAt: null,
+                    deferredDeadlineAt: null,
+                    stopReason: "safe_window_ceiling",
+                };
+            }
+            const sourceEvents = await this.source.readAllEvents(serviceId, instance.lastSuid);
+            await this.assertSourceBatchOrder(serviceId, materializer.id, generation, instance.lastSuid, sourceEvents);
+            let lateLowerQueryDurationMs = 0;
+            if (options.runOrderingDetector === true) {
+                lateLowerQueryDurationMs = await this.detectLateLowerSuid(serviceId, materializer.id, generation, instance.lastSuid, instance.updatedAt);
+            }
+            let current = instance;
+            let advancedSourceEvents = 0;
+            let appliedEvents = 0;
+            let conflicted = false;
+            for (const event of sourceEvents) {
+                // A G44 BLOCK tick may drain only through the last FULL snapshot's
+                // high-water mark.  Do not skip an earlier row or treat a later one
+                // as a new safe frontier; either would violate the source ordering
+                // proof that protects the materialized safe lane.
+                if (options.maximumSuid === null || (options.maximumSuid !== undefined && compareSuid(event.suid, options.maximumSuid) > 0)) {
+                    return {
+                        instance: current,
+                        dynamicLagBoundMs,
+                        safeWindowMs: windowMs,
+                        advancedSourceEvents,
+                        appliedEvents,
+                        lateLowerQueryDurationMs,
+                        indeterminate: false,
+                        deferredEventSuid: event.suid,
+                        deferredEventLastArrivedAt: event.lastArrivedAt,
+                        deferredDeadlineAt: null,
+                        stopReason: "frontier_fence",
+                    };
+                }
+                // Read-only SafeWindow rule: do not skip the first unsafe event or
+                // process later events ahead of a late lower SUID.
+                if (event.lastArrivedAt > nowMs - windowMs) {
+                    return {
+                        instance: current,
+                        dynamicLagBoundMs,
+                        safeWindowMs: windowMs,
+                        advancedSourceEvents,
+                        appliedEvents,
+                        lateLowerQueryDurationMs,
+                        indeterminate: false,
+                        deferredEventSuid: event.suid,
+                        deferredEventLastArrivedAt: event.lastArrivedAt,
+                        deferredDeadlineAt: event.lastArrivedAt + windowMs,
+                        stopReason: "safe_window_fence",
+                    };
+                }
+                await hooks.beforeApply?.(event);
+                const mutations = materializer.plan(event);
+                let result;
+                try {
+                    result = await this.materializedViews.applyMutationsAndAdvanceCheckpoint({
+                        serviceId,
+                        viewId: materializer.id,
+                        generation,
+                        // The durable schema represents an unadvanced checkpoint as an
+                        // empty string, while the atomic apply port reserves `null` for
+                        // that state so all non-null ingress values are full G32 SUIDs.
+                        expectedLastSuid: current.lastSuid.length === 0 ? null : current.lastSuid,
+                        lastSuid: event.suid,
+                        definitionVersion: materializer.version,
+                        updatedAt: nowMs,
+                        mutations,
+                    });
+                }
+                catch (error) {
+                    if (error instanceof MaterializedViewCasError) {
+                        conflicted = true;
+                        break;
+                    }
+                    throw error;
+                }
+                current = result.instance;
+                advancedSourceEvents += 1;
+                appliedEvents += 1;
+                // A safe checkpoint alone cannot retire unsafe marker state.  The
+                // exact matching receipt is observed in its own guarded transaction.
+                const unsafe = this.materializedViews.unsafeWindow();
+                if (await unsafe.hasTargetReceipt(serviceId, materializer.id, event.eventId, event.suid)) {
+                    await unsafe.observeSafeReceipt(serviceId, materializer.id, generation, event.eventId, event.suid);
+                }
+                await hooks.afterApply?.(event, result);
+            }
+            if (!conflicted) {
+                // This runs even when sourceEvents is empty: a previous unsafe write
+                // may only become collectable after the safe checkpoint is observed.
+                await this.materializedViews.collectUnsafeGarbage(serviceId, materializer.id, generation, materializer.version, current.lastSuid);
+                return {
+                    instance: current,
+                    dynamicLagBoundMs,
+                    safeWindowMs: windowMs,
+                    advancedSourceEvents,
+                    appliedEvents,
+                    lateLowerQueryDurationMs,
+                    indeterminate: false,
+                    deferredEventSuid: null,
+                    deferredEventLastArrivedAt: null,
+                    deferredDeadlineAt: null,
+                    stopReason: null,
+                };
+            }
+        }
+        throw new MaterializedViewStoreError("apply", "MV_CAS_MISMATCH", "Materialized-view catch-up did not converge after concurrent updates");
+    }
+    async detectLateLowerSuid(serviceId, viewId, generation, priorSuid, checkpointUpdatedAt) {
+        let lateLowerQueryDurationMs = 0;
+        if (priorSuid.length > 0) {
+            const detectorStartedAt = Date.now();
+            const evidence = this.source.findLateLowerSuidEvidence === undefined
+                ? undefined
+                : await this.source.findLateLowerSuidEvidence(serviceId, priorSuid, checkpointUpdatedAt, generation);
+            const lateLower = evidence === undefined
+                ? await this.source.findLateLowerSuid?.(serviceId, priorSuid, checkpointUpdatedAt)
+                : evidence.kind === "late-lower-suid" ? evidence.event : undefined;
+            lateLowerQueryDurationMs = evidence?.durationMs ?? Math.max(0, Date.now() - detectorStartedAt);
+            if (evidence?.kind === "unknown") {
+                const incident = {
+                    serviceId,
+                    identityKey: `ORDERING_DETECTOR_UNKNOWN|${serviceId}|${viewId}|${generation}|${priorSuid}|${checkpointUpdatedAt}`,
+                    classification: "ORDERING_DETECTOR_UNKNOWN",
+                    suid: priorSuid,
+                    observedAt: checkpointUpdatedAt,
+                };
+                // The detector has not proved a bounded refusal condition. Persist an
+                // alarm-only incident and continue the existing safe-lane path; an
+                // unknown clock/provenance observation must never be promoted to a
+                // fabricated ordering violation or a guessed quarantine.
+                await this.source.appendDeliveryIncident(incident);
+                console.error("SDT-G69_ORDERING_DETECTOR_UNKNOWN", JSON.stringify({
+                    ...incident,
+                    reason: evidence.reason ?? "unknown",
+                }));
+            }
+            if (lateLower !== undefined) {
+                const incident = {
+                    serviceId,
+                    identityKey: `LATE_LOWER_SUID|${serviceId}|${viewId}|${priorSuid}|${lateLower.suid}|${lateLower.eventId}`,
+                    classification: "ORDER_VIOLATION",
+                    suid: lateLower.suid,
+                    eventId: lateLower.eventId,
+                    incomingEventId: lateLower.eventId,
+                    observedAt: lateLower.lastArrivedAt,
+                };
+                await this.source.appendDeliveryIncident(incident);
+                await this.materializedViews.recordOrderingQuarantine({
+                    serviceId,
+                    viewId,
+                    generation,
+                    checkpointSuid: priorSuid,
+                    lateSuid: lateLower.suid,
+                    eventId: lateLower.eventId,
+                    classification: "LATE_LOWER_SUID",
+                    observedAt: lateLower.lastArrivedAt,
+                });
+                console.error("SDT-G69_ORDERING_QUARANTINE", JSON.stringify({
+                    serviceId,
+                    viewId,
+                    generation,
+                    checkpointSuid: priorSuid,
+                    lateSuid: lateLower.suid,
+                    eventId: lateLower.eventId,
+                    classification: "LATE_LOWER_SUID",
+                }));
+                throw new MaterializedViewStoreError("apply", "MV_ORDERING_QUARANTINED", "Materialized-view safe lane is quarantined for an ordering violation; rebuild and promote a generation");
+            }
+        }
+        return lateLowerQueryDurationMs;
+    }
+    async assertSourceBatchOrder(serviceId, viewId, generation, priorSuid, events) {
+        let previous = priorSuid;
+        for (const event of events) {
+            if (compareSuid(previous, event.suid) >= 0) {
+                const incident = {
+                    serviceId,
+                    identityKey: `ORDER_VIOLATION|${serviceId}|${viewId}|${previous}|${event.suid}|${event.eventId}`,
+                    classification: "ORDER_VIOLATION",
+                    suid: event.suid,
+                    eventId: event.eventId,
+                    incomingEventId: event.eventId,
+                    observedAt: event.lastArrivedAt,
+                };
+                await this.source.appendDeliveryIncident(incident);
+                await this.materializedViews.recordOrderingQuarantine({
+                    serviceId,
+                    viewId,
+                    generation,
+                    checkpointSuid: previous,
+                    lateSuid: event.suid,
+                    eventId: event.eventId,
+                    classification: "ORDER_VIOLATION",
+                    observedAt: event.lastArrivedAt,
+                });
+                console.error("SDT-G69_ORDERING_QUARANTINE", JSON.stringify({
+                    serviceId,
+                    viewId,
+                    generation,
+                    checkpointSuid: previous,
+                    lateSuid: event.suid,
+                    eventId: event.eventId,
+                    classification: "ORDER_VIOLATION",
+                }));
+                throw new MaterializedViewStoreError("apply", "MV_ORDERING_QUARANTINED", "Materialized-view safe lane is quarantined for an ordering violation; rebuild and promote a generation");
+            }
+            previous = event.suid;
+        }
+    }
+}
+async function sourceHistoryProof(events) {
+    const eventIds = events.map((event) => event.eventId);
+    const suids = events.map((event) => event.suid);
+    const maxSuid = events.reduce((maximum, event) => maximum === "" || compareSuid(event.suid, maximum) > 0 ? event.suid : maximum, "");
+    const canonical = events.map((event) => `${event.eventId}\u0000${event.suid}`).join("\n");
+    const digestBytes = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(canonical));
+    const digest = [...new Uint8Array(digestBytes)].map((value) => value.toString(16).padStart(2, "0")).join("");
+    return { eventIds, suids, maxSuid, digest };
+}
+function compareSuid(left, right) {
+    const leftBytes = new TextEncoder().encode(left);
+    const rightBytes = new TextEncoder().encode(right);
+    const shared = Math.min(leftBytes.length, rightBytes.length);
+    for (let index = 0; index < shared; index += 1) {
+        const difference = leftBytes[index] - rightBytes[index];
+        if (difference !== 0)
+            return difference;
+    }
+    return leftBytes.length - rightBytes.length;
+}

package/dist/mv/MaterializedViewRuntime.d.ts

@@ -0,0 +1,80 @@
+import type { ProjectionCheckpoint, ProjectionStore, StoredEvent } from "../store/types";
+export type MaterializedViewOperation = "build" | "follow" | "rebuild" | "reset" | "promote";
+export type MaterializedViewErrorCode = "MV_DEFINITION_INVALID" | "MV_BUILD_ALREADY_EXISTS" | "MV_BUILD_CONFLICT" | "MV_FOLLOW_CHECKPOINT_UNAVAILABLE" | "MV_CHECKPOINT_CONFLICT" | "MV_REBUILD_ID_INVALID" | "MV_REBUILD_CANDIDATE_EXISTS" | "MV_REBUILD_CONFLICT" | "MV_RESET_MISSING" | "MV_RESET_NOTHING_TO_RESET" | "MV_RESET_CONFLICT" | "MV_PROMOTE_CANDIDATE_MISSING" | "MV_PROMOTE_NOTHING_TO_PROMOTE" | "MV_PROMOTE_CONFLICT" | "MV_STATE_INVALID" | "MV_OPERATION_FAILED" | "MV_SOURCE_NOT_STRICTLY_SUID_ORDERED";
+/** A failed change operation is never represented as a successful no-op. */
+export declare class MaterializedViewOperationError extends Error {
+    readonly operation: MaterializedViewOperation;
+    readonly code: MaterializedViewErrorCode;
+    constructor(operation: MaterializedViewOperation, code: MaterializedViewErrorCode, message: string);
+}
+/** A deploy-time TypeScript definition; materialized views do not extend V1 HTTP wire. */
+export interface MaterializedViewDefinition<State> {
+    readonly id: string;
+    initialState(): State;
+    apply(state: State, event: StoredEvent): State;
+    serializeState(state: State): string;
+    deserializeState(stateJson: string): State;
+    version(state: State): number;
+}
+export interface MaterializedViewSnapshot<State> {
+    serviceId: string;
+    viewId: string;
+    checkpoint: ProjectionCheckpoint;
+    state: State;
+}
+export interface MaterializedViewFollowResult<State> extends MaterializedViewSnapshot<State> {
+    dynamicLagBoundMs: number;
+    safeWindowMs: number;
+    advancedSourceEvents: number;
+    appliedEvents: number;
+}
+export interface MaterializedViewRebuildResult<State> {
+    candidateId: string;
+    result: MaterializedViewFollowResult<State>;
+}
+export interface MaterializedViewFollowHooks {
+    /** Test-only crash boundary before durable state/checkpoint advancement. */
+    beforeCheckpoint?(event: StoredEvent, checkpoint: ProjectionCheckpoint): Promise<void> | void;
+    /** Test-only crash boundary after durable state/checkpoint advancement. */
+    afterCheckpoint?(event: StoredEvent, checkpoint: ProjectionCheckpoint): Promise<void> | void;
+}
+/** Stable durable namespace for the promoted materialized view. */
+export declare function materializedViewId(definitionId: string): string;
+/** Durable namespace for a rebuild candidate that has not yet been promoted. */
+export declare function materializedViewCandidateId(definitionId: string, rebuildId: string): string;
+/**
+ * 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 declare class MaterializedViewRuntime {
+    private readonly store;
+    constructor(store: ProjectionStore);
+    read<State>(serviceId: string, definition: MaterializedViewDefinition<State>): Promise<MaterializedViewSnapshot<State> | undefined>;
+    /** Creates the initial durable state then follows through the SafeWindow. */
+    build<State>(serviceId: string, definition: MaterializedViewDefinition<State>, nowMs: number, hooks?: MaterializedViewFollowHooks): Promise<MaterializedViewFollowResult<State>>;
+    /** Continues the promoted durable view from its own global SUID checkpoint. */
+    follow<State>(serviceId: string, definition: MaterializedViewDefinition<State>, nowMs: number, hooks?: MaterializedViewFollowHooks): Promise<MaterializedViewFollowResult<State>>;
+    /**
+     * Builds a separate durable candidate from the beginning of the global
+     * source. The caller must explicitly promote it; no rebuild silently swaps
+     * production state.
+     */
+    rebuild<State>(serviceId: string, definition: MaterializedViewDefinition<State>, rebuildId: string, nowMs: number, hooks?: MaterializedViewFollowHooks): Promise<MaterializedViewRebuildResult<State>>;
+    /** Resets the promoted view to a durable initial state, never a no-op. */
+    reset<State>(serviceId: string, definition: MaterializedViewDefinition<State>, nowMs: number): Promise<MaterializedViewSnapshot<State>>;
+    /** Promotes a previously rebuilt durable candidate with a compare-and-swap. */
+    promote<State>(serviceId: string, definition: MaterializedViewDefinition<State>, rebuildId: string, nowMs: number): Promise<MaterializedViewSnapshot<State>>;
+    private ensureInitialCheckpoint;
+    private followCheckpoint;
+    private checkedViewId;
+    private checkedDefinitionId;
+    private stateFrom;
+    private initialState;
+    private apply;
+    private checkpointFor;
+    private snapshot;
+    private failure;
+    private typedFailure;
+}