@sekiban/dcb-runtime 0.2.0

package/dist/mv/MaterializedViewStore.js

@@ -0,0 +1,875 @@
+import { assertJsonValue, } from "@sekiban/dcb-core";
+import { assertSortableUniqueId } from "../allocator/SortableUniqueId";
+import { UnsafeWindowMaterializedViewStore } from "./UnsafeWindowMaterializedView";
+export class MaterializedViewStoreError extends Error {
+    operation;
+    code;
+    constructor(operation, code, message, options) {
+        super(message, options);
+        this.operation = operation;
+        this.code = code;
+        this.name = "MaterializedViewStoreError";
+    }
+}
+/** A stale MV checkpoint is a failed atomic call, never a successful no-op. */
+export class MaterializedViewCasError extends MaterializedViewStoreError {
+    constructor(message = "Materialized-view checkpoint CAS did not match") {
+        super("apply", "MV_CAS_MISMATCH", message);
+        this.name = "MaterializedViewCasError";
+    }
+}
+export class MaterializedViewPromotionCasError extends MaterializedViewStoreError {
+    constructor(message = "Materialized-view active-generation CAS did not match") {
+        super("promote", "MV_PROMOTION_CAS_MISMATCH", message);
+        this.name = "MaterializedViewPromotionCasError";
+    }
+}
+export class MaterializedViewPatchError extends MaterializedViewStoreError {
+    constructor(message = "Materialized-view JSON patch target row does not exist") {
+        super("apply", "MV_PATCH_ROW_MISSING", message);
+        this.name = "MaterializedViewPatchError";
+    }
+}
+function asString(value, name) {
+    if (typeof value !== "string")
+        throw new Error(`MV ${name} was not a string`);
+    return value;
+}
+function asInteger(value, name) {
+    const number = typeof value === "number" ? value : Number(value);
+    if (!Number.isSafeInteger(number))
+        throw new Error(`MV ${name} was not a safe integer`);
+    return number;
+}
+function asStatus(value) {
+    if (value === "active" || value === "candidate" || value === "retired")
+        return value;
+    throw new Error("MV instance status was invalid");
+}
+/** V1 SUID comparison is bytewise ordinal, never locale-aware. */
+function compareSuid(left, right) {
+    const leftBytes = new TextEncoder().encode(left);
+    const rightBytes = new TextEncoder().encode(right);
+    for (let index = 0; index < Math.min(leftBytes.length, rightBytes.length); index += 1) {
+        const difference = leftBytes[index] - rightBytes[index];
+        if (difference !== 0)
+            return difference;
+    }
+    return leftBytes.length - rightBytes.length;
+}
+function maxReflectedSuid(rows) {
+    let maximum = "";
+    for (const row of rows) {
+        if (maximum === "" || compareSuid(row.sourceSuid, maximum) > 0)
+            maximum = row.sourceSuid;
+    }
+    return maximum;
+}
+function instanceFrom(row) {
+    return {
+        serviceId: asString(row.service_id, "service_id"),
+        viewId: asString(row.view_id, "view_id"),
+        generation: asInteger(row.generation, "generation"),
+        status: asStatus(row.status),
+        lastSuid: asString(row.last_suid, "last_suid"),
+        definitionVersion: asInteger(row.definition_version, "definition_version"),
+        updatedAt: asInteger(row.updated_at, "updated_at"),
+        rebuildVerifiedAt: row.rebuild_verified_at === null || row.rebuild_verified_at === undefined
+            ? null
+            : asInteger(row.rebuild_verified_at, "rebuild_verified_at"),
+        rebuildRecoveryId: row.rebuild_recovery_id === null || row.rebuild_recovery_id === undefined
+            ? null
+            : asString(row.rebuild_recovery_id, "rebuild_recovery_id"),
+        rebuildIncidentIdentity: row.rebuild_incident_identity === null || row.rebuild_incident_identity === undefined
+            ? null
+            : asString(row.rebuild_incident_identity, "rebuild_incident_identity"),
+        rebuildIncidentGeneration: row.rebuild_incident_generation === null || row.rebuild_incident_generation === undefined
+            ? null
+            : asInteger(row.rebuild_incident_generation, "rebuild_incident_generation"),
+        rebuildSourceEventCount: row.rebuild_source_event_count === null || row.rebuild_source_event_count === undefined
+            ? null
+            : asInteger(row.rebuild_source_event_count, "rebuild_source_event_count"),
+        rebuildSourceMaxSuid: row.rebuild_source_max_suid === null || row.rebuild_source_max_suid === undefined
+            ? null
+            : asString(row.rebuild_source_max_suid, "rebuild_source_max_suid"),
+        rebuildSourceHistoryDigest: row.rebuild_source_history_digest === null || row.rebuild_source_history_digest === undefined
+            ? null
+            : asString(row.rebuild_source_history_digest, "rebuild_source_history_digest"),
+    };
+}
+function valueType(value) {
+    if (value === "text" || value === "integer" || value === "real")
+        return value;
+    throw new Error("MV index value type was invalid");
+}
+function indexValue(row, type) {
+    if (type === "text")
+        return asString(row.text_value, "text_value");
+    const number = typeof row[`${type}_value`] === "number" ? row[`${type}_value`] : Number(row[`${type}_value`]);
+    if (!Number.isFinite(number) || (type === "integer" && !Number.isSafeInteger(number))) {
+        throw new Error(`MV ${type}_value was invalid`);
+    }
+    return number;
+}
+function operationId() {
+    return `mv-${crypto.randomUUID()}`;
+}
+function isCasFailure(error) {
+    const message = String(error);
+    return message.includes("mv_atomic_guards.checkpoint_match") || message.includes("MV_CAS_MISMATCH");
+}
+function isPatchFailure(error) {
+    return String(error).includes("CHECK constraint failed: checkpoint_match");
+}
+/**
+ * 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 class D1MaterializedViewStore {
+    database;
+    initialized = false;
+    unsafe;
+    constructor(database) {
+        this.database = database;
+        this.unsafe = new UnsafeWindowMaterializedViewStore(database);
+    }
+    async initialize() {
+        if (this.initialized)
+            return;
+        await this.database.prepare("SELECT 1 FROM mv_instances LIMIT 1").all();
+        await this.database.prepare("SELECT 1 FROM mv_atomic_guards LIMIT 1").all();
+        await this.database.prepare("SELECT 1 FROM mv_checkpoint_ahead_findings LIMIT 1").all();
+        await this.database.prepare("SELECT 1 FROM mv_ordering_quarantines LIMIT 1").all();
+        this.initialized = true;
+    }
+    async createActive(input) {
+        this.ready("create-active");
+        const generation = input.generation ?? 0;
+        this.validateGeneration(generation, "create-active");
+        const lastSuid = input.lastSuid ?? "";
+        if (lastSuid.length > 0)
+            assertSortableUniqueId(lastSuid);
+        try {
+            await this.database.batch([
+                this.database.prepare(`INSERT INTO mv_instances
+             (service_id, view_id, generation, status, last_suid, definition_version, updated_at)
+           VALUES (?, ?, ?, 'active', ?, ?, ?)`).bind(input.serviceId, input.viewId, generation, lastSuid, input.definitionVersion, input.updatedAt),
+                this.database.prepare(`INSERT INTO mv_active_generations (service_id, view_id, generation, updated_at)
+           VALUES (?, ?, ?, ?)`).bind(input.serviceId, input.viewId, generation, input.updatedAt),
+            ]);
+        }
+        catch (error) {
+            throw new MaterializedViewStoreError("create-active", "MV_INSTANCE_EXISTS", `Active materialized view already exists: ${String(error)}`, { cause: error });
+        }
+        return this.readInstance(input.serviceId, input.viewId, generation);
+    }
+    async createCandidate(input) {
+        this.ready("create-candidate");
+        this.validateGeneration(input.generation, "create-candidate");
+        if ((input.lastSuid ?? "").length > 0)
+            assertSortableUniqueId(input.lastSuid);
+        try {
+            await this.database.prepare(`INSERT INTO mv_instances
+           (service_id, view_id, generation, status, last_suid, definition_version, updated_at)
+         VALUES (?, ?, ?, 'candidate', ?, ?, ?)`).bind(input.serviceId, input.viewId, input.generation, input.lastSuid ?? "", input.definitionVersion, input.updatedAt).run();
+        }
+        catch (error) {
+            throw new MaterializedViewStoreError("create-candidate", "MV_INSTANCE_EXISTS", `Candidate generation already exists: ${String(error)}`, { cause: error });
+        }
+        return this.readInstance(input.serviceId, input.viewId, input.generation);
+    }
+    async beginRebuild(input) {
+        this.ready("create-candidate");
+        const generation = input.generation ?? await this.nextGeneration(input.serviceId, input.viewId);
+        return this.createCandidate({ ...input, generation });
+    }
+    async nextGeneration(serviceId, viewId) {
+        this.ready("create-candidate");
+        const row = await this.database.prepare(`SELECT COALESCE(MAX(generation), -1) AS generation FROM mv_instances WHERE service_id = ? AND view_id = ?`).bind(serviceId, viewId).first();
+        return asInteger(row?.generation ?? -1, "generation") + 1;
+    }
+    async readInstance(serviceId, viewId, generation) {
+        this.ready("initialize");
+        const row = await this.database.prepare(`SELECT service_id, view_id, generation, status, last_suid, definition_version, updated_at,
+              rebuild_verified_at, rebuild_recovery_id, rebuild_incident_identity,
+              rebuild_incident_generation, rebuild_source_event_count,
+              rebuild_source_max_suid, rebuild_source_history_digest
+         FROM mv_instances WHERE service_id = ? AND view_id = ? AND generation = ?`).bind(serviceId, viewId, generation).first();
+        return row === null || row === undefined ? undefined : instanceFrom(row);
+    }
+    async readActive(serviceId, viewId) {
+        this.ready("initialize");
+        const row = await this.database.prepare(`SELECT instance.service_id, instance.view_id, instance.generation, instance.status,
+              instance.last_suid, instance.definition_version, instance.updated_at,
+              instance.rebuild_verified_at, instance.rebuild_recovery_id,
+              instance.rebuild_incident_identity, instance.rebuild_incident_generation,
+              instance.rebuild_source_event_count, instance.rebuild_source_max_suid,
+              instance.rebuild_source_history_digest
+         FROM mv_active_generations pointer
+         JOIN mv_instances instance
+           ON instance.service_id = pointer.service_id
+          AND instance.view_id = pointer.view_id
+          AND instance.generation = pointer.generation
+        WHERE pointer.service_id = ? AND pointer.view_id = ?`).bind(serviceId, viewId).first();
+        return row === null || row === undefined ? undefined : instanceFrom(row);
+    }
+    async readRows(serviceId, viewId, generation) {
+        this.ready("initialize");
+        const selected = generation ?? (await this.readActive(serviceId, viewId))?.generation;
+        if (selected === undefined)
+            return [];
+        const result = await this.database.prepare(`SELECT service_id, view_id, generation, row_key, value_json, row_version, source_suid
+         FROM mv_rows
+        WHERE service_id = ? AND view_id = ? AND generation = ?
+        ORDER BY row_key COLLATE BINARY ASC`).bind(serviceId, viewId, selected).all();
+        return result.results.map((row) => this.rowFrom(row));
+    }
+    async readIndexEntries(serviceId, viewId, generation) {
+        this.ready("initialize");
+        const selected = generation ?? (await this.readActive(serviceId, viewId))?.generation;
+        if (selected === undefined)
+            return [];
+        const result = await this.database.prepare(`SELECT service_id, view_id, generation, index_id, value_type,
+              text_value, integer_value, real_value, row_key
+         FROM mv_index_entries
+        WHERE service_id = ? AND view_id = ? AND generation = ?
+        ORDER BY index_id COLLATE BINARY ASC, value_type COLLATE BINARY ASC,
+                 COALESCE(text_value, CAST(integer_value AS TEXT), CAST(real_value AS TEXT)) COLLATE BINARY ASC,
+                 row_key COLLATE BINARY ASC`).bind(serviceId, viewId, selected).all();
+        return result.results.map((row) => this.indexFrom(row));
+    }
+    /** Read rows through a declared index without exposing SQL identifiers to callers. */
+    async queryRows(serviceId, viewId, options = {}) {
+        this.ready("initialize");
+        const selected = options.generation ?? (await this.readActive(serviceId, viewId))?.generation;
+        if (selected === undefined)
+            return [];
+        const limit = options.limit === undefined ? 100 : options.limit;
+        const offset = options.offset ?? 0;
+        if ((limit !== null && (!Number.isSafeInteger(limit) || limit < 0)) || !Number.isSafeInteger(offset) || offset < 0) {
+            throw new MaterializedViewStoreError("initialize", "MV_VALUE_INVALID", "MV query limit/offset must be non-negative integers");
+        }
+        if (options.indexId === undefined) {
+            const limitClause = limit === null ? "" : " LIMIT ? OFFSET ?";
+            const direction = options.descending === true ? "DESC" : "ASC";
+            const values = [serviceId, viewId, selected];
+            if (limit !== null)
+                values.push(limit, offset);
+            const result = await this.database.prepare(`SELECT service_id, view_id, generation, row_key, value_json, row_version, source_suid
+           FROM mv_rows
+          WHERE service_id = ? AND view_id = ? AND generation = ?
+          ORDER BY row_key COLLATE BINARY ${direction}${limitClause}`).bind(...values).all();
+            return result.results.map((row) => this.rowFrom(row));
+        }
+        const valueType = options.valueType;
+        // COLLATE BINARY is meaningful for text and row-key tie breakers. SQLite
+        // keeps integer/real columns numerically ordered; the closed expression
+        // below remains static so request values never become SQL identifiers.
+        const orderColumn = valueType === "text"
+            ? "index_entry.text_value"
+            : valueType === "integer"
+                ? "index_entry.integer_value"
+                : valueType === "real"
+                    ? "index_entry.real_value"
+                    : "index_entry.row_key";
+        const direction = options.descending === true ? "DESC" : "ASC";
+        const indexPredicate = options.indexId === undefined ? "" : " AND index_entry.index_id = ?";
+        const typePredicate = valueType === undefined ? "" : " AND index_entry.value_type = ?";
+        const values = [serviceId, viewId, selected];
+        if (options.indexId !== undefined)
+            values.push(options.indexId);
+        if (valueType !== undefined)
+            values.push(valueType);
+        if (limit !== null)
+            values.push(limit, offset);
+        const limitClause = limit === null ? "" : " LIMIT ? OFFSET ?";
+        const result = await this.database.prepare(`SELECT row.service_id, row.view_id, row.generation, row.row_key,
+              row.value_json, row.row_version, row.source_suid
+         FROM mv_index_entries index_entry
+         JOIN mv_rows row
+           ON row.service_id = index_entry.service_id
+          AND row.view_id = index_entry.view_id
+          AND row.generation = index_entry.generation
+          AND row.row_key = index_entry.row_key
+        WHERE row.service_id = ? AND row.view_id = ? AND row.generation = ?${indexPredicate}${typePredicate}
+        ORDER BY ${orderColumn} COLLATE BINARY ${direction}, row.row_key COLLATE BINARY ${direction}${limitClause}`).bind(...values).all();
+        return result.results.map((row) => this.rowFrom(row));
+    }
+    /** SDT-G23 composed server page; count and page rows share one statement. */
+    async queryRowsWithTotal(serviceId, viewId, options = {}) {
+        this.ready("initialize");
+        const selected = options.generation ?? (await this.readActive(serviceId, viewId))?.generation;
+        if (selected === undefined)
+            return { rows: [], totalCount: 0 };
+        // Scalar V1 queries pass `limit: null` to retain their legacy unpaged
+        // result. SQLite uses LIMIT -1 for that one-statement composed read.
+        const limit = options.limit === null ? -1 : options.limit === undefined ? 100 : options.limit;
+        const offset = options.offset ?? 0;
+        if (!Number.isSafeInteger(limit) || limit < -1 || !Number.isSafeInteger(offset) || offset < 0) {
+            throw new MaterializedViewStoreError("initialize", "MV_VALUE_INVALID", "MV composed query needs limit -1 or a non-negative limit/offset");
+        }
+        return this.unsafe.queryComposedPage(serviceId, viewId, selected, limit, offset, options.descending === true);
+    }
+    /**
+     * 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.
+     */
+    async readListPage(serviceId, viewId, options = {}) {
+        this.ready("initialize");
+        const active = await this.readActive(serviceId, viewId);
+        if (active === undefined)
+            return { rows: [], totalCount: 0, readHead: "" };
+        const selected = options.generation ?? active.generation;
+        const selectedInstance = selected === active.generation
+            ? active
+            : await this.readInstance(serviceId, viewId, selected);
+        if (selectedInstance === undefined) {
+            throw new MaterializedViewStoreError("initialize", "MV_INSTANCE_MISSING", "Requested materialized-view generation is unavailable");
+        }
+        const limit = options.limit === null ? -1 : options.limit === undefined ? 100 : options.limit;
+        const offset = options.offset ?? 0;
+        if (!Number.isSafeInteger(limit) || limit < -1 || !Number.isSafeInteger(offset) || offset < 0) {
+            throw new MaterializedViewStoreError("initialize", "MV_VALUE_INVALID", "MV list query needs limit -1 or a non-negative limit/offset");
+        }
+        if (options.indexId !== undefined || options.valueType !== undefined) {
+            throw new MaterializedViewStoreError("initialize", "MV_VALUE_INVALID", "MV list query does not support an index selector");
+        }
+        const direction = options.descending === true ? "DESC" : "ASC";
+        const safeRows = `SELECT row_key, value_json, row_version, source_suid, 0 AS tombstone, 0 AS unsafe_layer FROM mv_rows
+          WHERE service_id = ? AND view_id = ? AND generation = ?`;
+        const result = options.consistency === "unsafe"
+            ? await this.database.prepare(`WITH candidates AS (
+           ${safeRows}
+           UNION ALL
+           SELECT row_key, value_json, row_version, source_suid, tombstone, 1 AS unsafe_layer FROM mv_unsafe_rows
+            WHERE service_id = ? AND view_id = ? AND generation = ?
+              AND source_suid COLLATE BINARY > ? COLLATE BINARY
+         ), ranked AS (
+           SELECT *, ROW_NUMBER() OVER (PARTITION BY row_key ORDER BY source_suid COLLATE BINARY DESC, unsafe_layer ASC) AS winner_rank FROM candidates
+         ), live AS (
+           SELECT *, COUNT(*) OVER() AS total_count FROM ranked WHERE winner_rank = 1 AND tombstone = 0
+         )
+         SELECT row_key, value_json, row_version, source_suid, total_count FROM live
+         ORDER BY source_suid COLLATE BINARY ${direction}, row_key COLLATE BINARY ${direction} LIMIT ? OFFSET ?`).bind(serviceId, viewId, selected, serviceId, viewId, selected, selectedInstance.lastSuid, limit, offset).all()
+            : await this.database.prepare(`WITH live AS (
+           SELECT row_key, value_json, row_version, source_suid, COUNT(*) OVER() AS total_count FROM mv_rows
+            WHERE service_id = ? AND view_id = ? AND generation = ?
+         )
+         SELECT row_key, value_json, row_version, source_suid, total_count FROM live
+         ORDER BY source_suid COLLATE BINARY ${direction}, row_key COLLATE BINARY ${direction} LIMIT ? OFFSET ?`).bind(serviceId, viewId, selected, limit, offset).all();
+        const rows = result.results.map((row) => ({
+            serviceId,
+            viewId,
+            generation: selected,
+            rowKey: asString(row.row_key, "row_key"),
+            value: assertJsonValue(JSON.parse(asString(row.value_json, "value_json")), "state-persistence"),
+            rowVersion: asInteger(row.row_version, "row_version"),
+            sourceSuid: asString(row.source_suid, "source_suid"),
+        }));
+        return {
+            rows,
+            totalCount: result.results.length === 0 ? 0 : asInteger(result.results[0].total_count, "total_count"),
+            // Safe reads report the active checkpoint even for an empty page. Unsafe
+            // reads instead report only what this page actually reflected.
+            readHead: options.consistency === "unsafe" ? maxReflectedSuid(rows) : selectedInstance.lastSuid,
+        };
+    }
+    /** Explicit unsafe port: callers must choose this exceptional immediate lane. */
+    unsafeWindow() {
+        this.ready("apply");
+        return this.unsafe;
+    }
+    /** Runs repairable unsafe GC after an idle or advancing safe catch-up pass. */
+    async collectUnsafeGarbage(serviceId, viewId, generation, definitionVersion, safeHead) {
+        this.ready("apply");
+        return this.unsafe.collectEligible(serviceId, viewId, generation, definitionVersion, safeHead);
+    }
+    async hasTargetReceipt(serviceId, viewId, eventId, suid) {
+        this.ready("initialize");
+        return this.unsafe.hasTargetReceipt(serviceId, viewId, eventId, suid);
+    }
+    /**
+     * 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.
+     */
+    async readWaitForState(serviceId, viewId, target) {
+        this.ready("initialize");
+        const row = await this.database.prepare(`WITH active AS (
+         SELECT instance.generation, instance.definition_version, instance.last_suid
+           FROM mv_active_generations pointer
+           JOIN mv_instances instance
+             ON instance.service_id = pointer.service_id
+            AND instance.view_id = pointer.view_id
+            AND instance.generation = pointer.generation
+          WHERE pointer.service_id = ? AND pointer.view_id = ?
+       )
+       SELECT
+         (SELECT generation FROM active) AS active_generation,
+         (SELECT definition_version FROM active) AS active_definition_version,
+         COALESCE((SELECT last_suid FROM active), '') AS safe_contiguous_head,
+         CASE WHEN EXISTS (
+           SELECT 1
+             FROM mv_wait_receipts receipt
+             JOIN active
+               ON active.generation = receipt.generation
+              AND active.definition_version = receipt.definition_version
+            WHERE receipt.service_id = ? AND receipt.view_id = ?
+              AND receipt.event_id = ? AND receipt.suid = ?
+         ) THEN 1 ELSE 0 END AS target_receipt,
+         CASE WHEN EXISTS (
+           SELECT 1
+             FROM mv_checkpoint_ahead_findings finding
+             JOIN active
+               ON active.generation = finding.generation
+            WHERE finding.service_id = ? AND finding.view_id = ?
+         ) THEN 1 ELSE 0 END AS checkpoint_ahead,
+         COALESCE((
+           SELECT arrival.rebuild_required
+             FROM mv_unsafe_arrivals arrival
+             JOIN active
+               ON active.generation = arrival.generation
+            WHERE arrival.service_id = ? AND arrival.view_id = ?
+         ), 0) AS rebuild_required,
+         CASE WHEN EXISTS (
+           SELECT 1
+             FROM mv_wait_target_poison finding
+             JOIN active
+               ON active.generation = finding.generation
+              AND active.definition_version = finding.definition_version
+            WHERE finding.service_id = ? AND finding.view_id = ?
+              AND finding.suid = ?
+              AND (? IS NULL OR finding.event_id = ?)
+         ) THEN 1 ELSE 0 END AS poison`).bind(serviceId, viewId, serviceId, viewId, target.eventId ?? "", target.suid, serviceId, viewId, serviceId, viewId, serviceId, viewId, target.suid, target.eventId ?? null, target.eventId ?? null).first();
+        if (row === null || row === undefined) {
+            throw new MaterializedViewStoreError("initialize", "MV_STORE_OPERATION_FAILED", "D1 wait-state query returned no row");
+        }
+        const generation = row.active_generation === null || row.active_generation === undefined
+            ? undefined
+            : asInteger(row.active_generation, "active_generation");
+        const definitionVersion = row.active_definition_version === null || row.active_definition_version === undefined
+            ? undefined
+            : asInteger(row.active_definition_version, "active_definition_version");
+        return {
+            activeGeneration: generation,
+            activeDefinitionVersion: definitionVersion,
+            safeContiguousHead: asString(row.safe_contiguous_head, "safe_contiguous_head"),
+            targetReceipt: asInteger(row.target_receipt, "target_receipt") === 1,
+            checkpointAhead: asInteger(row.checkpoint_ahead, "checkpoint_ahead") === 1,
+            rebuildRequired: asInteger(row.rebuild_required, "rebuild_required") === 1,
+            poison: asInteger(row.poison, "poison") === 1,
+        };
+    }
+    /** Idempotent operational fact: a stored Queue event needs unsafe retry/DLQ attention. */
+    async recordUnsafeFailureFinding(input) {
+        this.ready("apply");
+        const legacyFinding = this.database.prepare(`INSERT INTO mv_unsafe_failure_findings
+         (service_id, view_id, event_id, suid, classification, observed_at)
+       VALUES (?, ?, ?, ?, 'UNSAFE_APPLY_RETRY', ?)
+       ON CONFLICT (service_id, view_id, event_id, suid, classification) DO NOTHING`).bind(input.serviceId, input.viewId, input.eventId, input.suid, input.observedAt);
+        const targetPoison = input.generation === undefined
+            ? this.database.prepare(`INSERT INTO mv_wait_target_poison
+           (service_id, view_id, generation, definition_version, event_id, suid, classification, observed_at)
+         SELECT instance.service_id, instance.view_id, instance.generation, instance.definition_version, ?, ?, 'UNSAFE_APPLY_RETRY', ?
+           FROM mv_active_generations active
+           JOIN mv_instances instance
+             ON instance.service_id = active.service_id
+            AND instance.view_id = active.view_id
+            AND instance.generation = active.generation
+          WHERE active.service_id = ? AND active.view_id = ?
+         ON CONFLICT DO NOTHING`).bind(input.eventId, input.suid, input.observedAt, input.serviceId, input.viewId)
+            : this.database.prepare(`INSERT INTO mv_wait_target_poison
+           (service_id, view_id, generation, definition_version, event_id, suid, classification, observed_at)
+         SELECT instance.service_id, instance.view_id, instance.generation, instance.definition_version, ?, ?, 'UNSAFE_APPLY_RETRY', ?
+           FROM mv_instances instance
+          WHERE instance.service_id = ? AND instance.view_id = ? AND instance.generation = ?
+         ON CONFLICT DO NOTHING`).bind(input.eventId, input.suid, input.observedAt, input.serviceId, input.viewId, input.generation);
+        await this.database.batch([legacyFinding, targetPoison]);
+    }
+    /**
+     * Persist the source-reset observation exactly once for the affected
+     * generation.  This deliberately never rewinds `mv_instances.last_suid`.
+     */
+    async recordCheckpointAhead(input) {
+        this.ready("apply");
+        await this.database.prepare(`INSERT INTO mv_checkpoint_ahead_findings
+         (service_id, view_id, generation, checkpoint_suid, store_max_suid, observed_at)
+       VALUES (?, ?, ?, ?, ?, ?)
+       ON CONFLICT (service_id, view_id, generation) DO NOTHING`).bind(input.serviceId, input.viewId, input.generation, input.checkpointSuid, input.storeMaxSuid, input.observedAt).run();
+    }
+    /** An open finding on the active generation fail-closes composed MV reads. */
+    async hasCheckpointAheadFinding(serviceId, viewId) {
+        this.ready("initialize");
+        const result = await this.database.prepare(`SELECT 1 AS present
+         FROM mv_checkpoint_ahead_findings finding
+         JOIN mv_active_generations active
+           ON active.service_id = finding.service_id
+          AND active.view_id = finding.view_id
+          AND active.generation = finding.generation
+        WHERE finding.service_id = ? AND finding.view_id = ?
+        LIMIT 1`).bind(serviceId, viewId).first();
+        return result?.present === 1;
+    }
+    /** Open quarantine is keyed to the active generation; old generations are not a public read gate. */
+    async readOrderingQuarantine(serviceId, viewId) {
+        this.ready("initialize");
+        const row = await this.database.prepare(`SELECT quarantine.service_id, quarantine.view_id, quarantine.generation,
+              quarantine.checkpoint_suid, quarantine.late_suid, quarantine.event_id,
+              quarantine.classification, quarantine.status, quarantine.observed_at,
+              quarantine.resolved_at, quarantine.incident_identity
+         FROM mv_ordering_quarantines quarantine
+         JOIN mv_active_generations active
+           ON active.service_id = quarantine.service_id
+          AND active.view_id = quarantine.view_id
+          AND active.generation = quarantine.generation
+        WHERE quarantine.service_id = ? AND quarantine.view_id = ? AND quarantine.status = 'open'
+        LIMIT 1`).bind(serviceId, viewId).first();
+        if (row === null || row === undefined)
+            return undefined;
+        const classification = asString(row.classification, "ordering_quarantine.classification");
+        if (classification !== "LATE_LOWER_SUID" && classification !== "ORDER_VIOLATION") {
+            throw new MaterializedViewStoreError("initialize", "MV_STORE_OPERATION_FAILED", "Materialized-view ordering quarantine classification was invalid");
+        }
+        const status = asString(row.status, "ordering_quarantine.status");
+        if (status !== "open" && status !== "resolved") {
+            throw new MaterializedViewStoreError("initialize", "MV_STORE_OPERATION_FAILED", "Materialized-view ordering quarantine status was invalid");
+        }
+        return {
+            serviceId: asString(row.service_id, "ordering_quarantine.service_id"),
+            viewId: asString(row.view_id, "ordering_quarantine.view_id"),
+            generation: asInteger(row.generation, "ordering_quarantine.generation"),
+            checkpointSuid: asString(row.checkpoint_suid, "ordering_quarantine.checkpoint_suid"),
+            lateSuid: asString(row.late_suid, "ordering_quarantine.late_suid"),
+            eventId: asString(row.event_id, "ordering_quarantine.event_id"),
+            classification,
+            status,
+            observedAt: asInteger(row.observed_at, "ordering_quarantine.observed_at"),
+            resolvedAt: row.resolved_at === null || row.resolved_at === undefined
+                ? null
+                : asInteger(row.resolved_at, "ordering_quarantine.resolved_at"),
+            incidentIdentity: row.incident_identity === null || row.incident_identity === undefined
+                ? null
+                : asString(row.incident_identity, "ordering_quarantine.incident_identity"),
+        };
+    }
+    async readActiveGeneration(serviceId, viewId) {
+        this.ready("initialize");
+        return (await this.readActive(serviceId, viewId))?.generation;
+    }
+    /** Persist the detector result before stopping the safe pass. Repeated observations are idempotent. */
+    async recordOrderingQuarantine(input) {
+        this.ready("apply");
+        this.validateGeneration(input.generation, "apply");
+        const incidentIdentity = `${input.classification}|${input.serviceId}|${input.viewId}|${input.checkpointSuid}|${input.lateSuid}|${input.eventId}`;
+        await this.database.prepare(`INSERT INTO mv_ordering_quarantines
+         (service_id, view_id, generation, checkpoint_suid, late_suid, event_id, classification, status, observed_at, resolved_at, incident_identity)
+       VALUES (?, ?, ?, ?, ?, ?, ?, 'open', ?, NULL, ?)
+       ON CONFLICT (service_id, view_id, generation) DO UPDATE SET
+         checkpoint_suid = excluded.checkpoint_suid,
+         late_suid = excluded.late_suid,
+         event_id = excluded.event_id,
+         classification = excluded.classification,
+         status = 'open',
+         observed_at = MIN(mv_ordering_quarantines.observed_at, excluded.observed_at),
+         resolved_at = NULL,
+         incident_identity = excluded.incident_identity`).bind(input.serviceId, input.viewId, input.generation, input.checkpointSuid, input.lateSuid, input.eventId, input.classification, input.observedAt, incidentIdentity).run();
+    }
+    /**
+     * 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).
+     */
+    async markGenerationRebuilt(input) {
+        this.ready("promote");
+        this.validateGeneration(input.generation, "promote");
+        if (input.rebuildId.length === 0 ||
+            !Number.isSafeInteger(input.sourceEventCount) || input.sourceEventCount < 0 ||
+            input.sourceEventIds.length !== input.sourceEventCount ||
+            input.sourceSuids.length !== input.sourceEventCount ||
+            (input.sourceEventCount === 0 ? input.sourceMaxSuid !== "" : input.sourceMaxSuid.length === 0) ||
+            input.sourceHistoryDigest.length === 0) {
+            throw new MaterializedViewStoreError("promote", "MV_REBUILD_NOT_VERIFIED", "Rebuild proof does not describe a complete source history");
+        }
+        const quarantine = await this.database.prepare(`SELECT generation, incident_identity, event_id, late_suid
+         FROM mv_ordering_quarantines
+        WHERE service_id = ? AND view_id = ? AND status = 'open'
+        ORDER BY generation DESC LIMIT 1`).bind(input.serviceId, input.viewId).first();
+        const incidentGeneration = quarantine === null || quarantine === undefined
+            ? null
+            : asInteger(quarantine.generation, "rebuild.incident_generation");
+        const incidentIdentity = quarantine === null || quarantine === undefined
+            ? null
+            : typeof quarantine.incident_identity === "string" && quarantine.incident_identity.length > 0
+                ? quarantine.incident_identity
+                : null;
+        if (quarantine !== null && quarantine !== undefined) {
+            if (incidentIdentity === null) {
+                throw new MaterializedViewStoreError("promote", "MV_REBUILD_NOT_VERIFIED", "Ordering quarantine has no durable incident identity");
+            }
+            const incidentEventId = asString(quarantine.event_id, "rebuild.incident_event_id");
+            const incidentLateSuid = asString(quarantine.late_suid, "rebuild.incident_late_suid");
+            if (!input.sourceEventIds.includes(incidentEventId) || !input.sourceSuids.includes(incidentLateSuid)) {
+                throw new MaterializedViewStoreError("promote", "MV_REBUILD_NOT_VERIFIED", "Rebuild source history does not include the quarantined event");
+            }
+        }
+        const result = await this.database.prepare(`UPDATE mv_instances
+          SET rebuild_verified_at = ?,
+              rebuild_recovery_id = ?,
+              rebuild_incident_identity = ?,
+              rebuild_incident_generation = ?,
+              rebuild_source_event_count = ?,
+              rebuild_source_max_suid = ?,
+              rebuild_source_history_digest = ?
+        WHERE service_id = ? AND view_id = ? AND generation = ?
+          AND status = 'candidate'
+          AND last_suid COLLATE BINARY = ? COLLATE BINARY`).bind(input.verifiedAt, input.rebuildId, incidentIdentity, incidentGeneration, input.sourceEventCount, input.sourceMaxSuid, input.sourceHistoryDigest, input.serviceId, input.viewId, input.generation, input.sourceMaxSuid).run();
+        if ((result.meta?.changes ?? 0) !== 1) {
+            throw new MaterializedViewStoreError("promote", "MV_REBUILD_NOT_VERIFIED", "Candidate generation does not match the complete rebuild source history");
+        }
+    }
+    /**
+     * Apply rows/index entries and advance one generation checkpoint atomically.
+     * The guard row intentionally uses a NOT NULL failure to abort a stale CAS.
+     */
+    async applyMutationsAndAdvanceCheckpoint(input) {
+        assertSortableUniqueId(input.lastSuid);
+        if (input.expectedLastSuid !== null)
+            assertSortableUniqueId(input.expectedLastSuid);
+        for (const mutation of [...input.mutations.rowUpserts, ...input.mutations.rowPatches]) {
+            assertSortableUniqueId(mutation.sourceSuid);
+        }
+        this.ready("apply");
+        this.validateGeneration(input.generation, "apply");
+        const operation = operationId();
+        const statements = [
+            this.database.prepare(`INSERT INTO mv_atomic_guards (operation_id, checkpoint_match)
+         SELECT ?, CASE WHEN EXISTS (
+           SELECT 1 FROM mv_instances
+            WHERE service_id = ? AND view_id = ? AND generation = ?
+              AND ((? IS NULL AND last_suid = '') OR last_suid COLLATE BINARY = ? COLLATE BINARY)
+         ) THEN 1 ELSE NULL END`).bind(operation, input.serviceId, input.viewId, input.generation, input.expectedLastSuid, input.expectedLastSuid),
+        ];
+        // Patch guards are evaluated before any write. A missing target selects 0
+        // and violates the CHECK constraint, aborting the entire D1 batch.
+        for (const patch of input.mutations.rowPatches) {
+            statements.push(this.database.prepare(`INSERT INTO mv_atomic_guards (operation_id, checkpoint_match)
+         SELECT ?, CASE WHEN EXISTS (
+           SELECT 1 FROM mv_rows
+            WHERE service_id = ? AND view_id = ? AND generation = ? AND row_key COLLATE BINARY = ? COLLATE BINARY
+         ) THEN 1 ELSE 0 END`).bind(`${operation}:patch:${patch.rowKey}`, input.serviceId, input.viewId, input.generation, patch.rowKey));
+        }
+        for (const deletion of input.mutations.rowDeletes) {
+            statements.push(this.database.prepare(`DELETE FROM mv_index_entries WHERE service_id = ? AND view_id = ? AND generation = ? AND row_key = ?`).bind(input.serviceId, input.viewId, input.generation, deletion.rowKey));
+            statements.push(this.database.prepare(`DELETE FROM mv_rows WHERE service_id = ? AND view_id = ? AND generation = ? AND row_key = ?`).bind(input.serviceId, input.viewId, input.generation, deletion.rowKey));
+        }
+        for (const upsert of input.mutations.rowUpserts) {
+            // An upsert replaces all indexes for that row before inserting the
+            // finite descriptor set below; stale index entries cannot survive.
+            statements.push(this.database.prepare(`DELETE FROM mv_index_entries WHERE service_id = ? AND view_id = ? AND generation = ? AND row_key = ?`).bind(input.serviceId, input.viewId, input.generation, upsert.rowKey));
+            statements.push(this.database.prepare(`INSERT INTO mv_rows
+           (service_id, view_id, generation, row_key, value_json, row_version, source_suid)
+         VALUES (?, ?, ?, ?, ?, ?, ?)
+         ON CONFLICT (service_id, view_id, generation, row_key) DO UPDATE SET
+           value_json = excluded.value_json,
+           row_version = excluded.row_version,
+           source_suid = excluded.source_suid`).bind(input.serviceId, input.viewId, input.generation, upsert.rowKey, JSON.stringify(assertJsonValue(upsert.value, "state-persistence")), upsert.rowVersion, upsert.sourceSuid));
+        }
+        for (const patch of input.mutations.rowPatches) {
+            // A patch carrying index entries declares the complete replacement set
+            // for this row. With no entries the prior index rows remain intact.
+            if (patch.indexEntries.length > 0) {
+                statements.push(this.database.prepare(`DELETE FROM mv_index_entries WHERE service_id = ? AND view_id = ? AND generation = ? AND row_key = ?`).bind(input.serviceId, input.viewId, input.generation, patch.rowKey));
+            }
+            // json_patch performs the partial merge in SQLite as one prepared
+            // statement. No current row is read or merged by the runtime.
+            statements.push(this.database.prepare(`UPDATE mv_rows
+            SET value_json = json_patch(value_json, ?), row_version = ?, source_suid = ?
+          WHERE service_id = ? AND view_id = ? AND generation = ? AND row_key COLLATE BINARY = ? COLLATE BINARY`).bind(JSON.stringify(assertJsonValue(patch.patch, "state-persistence")), patch.rowVersion, patch.sourceSuid, input.serviceId, input.viewId, input.generation, patch.rowKey));
+        }
+        for (const deletion of input.mutations.indexDeletes) {
+            const indexPredicate = deletion.indexId === undefined ? "" : " AND index_id = ?";
+            const values = [input.serviceId, input.viewId, input.generation, deletion.rowKey];
+            if (deletion.indexId !== undefined)
+                values.push(deletion.indexId);
+            statements.push(this.database.prepare(`DELETE FROM mv_index_entries
+          WHERE service_id = ? AND view_id = ? AND generation = ? AND row_key = ?${indexPredicate}`).bind(...values));
+        }
+        for (const entry of input.mutations.indexEntries) {
+            const typed = entry.valueType === "text"
+                ? [entry.value, null, null]
+                : entry.valueType === "integer"
+                    ? [null, entry.value, null]
+                    : [null, null, entry.value];
+            statements.push(this.database.prepare(`INSERT INTO mv_index_entries
+           (service_id, view_id, generation, index_id, value_type, text_value, integer_value, real_value, row_key)
+         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+         ON CONFLICT (service_id, view_id, generation, index_id, value_type, text_value, integer_value, real_value, row_key)
+         DO NOTHING`).bind(input.serviceId, input.viewId, input.generation, entry.indexId, entry.valueType, ...typed, entry.rowKey));
+        }
+        for (const patch of input.mutations.rowPatches) {
+            for (const entry of patch.indexEntries) {
+                const typed = entry.valueType === "text"
+                    ? [entry.value, null, null]
+                    : entry.valueType === "integer"
+                        ? [null, entry.value, null]
+                        : [null, null, entry.value];
+                statements.push(this.database.prepare(`INSERT INTO mv_index_entries
+             (service_id, view_id, generation, index_id, value_type, text_value, integer_value, real_value, row_key)
+           VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+           ON CONFLICT (service_id, view_id, generation, index_id, value_type, text_value, integer_value, real_value, row_key)
+           DO NOTHING`).bind(input.serviceId, input.viewId, input.generation, entry.indexId, entry.valueType, ...typed, entry.rowKey));
+            }
+        }
+        statements.push(this.database.prepare(`UPDATE mv_instances
+          SET last_suid = ?, definition_version = ?, updated_at = MAX(updated_at, ?),
+              rebuild_verified_at = NULL,
+              rebuild_recovery_id = NULL,
+              rebuild_incident_identity = NULL,
+              rebuild_incident_generation = NULL,
+              rebuild_source_event_count = NULL,
+              rebuild_source_max_suid = NULL,
+              rebuild_source_history_digest = NULL
+        WHERE service_id = ? AND view_id = ? AND generation = ?`).bind(input.lastSuid, input.definitionVersion, input.updatedAt, input.serviceId, input.viewId, input.generation));
+        statements.push(this.database.prepare("DELETE FROM mv_atomic_guards WHERE operation_id = ? OR operation_id LIKE ?").bind(operation, `${operation}:%`));
+        try {
+            await this.database.batch(statements);
+        }
+        catch (error) {
+            if (isPatchFailure(error))
+                throw new MaterializedViewPatchError();
+            if (isCasFailure(error))
+                throw new MaterializedViewCasError();
+            throw new MaterializedViewStoreError("apply", "MV_STORE_OPERATION_FAILED", `Materialized-view atomic apply failed: ${String(error)}`, { cause: error });
+        }
+        const instance = await this.readInstance(input.serviceId, input.viewId, input.generation);
+        if (instance === undefined)
+            throw new MaterializedViewStoreError("apply", "MV_INSTANCE_MISSING", "Materialized-view instance disappeared after apply");
+        return {
+            instance,
+            rowUpserts: input.mutations.rowUpserts.length,
+            rowDeletes: input.mutations.rowDeletes.length,
+            rowPatches: input.mutations.rowPatches.length,
+            indexEntries: input.mutations.indexEntries.length,
+        };
+    }
+    async promoteGeneration(input) {
+        this.ready("promote");
+        this.validateGeneration(input.candidateGeneration, "promote");
+        const operation = operationId();
+        const statements = [
+            this.database.prepare(`INSERT INTO mv_atomic_guards (operation_id, checkpoint_match)
+         SELECT ?, CASE WHEN EXISTS (
+           SELECT 1 FROM mv_instances candidate
+           WHERE candidate.service_id = ? AND candidate.view_id = ?
+              AND candidate.generation = ? AND candidate.status = 'candidate'
+              AND (
+                NOT EXISTS (
+                   SELECT 1 FROM mv_ordering_quarantines open_quarantine
+                   WHERE open_quarantine.service_id = candidate.service_id
+                     AND open_quarantine.view_id = candidate.view_id
+                     AND open_quarantine.status = 'open'
+                )
+                OR EXISTS (
+                  SELECT 1 FROM mv_ordering_quarantines open_quarantine
+                   WHERE open_quarantine.service_id = candidate.service_id
+                     AND open_quarantine.view_id = candidate.view_id
+                     AND open_quarantine.status = 'open'
+                     AND open_quarantine.incident_identity IS NOT NULL
+                     AND candidate.rebuild_verified_at IS NOT NULL
+                     AND candidate.rebuild_incident_generation = open_quarantine.generation
+                     AND candidate.rebuild_incident_identity = open_quarantine.incident_identity
+                )
+              )
+         ) AND (
+           (? IS NULL AND NOT EXISTS (
+             SELECT 1 FROM mv_active_generations existing
+              WHERE existing.service_id = ? AND existing.view_id = ?
+           ))
+           OR (? IS NOT NULL AND EXISTS (
+             SELECT 1 FROM mv_active_generations pointer
+              WHERE pointer.service_id = ? AND pointer.view_id = ?
+                AND pointer.generation = ?
+           ))
+         ) THEN 1 ELSE NULL END`).bind(operation, input.serviceId, input.viewId, input.candidateGeneration, input.expectedActiveGeneration, input.serviceId, input.viewId, input.expectedActiveGeneration, input.serviceId, input.viewId, input.expectedActiveGeneration),
+            this.database.prepare(`UPDATE mv_instances SET status = 'retired', updated_at = ?
+          WHERE service_id = ? AND view_id = ? AND status = 'active'`).bind(input.updatedAt, input.serviceId, input.viewId),
+            this.database.prepare(`UPDATE mv_instances SET status = 'active', updated_at = ?
+          WHERE service_id = ? AND view_id = ? AND generation = ?`).bind(input.updatedAt, input.serviceId, input.viewId, input.candidateGeneration),
+            this.database.prepare(`INSERT INTO mv_active_generations (service_id, view_id, generation, updated_at)
+         VALUES (?, ?, ?, ?)
+         ON CONFLICT (service_id, view_id) DO UPDATE SET generation = excluded.generation, updated_at = excluded.updated_at`).bind(input.serviceId, input.viewId, input.candidateGeneration, input.updatedAt),
+            // A successful rebuild/promotion is the explicit recovery action for an
+            // open ordering quarantine. The active-generation pointer changes in the
+            // same batch, so a safe read never observes a cleared gate on the old
+            // generation with the new generation still unproven.
+            this.database.prepare(`UPDATE mv_ordering_quarantines
+            SET status = 'resolved', resolved_at = ?
+          WHERE service_id = ? AND view_id = ? AND status = 'open' AND generation <> ?
+            AND incident_identity = (
+              SELECT candidate.rebuild_incident_identity
+                FROM mv_instances candidate
+               WHERE candidate.service_id = ? AND candidate.view_id = ?
+                 AND candidate.generation = ? AND candidate.status = 'active'
+            )`).bind(input.updatedAt, input.serviceId, input.viewId, input.candidateGeneration, input.serviceId, input.viewId, input.candidateGeneration),
+            this.database.prepare("DELETE FROM mv_atomic_guards WHERE operation_id = ?").bind(operation),
+        ];
+        try {
+            await this.database.batch(statements);
+        }
+        catch (error) {
+            if (isCasFailure(error))
+                throw new MaterializedViewPromotionCasError();
+            throw new MaterializedViewStoreError("promote", "MV_STORE_OPERATION_FAILED", `Materialized-view promotion failed: ${String(error)}`, { cause: error });
+        }
+        const active = await this.readActive(input.serviceId, input.viewId);
+        if (active === undefined)
+            throw new MaterializedViewStoreError("promote", "MV_INSTANCE_MISSING", "Active generation disappeared after promotion");
+        return active;
+    }
+    /** Short aliases make the port convenient for runtime composition and tests. */
+    apply = this.applyMutationsAndAdvanceCheckpoint.bind(this);
+    promote = this.promoteGeneration.bind(this);
+    rowFrom(row) {
+        let value;
+        try {
+            value = assertJsonValue(JSON.parse(asString(row.value_json, "value_json")), "state-persistence");
+        }
+        catch (error) {
+            throw new MaterializedViewStoreError("initialize", "MV_VALUE_INVALID", `Materialized-view row JSON was invalid: ${String(error)}`, { cause: error });
+        }
+        return {
+            serviceId: asString(row.service_id, "service_id"),
+            viewId: asString(row.view_id, "view_id"),
+            generation: asInteger(row.generation, "generation"),
+            rowKey: asString(row.row_key, "row_key"),
+            value,
+            rowVersion: asInteger(row.row_version, "row_version"),
+            sourceSuid: asString(row.source_suid, "source_suid"),
+        };
+    }
+    indexFrom(row) {
+        const type = valueType(row.value_type);
+        return {
+            serviceId: asString(row.service_id, "service_id"),
+            viewId: asString(row.view_id, "view_id"),
+            generation: asInteger(row.generation, "generation"),
+            indexId: asString(row.index_id, "index_id"),
+            valueType: type,
+            value: indexValue(row, type),
+            rowKey: asString(row.row_key, "row_key"),
+        };
+    }
+    validateGeneration(generation, operation) {
+        if (!Number.isSafeInteger(generation) || generation < 0) {
+            throw new MaterializedViewStoreError(operation, "MV_GENERATION_INVALID", "Materialized-view generation must be a non-negative integer");
+        }
+    }
+    ready(operation) {
+        if (!this.initialized)
+            throw new MaterializedViewStoreError(operation, "MV_STORE_NOT_INITIALIZED", "D1MaterializedViewStore.initialize() must complete before use");
+    }
+}