@quereus/store 4.5.0 → 4.6.0

package/dist/src/common/store-module-index-build.js

@@ -0,0 +1,280 @@
+/**
+ * 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 { QuereusError, StatusCode, compilePredicate, logicalTypeCanHoldText, serializeKey } from '@quereus/quereus';
+import { resolveIndexKeyCollations, resolveDedupeKeyTransforms, resolveIndexKeyTransforms, resolvePkKeyCollations, resolvePkKeyTransforms, } from './pk-key-resolution.js';
+import { buildDataKey, buildFullScanBounds, buildIndexKey } from './key-builder.js';
+import { deserializeRow } from './serialization.js';
+// NOTE: this one constant is the only thing tying this file to the module chain (the graph
+// stays acyclic — the base layer is a leaf). If these helpers ever need to be usable without
+// loading the chain, move `DEFAULT_MAX_BATCH_BYTES` to a constants leaf and have the base
+// import it from there instead.
+import { DEFAULT_MAX_BATCH_BYTES } from './store-module-base.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 async function buildIndexEntries(dataEntries, indexStore, tableSchema, indexSchema, keyCollation, normalizers, skipDuplicateCheck = false, maxBatchBytes = DEFAULT_MAX_BATCH_BYTES) {
+    // Both halves key per-column: each index COLUMN under its own key collation
+    // (`resolveIndexKeyCollations` — index COLLATE ?? table column collation ?? BINARY)
+    // and the PK SUFFIX under each PK column's own key collation, so the suffix bytes
+    // match the data-store keys — and both halves match
+    // `StoreTable.updateSecondaryIndexes`' maintenance writes exactly. Those two call
+    // sites are the pair whose drift silently corrupts an index; change one and the
+    // other must change with it. `keyCollation` (the table key collation K) remains
+    // only as the `EncodeOptions` fallback for entries the resolvers leave undefined.
+    const encodeOptions = { collation: keyCollation, normalizers };
+    const pkDirections = tableSchema.primaryKeyDefinition.map(pk => !!pk.desc);
+    const pkCollations = resolvePkKeyCollations(tableSchema.primaryKeyDefinition, tableSchema.columns, keyCollation);
+    const indexCollations = resolveIndexKeyCollations(indexSchema, tableSchema.columns);
+    // Key-identity transforms for both halves, mirroring `StoreTable`'s maintenance
+    // writes (`updateSecondaryIndexes` / `encodeDataKey`) — a rebuild that skipped them
+    // would re-encode a TIMESPAN member under different bytes than DML writes.
+    const pkTransforms = resolvePkKeyTransforms(tableSchema.primaryKeyDefinition, tableSchema.columns);
+    const indexTransforms = resolveIndexKeyTransforms(indexSchema, tableSchema.columns);
+    const indexDirections = indexSchema.columns.map(col => !!col.desc);
+    const predicate = indexSchema.predicate
+        ? compilePredicate(indexSchema.predicate, tableSchema.columns, tableSchema.name)
+        : undefined;
+    // NOTE: `seen` holds one signature per DISTINCT indexed key for the WHOLE build and
+    // is NOT bounded by the maxBatchBytes chunking below (that bounds only the write
+    // batch). A very large UNIQUE index still spikes memory on this set. Bounding it
+    // needs a sort- or store-probe-based dedup (a separate design), not a batch knob.
+    const seen = (indexSchema.unique && !skipDuplicateCheck) ? new Set() : undefined;
+    const indexColIndices = indexSchema.columns.map(col => col.index);
+    const indexNormalizers = seen
+        ? indexDedupeNormalizers(tableSchema, indexSchema, normalizers)
+        : undefined;
+    // Deliberately NOT `indexTransforms`: the dedupe signature must reproduce
+    // `JSON_TYPE.compare`'s collation-honoring string-scalar case (which `serializeKey`'s
+    // normalizer applies), while `indexTransforms` stays the hard-structural physical key
+    // bytes `buildIndexKey` persists. See `storeDedupeKeyTransform`'s docstring.
+    const dedupeTransforms = seen
+        ? resolveDedupeKeyTransforms(indexColIndices, tableSchema.columns)
+        : undefined;
+    let batch = indexStore.batch();
+    // Serialized key bytes accumulated in the CURRENT batch. Flushed and reset once it
+    // crosses maxBatchBytes so a table larger than memory never buffers its whole index.
+    let batchBytes = 0;
+    for await (const entry of dataEntries) {
+        const row = deserializeRow(entry.value);
+        // Partial index: skip rows whose predicate is not unambiguously TRUE.
+        if (predicate && predicate.evaluate(row) !== true)
+            continue;
+        // Extract PK values
+        const pkValues = tableSchema.primaryKeyDefinition.map(pk => row[pk.index]);
+        // Extract index column values
+        const indexValues = indexSchema.columns.map(col => row[col.index]);
+        if (seen) {
+            // The signature returns null when any indexed column is NULL —
+            // SQL UNIQUE allows multiple NULLs, so those rows never collide.
+            const keySig = dedupeRowSignature(row, indexColIndices, indexNormalizers, dedupeTransforms);
+            if (keySig !== null) {
+                if (seen.has(keySig)) {
+                    const colNames = indexSchema.columns
+                        .map(c => tableSchema.columns[c.index]?.name ?? String(c.index))
+                        .join(', ');
+                    throw new QuereusError(`UNIQUE constraint failed: ${tableSchema.name} (${colNames})`, StatusCode.CONSTRAINT);
+                }
+                seen.add(keySig);
+            }
+        }
+        // Build and store index key
+        const indexKey = buildIndexKey({ values: indexValues, directions: indexDirections, collations: indexCollations, transforms: indexTransforms }, { values: pkValues, directions: pkDirections, collations: pkCollations, transforms: pkTransforms }, encodeOptions);
+        // Index value = the row's encoded DATA key, so an index scan resolves each
+        // entry back to its base row via a direct data-store read (see
+        // `StoreTable.scanIndex`). Encoded under the same PK directions + per-column
+        // PK collations + key transforms as `buildDataKey` / `updateSecondaryIndexes`,
+        // so the value byte-matches the data store's key for this row.
+        const dataKey = buildDataKey(pkValues, encodeOptions, pkDirections, pkCollations, pkTransforms);
+        batch.put(indexKey, dataKey);
+        // Bound heap: once the accumulated serialized key bytes cross the budget, flush
+        // the batch and start a fresh one. Both callers ITERATE the data store and WRITE
+        // the index store — different stores — so a mid-stream flush never mutates the
+        // stream being read, and this is safe on every provider. A mid-stream flush
+        // failure in `createIndex` is torn down by its try/catch (the whole fresh index
+        // store is deleted); in `rebuildSecondaryIndexes` it leaves a partial-but-
+        // recoverable index (re-run the rebuild — clear + rebuild is idempotent).
+        batchBytes += indexKey.length + dataKey.length;
+        if (batchBytes >= maxBatchBytes) {
+            await batch.write();
+            batch = indexStore.batch();
+            batchBytes = 0;
+        }
+    }
+    // Final flush of the residual. May be empty (an empty table, or a build whose last
+    // row exactly hit the budget and flushed) — providers accept an empty write.
+    await batch.write();
+}
+/**
+ * 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 async function validateUniqueOverExistingRows(rows, tableSchema, uc, keyNormalizers) {
+    await assertNoDuplicateRows(rows, tableSchema, uc.columns, uc.columns.map(idx => {
+        const column = tableSchema.columns[idx];
+        return keyNormalizers(logicalTypeCanHoldText(column.logicalType) ? column.collation : undefined);
+    }), uc.predicate ? compilePredicate(uc.predicate, tableSchema.columns, tableSchema.name) : undefined);
+}
+/**
+ * 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 async function validateUniqueIndexOverRows(rows, tableSchema, indexSchema, keyNormalizers) {
+    await assertNoDuplicateRows(rows, tableSchema, indexSchema.columns.map(col => col.index), indexDedupeNormalizers(tableSchema, indexSchema, keyNormalizers), indexSchema.predicate ? compilePredicate(indexSchema.predicate, tableSchema.columns, tableSchema.name) : undefined);
+}
+/** Adapts a raw KV entry stream into the row stream the uniqueness validators consume. */
+export async function* rowsFromEntries(entries) {
+    for await (const entry of entries) {
+        yield deserializeRow(entry.value);
+    }
+}
+/**
+ * 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 function effectiveDdlRows(table, rows) {
+    return rows ? rows() : rowsFromEntries(table.iterateEffectiveEntries(buildFullScanBounds()));
+}
+/**
+ * Per-column key normalizers for a UNIQUE INDEX dedupe signature, drawing each column's
+ * collation from the index column (if it carries one) else the underlying table column —
+ * so the signature honors a per-column collation registered on this connection, matching
+ * write-time enforcement.
+ *
+ * A column whose declared type can never hold text takes the identity normalizer regardless
+ * of its collation (the signature serializer normalizes only string values), so a comparator-only
+ * collation named on an integer column is not rejected here when the engine's own hash sites
+ * would accept it.
+ *
+ * NOTE: a JSON (or other collation-blind-but-text-capable) index column with a
+ * comparator-only custom collation (registered with no key normalizer) passes DDL —
+ * `assertIndexKeyCollationsCanKey` checks `resolveIndexKeyCollations`, which keys such a
+ * column hard-`BINARY` regardless of the declared name, and `BINARY` always has a
+ * normalizer — but THIS resolver looks up the column's own declared name (JSON can hold
+ * text, so it takes the textual branch above), and `keyNormalizers` throws for a name with
+ * no registered normalizer. The DDL-time check and this one are asking two different
+ * questions (can the physical key encode vs. can the dedupe signature encode) and can
+ * disagree. Confirmed by inspection, not exercised by a test: this surfaces as a thrown
+ * error at `CREATE UNIQUE INDEX` — confusing, since the same statement's key-collation gate
+ * just passed — but not a correctness hole (no bad state is built). If this needs a
+ * friendlier message, that is a follow-up, not implied by this ticket.
+ */
+function indexDedupeNormalizers(tableSchema, indexSchema, keyNormalizers) {
+    return indexSchema.columns.map(col => {
+        const column = tableSchema.columns[col.index];
+        return keyNormalizers(logicalTypeCanHoldText(column.logicalType)
+            ? (col.collation ?? column.collation)
+            : undefined);
+    });
+}
+/**
+ * Collation- and identity-aware dedupe signature of `row` over `colIndices`: each value
+ * runs through its column's key transform (`storeDedupeKeyTransform` — TIMESPAN's
+ * total-seconds `groupKey`, so 'PT1H' and 'PT60M' sign identically; JSON's structural
+ * bytes for everything but a string scalar, so reorder-equal objects sign identically
+ * while a string scalar is left for `serializeKey`'s normalizer) before `serializeKey`
+ * applies the per-column normalizer. Returns null when any covered value
+ * is NULL (SQL UNIQUE allows multiple NULLs). The build/validate-time twin of the
+ * write-time typed compare in `StoreTable.uniqueColumnComparators`.
+ *
+ * NOTE: `transforms` normalizes STRING values only through `serializeKey`'s collation
+ * normalizer — a transform whose output is a `Uint8Array` (as `storeSemanticKeyTransform`
+ * would produce) bypasses that normalizer entirely (`serializeKey` tags a byte array
+ * `x:` and never consults it). So any future semantic-ordering logical type that BOTH
+ * carries a key transform AND honors a collation in its `compare` (like JSON_TYPE) needs
+ * its own `storeDedupeKeyTransform` branch, or its build-time UNIQUE check silently
+ * degrades to BINARY while the write-time check honors the collation.
+ */
+function dedupeRowSignature(row, colIndices, normalizers, transforms) {
+    const values = colIndices.map((c, i) => {
+        const v = row[c];
+        const transform = transforms[i];
+        return transform && v !== null ? transform(v) : v;
+    });
+    return serializeKey(values, normalizers);
+}
+/**
+ * Throws CONSTRAINT on the first pair of `rows` that share a signature over `columnIndices`.
+ *
+ * SQL NULL semantics: {@link dedupeRowSignature} returns null when any constrained column is
+ * NULL, and such rows never collide. A partial `predicate` restricts the judged set to rows
+ * it accepts unambiguously. Shared by {@link validateUniqueOverExistingRows}
+ * (constraint columns) and {@link validateUniqueIndexOverRows} (index columns).
+ */
+async function assertNoDuplicateRows(rows, tableSchema, columnIndices, normalizers, predicate) {
+    const transforms = resolveDedupeKeyTransforms(columnIndices, tableSchema.columns);
+    const seen = new Set();
+    for await (const row of rows) {
+        if (predicate && predicate.evaluate(row) !== true)
+            continue;
+        const keySig = dedupeRowSignature(row, columnIndices, normalizers, transforms);
+        if (keySig === null)
+            continue;
+        if (seen.has(keySig)) {
+            const colNames = columnIndices.map(i => tableSchema.columns[i]?.name ?? String(i)).join(', ');
+            throw new QuereusError(`UNIQUE constraint failed: ${tableSchema.name} (${colNames})`, StatusCode.CONSTRAINT);
+        }
+        seen.add(keySig);
+    }
+}
+//# sourceMappingURL=store-module-index-build.js.map

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

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

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

@@ -0,0 +1,116 @@
+/**
+ * CREATE INDEX / DROP INDEX over a store-backed table, and the physical index stores
+ * they bring into (and out of) existence — including the hidden `_uc_*` stores that
+ * back a plain UNIQUE constraint, whose set is reconciled against the schema after
+ * every DDL that can change it.
+ *
+ * Fourth layer of the store-module chain:
+ *   StoreModuleBase -> StoreModuleCatalog -> StoreModuleSchemaSync -> StoreModuleIndex
+ *   -> StoreModuleAlterColumn -> StoreModuleAlter -> StoreModuleRename -> StoreModule
+ */
+import type { Database, EffectiveRowSource, KeyNormalizerResolver, TableIndexSchema, TableSchema } from '@quereus/quereus';
+import { StoreTable } from './store-table.js';
+import { StoreModuleSchemaSync } from './store-module-schema-sync.js';
+export declare abstract class StoreModuleIndex extends StoreModuleSchemaSync {
+    /**
+     * Creates an index on a store-backed table.
+     *
+     * `rows` — an {@link EffectiveRowSource} supplied by a wrapper module (the isolation
+     * layer) — replaces this module's own rows as the set the UNIQUE duplicate check judges.
+     * When present the check runs UP FRONT, before `getIndexStore` opens the index-store
+     * directory, so a rejection leaves no directory behind; and `buildIndexEntries` then
+     * populates the physical index from this module's own (committed) rows with its in-pass
+     * dup check disabled. Those two row sets legitimately differ — the wrapper's transaction
+     * may have deleted a committed duplicate — and an index entry with no live row behind it
+     * is harmless (see the entry-resolution note in `buildIndexEntries`).
+     */
+    createIndex(db: Database, schemaName: string, tableName: string, indexSchema: TableIndexSchema, rows?: EffectiveRowSource): Promise<void>;
+    /**
+     * Drops an index on a store-backed table.
+     *
+     * Mirrors createIndex: refreshes the connected StoreTable's cached
+     * tableSchema (removing the index entry and any UNIQUE constraint
+     * synthesized from it, tagged with `derivedFromIndex`), releases the
+     * cached index-store handle, and tears down the underlying index store.
+     */
+    dropIndex(db: Database, schemaName: string, tableName: string, indexName: string): Promise<void>;
+    /**
+     * Clear and rebuild every secondary index of `schema` against the (already
+     * re-encoded) data store. Secondary-index keys embed the PK suffix, so they must
+     * be rewritten whenever the data-store PK key bytes change — which happens both
+     * on `ALTER PRIMARY KEY` (the PK columns change) and on an `ALTER COLUMN … SET
+     * COLLATE` on a PK member (a PK column's key collation changes). Shared by both
+     * arms so the clear-then-rebuild stays identical. `schema` must already be the
+     * post-ALTER schema (its `primaryKeyDefinition` + column collations drive the new
+     * PK-suffix encoding via {@link buildIndexEntries}). `normalizers` is the owning
+     * connection's `db.getKeyNormalizerResolver()` — see {@link buildIndexEntries}.
+     *
+     * NOTE: reads the data store committed-only and writes the index stores outside the
+     * coordinator. Sound only because every caller calls `StoreModuleBase.ddlCommitPendingOps`
+     * first, so this module's "committed" is "everything live". A caller that skips that
+     * flush would rebuild an index missing its transaction's pending rows.
+     *
+     * `skipDuplicateCheck` suppresses {@link buildIndexEntries}' in-pass UNIQUE check.
+     * Both ALTER COLUMN rebuild callers set it — the value-rewriting / key-transform
+     * arm and the PK re-key arm (`SET COLLATE` on a PK member): each runs a
+     * pre-mutation UNIQUE re-validation that already judged the ISSUING connection's
+     * effective rows (a wrapper's overlay included), and this rebuild sees only THIS
+     * module's committed rows — a set that may retain a row the wrapper's transaction
+     * has deleted, so judging it here would spuriously reject a duplicate pair the
+     * probe correctly accepted (and, worse, reject AFTER the data store was already
+     * re-keyed). Mirrors the memory module's deliberately non-enforcing base rebuild
+     * (the probe is the only guard). `ALTER PRIMARY KEY`'s rebuild still enforces:
+     * that arm has no effective-row UNIQUE probe of its own.
+     */
+    protected rebuildSecondaryIndexes(schemaName: string, tableName: string, table: StoreTable, schema: TableSchema, normalizers: KeyNormalizerResolver, skipDuplicateCheck?: boolean): Promise<void>;
+    /**
+     * Build / tear down the physical index stores backing implicit UNIQUE indexes
+     * (`_uc_*`) after a DDL statement, by diffing the implicit-index NAMES the old vs
+     * new schema call for ({@link implicitUniqueIndexNameMap}):
+     *   - a name newly PRESENT (ADD CONSTRAINT UNIQUE, the target half of a
+     *     RENAME CONSTRAINT / rename of an unnamed UC's column, or a DROP INDEX that
+     *     retires the explicit index a UNIQUE was reusing) has its physical store
+     *     populated from this module's effective rows;
+     *   - a name newly ABSENT (DROP CONSTRAINT UNIQUE, the source half of a rename, or
+     *     a CREATE INDEX whose new index now realizes the UNIQUE) has its store torn
+     *     down, so nothing maintains it and a later rebuild does not reopen stale
+     *     entries.
+     *
+     * The SCHEMA entry itself is materialized/removed by `withImplicitUniqueIndexes`
+     * on the caller's `table.updateSchema`; only the physical store needs this. Called
+     * after every ALTER TABLE and after `createIndex` / `dropIndex`, and a no-op
+     * whenever the implicit-index name set is unchanged — the common case, including
+     * every PK / collation / data-type ALTER (whose same-name physical re-encode is
+     * already done by {@link rebuildSecondaryIndexes}) and every CREATE / DROP INDEX
+     * that does not cover a plain UNIQUE's columns.
+     *
+     * `oldSchema` is the pre-DDL schema: its `uniqueConstraints` give the old names and
+     * its `.indexes` the old reuse decisions. Either the engine-facing or the
+     * materialized copy works — `findReusableIndexForUnique` skips a constraint's own
+     * `_uc_*`, so a materialized input yields the same name set.
+     *
+     * NOTE: the build populates from THIS module's own effective rows (committed + this
+     * transaction's pending), never a wrapper's — mirroring `createIndex`. Under the
+     * isolation layer the wrapper's rows are what ADD CONSTRAINT's validation judged;
+     * the physical index legitimately fills from this module's committed rows and an
+     * entry with no live row behind it is harmless (both readers resolve to the live
+     * row). Duplicates were already rejected by `validateUniqueOverExistingRows` (ADD)
+     * or cannot exist (RENAME leaves data unchanged), so the in-pass check is skipped.
+     */
+    protected reconcileImplicitUniqueIndexStores(db: Database, schemaName: string, tableName: string, table: StoreTable, oldSchema: TableSchema): Promise<void>;
+    /**
+     * Close + delete one index's physical store: release the table's cached handle, then
+     * `deleteIndexStore` when the provider implements it (it closes the handle before
+     * removing the directory), else just `closeIndexStore`.
+     *
+     * The single teardown every path shares — `dropIndex`, `createIndex`'s build-failure
+     * rollback, the implicit `_uc_*` reconcile above, and `DROP COLUMN`'s removed-index
+     * pass (`StoreModuleAlter.alterDropColumn`). Each caller owns the surrounding
+     * posture, which deliberately differs: the DDL-commit flush (buffered ops are keyed
+     * on the KVStore HANDLE, so a doomed store's queued ops would replay into a closed
+     * store at commit — see `StoreModuleBase.ddlCommitPendingOps`) and, for
+     * `createIndex`, swallowing a teardown throw so it cannot mask the build error.
+     */
+    protected tearDownIndexStore(schemaName: string, tableName: string, table: StoreTable, indexName: string): Promise<void>;
+}
+//# sourceMappingURL=store-module-index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"store-module-index.d.ts","sourceRoot":"","sources":["../../../src/common/store-module-index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EACX,QAAQ,EACR,kBAAkB,EAClB,qBAAqB,EACrB,gBAAgB,EAChB,WAAW,EACX,MAAM,kBAAkB,CAAC;AAQ1B,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAG9C,OAAO,EAAE,qBAAqB,EAAE,MAAM,+BAA+B,CAAC;AA6BtE,8BAAsB,gBAAiB,SAAQ,qBAAqB;IACnE;;;;;;;;;;;OAWG;IACG,WAAW,CAChB,EAAE,EAAE,QAAQ,EACZ,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,MAAM,EACjB,WAAW,EAAE,gBAAgB,EAC7B,IAAI,CAAC,EAAE,kBAAkB,GACvB,OAAO,CAAC,IAAI,CAAC;IAmIhB;;;;;;;OAOG;IACG,SAAS,CACd,EAAE,EAAE,QAAQ,EACZ,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,GACf,OAAO,CAAC,IAAI,CAAC;IAyEhB;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;cACa,uBAAuB,CACtC,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,UAAU,EACjB,MAAM,EAAE,WAAW,EACnB,WAAW,EAAE,qBAAqB,EAClC,kBAAkB,UAAQ,GACxB,OAAO,CAAC,IAAI,CAAC;IA+BhB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAiCG;cACa,kCAAkC,CACjD,EAAE,EAAE,QAAQ,EACZ,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,UAAU,EACjB,SAAS,EAAE,WAAW,GACpB,OAAO,CAAC,IAAI,CAAC;IAsDhB;;;;;;;;;;;;OAYG;cACa,kBAAkB,CACjC,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,UAAU,EACjB,SAAS,EAAE,MAAM,GACf,OAAO,CAAC,IAAI,CAAC;CAQhB"}