@quereus/store 4.5.0 → 4.7.0

package/dist/src/common/store-module-catalog.js

@@ -0,0 +1,462 @@
+/**
+ * The catalog store: how a table / view / materialized view's DDL text is turned
+ * into a persisted entry, written, compared, reloaded and removed, plus the two
+ * pieces of durable open/close bookkeeping that live beside it (the clean-shutdown
+ * marker and the stale-materialized-view set).
+ *
+ * Second layer of the store-module chain:
+ *   StoreModuleBase -> StoreModuleCatalog -> StoreModuleSchemaSync -> StoreModuleIndex
+ *   -> StoreModuleAlterColumn -> StoreModuleAlter -> StoreModuleRename -> StoreModule
+ */
+import { exposedImplicitIndexes, generateIndexDDL, generateIndexTagsDDL, generateMaintainedTableDDL, generateTableDDL, generateViewDDL, isHiddenImplicitIndex, isMaintainedTable, } from '@quereus/quereus';
+import { CLEAN_SHUTDOWN_META_NAME, STALE_MVS_META_NAME, buildCatalogKey, buildCatalogScanBounds, buildMaterializedViewCatalogKey, buildMetaCatalogKey, buildViewCatalogKey, classifyCatalogKey, } from './key-builder.js';
+import { assertNoUnpairedSurrogate } from './encoding.js';
+import { StoreModuleBase } from './store-module-base.js';
+/**
+ * Guard the FULL persisted schema text, not just the object's own name: a lone
+ * surrogate anywhere in it — a quoted column name, a `default '…'` string literal, a
+ * `check` constraint's string constant — folds to U+FFFD under `TextEncoder` and would
+ * read back as different schema text than what was created. Independent of the
+ * catalog-key builders' identifier guard; it catches what they cannot see.
+ */
+function assertPersistableDdlText(ddl) {
+    assertNoUnpairedSurrogate(ddl, 'persisted schema text');
+}
+/**
+ * The catalog entry a plain view would be persisted as. Building it is the check:
+ * {@link buildViewCatalogKey} rejects an unencodable name, and the caller then runs
+ * {@link assertPersistableDdlText} over `ddl`. Shared by the write path
+ * ({@link saveViewDDL}) and the pre-flight veto
+ * ({@link assertCatalogObjectPersistable}) so the two cannot drift.
+ */
+function viewCatalogEntry(view) {
+    return {
+        key: buildViewCatalogKey(view.schemaName, view.name),
+        ddl: generateViewDDL(view),
+    };
+}
+/**
+ * The catalog entry a materialized view would be persisted as, or `undefined` when
+ * `table` carries no derivation (not an MV — nothing lands under the MV prefix).
+ * Counterpart of {@link viewCatalogEntry}; same write/veto sharing.
+ */
+function maintainedViewCatalogEntry(table) {
+    if (!isMaintainedTable(table))
+        return undefined;
+    return {
+        key: buildMaterializedViewCatalogKey(table.schemaName, table.name),
+        ddl: generateMaintainedTableDDL(table),
+    };
+}
+export class StoreModuleCatalog extends StoreModuleBase {
+    /**
+     * Build the catalog entry for a table: its CREATE TABLE DDL, one
+     * `CREATE [UNIQUE] INDEX` statement per persistable secondary index, and one
+     * `alter index … set tags (…)` statement per exposed implicit index carrying
+     * user tags, newline-joined into a single multi-statement bundle keyed by
+     * `{schema}.{table}`.
+     *
+     * Bundling the indexes into the table's own entry means every existing
+     * re-persist path — `saveTableDDL` (each `alterTable` arm, `renameTable`) and
+     * the `table_modified` listener (`persistCatalogIfChanged`) — carries the
+     * indexes along for free, and `removeTableDDL` drops them with the table. The
+     * bundle is consumed on reopen by `rehydrateCatalog` → `importCatalog`, whose
+     * `parser.parseAll` splits it AST-by-AST (never on `\n`) and imports each
+     * statement in document order, so the table registers before its indexes.
+     *
+     * Both the table DDL and the index DDL are emitted without a `db` arg, keeping
+     * the persistence-safe fully-qualified form. Hidden implicit covering indexes
+     * (the auto-built BTree backing a declared UNIQUE constraint) are excluded —
+     * they are a backing detail that round-trips via the table's UNIQUE constraint,
+     * not as a standalone CREATE INDEX. For store tables `buildTableSchemaFromAST`
+     * synthesizes none of those, so in practice every index is included; the guard
+     * is defensive. A `CREATE UNIQUE INDEX`'s derived UNIQUE constraint is already
+     * excluded from the table DDL by the generator, so it round-trips solely via
+     * its own `CREATE UNIQUE INDEX` line — no doubling.
+     *
+     * An *exposed* implicit index (a non-derived UNIQUE constraint tagged
+     * `quereus.expose_implicit_index = true`, never materialized in store mode)
+     * must NOT get a synthetic `CREATE INDEX` line — re-import would materialize a
+     * real `IndexSchema` and change the store-mode shape. Its user tags
+     * (`UniqueConstraintSchema.exposedIndexTags`) instead ride a trailing
+     * `alter index … set tags` line, which `importDDL` re-applies silently after
+     * the CREATE TABLE in the same entry has registered the constraint. Empty tag
+     * records emit no line, and `exposedImplicitIndexes` returns `[]` for
+     * memory-mode tables (name materialized) and orders descriptors by the
+     * `uniqueConstraints` array, so the bundle stays byte-deterministic — which
+     * the compare-write in `persistCatalogIfChanged` relies on.
+     */
+    buildCatalogEntry(tableSchema) {
+        // `tableSchema` is always the engine-facing schema (no `_uc_*`; the store keeps the
+        // materialized enforcement copy internal), so hidden implicit indexes reach here
+        // only through the `uniqueConstraints`-driven `isHiddenImplicitIndex` /
+        // `exposedImplicitIndexes` paths — never as a materialized `CREATE INDEX`.
+        const parts = [generateTableDDL(tableSchema)];
+        for (const idx of tableSchema.indexes ?? []) {
+            if (isHiddenImplicitIndex(tableSchema, idx.name))
+                continue;
+            parts.push(generateIndexDDL(idx, tableSchema));
+        }
+        for (const desc of exposedImplicitIndexes(tableSchema)) {
+            if (desc.tags && Object.keys(desc.tags).length > 0) {
+                parts.push(generateIndexTagsDDL(tableSchema.schemaName, desc.name, desc.tags));
+            }
+        }
+        return parts.join('\n');
+    }
+    /**
+     * Encode a bundle of persisted schema text (DDL) for the catalog store.
+     * The guard is {@link assertPersistableDdlText} — see it for why the FULL text
+     * is checked, not just the object's name.
+     */
+    encodeCatalogDDL(ddl) {
+        assertPersistableDdlText(ddl);
+        return new TextEncoder().encode(ddl);
+    }
+    /**
+     * The catalog entry a plain table would be persisted as: its `{schema}.{table}` key
+     * (which {@link buildCatalogKey} refuses for an unencodable identifier) plus the DDL
+     * bundle {@link buildCatalogEntry} produces. Counterpart of {@link viewCatalogEntry} /
+     * {@link maintainedViewCatalogEntry}, and shared the same way — by both write paths
+     * ({@link saveTableDDL}, {@link persistTableCatalogEntryIfChanged}) and by the
+     * pre-flight veto ({@link assertCatalogObjectPersistable}) — so they cannot drift.
+     */
+    tableCatalogEntry(tableSchema) {
+        return {
+            key: buildCatalogKey(tableSchema.schemaName, tableSchema.name),
+            ddl: this.buildCatalogEntry(tableSchema),
+        };
+    }
+    /**
+     * Save table DDL (bundled with its secondary index DDL) to the catalog store.
+     * Unconditional put — every caller has just produced the authoritative bundle
+     * (create-index / drop-index / an `alterTable` arm / `renameTable`). For the
+     * event-driven `table_added` path, which may be re-delivered over an entry that
+     * is already current, use {@link persistTableCatalogEntryIfChanged}.
+     */
+    async saveTableDDL(tableSchema) {
+        const { key, ddl } = this.tableCatalogEntry(tableSchema);
+        const catalogStore = await this.provider.getCatalogStore();
+        await catalogStore.put(key, this.encodeCatalogDDL(ddl));
+    }
+    /**
+     * Compare-write a TABLE's catalog entry: write when the entry is absent or its
+     * bundle differs, skip when identical.
+     *
+     * Two callers, both needing exactly this shape:
+     * - the `table_added` arm of `StoreModuleSchemaSync.dispatchSchemaChange` — the
+     *   authoritative write for a freshly registered store table, including one nobody
+     *   ever reads or writes;
+     * - `StoreTableBase.initializeStore`'s first-storage-access backstop, which the
+     *   `table_added` write normally renders a no-op.
+     *
+     * Distinct from both neighbours on purpose:
+     * - not {@link persistCatalogIfChanged}, whose absent → skip self-filter is exactly
+     *   the case this path exists to cover (a brand-new table has no entry yet);
+     * - not bare {@link saveTableDDL}, which always puts — `table_added` is also
+     *   delivered during rehydration for a store-hosted materialized-view backing, where
+     *   the entry is already current and a blind put would dirty otherwise-identical
+     *   catalog bytes.
+     *
+     * Shares {@link tableCatalogEntry} with the write and veto paths so all three agree
+     * on what a table's entry is.
+     */
+    async persistTableCatalogEntryIfChanged(tableSchema) {
+        const { key, ddl } = this.tableCatalogEntry(tableSchema);
+        await this.persistObjectCatalogEntryIfChanged(key, ddl);
+    }
+    /**
+     * Remove DDL from the catalog store when a table is dropped.
+     */
+    async removeTableDDL(schemaName, tableName) {
+        const catalogKey = buildCatalogKey(schemaName, tableName);
+        const catalogStore = await this.provider.getCatalogStore();
+        await catalogStore.delete(catalogKey);
+    }
+    /**
+     * Persist a plain view's catalog entry (DDL via `generateViewDDL`), keyed by its
+     * reserved view prefix. Compare-write (skip identical) — see
+     * {@link persistObjectCatalogEntryIfChanged}.
+     */
+    async saveViewDDL(view) {
+        const { key, ddl } = viewCatalogEntry(view);
+        await this.persistObjectCatalogEntryIfChanged(key, ddl);
+    }
+    /** Remove a plain view's catalog entry (on DROP VIEW). */
+    async removeViewDDL(schemaName, viewName) {
+        const catalogStore = await this.provider.getCatalogStore();
+        await catalogStore.delete(buildViewCatalogKey(schemaName, viewName));
+    }
+    /**
+     * Persist a materialized view's catalog entry (DDL via `generateMaintainedTableDDL`
+     * over the maintained table — the unified record), keyed by its reserved MV
+     * prefix. Compare-write (skip identical) — see
+     * {@link persistObjectCatalogEntryIfChanged}.
+     */
+    async saveMaterializedViewDDL(mv) {
+        const entry = maintainedViewCatalogEntry(mv);
+        // Callers only reach here with a maintained table; the guard keeps the shared
+        // helper's `undefined` arm honest rather than asserting non-null.
+        if (!entry)
+            return;
+        await this.persistObjectCatalogEntryIfChanged(entry.key, entry.ddl);
+    }
+    /** Remove a materialized view's catalog entry (on DROP MATERIALIZED VIEW). */
+    async removeMaterializedViewDDL(schemaName, mvName) {
+        const catalogStore = await this.provider.getCatalogStore();
+        await catalogStore.delete(buildMaterializedViewCatalogKey(schemaName, mvName));
+    }
+    /**
+     * Pre-flight veto (see `VirtualTableModule.assertCatalogObjectPersistable`): refuse a
+     * view / materialized view / table whose catalog entry this module could not durably
+     * write.
+     *
+     * It runs exactly the derivation the write path runs — {@link viewCatalogEntry} /
+     * {@link maintainedViewCatalogEntry} / {@link tableCatalogEntry} build the key
+     * (rejecting an unencodable identifier) and {@link assertPersistableDdlText} checks the
+     * generated DDL text — so the veto and the write cannot disagree about what is
+     * persistable. It is the only synchronous path a rejection can travel: the actual save
+     * is chained onto `persistQueue` behind a `SchemaChangeNotifier` listener, and both
+     * layers swallow.
+     *
+     * The `'table'` kind arrives only from the RENAME pre-flight scan, which offers EVERY
+     * table in every schema whose record the propagation would rewrite — most of them not
+     * ours. {@link ownsTableCatalogEntry} is the synchronous self-filter that keeps a
+     * memory-backed dependent from being refused on our behalf.
+     *
+     * Gated on `subscribedDb === db`: this module persists a view/MV only while subscribed
+     * to that `Database`'s change notifier. Since `StoreModule.onRegister` subscribes at
+     * `Database.registerModule` — before any statement can run — the gate no longer
+     * shields an unsubscribed module from vetoing; it now only declines to answer on
+     * behalf of a *different* `Database` than the one this module serves (the
+     * one-instance-one-database posture `ensureSchemaSubscription` documents). That case
+     * writes nothing, so vetoing there would reject a definition that loses nothing.
+     */
+    // NOTE: regenerates the object's full DDL text on every CREATE VIEW / CREATE MATERIALIZED
+    // VIEW / view-or-MV SET TAGS, and the persist that follows regenerates it again. DDL is
+    // rare and the text is small, so the duplicate render is not worth caching today; if a
+    // schema-heavy workload (a large `apply schema` deploying many views) ever shows up hot
+    // here, thread the already-built CatalogEntry from the veto through to the write.
+    assertCatalogObjectPersistable(db, kind, object) {
+        if (this.subscribedDb !== db)
+            return;
+        const entry = this.prospectiveCatalogEntry(kind, object);
+        if (entry)
+            assertPersistableDdlText(entry.ddl);
+    }
+    /**
+     * The entry {@link assertCatalogObjectPersistable} is being asked about, or `undefined`
+     * when this module would write none for it (a non-maintained table offered as
+     * `'materializedView'`, or a table we do not own).
+     */
+    prospectiveCatalogEntry(kind, object) {
+        switch (kind) {
+            case 'view': return viewCatalogEntry(object);
+            case 'materializedView': return maintainedViewCatalogEntry(object);
+            case 'table': {
+                const table = object;
+                return this.ownsTableCatalogEntry(table) ? this.tableCatalogEntry(table) : undefined;
+            }
+        }
+    }
+    /**
+     * Whether this module would be the one to write `table`'s catalog entry — the
+     * synchronous stand-in for the write path's absent-entry self-filter (see
+     * {@link persistCatalogIfChanged}), which reads the catalog store and so is unavailable
+     * to a hook that is synchronous and IO-free by contract.
+     *
+     * Also the self-filter for the `table_added` catalog write in
+     * `StoreModuleSchemaSync.dispatchSchemaChange`, which is likewise handed every table the
+     * engine registers regardless of who owns it.
+     *
+     * Ownership is tested exactly as `StoreModule.resolveOwnedTable` tests it: a table this
+     * session already touched (it is in `tables`), or one whose `vtabModule` is this module
+     * — or a WRAPPER exposing this module as `underlying`, which is what a store table looks
+     * like under `@quereus/quereus-isolation` (its `vtabModule` is the `IsolationModule`).
+     * Not ours ⇒ no entry ⇒ no check, which is what keeps a memory-backed dependent table in
+     * a database that also has store tables from being refused.
+     *
+     * It now agrees exactly with the `table_added` write path, which applies this same
+     * filter and then compare-writes ({@link persistTableCatalogEntryIfChanged}) with no
+     * absent → skip. It stays STRICTER than the `table_modified` write path
+     * ({@link persistCatalogIfChanged}), which skips an absent entry; refusing there is the
+     * safe side, since that table's own catalog write would throw on the diverged text
+     * anyway, on the swallowing persist queue with nothing left to tell the user.
+     */
+    ownsTableCatalogEntry(table) {
+        const tableKey = `${table.schemaName}.${table.name}`.toLowerCase();
+        if (this.tables.has(tableKey))
+            return true;
+        const owner = table.vtabModule;
+        return owner === this || owner?.underlying === this;
+    }
+    /**
+     * Compare-write a catalog entry: write only when the entry is absent or its DDL
+     * differs from `newDDL` (skip identical). Unlike {@link persistCatalogIfChanged}
+     * there is **no** absent→skip self-filter — the callers have already established
+     * that the object belongs in this db's catalog (a view/MV unconditionally, since
+     * one module instance serves one Database; a table via
+     * {@link persistTableCatalogEntryIfChanged}'s ownership filter). Skipping identical
+     * writes makes any event whose regenerated DDL is unchanged (e.g. a
+     * `materialized_view_refreshed`, or a `table_added` re-delivered for an
+     * already-persisted materialized-view backing during rehydration) a no-op, so a
+     * second consecutive reopen yields identical catalog bytes. (View/MV rehydration
+     * itself fires no view/MV events at all — `importCatalog` is silent.)
+     */
+    async persistObjectCatalogEntryIfChanged(key, newDDL) {
+        const catalogStore = await this.provider.getCatalogStore();
+        const existing = await catalogStore.get(key);
+        if (existing !== undefined && new TextDecoder().decode(existing) === newDDL)
+            return;
+        await catalogStore.put(key, this.encodeCatalogDDL(newDDL));
+    }
+    /**
+     * Read-compare-write the catalog DDL for a table that just fired `table_modified`.
+     *
+     * - **Absent** catalog entry → the table is not store-backed in this catalog (a
+     *   memory table in the same `db`, or a store table never persisted) → skip. This
+     *   self-filters foreign-module tables without relying on `vtabModule` identity
+     *   (which points at the isolation wrapper when wrapped).
+     * - **Present** but identical DDL → skip (no redundant write). This is what makes a
+     *   structural ALTER — whose own `alterTable` already wrote the final DDL, then fires
+     *   `table_modified` with that same final schema — a no-op here (no double-write).
+     * - **Present** and different DDL → re-persist (the tag swap; or a beneficial
+     *   propagated rewrite of a dependent store table).
+     */
+    async persistCatalogIfChanged(key, newObject) {
+        const catalogStore = await this.provider.getCatalogStore();
+        const existing = await catalogStore.get(key);
+        if (existing === undefined)
+            return; // not store-backed in this catalog — skip
+        // Regenerate the full bundle (table DDL + index DDL + exposed-implicit-index
+        // tag DDL): a SET TAGS on an index fires `table_modified` on the OWNING table
+        // with the updated index in `tableSchema.indexes` — or, for an exposed
+        // implicit index, with the updated `exposedIndexTags` on the originating
+        // UNIQUE constraint — so the changed DDL re-persists here with no
+        // index-specific plumbing. An identical bundle is what makes a structural
+        // ALTER (and the createIndex follow-up event) a no-op — no double-write.
+        const newDDL = this.buildCatalogEntry(newObject);
+        const existingDDL = new TextDecoder().decode(existing);
+        if (existingDDL === newDDL)
+            return; // identical — no redundant write
+        await catalogStore.put(key, this.encodeCatalogDDL(newDDL));
+    }
+    /**
+     * Load all DDL **values** from the catalog store (keys discarded).
+     * Used to restore persisted tables on startup and by tests asserting persisted DDL.
+     * Note: this returns table, view, AND materialized-view entries intermixed —
+     * `StoreModuleSchemaSync.rehydrateCatalog` uses {@link loadCatalogEntries} (keys retained) to
+     * classify them. Meta entries (e.g. the clean-shutdown marker) are not DDL
+     * and are filtered out.
+     */
+    async loadAllDDL() {
+        const catalogStore = await this.provider.getCatalogStore();
+        const bounds = buildCatalogScanBounds();
+        const decoder = new TextDecoder();
+        const ddlStatements = [];
+        for await (const entry of catalogStore.iterate(bounds)) {
+            if (classifyCatalogKey(entry.key) === 'meta')
+                continue;
+            const ddl = decoder.decode(entry.value);
+            ddlStatements.push(ddl);
+        }
+        return ddlStatements;
+    }
+    /**
+     * Load every catalog entry as `{ key, ddl }`. Unlike {@link loadAllDDL} (values
+     * only) this retains the key so `StoreModuleSchemaSync.rehydrateCatalog` can classify each entry
+     * (table / view / materialized view) by its reserved key prefix.
+     */
+    async loadCatalogEntries() {
+        const catalogStore = await this.provider.getCatalogStore();
+        const decoder = new TextDecoder();
+        const entries = [];
+        for await (const entry of catalogStore.iterate(buildCatalogScanBounds())) {
+            entries.push({ key: entry.key, ddl: decoder.decode(entry.value) });
+        }
+        return entries;
+    }
+    /**
+     * Consume the clean-shutdown marker, deleting it in the same breath (single-use).
+     *
+     * Returns `{ trusted, staleAtClose }`:
+     * - `trusted` — the marker was present AND its payload parsed as a string array.
+     *   Absence (a fresh store, a crash, or a prior rehydrate without an intervening
+     *   `StoreModule.closeAll`) yields `false`, so every adopt this session falls back to
+     *   refill.
+     * - `staleAtClose` — the qualified lowercased `schema.mv` names that were
+     *   stale-at-close (written by `StoreModule.closeAll`); those MVs refill even under trust.
+     *
+     * Conservative parse: any unparseable / wrong-shape payload (including a legacy
+     * bare `'1'`, which parses to a number, not an array) degrades to
+     * `{ trusted: false, staleAtClose: ∅ }` — refill everything — rather than
+     * trust-everything. The marker is deleted regardless of parse outcome.
+     */
+    async consumeCleanShutdownMarker() {
+        const catalogStore = await this.provider.getCatalogStore();
+        const markerKey = buildMetaCatalogKey(CLEAN_SHUTDOWN_META_NAME);
+        const raw = await catalogStore.get(markerKey);
+        if (raw === undefined)
+            return { trusted: false, staleAtClose: new Set() };
+        // Single-use AND durable-before-session-writes: forcing this delete to stable
+        // storage before any of the session's (independently flushed, different-store)
+        // data writes can land closes the power-loss window where a persisted data write
+        // outlives a lost marker-delete and resurrects a consumed marker. (Backends
+        // without a durability knob no-op the hint — losing it is conservative there, and
+        // memory has no crash.) See docs/mv-backing-host.md § Cross-module atomicity.
+        await catalogStore.delete(markerKey, { sync: true }); // single-use, regardless of parse outcome
+        try {
+            const parsed = JSON.parse(new TextDecoder().decode(raw));
+            if (!Array.isArray(parsed) || !parsed.every((s) => typeof s === 'string')) {
+                console.warn('[StoreModule] clean-shutdown marker payload is not a string array; refilling all backings.');
+                return { trusted: false, staleAtClose: new Set() };
+            }
+            return { trusted: true, staleAtClose: new Set(parsed) };
+        }
+        catch (e) {
+            console.warn(`[StoreModule] clean-shutdown marker payload did not parse as JSON; refilling all backings: ${e instanceof Error ? e.message : String(e)}`);
+            return { trusted: false, staleAtClose: new Set() };
+        }
+    }
+    /**
+     * Write the durable stale-MV set (`\x00meta\x00stale_mvs`) with `sync: true`. Unlike
+     * the clean-shutdown marker this entry is persistent current-truth — overwritten as
+     * staleness changes, never deleted — so a crash leaves the last synced value intact.
+     * The `sync` mirrors the marker-consume delete's durability discipline (and carries
+     * the same documented backend caveat: a backend without a durability knob no-ops it).
+     */
+    async writeDurableStaleMvSet(json) {
+        const catalogStore = await this.provider.getCatalogStore();
+        await catalogStore.put(buildMetaCatalogKey(STALE_MVS_META_NAME), new TextEncoder().encode(json), { sync: true });
+    }
+    /**
+     * Read + conservative-parse the durable stale-MV set, mirroring
+     * {@link consumeCleanShutdownMarker}'s parse discipline (but READ-only — never
+     * deleted). Returns:
+     * - `{ present: false }` — no entry on disk (a pre-atomic store, or an upgrade where
+     *   the capability was gained but no stale-set has been written yet) → the caller
+     *   falls back to the clean-shutdown marker path.
+     * - `{ present: true, stale }` — the parsed set of qualified `schema.mv` names.
+     * - `{ present: true, stale: null }` — a present but unparseable / wrong-shape payload
+     *   → the caller refills everything (the always-safe posture).
+     */
+    async readDurableStaleMvSet() {
+        const catalogStore = await this.provider.getCatalogStore();
+        const raw = await catalogStore.get(buildMetaCatalogKey(STALE_MVS_META_NAME));
+        if (raw === undefined)
+            return { present: false };
+        try {
+            const parsed = JSON.parse(new TextDecoder().decode(raw));
+            if (!Array.isArray(parsed) || !parsed.every((s) => typeof s === 'string')) {
+                console.warn('[StoreModule] durable stale-MV set payload is not a string array; refilling all backings.');
+                return { present: true, stale: null };
+            }
+            return { present: true, stale: new Set(parsed) };
+        }
+        catch (e) {
+            console.warn(`[StoreModule] durable stale-MV set payload did not parse as JSON; refilling all backings: ${e instanceof Error ? e.message : String(e)}`);
+            return { present: true, stale: null };
+        }
+    }
+}
+//# sourceMappingURL=store-module-catalog.js.map

package/dist/src/common/store-module-catalog.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"store-module-catalog.js","sourceRoot":"","sources":["../../../src/common/store-module-catalog.ts"],"names":[],"mappings":"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"}

package/dist/src/common/store-module-index-build.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Standalone index-population and uniqueness-validation helpers: streaming a table's
+ * committed rows into a secondary index's physical store in bounded batches, and the
+ * duplicate probes that judge a UNIQUE constraint or UNIQUE index against a row stream
+ * before it is enforced.
+ *
+ * Free functions rather than a layer of the store-module chain — none of them reads
+ * module state; each takes the stores and schema it needs.
+ */
+import type { EffectiveRowSource, KeyNormalizerResolver, Row, TableIndexSchema, TableSchema, UniqueConstraintSchema } from '@quereus/quereus';
+import type { KVEntry, KVStore } from './kv-store.js';
+import type { StoreTable } from './store-table.js';
+/**
+ * Build index entries for all existing rows in a table.
+ *
+ * `dataEntries` is the row stream to index. Callers choose its visibility:
+ * `createIndex` passes the table's EFFECTIVE stream (committed + pending, so
+ * an open transaction's rows are indexed too), while `rebuildSecondaryIndexes`
+ * passes the raw committed stream — it runs immediately after an ALTER has
+ * re-encoded the data store in place, and any pending ops still address the
+ * pre-ALTER key bytes.
+ *
+ * For UNIQUE indexes, performs an in-pass duplicate check (honoring partial
+ * predicates and SQL NULL semantics: multiple NULLs are allowed) and throws
+ * CONSTRAINT before any entries are written. Mirrors the memory module's
+ * populateNewIndex so `CREATE UNIQUE INDEX` over duplicated data fails
+ * atomically. `skipDuplicateCheck` suppresses it: `createIndex` sets it when a
+ * wrapper module supplied the rows to judge, having already validated them (see
+ * {@link validateUniqueIndexOverRows}). Judging `dataEntries` too would reject a
+ * committed duplicate the wrapper's transaction has already deleted.
+ *
+ * `normalizers` MUST be the owning connection's `db.getKeyNormalizerResolver()` —
+ * the same resolver `StoreTable.encodeOptions` carries. A rebuild that resolved
+ * collations any other way would re-encode the PK suffix under different bytes than
+ * the table writes at maintenance time, silently corrupting the index.
+ */
+export declare function buildIndexEntries(dataEntries: AsyncIterable<KVEntry>, indexStore: KVStore, tableSchema: TableSchema, indexSchema: TableIndexSchema, keyCollation: string, normalizers: KeyNormalizerResolver, skipDuplicateCheck?: boolean, maxBatchBytes?: number): Promise<void>;
+/**
+ * Validates `rows` against a UNIQUE constraint, throwing `CONSTRAINT` on the first
+ * duplicate before any schema mutation. Used by `ADD CONSTRAINT UNIQUE` (validate
+ * against the current collation) and by `SET COLLATE` (pass an `updatedSchema` whose
+ * altered column carries the NEW collation, so the dedup is performed under it).
+ * Mirrors the duplicate detection in {@link buildIndexEntries}: a `seen` Set keyed on
+ * a per-column collation-aware signature of the constrained values, with SQL NULL
+ * semantics (a row with any NULL constrained value never counts as a duplicate) and
+ * the partial `predicate` honored.
+ *
+ * `rows` MUST be the rows the DDL-issuing connection can SEE. Ordinarily that is this
+ * table's EFFECTIVE stream (committed rows merged with the open transaction's own
+ * pending puts/deletes — `StoreTable.iterateEffectiveEntries`, adapted by
+ * {@link rowsFromEntries}); when a wrapper module holds the pending rows outside this
+ * module it hands them down as an `EffectiveRowSource` instead. Either way, a
+ * committed-only stream would let a duplicate inserted earlier in the same transaction
+ * slip past validation and land in the table once the transaction commits.
+ *
+ * No index store is written — store UNIQUE enforcement is a full-scan over
+ * `uniqueConstraints` at write time. The signature is built by
+ * {@link dedupeRowSignature} with one normalizer per constrained column, resolved from
+ * `tableSchema.columns[idx].collation` through the connection's
+ * `db.getKeyNormalizerResolver()`, so a per-column collation registered with
+ * `db.registerCollation` is honored (matching write-time `compareSqlValues`
+ * enforcement). A comparator-only collation raises: rows that cannot be bucketed
+ * cannot be deduped. Columns whose declared type can never hold text take the
+ * identity normalizer and so never raise.
+ */
+export declare function validateUniqueOverExistingRows(rows: AsyncIterable<Row>, tableSchema: TableSchema, uc: UniqueConstraintSchema, keyNormalizers: KeyNormalizerResolver): Promise<void>;
+/**
+ * Index-shaped twin of {@link validateUniqueOverExistingRows}, used by
+ * `StoreModuleIndex.createIndex` when a wrapper module supplies the rows to judge. Dedupes on the
+ * index's own columns under the index column's COLLATE (falling back to the table
+ * column's), so it enforces exactly what `buildIndexEntries`' suppressed in-pass check
+ * would have — over the wrapper's rows instead of this module's committed ones.
+ */
+export declare function validateUniqueIndexOverRows(rows: AsyncIterable<Row>, tableSchema: TableSchema, indexSchema: TableIndexSchema, keyNormalizers: KeyNormalizerResolver): Promise<void>;
+/** Adapts a raw KV entry stream into the row stream the uniqueness validators consume. */
+export declare function rowsFromEntries(entries: AsyncIterable<KVEntry>): AsyncIterable<Row>;
+/**
+ * The rows a DDL-issuing connection can SEE, as every pre-mutation probe in the ALTER
+ * path needs them: a wrapper module's `EffectiveRowSource` when the isolation layer
+ * holds this transaction's staged rows outside the store, else this table's own
+ * effective stream (committed rows merged with the module's buffered puts/deletes).
+ *
+ * One fresh stream per call — an async generator is single-shot, and an
+ * `EffectiveRowSource` is re-callable for exactly that reason, so a probe that needs
+ * two walks calls this twice.
+ */
+export declare function effectiveDdlRows(table: StoreTable, rows?: EffectiveRowSource): AsyncIterable<Row>;
+//# sourceMappingURL=store-module-index-build.d.ts.map

package/dist/src/common/store-module-index-build.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store-module-index-build.d.ts","sourceRoot":"","sources":["../../../src/common/store-module-index-build.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAEX,kBAAkB,EAElB,qBAAqB,EACrB,GAAG,EAEH,gBAAgB,EAChB,WAAW,EACX,sBAAsB,EACtB,MAAM,kBAAkB,CAAC;AAE1B,OAAO,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAUtD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAOnD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAsB,iBAAiB,CACtC,WAAW,EAAE,aAAa,CAAC,OAAO,CAAC,EACnC,UAAU,EAAE,OAAO,EACnB,WAAW,EAAE,WAAW,EACxB,WAAW,EAAE,gBAAgB,EAC7B,YAAY,EAAE,MAAM,EACpB,WAAW,EAAE,qBAAqB,EAClC,kBAAkB,UAAQ,EAC1B,aAAa,GAAE,MAAgC,GAC7C,OAAO,CAAC,IAAI,CAAC,CA4Gf;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAsB,8BAA8B,CACnD,IAAI,EAAE,aAAa,CAAC,GAAG,CAAC,EACxB,WAAW,EAAE,WAAW,EACxB,EAAE,EAAE,sBAAsB,EAC1B,cAAc,EAAE,qBAAqB,GACnC,OAAO,CAAC,IAAI,CAAC,CAWf;AAED;;;;;;GAMG;AACH,wBAAsB,2BAA2B,CAChD,IAAI,EAAE,aAAa,CAAC,GAAG,CAAC,EACxB,WAAW,EAAE,WAAW,EACxB,WAAW,EAAE,gBAAgB,EAC7B,cAAc,EAAE,qBAAqB,GACnC,OAAO,CAAC,IAAI,CAAC,CAQf;AAED,0FAA0F;AAC1F,wBAAuB,eAAe,CAAC,OAAO,EAAE,aAAa,CAAC,OAAO,CAAC,GAAG,aAAa,CAAC,GAAG,CAAC,CAI1F;AAED;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,UAAU,EAAE,IAAI,CAAC,EAAE,kBAAkB,GAAG,aAAa,CAAC,GAAG,CAAC,CAEjG"}